diff --git a/pep-0457.txt b/pep-0457.txt index 6e0596c00..38efa0917 100644 --- a/pep-0457.txt +++ b/pep-0457.txt @@ -111,7 +111,7 @@ The Current State Of Documentation For Positional-Only Parameters The documentation for positional-only parameters is incomplete and inconsistent: -* Some functions denote optional groups of positional-only arguments +* Some functions denote optional *groups* of positional-only arguments by enclosing them in nested square brackets. [#BORDER]_ * Some functions denote optional groups of positional-only arguments @@ -145,44 +145,9 @@ All parameters before the ``/`` are positional-only. If ``/`` is not specified in a function signature, that function does not accept any positional-only parameters. -Positional-only parameters can be optional, but the mechanism is -significantly different from positional-or-keyword or keyword-only -parameters. Positional-only parameters don't accept default -values. Instead, positional-only parameters can be specified -in optional "groups". Groups of parameters are surrounded by -square brackets, like so:: - - def addch([y, x,] ch, [attr,] /): - -Positional-only parameters that are not in an option group are -"required" positional-only parameters. All "required" positional-only -parameters must be contiguous. - -Parameters in an optional group accept arguments in a group; you -must provide arguments either for all of the them or for none of them. -Using the example of ``addch()`` above, you could not call ``addch()`` -in such a way that ``x`` was specified but ``y`` was not (and vice versa). -The mapping of positional parameters to optional groups is done -based on fitting the number of parameters to groups. Based on the -above definition, ``addch()`` would assign arguments to parameters -in the following way: - - +-------------------+------------------------------+ - |Number of arguments|Parameter assignment | - +-------------------+------------------------------+ - |0 |*raises an exception* | - +-------------------+------------------------------+ - |1 |``ch`` | - +-------------------+------------------------------+ - |2 |``ch``, ``attr`` | - +-------------------+------------------------------+ - |3 |``y``, ``x``, ``ch`` | - +-------------------+------------------------------+ - |4 |``y``, ``x``, ``ch``, ``attr``| - +-------------------+------------------------------+ - |5 or more |*raises an exception* | - +-------------------+------------------------------+ - +Positional-only parameters can have a default value, and if they +do they are optional. Positional-only parameters that don't have +a default value are "required" positional-only parameters. More semantics of positional-only parameters: @@ -191,32 +156,12 @@ More semantics of positional-only parameters: are *never* externally addressable by name. (Similarly to ``*args`` and ``**kwargs``.) -* It's possible to nest option groups. - -* If there are no required parameters, all option groups behave - as if they're to the right of the required parameter group. - -* For clarity and consistency, the comma for a parameter always - comes immediately after the parameter name. It's a syntax error - to specify a square bracket between the name of a parameter and - the following comma. (This is far more readable than putting - the comma outside the square bracket, particularly for nested - groups.) - * If there are arguments after the ``/``, then you must specify a comma after the ``/``, just as there is a comma after the ``*`` denoting the shift to keyword-only parameters. * This syntax has no effect on ``*args`` or ``**kwargs``. -It's possible to specify a function prototype where the mapping -of arguments to parameters is ambiguous. Consider:: - - def range([start,] stop, [range,] /): - -Python disambiguates these situations by preferring optional groups -to the *left* of the required group. - ====================== Additional Limitations ====================== @@ -230,18 +175,17 @@ easier. Specifically: cannot have any other kind of parameter. (This will probably be relaxed slightly in the near future.) -* Multiple option groups on either side of the required - positional-only parameters must be nested, with the - nesting getting deeper the further away the group is - from the required positional-parameter group. - - Put another way: - all the left-brackets for option groups to the - left of the required group must be specified contiguously, - and - all the right-brackets for option groups to the - right of the required group must be specified contiguously. - +* Argument Clinic supports an additional syntax called + "optional groups". An "optional group" is a sequential + set of positional-only parameters that must be specified + or not-specified as a group. If, for example, you define + a function in Argument Clinic that takes four parameters, + and all of them are positional-only and in one optional + group, then when calling the function you must specify + either zero arguments or four arguments. This is necessary + to cover more of Python's legacy library, but is outside + the scope of this PEP, and is not recommended for actual + inclusion in the Python language. ============================== Notes For A Future Implementor