[Python-checkins] peps: PEP 436: fix markup and make it consistent.
georg.brandl
python-checkins at python.org
Tue Oct 8 16:09:27 CEST 2013
http://hg.python.org/peps/rev/9b157de338b8
changeset: 5180:9b157de338b8
user: gbrandl
date: Tue Oct 08 16:09:05 2013 +0200
summary:
PEP 436: fix markup and make it consistent.
files:
pep-0436.txt | 356 ++++++++++++++++++--------------------
1 files changed, 170 insertions(+), 186 deletions(-)
diff --git a/pep-0436.txt b/pep-0436.txt
--- a/pep-0436.txt
+++ b/pep-0436.txt
@@ -49,62 +49,62 @@
in numerous ways. The modern API is complex, to the point that it
is somewhat painful to use. Consider:
- * There are now forty different "format units"; a few are even three
- characters long. This makes it difficult for the programmer to
- understand what the format string says--or even perhaps to parse
- it--without constantly cross-indexing it with the documentation.
- * There are also six meta-format units that may be buried in the
- format string. (They are: ``"()|$:;"``.)
- * The more format units are added, the less likely it is the
- implementer can pick an easy-to-use mnemonic for the format unit,
- because the character of choice is probably already in use. In
- other words, the more format units we have, the more obtuse the
- 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 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 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]_
+* There are now forty different "format units"; a few are even three
+ characters long. This makes it difficult for the programmer to
+ understand what the format string says--or even perhaps to parse
+ it--without constantly cross-indexing it with the documentation.
+* There are also six meta-format units that may be buried in the
+ format string. (They are: ``"()|$:;"``.)
+* The more format units are added, the less likely it is the
+ implementer can pick an easy-to-use mnemonic for the format unit,
+ because the character of choice is probably already in use. In
+ other words, the more format units we have, the more obtuse the
+ 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 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 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]_
- * Declaring the variable to store the argument.
- * Passing in a pointer to that variable in the correct spot in
- ``PyArg_ParseTupleAndKeywords()``, also passing in any
- "length" or "converter" arguments in the correct order.
- * Adding the name of the argument in the correct spot of the
- "keywords" array passed in to
- ``PyArg_ParseTupleAndKeywords()``.
- * Adding the format unit to the correct spot in the format
- string.
- * Adding the parameter to the prototype in the docstring.
- * Documenting the parameter in the docstring.
+ * Declaring the variable to store the argument.
+ * Passing in a pointer to that variable in the correct spot in
+ ``PyArg_ParseTupleAndKeywords()``, also passing in any
+ "length" or "converter" arguments in the correct order.
+ * Adding the name of the argument in the correct spot of the
+ "keywords" array passed in to
+ ``PyArg_ParseTupleAndKeywords()``.
+ * Adding the format unit to the correct spot in the format
+ string.
+ * Adding the parameter to the prototype in the docstring.
+ * Documenting the parameter in the docstring.
- * There is currently no mechanism for builtin functions to provide
- their "signature" information (see ``inspect.getfullargspec`` and
- ``inspect.Signature``). Adding this information using a mechanism
- similar to the existing ``PyArg_Parse`` functions would require
- repeating ourselves yet again.
+* There is currently no mechanism for builtin functions to provide
+ their "signature" information (see ``inspect.getfullargspec`` and
+ ``inspect.Signature``). Adding this information using a mechanism
+ similar to the existing ``PyArg_Parse`` functions would require
+ repeating ourselves yet again.
The goal of Argument Clinic is to replace this API with a mechanism
inheriting none of these downsides:
- * You need specify each parameter only once.
- * All information about a parameter is kept together in one place.
- * For each parameter, you specify a conversion function; Argument
- 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.
- * 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,
- repetitious code and data structures CPython needs internally.
- Once you've specified the interface, the next step is simply to
- write your implementation using native C types. Every detail of
- argument parsing is handled for you.
+* You need specify each parameter only once.
+* All information about a parameter is kept together in one place.
+* For each parameter, you specify a conversion function; Argument
+ 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.
+* 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,
+ repetitious code and data structures CPython needs internally.
+ Once you've specified the interface, the next step is simply to
+ write your implementation using native C types. Every detail of
+ argument parsing is handled for you.
Argument Clinic is implemented as a preprocessor. It draws inspiration
for its workflow directly from [Cog]_ by Ned Batchelder. To use Clinic,
@@ -121,11 +121,11 @@
Future goals of Argument Clinic include:
- * 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.
+* 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
@@ -141,117 +141,115 @@
::
- +-----------------------+-----------------------------------------------------------------+
- | Section | Example |
- +-----------------------+-----------------------------------------------------------------+
- | Clinic DSL start | /*[clinic] |
- | Module declaration | module module_name |
- | Class declaration | class module_name.class_name |
- | Function declaration | module_name.function_name -> return_annotation |
- | Parameter declaration | name : converter(param=value) |
- | Parameter docstring | Lorem ipsum dolor sit amet, consectetur |
- | | adipisicing elit, sed do eiusmod tempor |
- | Function docstring | Lorem ipsum dolor sit amet, consectetur adipisicing |
- | | elit, sed do eiusmod tempor incididunt ut labore et |
- | Clinic DSL end | [clinic]*/ |
- | Clinic output | ... |
- | Clinic output end | /*[clinic end output:<checksum>]*/ |
- +-----------------------+-----------------------------------------------------------------+
+ +-----------------------+-----------------------------------------------------------------+
+ | Section | Example |
+ +-----------------------+-----------------------------------------------------------------+
+ | Clinic DSL start | /*[clinic] |
+ | Module declaration | module module_name |
+ | Class declaration | class module_name.class_name |
+ | Function declaration | module_name.function_name -> return_annotation |
+ | Parameter declaration | name : converter(param=value) |
+ | Parameter docstring | Lorem ipsum dolor sit amet, consectetur |
+ | | adipisicing elit, sed do eiusmod tempor |
+ | Function docstring | Lorem ipsum dolor sit amet, consectetur adipisicing |
+ | | elit, sed do eiusmod tempor incididunt ut labore et |
+ | Clinic DSL end | [clinic]*/ |
+ | Clinic output | ... |
+ | Clinic output end | /*[clinic end output:<checksum>]*/ |
+ +-----------------------+-----------------------------------------------------------------+
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
+locally::
-::
+ /*[clinic]
+ os.stat as os_stat_fn -> stat result
- /*[clinic]
- os.stat as os_stat_fn -> stat result
+ path: path_t(allow_fd=1)
+ Path to be examined; can be string, bytes, or open-file-descriptor int.
- path: path_t(allow_fd=1)
- Path to be examined; can be string, bytes, or open-file-descriptor int.
+ *
- *
+ dir_fd: OS_STAT_DIR_FD_CONVERTER = DEFAULT_DIR_FD
+ If not None, it should be a file descriptor open to a directory,
+ and path should be a relative string; path will then be relative to
+ that directory.
- dir_fd: OS_STAT_DIR_FD_CONVERTER = DEFAULT_DIR_FD
- If not None, it should be a file descriptor open to a directory,
- and path should be a relative string; path will then be relative to
- that directory.
+ follow_symlinks: bool = True
+ If False, and the last element of the path is a symbolic link,
+ stat will examine the symbolic link itself instead of the file
+ the link points to.
- follow_symlinks: bool = True
- If False, and the last element of the path is a symbolic link,
- stat will examine the symbolic link itself instead of the file
- the link points to.
+ Perform a stat system call on the given path.
- Perform a stat system call on the given path.
+ {parameters}
- {parameters}
+ dir_fd and follow_symlinks may not be implemented
+ on your platform. If they are unavailable, using them will raise a
+ NotImplementedError.
- dir_fd and follow_symlinks may not be implemented
- on your platform. If they are unavailable, using them will raise a
- NotImplementedError.
+ It's an error to use dir_fd or follow_symlinks when specifying path as
+ an open file descriptor.
- 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::
- /*[clinic]
- os.access
- path: path
- mode: int
- *
- dir_fd: OS_ACCESS_DIR_FD_CONVERTER = 1
- effective_ids: bool = False
- follow_symlinks: bool = True
- Use the real uid/gid to test for access to a path.
- Returns True if granted, False otherwise.
+ /*[clinic]
+ os.access
+ path: path
+ mode: int
+ *
+ dir_fd: OS_ACCESS_DIR_FD_CONVERTER = 1
+ effective_ids: bool = False
+ follow_symlinks: bool = True
+ Use the real uid/gid to test for access to a path.
+ Returns True if granted, False otherwise.
- {parameters}
+ {parameters}
- dir_fd, effective_ids, and follow_symlinks may not be implemented
- on your platform. If they are unavailable, using them will raise a
- NotImplementedError.
+ dir_fd, effective_ids, and follow_symlinks may not be implemented
+ on your platform. If they are unavailable, using them will raise a
+ NotImplementedError.
- Note that most operations will use the effective uid/gid, therefore this
- routine can be used in a suid/sgid environment to test if the invoking user
- has the specified access to the path.
+ Note that most operations will use the effective uid/gid, therefore this
+ routine can be used in a suid/sgid environment to test if the invoking user
+ has the specified access to the path.
- [clinic]*/
+ [clinic]*/
This final example shows a Clinic code block handling groups of
optional parameters, including parameters on the left::
- /*[clinic]
- curses.window.addch
+ /*[clinic]
+ curses.window.addch
- [
- y: int
- Y-coordinate.
+ [
+ y: int
+ Y-coordinate.
- x: int
- X-coordinate.
- ]
+ x: int
+ X-coordinate.
+ ]
- ch: char
- Character to add.
+ ch: char
+ Character to add.
- [
- attr: long
- Attributes for the character.
- ]
+ [
+ attr: long
+ 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
- current settings for the window object.
- [clinic]*/
+ 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
+ current settings for the window object.
+ [clinic]*/
General Behavior Of the Argument Clinic DSL
@@ -275,17 +273,13 @@
-----------------------------
When a C file implements a module or class, this should be declared to
-Clinic. The syntax is simple:
+Clinic. The syntax is simple::
-::
+ module module_name
- module module_name
+or ::
-or
-
-::
-
- class module_name.class_name
+ class module_name.class_name
(Note that these are not actually special syntax; they are implemented
as `Directives`_.)
@@ -297,11 +291,9 @@
Function Declaration
--------------------
-The full form of the function declaration is as follows:
+The full form of the function declaration is as follows::
-::
-
- dotted.name [ as legal_c_id ] [ -> return_annotation ]
+ dotted.name [ as legal_c_id ] [ -> return_annotation ]
The dotted name should be the full name of the function, starting
with the highest-level package (e.g. "os.stat" or "curses.window.addch").
@@ -323,11 +315,9 @@
Parameter Declaration
---------------------
-The full form of the parameter declaration line as as follows:
+The full form of the parameter declaration line as as follows::
-::
-
- name: converter [ (parameter=value [, parameter2=value2]) ] [ = default]
+ name: converter [ (parameter=value [, parameter2=value2]) ] [ = default]
The "name" must be a legal C identifier. Whitespace is permitted between
the name and the colon (though this is not the preferred style). Whitespace
@@ -377,11 +367,9 @@
Clinic provides a set of legacy converters that match ``PyArg_ParseTuple``
format units. They are specified as a C string containing the format
unit. For example, to specify a parameter "foo" as taking a Python
-"int" and emitting a C int, you could specify:
+"int" and emitting a C int, you could specify::
-::
-
- foo : "i"
+ foo : "i"
(To more closely resemble a C string, these must always use double quotes.)
@@ -554,11 +542,9 @@
Directives are similar to *pragmas* in C; they are statements
that modify Argument Clinic's behavior.
-The format of a directive is as follows:
+The format of a directive is as follows::
-::
-
- directive_name [argument [second_argument [ ... ]]]
+ directive_name [argument [second_argument [ ... ]]]
Directives only take positional arguments.
@@ -566,7 +552,7 @@
or a function declaration. It may contain both, in which
case all directives must come before the function declaration.
-Internally directives map directly to Python callables.
+Internally directives map directly to Python callables.
The directive's arguments are passed directly to the callable
as positional arguments of type ``str()``.
@@ -581,18 +567,16 @@
Argument Clinic also permits embedding Python code inside C files,
which is executed in-place when Argument Clinic processes the file.
-Embedded code looks like this:
+Embedded code looks like this::
-::
+ /*[python]
- /*[python]
+ # this is python code!
+ print("/" + "* Hello world! *" + "/")
- # this is python code!
- print("/" + "* Hello world! *" + "/")
-
- [python]*/
- /* Hello world! */
- /*[python end:da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
+ [python]*/
+ /* Hello world! */
+ /*[python end:da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
The ``"/* Hello world! */"`` line above was generated by running the Python
code in the preceding comment.
@@ -610,14 +594,14 @@
is everything printed using ``builtins.print``. For "clinic"
sections, the output is valid C code, including:
- * a ``#define`` providing the correct ``methoddef`` structure for the
- function
- * 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
- * the definition line of the "impl" function
- * and a comment indicating the end of output.
+* a ``#define`` providing the correct ``methoddef`` structure for the
+ function
+* 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
+* the definition line of the "impl" function
+* and a comment indicating the end of output.
The intention is that you write the body of your impl function immediately
after the output -- as in, you write a left-curly-brace immediately after
@@ -738,15 +722,15 @@
::
- /*[clinic]
- ... prototype and parameters (including parameter docstrings) go here
- [clinic]*/
- ... some output ...
- /*[clinic docstring start]*/
- ... hand-edited function docstring goes here <-- you edit this by hand!
- /*[clinic docstring end]*/
- ... more output
- /*[clinic output end]*/
+ /*[clinic]
+ ... prototype and parameters (including parameter docstrings) go here
+ [clinic]*/
+ ... some output ...
+ /*[clinic docstring start]*/
+ ... hand-edited function docstring goes here <-- you edit this by hand!
+ /*[clinic docstring end]*/
+ ... more output
+ /*[clinic output end]*/
I tried it this way and don't like it -- I think it's clumsy. I
prefer that everything you write goes in one place, rather than
@@ -756,7 +740,7 @@
* Argument Clinic does not support automatic tuple unpacking
(the "``(OOO)``" style format string for ``PyArg_ParseTuple()``.)
-* Argument Clinic removes some dynamism / flexibility. With
+* 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
@@ -773,7 +757,7 @@
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.
+deep dive on the topic at PyCon US 2013.
References
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list