From 3f4938f0ba33fbfe15338342968fe310e293bf15 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Tue, 5 Mar 2019 21:59:06 +0000 Subject: [PATCH] Add some clarifications to the PEP and implementation link (GH-907) --- pep-0570.rst | 66 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 27 deletions(-) diff --git a/pep-0570.rst b/pep-0570.rst index ddfaa674e..021605773 100644 --- a/pep-0570.rst +++ b/pep-0570.rst @@ -37,15 +37,32 @@ 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. +Users might want to restrict their API to not allow for parameters +to be referenced via keyword, as that exposes the name of the +parameter as part of the API. If a user of said API starts using the +argument by keyword when calling it and then the name of the parameter +is changed, it will be a breaking change. By using positional-only +parameters the developer can later change the name of an argument or +transform them to ``*args`` without breaking the API. + 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. +accepting a specific number of positional-only parameters. Also, +it makes the signature of the function ambiguous as users won't +know how many parameters the function takes by looking at help() +or auto-generated documentation. + 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. +syntax for it. The '/' syntax is already exposed in the +documentation for some builtins and interfaces generated by +the argument clinic. Making positional only arguments a possibility +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. ----------------------------------------------------- Positional-Only Parameter Semantics In Current Python @@ -87,7 +104,8 @@ 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. +not to mention the work of implementing said argument parsing +and the lack of clarity that generates in the signature. ========== Motivation @@ -170,38 +188,29 @@ Full grammar specification A draft of the proposed grammar specification is:: new_typedargslist: - tfpdef (',' tfpdef)* ',' '/' [',' [typedargslist]] | typedargslist + tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [',' [typedargslist]] | typedargslist new_varargslist: - vfpdef (',' vfpdef)* ',' '/' [',' [varargslist]] | varargslist + vfpdef ['=' test] (',' vfpdef ['=' test])* ',' '/' [',' [varargslist]] | varargslist -It will be added to the actual typedargslist and varargslist -but for easier discussion is presented as new_typedargslist and new_varargslist +It will be added to the actual typedargslist and varargslist but for easier discussion is +presented as new_typedargslist and new_varargslist. Also, notice that using a construction +using two new rules (new_varargslist and new_varargslist) is not possible with the current +parser as the rule is not LL(1). This is the reason the rule needs to be include in the +existing typedargslist and varargslist (in the same way keyword-only arguments were introduced). -=================== -Implementation Plan -=================== +============== +Implementation +============== -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. +An initial implementation that passes the CPython test suite is available +for evaluation [#posonly-impl]_. 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. +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 @@ -315,6 +324,9 @@ Braulio Valdivieso. .. [#python-ideas-decorator-based] https://mail.python.org/pipermail/python-ideas/2017-February/044888.html +.. [#posonly-impl] + https://github.com/pablogsal/cpython_positional_only + ========= Copyright =========