[Python-checkins] peps: Updated PEP 429 (3.4 release schedule) as 3.4.0a3 just went out.
larry.hastings
python-checkins at python.org
Mon Sep 30 02:15:37 CEST 2013
http://hg.python.org/peps/rev/67309f9622e7
changeset: 5155:67309f9622e7
user: Larry Hastings <larry at hastings.org>
date: Mon Sep 30 01:15:30 2013 +0100
summary:
Updated PEP 429 (3.4 release schedule) as 3.4.0a3 just went out.
files:
pep-0429.txt | 2 +-
pep-0436.txt | 116 ++++++++++++++++++--------------------
2 files changed, 56 insertions(+), 62 deletions(-)
diff --git a/pep-0429.txt b/pep-0429.txt
--- a/pep-0429.txt
+++ b/pep-0429.txt
@@ -38,10 +38,10 @@
- 3.4.0 alpha 1: August 3, 2013
- 3.4.0 alpha 2: September 9, 2013
+- 3.4.0 alpha 3: September 29, 2013
The anticipated schedule for future releases:
-- 3.4.0 alpha 3: September 29, 2013
- 3.4.0 alpha 4: October 20, 2013
- 3.4.0 beta 1: November 24, 2013
diff --git a/pep-0436.txt b/pep-0436.txt
--- a/pep-0436.txt
+++ b/pep-0436.txt
@@ -62,10 +62,10 @@
format units become.
* Several format units are nearly identical to others, having only
subtle differences. This makes understanding the exact semantics
- of the format string even harder, and can make choosing the right
- format unit a conundrum.
+ of the format string even harder, and can make it difficult to
+ figure out exactly which format unit you want.
* The docstring is specified as a static C string, making it mildly
- bothersome to read and edit.
+ bothersome to read and edit since it must obey C string quoting rules.
* When adding a new parameter to a function using
``PyArg_ParseTupleAndKeywords()``, it's necessary to touch six
different places in the code: [4]_
@@ -97,7 +97,7 @@
Clinic handles the translation from Python value into C value for
you.
* Argument Clinic also allows for fine-tuning of argument processing
- behavior with parameterized conversion functions..
+ behavior with parameterized conversion functions.
* Docstrings are written in plain text. Function docstrings are
required; per-parameter docstrings are encouraged.
* From this, Argument Clinic generates for you all the mundane,
@@ -121,8 +121,11 @@
Future goals of Argument Clinic include:
- * providing signature information for builtins, and
- * speed improvements to the generated code.
+ * providing signature information for builtins,
+ * enabling alternative implementations of Python to create
+ automated library compatibility tests, and
+ * speeding up argument parsing with improvements to the
+ generated code.
DSL Syntax Summary
@@ -158,6 +161,8 @@
To give some flavor of the proposed DSL syntax, here are some sample Clinic
code blocks. This first block reflects the normally preferred style, including
blank lines between parameters and per-argument docstrings.
+It also includes a user-defined converter (``path_t``) created
+locally
::
@@ -310,7 +315,9 @@
If skipped, the "as" keyword must also be omitted.
The return annotation is also optional. If skipped, the arrow ("``->``")
-must also be omitted.
+must also be omitted. If specified, the value for the return annotation
+must be compatible with ``ast.literal_eval``, and it is interpreted as
+a *return converter*.
Parameter Declaration
@@ -341,7 +348,8 @@
syntactically resemble Python literal values. These parameters are always
optional, permitting all conversion functions to be called without
any parameters. In this case, you may also omit the parentheses entirely;
-this is always equivalent to specifying empty parentheses.
+this is always equivalent to specifying empty parentheses. The values
+supplied for these parameters must be compatible with ``ast.literal_eval``.
The "default" is a Python literal value. Default values are optional;
if not specified you must omit the equals sign too. Parameters which
@@ -418,9 +426,9 @@
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
+ non-positional-only arguments. Therefore: if ``/``
+ is specified for a function, it must currently always
+ be after the *last* parameter. Also, Argument Clinic
does not currently support default values for
positional-only parameters.
@@ -470,7 +478,7 @@
All converters accept the following parameters:
-``default``
+``doc_default``
The Python value to use in place of the parameter's actual default
in Python contexts. In other words: when specified, this value will
be used for the parameter's default in the docstring, and in the
@@ -489,6 +497,11 @@
Additionally, converters may accept one or more of these optional
parameters, on an individual basis:
+``annotation``
+ Explicitly specifies the per-parameter annotation for this
+ parameter. Normally it's the responsibility of the conversion
+ function to generate the annotation (if any).
+
``bitwise``
For converters that accept unsigned integers. If the Python integer
passed in is signed, copy the bits directly even if it is negative.
@@ -526,6 +539,14 @@
be allowed to have embedded zeroes.
+Return Converters
+-----------------
+
+A *return converter* conceptually performs the inverse operation of
+a converter: it converts a native C value into its equivalent Python
+value.
+
+
Directives
----------
@@ -594,7 +615,7 @@
* a prototype for the "impl" function -- this is what you'll write
to implement this function
* a function that handles all argument processing, which calls your
- "impl" function
+ "impl" function
* the definition line of the "impl" function
* and a comment indicating the end of output.
@@ -683,31 +704,14 @@
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.
+* The API for supplying inspect.Signature metadata for builtins is
+ currently under discussion. Argument Clinic will add support for
+ the prototype when it becomes viable.
- 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).
+* Nick Coghlan suggests that we a) only support at most one left-optional
+ group per function, and b) in the face of ambiguity, prefer the left
+ group over the right group. This would solve all our existing use cases
+ including range().
* Optimally we'd want Argument Clinic run automatically as part of the
normal Python build process. But this presents a bootstrapping problem;
@@ -716,20 +720,10 @@
what the best solution might be. (Supporting this will also require
a parallel solution for Windows.)
-* The original Clinic DSL syntax allowed naming the "groups" for
- positional-only argument parsing. The current one does not;
- they will therefore get computer-generated names (probably
- left_1, right_2, etc.). Do we care about allowing the user
- to explicitly specify names for the groups? The thing is, there's
- no good place to put it. Only one syntax suggests itself to me,
- and it's a syntax only a mother could love:
-
- ::
-
- [ group_name
- name: converter
- name2: converter2
- ]
+* On a related note: inspect.Signature has no way of representing
+ blocks of arguments, like the left-optional block of ``y`` and ``x``
+ for ``curses.window.addch``. How far are we going to go in supporting
+ this admittedly aberrant parameter paradigm?
* During the PyCon US 2013 Language Summit, there was discussion of having
Argument Clinic also generate the actual documentation (in ReST, processed
@@ -759,17 +753,17 @@
having an island of hand-edited stuff in the middle of the DSL
output.
-* Do we need to support tuple unpacking? (The "``(OOO)``" style
- format string.) Boy I sure hope not.
+* Argument Clinic does not support automatic tuple unpacking
+ (the "``(OOO)``" style format string for ``PyArg_ParseTuple()``.)
-* This approach removes some dynamism / flexibility. With the
- existing syntax one could theoretically pass in different encodings
- at runtime for the "``es``"/"``et``" format units. AFAICT CPython
- doesn't do this itself, however it's possible external users might
- do this. (Trivia: there are no uses of "``es``" exercised by
- regrtest, and all the uses of "``et``" exercised are in
- socketmodule.c, except for one in _ssl.c. They're all static,
- specifying the encoding ``"idna"``.)
+* Argument Clinic removes some dynamism / flexibility. With
+ ``PyArg_ParseTuple()`` one could theoretically pass in different
+ encodings at runtime for the "``es``"/"``et``" format units.
+ AFAICT CPython doesn't do this itself, however it's possible
+ external users might do this. (Trivia: there are no uses of
+ "``es``" exercised by regrtest, and all the uses of "``et``"
+ exercised are in socketmodule.c, except for one in _ssl.c.
+ They're all static, specifying the encoding ``"idna"``.)
Acknowledgements
================
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list