Update for 436, explicitly supporting positional parameters forever, amen.
This commit is contained in:
Larry Hastings
parent
d247c96780
commit
18ff314c75
87
pep-0436.txt
87
pep-0436.txt
|
|
@ -190,7 +190,7 @@ blank lines between parameters and per-argument docstrings.
|
|||
It's an error to use dir_fd or follow_symlinks when specifying path as
|
||||
an open file descriptor.
|
||||
|
||||
[clinic]*/
|
||||
[clinic]*/
|
||||
|
||||
This second example shows a minimal Clinic code block, omitting all
|
||||
parameter docstrings and non-significant blank lines::
|
||||
|
|
@ -225,11 +225,11 @@ optional parameters, including parameters on the left::
|
|||
curses.window.addch
|
||||
|
||||
[
|
||||
x: int
|
||||
X-coordinate.
|
||||
|
||||
y: int
|
||||
Y-coordinate.
|
||||
|
||||
x: int
|
||||
X-coordinate.
|
||||
]
|
||||
|
||||
ch: char
|
||||
|
|
@ -240,6 +240,8 @@ optional parameters, including parameters on the left::
|
|||
Attributes for the character.
|
||||
]
|
||||
|
||||
/
|
||||
|
||||
Paint character ch at (y, x) with attributes attr,
|
||||
overwriting any character previously painter at that location.
|
||||
By default, the character position and attributes are the
|
||||
|
|
@ -405,17 +407,25 @@ declarations. The four symbols are:
|
|||
Establishes the start of an optional "group" of parameters.
|
||||
Note that "groups" may nest inside other "groups".
|
||||
See `Functions With Positional-Only Parameters`_ below.
|
||||
Note that currently ``[`` is only legal for use in functions
|
||||
where *all* parameters are marked positional-only, see
|
||||
``/`` below.
|
||||
|
||||
``]``
|
||||
Ends an optional "group" of parameters.
|
||||
|
||||
``/``
|
||||
This hints to Argument Clinic that this function is performance-sensitive,
|
||||
and that it's acceptable to forego supporting keyword parameters when parsing.
|
||||
(In early implementations of Clinic, this will switch Clinic from generating
|
||||
code using ``PyArg_ParseTupleAndKeywords`` to using ``PyArg_ParseTuple``.
|
||||
The hope is that in the future there will be no appreciable speed difference,
|
||||
rendering this syntax irrelevant and deprecated but harmless.)
|
||||
Establishes that all the *proceeding* arguments are
|
||||
positional-only. For now, Argument Clinic does not
|
||||
support functions with both positional-only and
|
||||
non-positional-only arguments; therefore, if ``/``
|
||||
is specified for a function, currently it must always
|
||||
be after the last parameter. Also, Argument Clinic
|
||||
does not currently support default values for
|
||||
positional-only parameters.
|
||||
|
||||
(The semantics of ``/`` follow a syntax for positional-only
|
||||
parameters in Python once proposed by Guido. [5]_ )
|
||||
|
||||
|
||||
Function Docstring
|
||||
|
|
@ -541,8 +551,8 @@ as positional arguments of type ``str()``.
|
|||
|
||||
Example possible directives include the production,
|
||||
suppression, or redirection of Clinic output. Also, the
|
||||
"module" and "class" keywords are actually implemented
|
||||
as directives.
|
||||
"module" and "class" keywords are implemented
|
||||
as directives in the prototype.
|
||||
|
||||
|
||||
Python Code
|
||||
|
|
@ -650,7 +660,7 @@ Current Status
|
|||
|
||||
As of this writing, there is a working prototype implementation of
|
||||
Argument Clinic available online (though the syntax may be out of date
|
||||
as you read this). [7]_ The prototype generates code using the
|
||||
as you read this). [6]_ The prototype generates code using the
|
||||
existing ``PyArg_Parse`` APIs. It supports translating to all current
|
||||
format units except the mysterious ``"w*"``. Sample functions using
|
||||
Argument Clinic exercise all major features, including positional-only
|
||||
|
|
@ -673,6 +683,32 @@ dynamically adding your own custom DSL!
|
|||
Notes / TBD
|
||||
===========
|
||||
|
||||
* The DSL currently makes no provision for specifying per-parameter
|
||||
type annotations. This is something explicitly supported in Python;
|
||||
it should be supported for builtins too, once we have reflection support.
|
||||
|
||||
It seems to me that the syntax for parameter lines--dictated by
|
||||
Guido--suggests conversion functions are themselves type annotations.
|
||||
This makes intuitive sense. But my thought experiments in how to
|
||||
convert the conversion function specification into a per-parameter
|
||||
type annotation ranged from obnoxious to toxic; I don't think that
|
||||
line of thinking will bear fruit.
|
||||
|
||||
Instead, I think wee need to add a new syntax allowing functions
|
||||
to explicitly specify a per-parameter type annotation. The problem:
|
||||
what should that syntax be? I've only had one idea so far, and I
|
||||
don't find it all that appealing: allow a optional second colon
|
||||
on the parameter line, and the type annotation would be specified...
|
||||
somewhere, either between the first and second colons, or between
|
||||
the second colon and the (optional) default.
|
||||
|
||||
Also, I don't think this could specify any arbitrary Python value.
|
||||
I suspect it would suffer heavy restrictions on what types and
|
||||
literals it could use. Perhaps the best solution would be to
|
||||
store the exact string in static data, and have Python evaluate
|
||||
it on demand? If so, it would be safest to restrict it to Python
|
||||
literal syntax, permitting no function calls (even to builtins).
|
||||
|
||||
* Optimally we'd want Argument Clinic run automatically as part of the
|
||||
normal Python build process. But this presents a bootstrapping problem;
|
||||
if you don't have a system Python 3, you need a Python 3 executable to
|
||||
|
|
@ -735,6 +771,16 @@ Notes / TBD
|
|||
socketmodule.c, except for one in _ssl.c. They're all static,
|
||||
specifying the encoding ``"idna"``.)
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
The PEP author wishes to thank Ned Batchelder for permission to
|
||||
shamelessly rip off his clever design for Cog--"my favorite tool
|
||||
that I've never gotten to use". Thanks also to everyone who provided
|
||||
feedback on the [bugtracker issue] and on python-dev. Special thanks
|
||||
to Nick Coglan and Guido van Rossum for a rousing two-hour in-person
|
||||
deep dive on the topic at PyCon US 2013.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
|
@ -742,6 +788,8 @@ References
|
|||
.. [Cog] ``Cog``:
|
||||
http://nedbatchelder.com/code/cog/
|
||||
|
||||
.. [bugtracker issue] Issue 16612 on the python.org bug tracker:
|
||||
http://bugs.python.org/issue16612
|
||||
|
||||
.. [1] ``PyArg_ParseTuple()``:
|
||||
http://docs.python.org/3/c-api/arg.html#PyArg_ParseTuple
|
||||
|
|
@ -755,13 +803,14 @@ References
|
|||
.. [4] Keyword parameters for extension functions:
|
||||
http://docs.python.org/3/extending/extending.html#keyword-parameters-for-extension-functions
|
||||
|
||||
.. [5] ``shlex.split()``:
|
||||
http://docs.python.org/3/library/shlex.html#shlex.split
|
||||
.. [5] Guido van Rossum, posting to python-ideas, March 2012:
|
||||
http://mail.python.org/pipermail/python-ideas/2012-March/014364.html
|
||||
and
|
||||
http://mail.python.org/pipermail/python-ideas/2012-March/014378.html
|
||||
and
|
||||
http://mail.python.org/pipermail/python-ideas/2012-March/014417.html
|
||||
|
||||
.. [6] ``PyArg_`` "converter" functions, see ``"O&"`` in this section:
|
||||
http://docs.python.org/3/c-api/arg.html#other-objects
|
||||
|
||||
.. [7] Argument Clinic prototype:
|
||||
.. [6] Argument Clinic prototype:
|
||||
https://bitbucket.org/larry/python-clinic/
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue