PEP 570: Positional-Only Parameters (#564)
This commit is contained in:
Mario Corchero
Brett Cannon
parent
d084110591
commit
8c4563933f
|
|
@ -0,0 +1,322 @@
|
|||
PEP: 570
|
||||
Title: Python Positional-Only Parameters
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: Larry Hastings <larry@hastings.org>,
|
||||
Pablo Galindo <pablogsal@gmail.com>,
|
||||
Mario Corchero <mariocj89@gmail.com>
|
||||
Discussions-To: Python-Dev <python-dev@python.org>
|
||||
Status: Draft
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 20-Jan-2018
|
||||
|
||||
|
||||
========
|
||||
Overview
|
||||
========
|
||||
|
||||
This PEP proposes a syntax for positional-only parameters in Python.
|
||||
Positional-only parameters are parameters without an externally-usable
|
||||
name; when a function accepting positional-only parameters is called,
|
||||
positional arguments are mapped to these parameters based solely on
|
||||
their position.
|
||||
|
||||
=========
|
||||
Rationale
|
||||
=========
|
||||
|
||||
Python has always supported positional-only parameters.
|
||||
Early versions of Python lacked the concept of specifying
|
||||
parameters by name, so naturally all parameters were
|
||||
positional-only. This changed around Python 1.0, when
|
||||
all parameters suddenly became positional-or-keyword.
|
||||
This allowed users to provide arguments to a function both
|
||||
positionally or referencing the keyword used in the definition
|
||||
of it. But, this is not always desired nor even available as
|
||||
even in current versions of Python, many CPython
|
||||
"builtin" functions still only accept positional-only arguments.
|
||||
|
||||
Even if positional arguments only in a function can be achieved
|
||||
via using ``*args`` parameters and extracting them one by one,
|
||||
the solution is far from ideal and not as expressive as the one
|
||||
proposed in this PEP, which targets to provide syntax to specify
|
||||
accepting a specific number of positional-only parameters.
|
||||
Additionally, this will bridge the gap we currently find between
|
||||
builtin functions that today allows to specify positional-only
|
||||
parameters and pure Python implementations that lack the
|
||||
syntax for it.
|
||||
|
||||
-----------------------------------------------------
|
||||
Positional-Only Parameter Semantics In Current Python
|
||||
-----------------------------------------------------
|
||||
|
||||
There are many, many examples of builtins that only
|
||||
accept positional-only parameters. The resulting
|
||||
semantics are easily experienced by the Python
|
||||
programmer--just try calling one, specifying its
|
||||
arguments by name::
|
||||
|
||||
|
||||
>>> help(pow)
|
||||
...
|
||||
pow(x, y, z=None, /)
|
||||
...
|
||||
>>> pow(x=5, y=3)
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in <module>
|
||||
TypeError: pow() takes no keyword arguments
|
||||
|
||||
Pow clearly expresses that its arguments are only positional
|
||||
via the ``/`` marker, but this is at the moment only documentational,
|
||||
Python developers cannot write such syntax.
|
||||
|
||||
In addition, there are some functions with particularly
|
||||
interesting semantics:
|
||||
|
||||
* ``range()``, which accepts an optional parameter
|
||||
to the *left* of its required parameter. [#RANGE]_
|
||||
|
||||
* ``dict()``, whose mapping/iterator parameter is optional and
|
||||
semantically must be positional-only. Any externally
|
||||
visible name for this parameter would occlude
|
||||
that name going into the ``**kwarg`` keyword variadic
|
||||
parameter dict! [#DICT]_
|
||||
|
||||
Obviously one can simulate any of these in pure Python code
|
||||
by accepting ``(*args, **kwargs)`` and parsing the arguments
|
||||
by hand. But this results in a disconnect between the
|
||||
Python function signature and what it actually accepts,
|
||||
not to mention the work of implementing said argument parsing.
|
||||
|
||||
==========
|
||||
Motivation
|
||||
==========
|
||||
|
||||
The new syntax will allow developers to further control how their
|
||||
API can be consumed. It will allow restricting the usage of keyword
|
||||
Specify arguments by adding the new type of positional-only ones.
|
||||
|
||||
A similar PEP with a broader scope (PEP 457) was proposed
|
||||
to define the syntax. This PEP builds on top of part of it
|
||||
to define and provide an implementation for the ``/`` syntax on
|
||||
function signatures.
|
||||
|
||||
=================================================================
|
||||
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
|
||||
by enclosing them in nested square brackets. [#BORDER]_
|
||||
|
||||
* Some functions denote optional groups of positional-only arguments
|
||||
by presenting multiple prototypes with varying numbers of
|
||||
arguments. [#SENDFILE]_
|
||||
|
||||
* Some functions use *both* of the above approaches. [#RANGE]_ [#ADDCH]_
|
||||
|
||||
One more important idea to consider: currently in the documentation
|
||||
there's no way to tell whether a function takes positional-only
|
||||
parameters. ``open()`` accepts keyword arguments, ``ord()`` does
|
||||
not, but there is no way of telling just by reading the
|
||||
documentation that this is true.
|
||||
|
||||
====================
|
||||
Syntax And Semantics
|
||||
====================
|
||||
|
||||
From the "ten-thousand foot view", and ignoring ``*args`` and ``**kwargs``
|
||||
for now, the grammar for a function definition currently looks like this::
|
||||
|
||||
def name(positional_or_keyword_parameters, *, keyword_only_parameters):
|
||||
|
||||
Building on that perspective, the new syntax for functions would look
|
||||
like this::
|
||||
|
||||
def name(positional_only_parameters, /, positional_or_keyword_parameters,
|
||||
*, keyword_only_parameters):
|
||||
|
||||
All parameters before the ``/`` are positional-only. If ``/`` is
|
||||
not specified in a function signature, that function does not
|
||||
accept any positional-only parameters.
|
||||
The logic around optional values for positional-only argument
|
||||
Remains the same as the one for positional-or-keyword. Once
|
||||
a positional-only argument is provided with a default,
|
||||
the following positional-only and positional-or-keyword argument
|
||||
need to have a default as well. Positional-only parameters that
|
||||
don’t have a default value are "required" positional-only parameters.
|
||||
Therefore the following are valid signatures::
|
||||
|
||||
def name(p1, p2, /, p_or_kw, *, kw):
|
||||
def name(p1, p2=None, /, p_or_kw=None, *, kw):
|
||||
def name(p1, p2=None, /, *, kw):
|
||||
def name(p1, p2=None, /):
|
||||
def name(p1, p2, /, p_or_kw):
|
||||
def name(p1, p2, /):
|
||||
|
||||
Whilst the followings are not::
|
||||
|
||||
def name(p1, p2=None, /, p_or_kw, *, kw):
|
||||
def name(p1=None, p2, /, p_or_kw=None, *, kw):
|
||||
def name(p1=None, p2, /):
|
||||
|
||||
==========================
|
||||
Full grammar specification
|
||||
==========================
|
||||
|
||||
A draft of the proposed grammar specification is::
|
||||
|
||||
new_typedargslist:
|
||||
tfpdef (',' tfpdef)* ',' '/' [',' [typedargslist]] | typedargslist
|
||||
|
||||
new_varargslist:
|
||||
vfpdef (',' vfpdef)* ',' '/' [',' [varargslist]] | varargslist
|
||||
|
||||
It will be added to the actual typedargslist and varargslist
|
||||
but for easier discussion is presented as new_typedargslist and new_varargslist
|
||||
|
||||
|
||||
===================
|
||||
Implementation Plan
|
||||
===================
|
||||
|
||||
The implementation will involve a full change of the Grammar. This will
|
||||
involve following the steps outlined in PEP 306 [#PEP306]_. In addition, other
|
||||
steps are needed including:
|
||||
|
||||
* Modifying the code object and the function object to be aware of positional
|
||||
only arguments.
|
||||
|
||||
* Modifiying ``ceval.c`` (``PyEval_EvalCodeEx``, ``PyEval_EvalFrameEx``...)
|
||||
to correctly handle positional-only arguments.
|
||||
|
||||
* Modifying ``marshal.c`` to account for the modifications of the code object.
|
||||
|
||||
|
||||
This does not intend to be a guide or a comprehensive recipe on how to implement
|
||||
this but a rough outline of the changes this will make to the codebase.
|
||||
|
||||
The advantages of this implementation involve speed, consistency with the
|
||||
implementation of keyword-only parameters as in PEP 3102 and a simpler implementation
|
||||
of all the tools and modules that will be impacted by this change.
|
||||
|
||||
==============
|
||||
Rejected Ideas
|
||||
==============
|
||||
|
||||
----------
|
||||
Do Nothing
|
||||
----------
|
||||
|
||||
Always an option, just not adding it. It was considered
|
||||
though that the benefits of adding it is worth the complexity
|
||||
it adds to the language.
|
||||
|
||||
---------------------
|
||||
After marker proposal
|
||||
---------------------
|
||||
|
||||
A complaint against the proposal is the fact that the modifier of
|
||||
the signature impacts the "already passed" tokens.
|
||||
|
||||
This might make confusing to "human parsers" to read functions
|
||||
with many arguments. Example::
|
||||
|
||||
def really_bad_example_of_a_python_function(fist_long_argument, second_long_argument,
|
||||
third_long_argument, /):
|
||||
|
||||
It is not until you reach the end of the signature that the reader
|
||||
realized the ``/`` and therefore the fact that the arguments are
|
||||
position-only. This deviates from how the keyword-only marker works.
|
||||
|
||||
That said we could not find an implementation that would modify the
|
||||
arguments after the marker, as that will force the one before the
|
||||
marker to be position only as well. Example::
|
||||
|
||||
def (x, y, /, z):
|
||||
|
||||
If we define that ``/`` makes only z position-only it won't be possible
|
||||
to call x and y via keyword argument. Finding a way to work around it
|
||||
will add confusion given that at the moment keyword arguments cannot be
|
||||
followed by positional arguments. ``/`` will therefore make both the
|
||||
preceding and following position-only.
|
||||
|
||||
-------------------
|
||||
Per-argument marker
|
||||
-------------------
|
||||
|
||||
Using a per argument marker might be an option as well. The approach
|
||||
basically adds a token to each of the arguments that are position only
|
||||
and requires those to be placed together. Example::
|
||||
|
||||
def (.arg1, .arg2, arg3):
|
||||
|
||||
Note the dot on arg1 and arg2. Even if this approach might look easier
|
||||
to read it has been discarded as ``/`` goes further inline with the
|
||||
keyword-only approach and is less error prone.
|
||||
|
||||
|
||||
----------------
|
||||
Using decorators
|
||||
----------------
|
||||
|
||||
It has been suggested on python-ideas [#python-ideas-decorator-based]_ to provide
|
||||
a decorator written in Python as an implementation for this feature. This approach
|
||||
has the advantage that keeps parameter declaration more easy to read but also
|
||||
introduces an asymmetry on how parameter behaviour is declared. Also, as the ``/``
|
||||
syntax is already introduced for C functions, this inconsistency will make more
|
||||
difficult to implement all tools and modules that deal with this syntax including
|
||||
but not limited to, the argument clinic, the inspect module and the ast module.
|
||||
Another disadvantage of this approach is that calling the decorated functions
|
||||
will be slower than the functions generated if the feature was implemented directly
|
||||
in C.
|
||||
|
||||
======
|
||||
Thanks
|
||||
======
|
||||
|
||||
Credit for most 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 positional-or-keyword
|
||||
parameters go to Guido van Rossum, in a proposal from 2012. [#GUIDO]_
|
||||
|
||||
Credit for discussion about the simplification of the grammar goes to
|
||||
Braulio Valdivieso.
|
||||
|
||||
.. [#DICT]
|
||||
http://docs.python.org/3/library/stdtypes.html#dict
|
||||
|
||||
.. [#RANGE]
|
||||
http://docs.python.org/3/library/functions.html#func-range
|
||||
|
||||
.. [#BORDER]
|
||||
http://docs.python.org/3/library/curses.html#curses.window.border
|
||||
|
||||
.. [#SENDFILE]
|
||||
http://docs.python.org/3/library/os.html#os.sendfile
|
||||
|
||||
.. [#ADDCH]
|
||||
http://docs.python.org/3/library/curses.html#curses.window.addch
|
||||
|
||||
.. [#GUIDO]
|
||||
Guido van Rossum, posting to python-ideas, March 2012:
|
||||
https://mail.python.org/pipermail/python-ideas/2012-March/014364.html
|
||||
and
|
||||
https://mail.python.org/pipermail/python-ideas/2012-March/014378.html
|
||||
and
|
||||
https://mail.python.org/pipermail/python-ideas/2012-March/014417.html
|
||||
|
||||
.. [#PEP306]
|
||||
https://www.python.org/dev/peps/pep-0306/
|
||||
|
||||
.. [#python-ideas-decorator-based]
|
||||
https://mail.python.org/pipermail/python-ideas/2017-February/044888.html
|
||||
|
||||
=========
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
Loading…
Reference in New Issue