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

Nick Coghlan ncoghlan at gmail.com
Sun Jul 7 00:32:46 CEST 2013

On 7 Jul 2013 05:22, "Larry Hastings" <larry at hastings.org> wrote:
> 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
>> >>> 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.

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

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).


> /arry
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130707/109b6d4d/attachment.html>

More information about the Python-Dev mailing list