From 18ff314c751bf369e421448afeb2eacba9ba7681 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Mon, 18 Mar 2013 01:47:29 -0700 Subject: [PATCH] Update for 436, explicitly supporting positional parameters forever, amen. --- pep-0436.txt | 87 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 68 insertions(+), 19 deletions(-) diff --git a/pep-0436.txt b/pep-0436.txt index da2015427..98c8272a9 100644 --- a/pep-0436.txt +++ b/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/