From d3b0dfacba09d7d122e1ca5917ddff1f97eb39d3 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 5 Apr 2019 15:09:18 -0700 Subject: [PATCH] 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.) --- pep-0570.rst | 90 ++++++++++++++++++++++++++-------------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/pep-0570.rst b/pep-0570.rst index 540d32d54..d307c48e3 100644 --- a/pep-0570.rst +++ b/pep-0570.rst @@ -8,7 +8,7 @@ Author: Larry Hastings , Eric N. Vander Weele BDFL-Delegate: Guido van Rossum 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]_