[Python-Dev] PEP 457: Syntax For Positional-Only Parameters

[R. David Murray]

On Wed, 09 Oct 2013 17:05:12 +0100, Paul Moore <p.f.moore at gmail.com> wrote:
> On 9 October 2013 16:07, Larry Hastings <larry at hastings.org> wrote:
> > On 10/09/2013 04:38 PM, Paul Moore wrote:
> >
> > For that matter, why does the syntax used by Argument Clinic have to
> > be the same as whatever future syntax is used in Python? If indeed,
> > any ever is? What benefit do we get given the cost (rushing in a
> > syntax that nobody is actually convinced we even need in Python yet).
> >
> > In other words, why does PEP this need to be separated out from the
> > Argument Clinic PEP at all?
> >
> >
> > I propose to use this syntax in three places:
> >
> > As input to Argument Clinic.
> > As input to the Python C API, to express the metadata for builtins.
> > As the first line of output of pydoc (aka "help()") when reviewing a
> > function.
> >
> > Of these, 3 is visible to users.  Theoretically all of them could use
> > different syntaxes.  But consistency is desirable, so it would be better if
> > these syntaxes were as similar as possible.
> 
> OK, all of those are reasonable points. I'm still -0 because I find
> the proposed syntax ugly, but I can't offer a better syntactic
> solution. My proposal is to hide the ugly syntax internally, and use
> prose documentation where users can see. You may disagree, that's
> fine.
> 
> >  Python syntax works well for
> > all three syntaxes, except it does not support positional-only parameters.
> > It seemed reasonable to codify twenty-year old practice in a syntax
> > extension that I could use in all of the above.
> 
> I remain -1 on forcing "Python syntax" to support all of these odd
> corner cases (and positional-only is already a corner case,
> range/addch are seriously so).
> 
> I don't see any reason for the proposal to mandate that the arguments
> made here should apply to any future changes to core Python syntax.
> Either we have the debate now, or we agree that the proposal doesn't
> apply to Python.

It seems to me, then, that the solution for the
handle-the-ugly-existing-practice-groups issue is to make case (3)
(pydoc prototype) match the convention that we have arrived at for the
documentation:  multiple signature lines to represent what Argument Clinic
represents with the group notation.

We don't currently have a doc solution for 'positional only' arguments.
How about a variant on the '_' markup idea:

    range(<stop>)
    range(<start>, <stop>[, <step>])

This takes advantage of the fact that the <> notation is commonly used
in various kinds of programming documentation to indicate "put your
specific value here".

--David