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

[R. David Murray]

On Sun, 07 Jul 2013 04:48:18 +0200, Larry Hastings <larry at hastings.org> wrote:
> On 07/07/2013 03:04 AM, Nick Coghlan wrote:
> >
> > On 7 Jul 2013 10:25, "Larry Hastings" <larry at hastings.org 
> > <mailto:larry at hastings.org>> wrote:
> > >>
> > >> 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.
> >
> > 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.
> >
> 
> We don't have to invent a notation--because we already have one. It's 
> square brackets enclosing the optional parameter groups.  This is the 
> syntax Guido dictated for Argument Clinic to use in its input DSL back 
> at PyCon US 2013.  And the Python standard library documentation has 
> been using this convention since the 90s. (Admittedly as a documentation 
> convention, not in code.  But what we're talking about is documentation 
> so I claim it's totally relevant.)
> 
> If we combine that with the admittedly-new "/" indicating "all previous 
> parameters are positional-only", which we're also already using in the 
> Argument Clinic input DSL syntax (at your suggestion!), we have a 
> complete, crisp syntax.  I suppose "/" isn't really necessary, the 
> Python documentation has survived without it for a long time.  But I 
> think it'd would be a nice clarification; it would convey that you can't 
> splat in **kwargs into functions specifying it, for example.
> 
> I expect this to be the format of the signature-for-builtins static data 
> too, as well as the Argument Clinic input syntax.  Sure seems like a 
> nice idea to use the same syntax everywhere.  Particularly allowing as 
> how it's so nice and readable.
> 
> 
> An admission: the Python standard library documentation actually uses 
> *both* square-brackets-for-optional-groups and multiple lines. Sometimes 
> even for the same function!  An example:
> 
>     http://docs.python.org/3/library/curses.html#curses.window.addch
> 
> Of the two, I believe the square brackets syntax is far more common.

Sorry to make your life more complicated, but unless I'm misunderstanding
something, issue 18220 (http://bugs.python.org/issue18220) throws another
monkey-wrench in to this.  If I'm understanding this discussion correctly,
that example:

    islice(stop)
    islice(start, stop [, step])

requires the multiple-signature approach.

Note also that the python3 documentation has moved away from the []
notation wherever possible.

--David