[Python-checkins] peps: Update for 436, explicitly supporting positional parameters forever, amen.
larry.hastings
python-checkins at python.org
Mon Mar 18 09:47:38 CET 2013
http://hg.python.org/peps/rev/890e9a9afc1e
changeset: 4805:890e9a9afc1e
user: Larry Hastings <larry at hastings.org>
date: Mon Mar 18 01:47:29 2013 -0700
summary:
Update for 436, explicitly supporting positional parameters forever, amen.
files:
pep-0436.txt | 87 +++++++++++++++++++++++++++++++--------
1 files changed, 68 insertions(+), 19 deletions(-)
diff --git a/pep-0436.txt b/pep-0436.txt
--- a/pep-0436.txt
+++ b/pep-0436.txt
@@ -190,7 +190,7 @@
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 @@
curses.window.addch
[
+ y: int
+ Y-coordinate.
+
x: int
X-coordinate.
-
- y: int
- Y-coordinate.
]
ch: char
@@ -240,6 +240,8 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
.. [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 @@
.. [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/
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list