Add further rationale and related work (#921)

Add further content as suggested by Victor Stinner in an offline
conversation.
This commit is contained in:
Mario Corchero 2019-03-11 11:13:46 -04:00 committed by Guido van Rossum
parent fb41c35fcb
commit bbdcedb71b
1 changed files with 67 additions and 0 deletions

View File

@ -64,6 +64,31 @@ in Python will bring consistency and will remove confusion from
users that are not familiarized with the fact that positional only
arguments are allowed in builtins and argument clinic C interfaces.
We find this useful in multiple situation, say for example we
are looking at creating a function that converts from one type to
another::
def as_my_type(x):
...
The name of the parameter provides no value whatsoever and forces
the user to maintain it's name forever as user might rely on it
being used as a keyword only.
Another good example is APIs that want to transmit the feeling
of ownership through positional arguments, see::
class MyDecorator:
def __init__(self, original_function):
...
Again we get no value from using keyword arguments here and it can limit
future evolutions of the API. Say at a later time we want the decorator
to be able to take multiple functions, we will be forced to keep
the original argument always or we'd potentially break users.
By being able to define positional only arguments we can change the
name of those at will or even change them by ``*args``.
-----------------------------------------------------
Positional-Only Parameter Semantics In Current Python
-----------------------------------------------------
@ -120,6 +145,37 @@ 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.
Providing positional only arguments will allow for maintaining the
interface when creating pure Python implementation of C modules, which
provides not only the API benefits outlined in this document but it is
also faster, see this thread about converting keyword arguments to positional
[#thread-keyword-to-positional]_ and PEP-399 [#PEP399]_, which requires the
same API for C accelerators than the Python implementation.
There has been multiple changes in builtin functions that moved away
from keyword arguments, like ``bool``, ``float``, ``list``, ``int``, ``tuple``
which is a non-backward compatible. By having proper support for
positional only arguments, this kind of APIs where it is clear that
passing a keyword argument provides no clarity would be able to
follow a similar approach that those builtins without breaking users.
This is a well discussed recurring topic in the Python mailing lists:
* September 2018: `Anders Hovmöller: [Python-ideas] Positional-only
parameters
<https://mail.python.org/pipermail/python-ideas/2018-September/053233.html>`_
* February 2017: `Victor Stinner: [Python-ideas] Positional-only
parameters
<https://mail.python.org/pipermail/python-ideas/2017-February/044879.html>`_,
`discussion continued in March
<https://mail.python.org/pipermail/python-ideas/2017-March/044956.html>`_
* February 2017: [#python-ideas-decorator-based]_
* March 2012: [#GUIDO]_
* May 2007: `George Sakkis: [Python-ideas] Positional only arguments
<https://mail.python.org/pipermail/python-ideas/2007-May/000704.html>`_
* May 2006: `Benji York: [Python-Dev] Positional-only Arguments
<https://mail.python.org/pipermail/python-dev/2006-May/064790.html>`_
=================================================================
The Current State Of Documentation For Positional-Only Parameters
=================================================================
@ -267,6 +323,8 @@ 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.
There are some libraries that use leading underscore[#leading-underscore]_
to mark those arguments as positional only.
----------------
Using decorators
@ -321,12 +379,21 @@ Braulio Valdivieso.
.. [#PEP306]
https://www.python.org/dev/peps/pep-0306/
.. [#PEP399]
https://www.python.org/dev/peps/pep-0399/
.. [#python-ideas-decorator-based]
https://mail.python.org/pipermail/python-ideas/2017-February/044888.html
.. [#posonly-impl]
https://github.com/pablogsal/cpython_positional_only
.. [#thread-keyword-to-positional]
https://mail.python.org/pipermail/python-ideas/2016-January/037874.html
.. [#leading-underscore]
https://mail.python.org/pipermail/python-ideas/2018-September/053319.html
=========
Copyright
=========