Update for 436, explicitly supporting positional parameters forever, amen.

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,
+    Establishes that all the *proceeding* arguments are
-    and that it's acceptable to forego supporting keyword parameters when parsing.
+    positional-only.  For now, Argument Clinic does not
-    (In early implementations of Clinic, this will switch Clinic from generating
+    support functions with both positional-only and
-    code using ``PyArg_ParseTupleAndKeywords`` to using ``PyArg_ParseTuple``.
+    non-positional-only arguments; therefore, if ``/``
-    The hope is that in the future there will be no appreciable speed difference,
+    is specified for a function, currently it must always
-    rendering this syntax irrelevant and deprecated but harmless.)
+    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
+"module" and "class" keywords are implemented
-as directives.
+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()``:
+.. [5] Guido van Rossum, posting to python-ideas, March 2012:
-   http://docs.python.org/3/library/shlex.html#shlex.split
+   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:
+.. [6] Argument Clinic prototype:
-   http://docs.python.org/3/c-api/arg.html#other-objects
-
-.. [7] Argument Clinic prototype:
    https://bitbucket.org/larry/python-clinic/