[Python-Dev] Rough idea for adding introspection information for builtins (original) (raw)

R. David Murray rdmurray at bitdance.com
Sun Jul 7 07:25:04 CEST 2013

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

More information about the Python-Dev mailing list