Updated PEP 429 (3.4 release schedule) as 3.4.0a3 just went out.
This commit is contained in:
Larry Hastings
parent
6482692ff6
commit
2bbbeeb805
|
|
@ -38,10 +38,10 @@ The releases so far:
|
|||
|
||||
- 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
|
||||
|
||||
|
|
|
|||
116
pep-0436.txt
116
pep-0436.txt
|
|
@ -62,10 +62,10 @@ is somewhat painful to use. Consider:
|
|||
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 @@ inheriting none of these downsides:
|
|||
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 @@ interpreter.
|
|||
|
||||
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 @@ statement, lending it some familiarity to Python core developers.
|
|||
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 @@ with your own; substitute "legal_c_id" with any legal C identifier.
|
|||
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 @@ a Python function call: the parameter must always be named, as if they were
|
|||
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 @@ declarations. The four symbols are:
|
|||
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 @@ Example converter functions:
|
|||
|
||||
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 @@ All converters accept the following parameters:
|
|||
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 @@ parameters, on an individual basis:
|
|||
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 @@ sections, the output is valid C code, including:
|
|||
* 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 @@ 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.
|
||||
* 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 @@ Notes / TBD
|
|||
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 @@ Notes / TBD
|
|||
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
|
||||
================
|
||||
|
|
|
|||
Loading…
Reference in New Issue