[Python-Dev] Rough idea for adding introspection information for builtins

[Nick Coghlan]

On 7 Jul 2013 10:25, "Larry Hastings" <larry at hastings.org> wrote:
>
> On 07/07/2013 12:32 AM, Nick Coghlan wrote:
>>
>> Rather than perpetuating unwanted complexity, can't we just add a single
"incomplete signature" flag to handle the legacy cases, and leave those to
the docstrings?
>>
>> As in, if the flag is set, pydoc displays the "..." because it knows the
signature data isn't quite right.
>>
>> Alternatively (and even more simply), is it really so bad if argument
clinic doesn't support introspection of such functions at all, and avoids
setting __signature__ for such cases?
>>
>> As a third option, we could add an "alternative signatures" attribute to
capture multiple orthogonal signatures that should be presented on separate
lines.
>>
>> All of those possibilities sound more appealing to me than adding direct
support for parameter groups at the Python level (with my preference being
to postpone the question to 3.5 by not allowing introspection of affected
functions in this initial iteration).
>
>
> First, I think the PyCharm case is compelling enough on its own.  I
realized after I sent it that there's a related class of tools that are
interested: PyFlakes, PyLint, and the like.  I'm sure the static
correctness analyzers would like to be able to automatically determine
"this is an illegal number of parameters for this function" for
builtins--particularly for third-party builtins!  The fact that we wouldn't
need to special-case pydoc suggests it's the superior approach.  ("Special
cases aren't special enough to break the rules.")
>
> Second, the added complexity would be a single new member on the
Parameter object.  Let me propose such a parameter here, in the style of
the Parameter class documentation:
>>
>> group
>>>
>>> If not None, represents which "optional parameter group" this parameter
belongs to.  Optional parameter groups are contiguous sequences of
parameters that must either all be specified or all be unspecified.  For
example, if a function takes four parameters but the last two are in an
optional parameter group, you could specify either two or four arguments to
that function--it would be illegal to specify three arguments.  Parameter
groups can only contain positional-only parameters; therefore group will
only be a non-None value when kind is POSITIONAL_ONLY.
>
>
> I suggest that is a manageable level of complexity.  And that the tooling
projects would very much like to have this information.
>
> Third, your proposals are respectively: 1) a hack which fixes the
docstring but doesn't fix the introspection information (so we'd be
providing incorrect introspection information to tools), 2) a small cop-out
(which I think would also probably require a hack to pydoc), and 3) way
more complicated than doing it the right way (so I don't see how it's an
improvement).  Of your three suggestions I dislike 2) least.
>
> This facet of call signatures has existed in Python since the addition of
range().  I concede that it's legacy, but it's not going away.  Ever.  I
now think we're better off embracing this complexity than trying to sweep
it under the rug.

The "group" attribute sounds reasonable to me, with the proviso that we use
"multiple signature lines" as the way to represent them in pydoc (rather
than inventing a notation for showing them in a single signature line).

It occurs to me that "type" is itself an example of this kind of dual
signature.

Cheers,
Nick.

>
>
> /arry
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130707/afa3d53d/attachment.html>