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

[Larry Hastings]

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.


//arry/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130707/a432f205/attachment-0001.html>