PEP 570: Accept (#977)
Also fix various capitalization, style and markup nits found during review (I'm still not 100% happy with the use of would vs. will everywhere, but I declare it's good enough. Someone with a degree in English can fix this up.) (I also think that the section "After Separator Proposal" could use some editing, but this won't affect acceptance of the PEP.)
This commit is contained in:
Guido van Rossum
GitHub
parent
1e2f409b47
commit
d3b0dfacba
90
pep-0570.rst
90
pep-0570.rst
|
|
@ -8,7 +8,7 @@ Author: Larry Hastings <larry@hastings.org>,
|
|||
Eric N. Vander Weele <ericvw@gmail.com>
|
||||
BDFL-Delegate: Guido van Rossum <guido@python.org>
|
||||
Discussions-To: https://discuss.python.org/t/pep-570-python-positional-only-parameters/1078
|
||||
Status: Draft
|
||||
Status: Accepted
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 20-Jan-2018
|
||||
|
|
@ -25,11 +25,11 @@ Positional-only parameters have no externally-usable name. When a function
|
|||
accepting positional-only parameters is called, positional arguments are mapped
|
||||
to these parameters based solely on their order.
|
||||
|
||||
When designing APIs (application programmable interfaces), library
|
||||
When designing APIs (application programming interfaces), library
|
||||
authors try to ensure correct and intended usage of an API. Without the ability to
|
||||
specify which parameters are positional-only, library authors must use careful consideration
|
||||
when choosing appropriate parameter names. This consideration must be taken
|
||||
into account even if the function requires the parameters or the parameters
|
||||
specify which parameters are positional-only, library authors must be careful
|
||||
when choosing appropriate parameter names. This care must be taken
|
||||
even for required parameters or when the parameters
|
||||
have no external semantic meaning for callers of the API.
|
||||
|
||||
In this PEP, we discuss:
|
||||
|
|
@ -44,7 +44,7 @@ Within context of the motivation, we then:
|
|||
|
||||
* discuss why positional-only parameters should be a feature intrinsic to the
|
||||
language
|
||||
* propose the syntax for demarcating positional-only parameters
|
||||
* propose the syntax for marking positional-only parameters
|
||||
* present how to teach this new feature
|
||||
* note rejected ideas in further detail
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ History of Positional-Only Parameter Semantics in Python
|
|||
Python originally supported positional-only parameters. Early versions of the
|
||||
language lacked the ability to call functions with arguments bound to parameters
|
||||
by name. Around Python 1.0, parameter semantics changed to be
|
||||
positional-or-keyword. Since then, callers have been able to provide arguments
|
||||
positional-or-keyword. Since then, users have been able to provide arguments
|
||||
to a function either positionally or by the keyword name specified in the
|
||||
function's definition.
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ Problems Without Positional-Only Parameters
|
|||
-------------------------------------------
|
||||
|
||||
Without positional-only parameters, there are challenges for library authors
|
||||
and callers of APIs. The following subsections outline the problems
|
||||
and users of APIs. The following subsections outline the problems
|
||||
encountered by each entity.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
@ -126,20 +126,20 @@ the parameter because it would be a breaking change.
|
|||
Positional-only parameters can be emulated by extracting arguments from
|
||||
``*args`` one by one. However, this approach is error-prone and is not
|
||||
synonymous with the function definition, as previously mentioned. The usage of
|
||||
the function is ambiguous and forces callers to look at ``help()``, the
|
||||
the function is ambiguous and forces users to look at ``help()``, the
|
||||
associated auto-generated documentation, or source code to understand what
|
||||
parameters the function contractually accepts.
|
||||
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Challenges for Callers of an API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Challenges for Users of an API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Callers may be surprised when first encountering positional-only notation. This
|
||||
Users may be surprised when first encountering positional-only notation. This
|
||||
is expected given that it has only recently been documented
|
||||
[#document-positional-only]_ and it is not possible to use in Python code. For
|
||||
these reasons, this notation is currently an outlier that appears only in
|
||||
CPython's APIs developed in C. Documenting the notation and making it possible
|
||||
to be used in Python code would eliminate this disconnect.
|
||||
CPython APIs developed in C. Documenting the notation and making it possible
|
||||
to use it in Python code would eliminate this disconnect.
|
||||
|
||||
Furthermore, the current documentation for positional-only parameters is inconsistent:
|
||||
|
||||
|
|
@ -152,7 +152,7 @@ Furthermore, the current documentation for positional-only parameters is inconsi
|
|||
|
||||
* Some functions use *both* of the above approaches. [#RANGE]_ [#ADDCH]_
|
||||
|
||||
Another point of consideration the current documentation does not distinguish
|
||||
Another point the current documentation does not distinguish is
|
||||
whether a function takes positional-only parameters. ``open()`` accepts keyword
|
||||
arguments; however, ``ord()`` does not — there is no way of telling just by
|
||||
reading the existing documentation.
|
||||
|
|
@ -250,7 +250,7 @@ take ``self`` as a positional-only parameter::
|
|||
Improving Language Consistency
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Python language, itself, would be more consistent with positional-only
|
||||
The Python language would be more consistent with positional-only
|
||||
parameters. If the concept is a normal feature of Python rather than a feature
|
||||
exclusive to extension modules, it would reduce confusion for users
|
||||
encountering functions with positional-only parameters. Some major
|
||||
|
|
@ -263,7 +263,7 @@ the positional syntax would improve consistency. The ``/`` syntax is already exp
|
|||
in the existing documentation such as when builtins and interfaces are generated
|
||||
by the argument clinic.
|
||||
|
||||
Another essential aspect to consider is PEP 399 [#PEP399]_, which mandates that
|
||||
Another essential aspect to consider is PEP 399, which mandates that
|
||||
pure Python versions of modules in the standard library *must* have the same
|
||||
interface and semantics that the accelerator modules implemented in C. For
|
||||
example, if ``collections.defaultdict`` were to have a pure Python
|
||||
|
|
@ -277,11 +277,11 @@ Rationale
|
|||
We propose to introduce positional-only parameters as a new syntax to the
|
||||
Python language.
|
||||
|
||||
The new syntax would enable library authors to further control how their API
|
||||
can be called. It would designate which parameters must be called as
|
||||
The new syntax will enable library authors to further control how their API
|
||||
can be called. It will allow designating which parameters must be called as
|
||||
positional-only, while preventing them from being called as keyword arguments.
|
||||
|
||||
Previously, PEP 457 proposed to define the syntax, but with a much broader
|
||||
Previously, (informational) PEP 457 defined the syntax, but with a much more vague
|
||||
scope. This PEP takes the original proposal a step further by justifying
|
||||
the syntax and providing an implementation for the ``/`` syntax in function
|
||||
definitions.
|
||||
|
|
@ -302,9 +302,9 @@ backwards-incompatible changes were made to disallow keyword arguments to
|
|||
Maintainability
|
||||
---------------
|
||||
|
||||
Providing a way to specify positional-only parameters in Python would make it
|
||||
Providing a way to specify positional-only parameters in Python will make it
|
||||
easier to maintain pure Python implementations of C modules. Additionally,
|
||||
library authors defining functions would have the choice for choosing
|
||||
library authors defining functions will have the choice for choosing
|
||||
positional-only parameters if they determine that passing a keyword argument
|
||||
provides no additional clarity.
|
||||
|
||||
|
|
@ -345,11 +345,11 @@ intended order::
|
|||
range(start=0, stop=5, step=2)
|
||||
|
||||
-------------------------------------------
|
||||
Compatibility for Pure Python and C modules
|
||||
Compatibility for Pure Python and C Modules
|
||||
-------------------------------------------
|
||||
|
||||
Another critical motivation for positional-only parameters is PEP 399
|
||||
[#PEP399]_: Pure Python/C Accelerator Module Compatibility Requirements. This
|
||||
Another critical motivation for positional-only parameters is PEP 399:
|
||||
Pure Python/C Accelerator Module Compatibility Requirements. This
|
||||
PEP states that:
|
||||
|
||||
This PEP requires that in these instances that the C code must pass the
|
||||
|
|
@ -372,7 +372,7 @@ other Python implementations. For example::
|
|||
2918445923
|
||||
|
||||
Other Python implementations can reproduce the CPython APIs manually, but this
|
||||
goes against the spirit of PEP 399 [#PEP399]_ to avoid duplication of effort by
|
||||
goes against the spirit of PEP 399 to avoid duplication of effort by
|
||||
mandating that all modules added to Python's standard library **must** have a
|
||||
pure Python implementation with the same interface and semantics.
|
||||
|
||||
|
|
@ -418,7 +418,7 @@ Optimizations
|
|||
A final argument in favor of positional-only parameters is that they allow some
|
||||
new optimizations like the ones already present in the argument clinic due to
|
||||
the fact that parameters are expected to be passed in strict order. For example, CPython's
|
||||
internal *METH_FASTCALL* calling convention has been recently specialized for
|
||||
internal ``METH_FASTCALL`` calling convention has been recently specialized for
|
||||
functions with positional-only parameters to eliminate the cost for handling
|
||||
empty keywords. Similar performance improvements can be applied when creating
|
||||
the evaluation frame of Python functions thanks to positional-only parameters.
|
||||
|
|
@ -444,7 +444,7 @@ like::
|
|||
|
||||
The following would apply:
|
||||
|
||||
* All parameters left of the ``/`` are demarcated as positional-only.
|
||||
* All parameters left of the ``/`` are treated as positional-only.
|
||||
* If ``/`` is not specified in the function definition, that function does not
|
||||
accept any positional-only arguments.
|
||||
* The logic around optional values for positional-only parameters remains the
|
||||
|
|
@ -476,7 +476,7 @@ While the following would be invalid::
|
|||
def name(p1=None, p2, /):
|
||||
|
||||
--------------------------
|
||||
Full grammar specification
|
||||
Full Grammar Specification
|
||||
--------------------------
|
||||
|
||||
A simplified view of the proposed grammar specification is::
|
||||
|
|
@ -514,18 +514,18 @@ and for ``varargslist`` would be::
|
|||
| '**' vfpdef [',']
|
||||
)
|
||||
|
||||
--------------------------------
|
||||
Origin of the "/" as a separator
|
||||
--------------------------------
|
||||
----------------------------
|
||||
Origin of "/" as a Separator
|
||||
----------------------------
|
||||
|
||||
Using the "/" as a separator was initially proposed by Guido van Rossum
|
||||
Using ``/`` as a separator was initially proposed by Guido van Rossum
|
||||
in 2012 [#GUIDO]_ :
|
||||
|
||||
Alternative proposal: how about using '/' ? It's kind of the opposite
|
||||
of '*' which means "keyword argument", and '/' is not a new character.
|
||||
|
||||
=================
|
||||
How to teach this
|
||||
How To Teach This
|
||||
=================
|
||||
|
||||
Introducing a dedicated syntax to mark positional-only parameters is closely
|
||||
|
|
@ -573,7 +573,7 @@ If ``/`` and ``*`` are not present in the function definition, arguments may
|
|||
be passed to a function by position or by keyword.
|
||||
|
||||
--------------------------
|
||||
Positional-only Parameters
|
||||
Positional-Only Parameters
|
||||
--------------------------
|
||||
|
||||
Looking at this in a bit more detail, it is possible to mark certain parameters
|
||||
|
|
@ -587,7 +587,7 @@ parameters.
|
|||
Parameters following the ``/`` may be *positional-or-keyword* or *keyword-only*.
|
||||
|
||||
----------------------
|
||||
Keyword-only Arguments
|
||||
Keyword-Only Arguments
|
||||
----------------------
|
||||
|
||||
To mark parameters as *keyword-only*, indicating the parameters must be passed
|
||||
|
|
@ -739,7 +739,7 @@ additional syntax. However, we have decided to reject this idea because:
|
|||
|
||||
|
||||
-------------------
|
||||
Per-argument marker
|
||||
Per-Argument Marker
|
||||
-------------------
|
||||
|
||||
A per-argument marker is another language-intrinsic option. The approach adds
|
||||
|
|
@ -756,7 +756,7 @@ It should be noted that some libraries already use leading underscore
|
|||
[#leading-underscore]_ to conventionally indicate parameters as positional-only.
|
||||
|
||||
-----------------------------------
|
||||
Using "__" as a per-argument marker
|
||||
Using "__" as a Per-Argument Marker
|
||||
-----------------------------------
|
||||
|
||||
Some libraries and applications (like ``mypy`` or ``jinja``) use names
|
||||
|
|
@ -783,7 +783,7 @@ a new syntax because:
|
|||
|
||||
|
||||
-------------------------------------------------
|
||||
Group positional-only parameters with parenthesis
|
||||
Group Positional-Only Parameters With Parentheses
|
||||
-------------------------------------------------
|
||||
|
||||
Tuple parameter unpacking is a Python 2 feature which allows the use of a tuple
|
||||
|
|
@ -809,21 +809,21 @@ reasons:
|
|||
confusion because it can be confused with a tuple declaration.
|
||||
|
||||
------------------------
|
||||
After separator proposal
|
||||
After Separator Proposal
|
||||
------------------------
|
||||
|
||||
Demarcating positional-parameters after the ``/`` was another consideration.
|
||||
Marking positional-parameters after the ``/`` was another idea considered.
|
||||
However, we were unable to find an approach which would modify the arguments
|
||||
after the marker. Otherwise, would force the parameters before the marker to
|
||||
be positional-only as well. For example::
|
||||
|
||||
def (x, y, /, z):
|
||||
|
||||
If we define that ``/`` demarcates ``z`` as positional-only, it would not be
|
||||
If we define that ``/`` marks ``z`` as positional-only, it would not be
|
||||
possible to specify ``x`` and ``y`` as keyword arguments. Finding a way to
|
||||
work around this limitation would add confusion given that at the moment
|
||||
keyword arguments cannot be followed by positional arguments. Therefore, ``/``
|
||||
will make both the preceding and following parameters positional-only.
|
||||
would make both the preceding and following parameters positional-only.
|
||||
|
||||
======
|
||||
Thanks
|
||||
|
|
@ -832,7 +832,7 @@ Thanks
|
|||
Credit for some of the content of this PEP is contained in Larry Hastings’s
|
||||
PEP 457.
|
||||
|
||||
Credit for the use of '/' as the separator between positional-only and
|
||||
Credit for the use of ``/`` as the separator between positional-only and
|
||||
positional-or-keyword parameters go to Guido van Rossum, in a proposal from
|
||||
2012. [#GUIDO]_
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue