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

[Larry Hastings]

Revisiting a four-month-old discussion:

On 03/19/2013 11:00 AM, Larry Hastings wrote:
> As for handling optional argument groups, my gut feeling is that we're 
> better off not leaking it out of Argument Clinic--don't expose it in 
> this string we're talking about, and don't add support for it in the 
> inspect.Parameter object.  I'm not going to debate range(), the syntax 
> of which predates one of our release managers.  But I suggest option 
> groups are simply a misfeature of the curses module.  There are some 
> other possible uses in builtins (I forgot to dig those out this 
> evening) but so far we're talking adding complexity to an array of 
> technologies (this representation, the parser, the Parameter object) 
> to support a handful of uses of something we shouldn't have done in 
> the first place, for consumers who I think won't care and won't 
> appreciate the added conceptual complexity.

I'm sad to say I've just about changed my mind on this.

This is what help(os.stat) looks like in my dev branch for Argument Clinic:

     >>> help(os.stat)
    Help on built-in function stat in module posix:

    stat(...)
         os.stat(path, *, dir_fd=None, follow_symlinks=True)
    ...


Argument Clinic added the line starting with "os.stat(path, ". pydoc 
generated the "stat(...)" line.  It doesn't have any info because of the 
lack of introspection information.

Once builtins have introspection information, pydoc can do a better job, 
and Argument Clinic can stop generating its redundant prototype line.  
But if pydoc doesn't have argument group information, it won't be able 
to tell where one group ends and the next begins, and it won't be able 
to render the prototype for the help text correctly.  I fear misleading 
text is even worse than no text at all.

I also suggest that fancy editors (PyCharm etc) want as much information 
as we can give them.  If we give them argument group information, they 
can flag malformed calls (e.g. "there's no way to legally call this 
function with exactly three arguments").

I therefore have two credible consumers of this information.  That's 
enough for me: I propose we amend the Parameter object to add option 
group information for positional-only parameters.


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