iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2019-04-05 15:09:18 -07:00 committed by GitHub
parent 1e2f409b47
commit d3b0dfacba
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 45 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
pep-0570.rst
View File

@ -8,7 +8,7 @@ Author: Larry Hastings <larry@hastings.org>,
Eric N. Vander Weele <ericvw@gmail.com> Eric N. Vander Weele <ericvw@gmail.com>
BDFL-Delegate: Guido van Rossum <guido@python.org> BDFL-Delegate: Guido van Rossum <guido@python.org>
Discussions-To: https://discuss.python.org/t/pep-570-python-positional-only-parameters/1078 Discussions-To: https://discuss.python.org/t/pep-570-python-positional-only-parameters/1078
Status: Draft Status: Accepted
Type: Standards Track Type: Standards Track
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 20-Jan-2018 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 accepting positional-only parameters is called, positional arguments are mapped
to these parameters based solely on their order. 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 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 specify which parameters are positional-only, library authors must be careful
when choosing appropriate parameter names. This consideration must be taken when choosing appropriate parameter names. This care must be taken
into account even if the function requires the parameters or the parameters even for required parameters or when the parameters
have no external semantic meaning for callers of the API. have no external semantic meaning for callers of the API.
In this PEP, we discuss: 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 * discuss why positional-only parameters should be a feature intrinsic to the
language language
* propose the syntax for demarcating positional-only parameters * propose the syntax for marking positional-only parameters
* present how to teach this new feature * present how to teach this new feature
* note rejected ideas in further detail * 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 Python originally supported positional-only parameters. Early versions of the
language lacked the ability to call functions with arguments bound to parameters language lacked the ability to call functions with arguments bound to parameters
by name. Around Python 1.0, parameter semantics changed to be 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 to a function either positionally or by the keyword name specified in the
function's definition. function's definition.
@ -106,7 +106,7 @@ Problems Without Positional-Only Parameters
------------------------------------------- -------------------------------------------
Without positional-only parameters, there are challenges for library authors 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. 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 Positional-only parameters can be emulated by extracting arguments from
``*args`` one by one. However, this approach is error-prone and is not ``*args`` one by one. However, this approach is error-prone and is not
synonymous with the function definition, as previously mentioned. The usage of 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 associated auto-generated documentation, or source code to understand what
parameters the function contractually accepts. 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 is expected given that it has only recently been documented
[#document-positional-only]_ and it is not possible to use in Python code. For [#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 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 CPython APIs developed in C. Documenting the notation and making it possible
to be used in Python code would eliminate this disconnect. to use it in Python code would eliminate this disconnect.
Furthermore, the current documentation for positional-only parameters is inconsistent: 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]_ * 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 whether a function takes positional-only parameters. ``open()`` accepts keyword
arguments; however, ``ord()`` does not — there is no way of telling just by arguments; however, ``ord()`` does not — there is no way of telling just by
reading the existing documentation. reading the existing documentation.
@ -250,7 +250,7 @@ take ``self`` as a positional-only parameter::
Improving Language Consistency 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 parameters. If the concept is a normal feature of Python rather than a feature
exclusive to extension modules, it would reduce confusion for users exclusive to extension modules, it would reduce confusion for users
encountering functions with positional-only parameters. Some major 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 in the existing documentation such as when builtins and interfaces are generated
by the argument clinic. 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 pure Python versions of modules in the standard library *must* have the same
interface and semantics that the accelerator modules implemented in C. For interface and semantics that the accelerator modules implemented in C. For
example, if ``collections.defaultdict`` were to have a pure Python 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 We propose to introduce positional-only parameters as a new syntax to the
Python language. Python language.
The new syntax would enable library authors to further control how their API The new syntax will enable library authors to further control how their API
can be called. It would designate which parameters must be called as can be called. It will allow designating which parameters must be called as
positional-only, while preventing them from being called as keyword arguments. 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 scope. This PEP takes the original proposal a step further by justifying
the syntax and providing an implementation for the ``/`` syntax in function the syntax and providing an implementation for the ``/`` syntax in function
definitions. definitions.
@ -302,9 +302,9 @@ backwards-incompatible changes were made to disallow keyword arguments to
Maintainability 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, 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 positional-only parameters if they determine that passing a keyword argument
provides no additional clarity. provides no additional clarity.
@ -345,11 +345,11 @@ intended order::
range(start=0, stop=5, step=2) 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 Another critical motivation for positional-only parameters is PEP 399:
[#PEP399]_: Pure Python/C Accelerator Module Compatibility Requirements. This Pure Python/C Accelerator Module Compatibility Requirements. This
PEP states that: PEP states that:
This PEP requires that in these instances that the C code must pass the This PEP requires that in these instances that the C code must pass the
@ -372,7 +372,7 @@ other Python implementations. For example::
2918445923 2918445923
Other Python implementations can reproduce the CPython APIs manually, but this 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 mandating that all modules added to Python's standard library **must** have a
pure Python implementation with the same interface and semantics. 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 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 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 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 functions with positional-only parameters to eliminate the cost for handling
empty keywords. Similar performance improvements can be applied when creating empty keywords. Similar performance improvements can be applied when creating
the evaluation frame of Python functions thanks to positional-only parameters. the evaluation frame of Python functions thanks to positional-only parameters.
@ -444,7 +444,7 @@ like::
The following would apply: 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 * If ``/`` is not specified in the function definition, that function does not
accept any positional-only arguments. accept any positional-only arguments.
* The logic around optional values for positional-only parameters remains the * 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, /): def name(p1=None, p2, /):
-------------------------- --------------------------
Full grammar specification Full Grammar Specification
-------------------------- --------------------------
A simplified view of the proposed grammar specification is:: A simplified view of the proposed grammar specification is::
@ -514,18 +514,18 @@ and for ``varargslist`` would be::
| '**' vfpdef [','] | '**' 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]_ : in 2012 [#GUIDO]_ :
Alternative proposal: how about using '/' ? It's kind of the opposite Alternative proposal: how about using '/' ? It's kind of the opposite
of '*' which means "keyword argument", and '/' is not a new character. 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 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. 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 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*. 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 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 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. [#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 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 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. 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 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 after the marker. Otherwise, would force the parameters before the marker to
be positional-only as well. For example:: be positional-only as well. For example::
def (x, y, /, z): 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 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 work around this limitation would add confusion given that at the moment
keyword arguments cannot be followed by positional arguments. Therefore, ``/`` 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 Thanks
@ -832,7 +832,7 @@ Thanks
Credit for some of the content of this PEP is contained in Larry Hastings’s Credit for some of the content of this PEP is contained in Larry Hastings’s
PEP 457. 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 positional-or-keyword parameters go to Guido van Rossum, in a proposal from
2012. [#GUIDO]_ 2012. [#GUIDO]_