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

[Larry Hastings]

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.


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