Reformat file prior to editing.

Doc/c-api/arg.rst

@@ -10,46 +10,48 @@ methods.  Additional information and examples are available in
 :ref:`extending-index`.
 
 The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format
+:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use
-strings* which are used to tell the function about the expected arguments.  The
+*format strings* which are used to tell the function about the expected
-format strings use the same syntax for each of these functions.
+arguments.  The format strings use the same syntax for each of these
+functions.
 
 A format string consists of zero or more "format units."  A format unit
-describes one Python object; it is usually a single character or a parenthesized
+describes one Python object; it is usually a single character or a
-sequence of format units.  With a few exceptions, a format unit that is not a
+parenthesized sequence of format units.  With a few exceptions, a format unit
-parenthesized sequence normally corresponds to a single address argument to
+that is not a parenthesized sequence normally corresponds to a single address
-these functions.  In the following description, the quoted form is the format
+argument to these functions.  In the following description, the quoted form is
-unit; the entry in (round) parentheses is the Python object type that matches
+the format unit; the entry in (round) parentheses is the Python object type
-the format unit; and the entry in [square] brackets is the type of the C
+that matches the format unit; and the entry in [square] brackets is the type
-variable(s) whose address should be passed.
+of the C variable(s) whose address should be passed.
 
 ``s`` (string or Unicode object) [const char \*]
-   Convert a Python string or Unicode object to a C pointer to a character string.
+   Convert a Python string or Unicode object to a C pointer to a character
-   You must not provide storage for the string itself; a pointer to an existing
+   string.  You must not provide storage for the string itself; a pointer to
-   string is stored into the character pointer variable whose address you pass.
+   an existing string is stored into the character pointer variable whose
-   The C string is NUL-terminated.  The Python string must not contain embedded NUL
+   address you pass.  The C string is NUL-terminated.  The Python string must
-   bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are
+   not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is
-   converted to C strings using the default encoding.  If this conversion fails, a
+   raised. Unicode objects are converted to C strings using the default
-   :exc:`UnicodeError` is raised.
+   encoding.  If this conversion fails, a :exc:`UnicodeError` is raised.
 
 ``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
-   This variant on ``s`` stores into two C variables, the first one a pointer to a
+   This variant on ``s`` stores into two C variables, the first one a pointer
-   character string, the second one its length.  In this case the Python string may
+   to a character string, the second one its length.  In this case the Python
-   contain embedded null bytes.  Unicode objects pass back a pointer to the default
+   string may contain embedded null bytes.  Unicode objects pass back a
-   encoded string version of the object if such a conversion is possible.  All
+   pointer to the default encoded string version of the object if such a
-   other read-buffer compatible objects pass back a reference to the raw internal
+   conversion is possible.  All other read-buffer compatible objects pass back
-   data representation.
+   a reference to the raw internal data representation.
 
-   Starting with Python 2.5 the type of the length argument can be
+   Starting with Python 2.5 the type of the length argument can be controlled
-   controlled by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before
+   by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
-   including :file:`Python.h`.  If the macro is defined, length is a
+   :file:`Python.h`.  If the macro is defined, length is a :ctype:`Py_ssize_t`
-   :ctype:`Py_ssize_t` rather than an int.
+   rather than an int.
 
 ``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
-   Similar to ``s#``, this code fills a Py_buffer structure provided by the caller.
+   Similar to ``s#``, this code fills a Py_buffer structure provided by the
-   The buffer gets locked, so that the caller can subsequently use the buffer even
+   caller.  The buffer gets locked, so that the caller can subsequently use
-   inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is responsible for calling
+   the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
-   ``PyBuffer_Release`` with the structure after it has processed the data.
+   responsible for calling ``PyBuffer_Release`` with the structure after it
+   has processed the data.
 
    .. versionadded:: 2.6
 
@@ -66,83 +68,86 @@ variable(s) whose address should be passed.
    .. versionadded:: 2.6
 
 ``u`` (Unicode object) [Py_UNICODE \*]
-   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
+   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
-   16-bit Unicode (UTF-16) data.  As with ``s``, there is no need to provide
+   of 16-bit Unicode (UTF-16) data.  As with ``s``, there is no need to
-   storage for the Unicode data buffer; a pointer to the existing Unicode data is
+   provide storage for the Unicode data buffer; a pointer to the existing
-   stored into the :ctype:`Py_UNICODE` pointer variable whose address you pass.
+   Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose
+   address you pass.
 
 ``u#`` (Unicode object) [Py_UNICODE \*, int]
-   This variant on ``u`` stores into two C variables, the first one a pointer to a
+   This variant on ``u`` stores into two C variables, the first one a pointer
-   Unicode data buffer, the second one its length. Non-Unicode objects are handled
+   to a Unicode data buffer, the second one its length. Non-Unicode objects
-   by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE`
+   are handled by interpreting their read-buffer pointer as pointer to a
-   array.
+   :ctype:`Py_UNICODE` array.
 
 ``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   This variant on ``s`` is used for encoding Unicode and objects convertible to
+   This variant on ``s`` is used for encoding Unicode and objects convertible
-   Unicode into a character buffer. It only works for encoded data without embedded
+   to Unicode into a character buffer. It only works for encoded data without
-   NUL bytes.
+   embedded NUL bytes.
 
    This format requires two arguments.  The first is only used as input, and
-   must be a :ctype:`const char\*` which points to the name of an encoding as a
+   must be a :ctype:`const char\*` which points to the name of an encoding as
-   NUL-terminated string, or *NULL*, in which case the default encoding is used.
+   a NUL-terminated string, or *NULL*, in which case the default encoding is
-   An exception is raised if the named encoding is not known to Python.  The
+   used.  An exception is raised if the named encoding is not known to Python.
-   second argument must be a :ctype:`char\*\*`; the value of the pointer it
+   The second argument must be a :ctype:`char\*\*`; the value of the pointer
-   references will be set to a buffer with the contents of the argument text.
+   it references will be set to a buffer with the contents of the argument
-   The text will be encoded in the encoding specified by the first argument.
+   text.  The text will be encoded in the encoding specified by the first
+   argument.
 
-   :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
+   :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
-   encoded data into this buffer and adjust *\*buffer* to reference the newly
+   the encoded data into this buffer and adjust *\*buffer* to reference the
-   allocated storage.  The caller is responsible for calling :cfunc:`PyMem_Free` to
+   newly allocated storage.  The caller is responsible for calling
-   free the allocated buffer after use.
+   :cfunc:`PyMem_Free` to free the allocated buffer after use.
 
 ``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
    Same as ``es`` except that 8-bit string objects are passed through without
-   recoding them.  Instead, the implementation assumes that the string object uses
+   recoding them.  Instead, the implementation assumes that the string object
-   the encoding passed in as parameter.
+   uses the encoding passed in as parameter.
 
 ``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
-   This variant on ``s#`` is used for encoding Unicode and objects convertible to
+   This variant on ``s#`` is used for encoding Unicode and objects convertible
-   Unicode into a character buffer.  Unlike the ``es`` format, this variant allows
+   to Unicode into a character buffer.  Unlike the ``es`` format, this variant
-   input data which contains NUL characters.
+   allows input data which contains NUL characters.
 
-   It requires three arguments.  The first is only used as input, and must be a
+   It requires three arguments.  The first is only used as input, and must be
-   :ctype:`const char\*` which points to the name of an encoding as a
+   a :ctype:`const char\*` which points to the name of an encoding as a
-   NUL-terminated string, or *NULL*, in which case the default encoding is used.
+   NUL-terminated string, or *NULL*, in which case the default encoding is
-   An exception is raised if the named encoding is not known to Python.  The
+   used.  An exception is raised if the named encoding is not known to Python.
-   second argument must be a :ctype:`char\*\*`; the value of the pointer it
+   The second argument must be a :ctype:`char\*\*`; the value of the pointer
-   references will be set to a buffer with the contents of the argument text.
+   it references will be set to a buffer with the contents of the argument
-   The text will be encoded in the encoding specified by the first argument.
+   text.  The text will be encoded in the encoding specified by the first
-   The third argument must be a pointer to an integer; the referenced integer
+   argument.  The third argument must be a pointer to an integer; the
-   will be set to the number of bytes in the output buffer.
+   referenced integer will be set to the number of bytes in the output buffer.
 
    There are two modes of operation:
 
-   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
+   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
-   the needed size, copy the encoded data into this buffer and set *\*buffer* to
+   of the needed size, copy the encoded data into this buffer and set
-   reference the newly allocated storage.  The caller is responsible for calling
+   *\*buffer* to reference the newly allocated storage.  The caller is
-   :cfunc:`PyMem_Free` to free the allocated buffer after usage.
+   responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer
+   after usage.
 
    If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
-   :cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the
+   :cfunc:`PyArg_ParseTuple` will use this location as the buffer and
-   initial value of *\*buffer_length* as the buffer size.  It will then copy the
+   interpret the initial value of *\*buffer_length* as the buffer size.  It
-   encoded data into the buffer and NUL-terminate it.  If the buffer is not large
+   will then copy the encoded data into the buffer and NUL-terminate it.  If
-   enough, a :exc:`ValueError` will be set.
+   the buffer is not large enough, a :exc:`ValueError` will be set.
 
    In both cases, *\*buffer_length* is set to the length of the encoded data
    without the trailing NUL byte.
 
 ``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
-   Same as ``es#`` except that string objects are passed through without recoding
+   Same as ``es#`` except that string objects are passed through without
-   them. Instead, the implementation assumes that the string object uses the
+   recoding them. Instead, the implementation assumes that the string object
-   encoding passed in as parameter.
+   uses the encoding passed in as parameter.
 
 ``b`` (integer) [unsigned char]
    Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
    :ctype:`unsigned char`.
 
 ``B`` (integer) [unsigned char]
-   Convert a Python integer to a tiny int without overflow checking, stored in a C
+   Convert a Python integer to a tiny int without overflow checking, stored in
-   :ctype:`unsigned char`.
+   a C :ctype:`unsigned char`.
 
    .. versionadded:: 2.3
 
@@ -150,8 +155,8 @@ variable(s) whose address should be passed.
    Convert a Python integer to a C :ctype:`short int`.
 
 ``H`` (integer) [unsigned short int]
-   Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
+   Convert a Python integer to a C :ctype:`unsigned short int`, without
-   checking.
+   overflow checking.
 
    .. versionadded:: 2.3
 
@@ -168,20 +173,21 @@ variable(s) whose address should be passed.
    Convert a Python integer to a C :ctype:`long int`.
 
 ``k`` (integer) [unsigned long]
-   Convert a Python integer or long integer to a C :ctype:`unsigned long` without
+   Convert a Python integer or long integer to a C :ctype:`unsigned long`
-   overflow checking.
+   without overflow checking.
 
    .. versionadded:: 2.3
 
 ``L`` (integer) [PY_LONG_LONG]
    Convert a Python integer to a C :ctype:`long long`.  This format is only
-   available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
+   available on platforms that support :ctype:`long long` (or :ctype:`_int64`
-   Windows).
+   on Windows).
 
 ``K`` (integer) [unsigned PY_LONG_LONG]
    Convert a Python integer or long integer to a C :ctype:`unsigned long long`
    without overflow checking.  This format is only available on platforms that
-   support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
+   support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
+   Windows).
 
    .. versionadded:: 2.3
 
@@ -204,60 +210,61 @@ variable(s) whose address should be passed.
    Convert a Python complex number to a C :ctype:`Py_complex` structure.
 
 ``O`` (object) [PyObject \*]
-   Store a Python object (without any conversion) in a C object pointer.  The C
+   Store a Python object (without any conversion) in a C object pointer.  The
-   program thus receives the actual object that was passed.  The object's reference
+   C program thus receives the actual object that was passed.  The object's
-   count is not increased.  The pointer stored is not *NULL*.
+   reference count is not increased.  The pointer stored is not *NULL*.
 
 ``O!`` (object) [*typeobject*, PyObject \*]
    Store a Python object in a C object pointer.  This is similar to ``O``, but
-   takes two C arguments: the first is the address of a Python type object, the
+   takes two C arguments: the first is the address of a Python type object,
-   second is the address of the C variable (of type :ctype:`PyObject\*`) into which
+   the second is the address of the C variable (of type :ctype:`PyObject\*`)
-   the object pointer is stored.  If the Python object does not have the required
+   into which the object pointer is stored.  If the Python object does not
-   type, :exc:`TypeError` is raised.
+   have the required type, :exc:`TypeError` is raised.
 
 ``O&`` (object) [*converter*, *anything*]
-   Convert a Python object to a C variable through a *converter* function.  This
+   Convert a Python object to a C variable through a *converter* function.
-   takes two arguments: the first is a function, the second is the address of a C
+   This takes two arguments: the first is a function, the second is the
-   variable (of arbitrary type), converted to :ctype:`void \*`.  The *converter*
+   address of a C variable (of arbitrary type), converted to :ctype:`void \*`.
-   function in turn is called as follows::
+   The *converter* function in turn is called as follows::
 
       status = converter(object, address);
 
    where *object* is the Python object to be converted and *address* is the
-   :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function.
+   :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`
-   The returned *status* should be ``1`` for a successful conversion and ``0`` if
+   function.  The returned *status* should be ``1`` for a successful
-   the conversion has failed.  When the conversion fails, the *converter* function
+   conversion and ``0`` if the conversion has failed.  When the conversion
-   should raise an exception and leave the content of *address* unmodified.
+   fails, the *converter* function should raise an exception and leave the
+   content of *address* unmodified.
 
 ``S`` (string) [PyStringObject \*]
    Like ``O`` but requires that the Python object is a string object.  Raises
-   :exc:`TypeError` if the object is not a string object.  The C variable may also
+   :exc:`TypeError` if the object is not a string object.  The C variable may
-   be declared as :ctype:`PyObject\*`.
+   also be declared as :ctype:`PyObject\*`.
 
 ``U`` (Unicode string) [PyUnicodeObject \*]
    Like ``O`` but requires that the Python object is a Unicode object.  Raises
-   :exc:`TypeError` if the object is not a Unicode object.  The C variable may also
+   :exc:`TypeError` if the object is not a Unicode object.  The C variable may
-   be declared as :ctype:`PyObject\*`.
+   also be declared as :ctype:`PyObject\*`.
 
 ``t#`` (read-only character buffer) [char \*, int]
    Like ``s#``, but accepts any object which implements the read-only buffer
-   interface.  The :ctype:`char\*` variable is set to point to the first byte of
+   interface.  The :ctype:`char\*` variable is set to point to the first byte
-   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
+   of the buffer, and the :ctype:`int` is set to the length of the buffer.
-   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+   Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
-   others.
+   for all others.
 
 ``w`` (read-write character buffer) [char \*]
-   Similar to ``s``, but accepts any object which implements the read-write buffer
+   Similar to ``s``, but accepts any object which implements the read-write
-   interface.  The caller must determine the length of the buffer by other means,
+   buffer interface.  The caller must determine the length of the buffer by
-   or use ``w#`` instead.  Only single-segment buffer objects are accepted;
+   other means, or use ``w#`` instead.  Only single-segment buffer objects are
-   :exc:`TypeError` is raised for all others.
+   accepted; :exc:`TypeError` is raised for all others.
 
 ``w#`` (read-write character buffer) [char \*, Py_ssize_t]
    Like ``s#``, but accepts any object which implements the read-write buffer
-   interface.  The :ctype:`char \*` variable is set to point to the first byte of
+   interface.  The :ctype:`char \*` variable is set to point to the first byte
-   the buffer, and the :ctype:`int` is set to the length of the buffer.  Only
+   of the buffer, and the :ctype:`int` is set to the length of the buffer.
-   single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+   Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
-   others.
+   for all others.
 
 ``w*`` (read-write byte-oriented buffer) [Py_buffer \*]
    This is to ``w`` what ``s*`` is to ``s``.
@@ -265,72 +272,72 @@ variable(s) whose address should be passed.
    .. versionadded:: 2.6
 
 ``(items)`` (tuple) [*matching-items*]
-   The object must be a Python sequence whose length is the number of format units
+   The object must be a Python sequence whose length is the number of format
-   in *items*.  The C arguments must correspond to the individual format units in
+   units in *items*.  The C arguments must correspond to the individual format
-   *items*.  Format units for sequences may be nested.
+   units in *items*.  Format units for sequences may be nested.
 
    .. note::
 
-      Prior to Python version 1.5.2, this format specifier only accepted a tuple
+      Prior to Python version 1.5.2, this format specifier only accepted a
-      containing the individual parameters, not an arbitrary sequence.  Code which
+      tuple containing the individual parameters, not an arbitrary sequence.
-      previously caused :exc:`TypeError` to be raised here may now proceed without an
+      Code which previously caused :exc:`TypeError` to be raised here may now
-      exception.  This is not expected to be a problem for existing code.
+      proceed without an exception.  This is not expected to be a problem for
+      existing code.
 
 It is possible to pass Python long integers where integers are requested;
 however no proper range checking is done --- the most significant bits are
 silently truncated when the receiving field is too small to receive the value
-(actually, the semantics are inherited from downcasts in C --- your mileage may
+(actually, the semantics are inherited from downcasts in C --- your mileage
-vary).
+may vary).
 
 A few other characters have a meaning in a format string.  These may not occur
 inside nested parentheses.  They are:
 
 ``|``
-   Indicates that the remaining arguments in the Python argument list are optional.
+   Indicates that the remaining arguments in the Python argument list are
-   The C variables corresponding to optional arguments should be initialized to
+   optional.  The C variables corresponding to optional arguments should be
-   their default value --- when an optional argument is not specified,
+   initialized to their default value --- when an optional argument is not
-   :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C
+   specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the
-   variable(s).
+   corresponding C variable(s).
 
 ``:``
-   The list of format units ends here; the string after the colon is used as the
+   The list of format units ends here; the string after the colon is used as
-   function name in error messages (the "associated value" of the exception that
+   the function name in error messages (the "associated value" of the
-   :cfunc:`PyArg_ParseTuple` raises).
+   exception that :cfunc:`PyArg_ParseTuple` raises).
 
 ``;``
-   The list of format units ends here; the string after the semicolon is used as
+   The list of format units ends here; the string after the semicolon is used
-   the error message *instead* of the default error message.  ``:`` and ``;``
+   as the error message *instead* of the default error message.  ``:`` and
-   mutually exclude each other.
+   ``;`` mutually exclude each other.
 
 Note that any Python object references which are provided to the caller are
 *borrowed* references; do not decrement their reference count!
 
 Additional arguments passed to these functions must be addresses of variables
 whose type is determined by the format string; these are used to store values
-from the input tuple.  There are a few cases, as described in the list of format
+from the input tuple.  There are a few cases, as described in the list of
-units above, where these parameters are used as input values; they should match
+format units above, where these parameters are used as input values; they
-what is specified for the corresponding format unit in that case.
+should match what is specified for the corresponding format unit in that case.
 
-For the conversion to succeed, the *arg* object must match the format
+For the conversion to succeed, the *arg* object must match the format and the
-and the format must be exhausted.  On success, the
+format must be exhausted.  On success, the :cfunc:`PyArg_Parse\*` functions
-:cfunc:`PyArg_Parse\*` functions return true, otherwise they return
+return true, otherwise they return false and raise an appropriate exception.
-false and raise an appropriate exception. When the
+When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in
-:cfunc:`PyArg_Parse\*` functions fail due to conversion failure in one
+one of the format units, the variables at the addresses corresponding to that
-of the format units, the variables at the addresses corresponding to that
 and the following format units are left untouched.
 
 
 .. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
 
-   Parse the parameters of a function that takes only positional parameters into
+   Parse the parameters of a function that takes only positional parameters
-   local variables.  Returns true on success; on failure, it returns false and
+   into local variables.  Returns true on success; on failure, it returns
-   raises the appropriate exception.
+   false and raises the appropriate exception.
 
 
 .. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
 
-   Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather
+   Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
-   than a variable number of arguments.
+   rather than a variable number of arguments.
 
 
 .. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
@@ -348,32 +355,33 @@ and the following format units are left untouched.
 
 .. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
 
-   Function used to deconstruct the argument lists of "old-style" functions ---
+   Function used to deconstruct the argument lists of "old-style" functions
-   these are functions which use the :const:`METH_OLDARGS` parameter parsing
+   --- these are functions which use the :const:`METH_OLDARGS` parameter
-   method.  This is not recommended for use in parameter parsing in new code, and
+   parsing method.  This is not recommended for use in parameter parsing in
-   most code in the standard interpreter has been modified to no longer use this
+   new code, and most code in the standard interpreter has been modified to no
-   for that purpose.  It does remain a convenient way to decompose other tuples,
+   longer use this for that purpose.  It does remain a convenient way to
-   however, and may continue to be used for that purpose.
+   decompose other tuples, however, and may continue to be used for that
+   purpose.
 
 
 .. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
 
    A simpler form of parameter retrieval which does not use a format string to
-   specify the types of the arguments.  Functions which use this method to retrieve
+   specify the types of the arguments.  Functions which use this method to
-   their parameters should be declared as :const:`METH_VARARGS` in function or
+   retrieve their parameters should be declared as :const:`METH_VARARGS` in
-   method tables.  The tuple containing the actual parameters should be passed as
+   function or method tables.  The tuple containing the actual parameters
-   *args*; it must actually be a tuple.  The length of the tuple must be at least
+   should be passed as *args*; it must actually be a tuple.  The length of the
-   *min* and no more than *max*; *min* and *max* may be equal.  Additional
+   tuple must be at least *min* and no more than *max*; *min* and *max* may be
-   arguments must be passed to the function, each of which should be a pointer to a
+   equal.  Additional arguments must be passed to the function, each of which
-   :ctype:`PyObject\*` variable; these will be filled in with the values from
+   should be a pointer to a :ctype:`PyObject\*` variable; these will be filled
-   *args*; they will contain borrowed references.  The variables which correspond
+   in with the values from *args*; they will contain borrowed references.  The
-   to optional parameters not given by *args* will not be filled in; these should
+   variables which correspond to optional parameters not given by *args* will
-   be initialized by the caller. This function returns true on success and false if
+   not be filled in; these should be initialized by the caller. This function
-   *args* is not a tuple or contains the wrong number of elements; an exception
+   returns true on success and false if *args* is not a tuple or contains the
-   will be set if there was a failure.
+   wrong number of elements; an exception will be set if there was a failure.
 
-   This is an example of the use of this function, taken from the sources for the
+   This is an example of the use of this function, taken from the sources for
-   :mod:`_weakref` helper module for weak references::
+   the :mod:`_weakref` helper module for weak references::
 
       static PyObject *
       weakref_ref(PyObject *self, PyObject *args)
@@ -388,8 +396,8 @@ and the following format units are left untouched.
           return result;
       }
 
-   The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
+   The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely
-   this call to :cfunc:`PyArg_ParseTuple`::
+   equivalent to this call to :cfunc:`PyArg_ParseTuple`::
 
       PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
 
@@ -398,40 +406,42 @@ and the following format units are left untouched.
 
 .. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
 
-   Create a new value based on a format string similar to those accepted by the
+   Create a new value based on a format string similar to those accepted by
-   :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
+   the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.
-   the value or *NULL* in the case of an error; an exception will be raised if
+   Returns the value or *NULL* in the case of an error; an exception will be
-   *NULL* is returned.
+   raised if *NULL* is returned.
 
-   :cfunc:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
+   :cfunc:`Py_BuildValue` does not always build a tuple.  It builds a tuple
-   its format string contains two or more format units.  If the format string is
+   only if its format string contains two or more format units.  If the format
-   empty, it returns ``None``; if it contains exactly one format unit, it returns
+   string is empty, it returns ``None``; if it contains exactly one format
-   whatever object is described by that format unit.  To force it to return a tuple
+   unit, it returns whatever object is described by that format unit.  To
-   of size 0 or one, parenthesize the format string.
+   force it to return a tuple of size 0 or one, parenthesize the format
+   string.
 
-   When memory buffers are passed as parameters to supply data to build objects, as
+   When memory buffers are passed as parameters to supply data to build
-   for the ``s`` and ``s#`` formats, the required data is copied.  Buffers provided
+   objects, as for the ``s`` and ``s#`` formats, the required data is copied.
-   by the caller are never referenced by the objects created by
+   Buffers provided by the caller are never referenced by the objects created
-   :cfunc:`Py_BuildValue`.  In other words, if your code invokes :cfunc:`malloc`
+   by :cfunc:`Py_BuildValue`.  In other words, if your code invokes
-   and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is
+   :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
-   responsible for calling :cfunc:`free` for that memory once
+   your code is responsible for calling :cfunc:`free` for that memory once
    :cfunc:`Py_BuildValue` returns.
 
-   In the following description, the quoted form is the format unit; the entry in
+   In the following description, the quoted form is the format unit; the entry
-   (round) parentheses is the Python object type that the format unit will return;
+   in (round) parentheses is the Python object type that the format unit will
-   and the entry in [square] brackets is the type of the C value(s) to be passed.
+   return; and the entry in [square] brackets is the type of the C value(s) to
+   be passed.
 
-   The characters space, tab, colon and comma are ignored in format strings (but
+   The characters space, tab, colon and comma are ignored in format strings
-   not within format units such as ``s#``).  This can be used to make long format
+   (but not within format units such as ``s#``).  This can be used to make
-   strings a tad more readable.
+   long format strings a tad more readable.
 
    ``s`` (string) [char \*]
-      Convert a null-terminated C string to a Python object.  If the C string pointer
+      Convert a null-terminated C string to a Python object.  If the C string
-      is *NULL*, ``None`` is used.
+      pointer is *NULL*, ``None`` is used.
 
    ``s#`` (string) [char \*, int]
-      Convert a C string and its length to a Python object.  If the C string pointer
+      Convert a C string and its length to a Python object.  If the C string
-      is *NULL*, the length is ignored and ``None`` is returned.
+      pointer is *NULL*, the length is ignored and ``None`` is returned.
 
    ``z`` (string or ``None``) [char \*]
       Same as ``s``.
@@ -440,13 +450,14 @@ and the following format units are left untouched.
       Same as ``s#``.
 
    ``u`` (Unicode string) [Py_UNICODE \*]
-      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
+      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
-      Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
+      Python Unicode object.  If the Unicode buffer pointer is *NULL*,
+      ``None`` is returned.
 
    ``u#`` (Unicode string) [Py_UNICODE \*, int]
-      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
+      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
-      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
+      Python Unicode object.   If the Unicode buffer pointer is *NULL*, the
-      and ``None`` is returned.
+      length is ignored and ``None`` is returned.
 
    ``i`` (integer) [int]
       Convert a plain C :ctype:`int` to a Python integer object.
@@ -467,20 +478,20 @@ and the following format units are left untouched.
       Convert a C :ctype:`unsigned short int` to a Python integer object.
 
    ``I`` (integer/long) [unsigned int]
-      Convert a C :ctype:`unsigned int` to a Python integer object or a Python long
+      Convert a C :ctype:`unsigned int` to a Python integer object or a Python
-      integer object, if it is larger than ``sys.maxint``.
+      long integer object, if it is larger than ``sys.maxint``.
 
    ``k`` (integer/long) [unsigned long]
-      Convert a C :ctype:`unsigned long` to a Python integer object or a Python long
+      Convert a C :ctype:`unsigned long` to a Python integer object or a
-      integer object, if it is larger than ``sys.maxint``.
+      Python long integer object, if it is larger than ``sys.maxint``.
 
    ``L`` (long) [PY_LONG_LONG]
-      Convert a C :ctype:`long long` to a Python long integer object. Only available
+      Convert a C :ctype:`long long` to a Python long integer object. Only
-      on platforms that support :ctype:`long long`.
+      available on platforms that support :ctype:`long long`.
 
    ``K`` (long) [unsigned PY_LONG_LONG]
-      Convert a C :ctype:`unsigned long long` to a Python long integer object. Only
+      Convert a C :ctype:`unsigned long long` to a Python long integer object.
-      available on platforms that support :ctype:`unsigned long long`.
+      Only available on platforms that support :ctype:`unsigned long long`.
 
    ``n`` (int) [Py_ssize_t]
       Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
@@ -488,8 +499,8 @@ and the following format units are left untouched.
       .. versionadded:: 2.5
 
    ``c`` (string of length 1) [char]
-      Convert a C :ctype:`int` representing a character to a Python string of length
+      Convert a C :ctype:`int` representing a character to a Python string of
-      1.
+      length 1.
 
    ``d`` (float) [double]
       Convert a C :ctype:`double` to a Python floating point number.
@@ -502,39 +513,41 @@ and the following format units are left untouched.
 
    ``O`` (object) [PyObject \*]
       Pass a Python object untouched (except for its reference count, which is
-      incremented by one).  If the object passed in is a *NULL* pointer, it is assumed
+      incremented by one).  If the object passed in is a *NULL* pointer, it is
-      that this was caused because the call producing the argument found an error and
+      assumed that this was caused because the call producing the argument
-      set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't
+      found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`
-      raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
+      will return *NULL* but won't raise an exception.  If no exception has
-      set.
+      been raised yet, :exc:`SystemError` is set.
 
    ``S`` (object) [PyObject \*]
       Same as ``O``.
 
    ``N`` (object) [PyObject \*]
-      Same as ``O``, except it doesn't increment the reference count on the object.
+      Same as ``O``, except it doesn't increment the reference count on the
-      Useful when the object is created by a call to an object constructor in the
+      object.  Useful when the object is created by a call to an object
-      argument list.
+      constructor in the argument list.
 
    ``O&`` (object) [*converter*, *anything*]
-      Convert *anything* to a Python object through a *converter* function.  The
+      Convert *anything* to a Python object through a *converter* function.
-      function is called with *anything* (which should be compatible with :ctype:`void
+      The function is called with *anything* (which should be compatible with
-      \*`) as its argument and should return a "new" Python object, or *NULL* if an
+      :ctype:`void \*`) as its argument and should return a "new" Python
-      error occurred.
+      object, or *NULL* if an error occurred.
 
    ``(items)`` (tuple) [*matching-items*]
-      Convert a sequence of C values to a Python tuple with the same number of items.
+      Convert a sequence of C values to a Python tuple with the same number of
+      items.
 
    ``[items]`` (list) [*matching-items*]
-      Convert a sequence of C values to a Python list with the same number of items.
+      Convert a sequence of C values to a Python list with the same number of
+      items.
 
    ``{items}`` (dictionary) [*matching-items*]
-      Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
+      Convert a sequence of C values to a Python dictionary.  Each pair of
-      C values adds one item to the dictionary, serving as key and value,
+      consecutive C values adds one item to the dictionary, serving as key and
-      respectively.
+      value, respectively.
 
-   If there is an error in the format string, the :exc:`SystemError` exception is
+   If there is an error in the format string, the :exc:`SystemError` exception
-   set and *NULL* returned.
+   is set and *NULL* returned.
 
 .. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)