On Sun, 07 Jul 2013 04:48:18 +0200, Larry Hastings <la...@hastings.org> wrote: > On 07/07/2013 03:04 AM, Nick Coghlan wrote: > > > > On 7 Jul 2013 10:25, "Larry Hastings" <la...@hastings.org > > <mailto:la...@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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
