Move the 2.6 reST doc tree in place.
diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst
new file mode 100644
index 0000000..2a86dcb
--- /dev/null
+++ b/Doc/c-api/utilities.rst
@@ -0,0 +1,1017 @@
+.. highlightlang:: c
+
+
+.. _utilities:
+
+*********
+Utilities
+*********
+
+The functions in this chapter perform various utility tasks, ranging from
+helping C code be more portable across platforms, using Python modules from C,
+and parsing function arguments and constructing Python values from C values.
+
+
+.. _os:
+
+Operating System Utilities
+==========================
+
+
+.. cfunction:: int Py_FdIsInteractive(FILE *fp, const char *filename)
+
+ Return true (nonzero) if the standard I/O file *fp* with name *filename* is
+ deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
+ is true. If the global flag :cdata:`Py_InteractiveFlag` is true, this function
+ also returns true if the *filename* pointer is *NULL* or if the name is equal to
+ one of the strings ``'<stdin>'`` or ``'???'``.
+
+
+.. cfunction:: long PyOS_GetLastModificationTime(char *filename)
+
+ Return the time of last modification of the file *filename*. The result is
+ encoded in the same way as the timestamp returned by the standard C library
+ function :cfunc:`time`.
+
+
+.. cfunction:: void PyOS_AfterFork()
+
+ Function to update some internal state after a process fork; this should be
+ called in the new process if the Python interpreter will continue to be used.
+ If a new executable is loaded into the new process, this function does not need
+ to be called.
+
+
+.. cfunction:: int PyOS_CheckStack()
+
+ Return true when the interpreter runs out of stack space. This is a reliable
+ check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+ on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
+ will be defined automatically; you should never change the definition in your
+ own code.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_getsig(int i)
+
+ Return the current signal handler for signal *i*. This is a thin wrapper around
+ either :cfunc:`sigaction` or :cfunc:`signal`. Do not call those functions
+ directly! :ctype:`PyOS_sighandler_t` is a typedef alias for :ctype:`void
+ (\*)(int)`.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
+
+ Set the signal handler for signal *i* to be *h*; return the old signal handler.
+ This is a thin wrapper around either :cfunc:`sigaction` or :cfunc:`signal`. Do
+ not call those functions directly! :ctype:`PyOS_sighandler_t` is a typedef
+ alias for :ctype:`void (\*)(int)`.
+
+
+.. _processcontrol:
+
+Process Control
+===============
+
+
+.. cfunction:: void Py_FatalError(const char *message)
+
+ .. index:: single: abort()
+
+ Print a fatal error message and kill the process. No cleanup is performed.
+ This function should only be invoked when a condition is detected that would
+ make it dangerous to continue using the Python interpreter; e.g., when the
+ object administration appears to be corrupted. On Unix, the standard C library
+ function :cfunc:`abort` is called which will attempt to produce a :file:`core`
+ file.
+
+
+.. cfunction:: void Py_Exit(int status)
+
+ .. index::
+ single: Py_Finalize()
+ single: exit()
+
+ Exit the current process. This calls :cfunc:`Py_Finalize` and then calls the
+ standard C library function ``exit(status)``.
+
+
+.. cfunction:: int Py_AtExit(void (*func) ())
+
+ .. index::
+ single: Py_Finalize()
+ single: cleanup functions
+
+ Register a cleanup function to be called by :cfunc:`Py_Finalize`. The cleanup
+ function will be called with no arguments and should return no value. At most
+ 32 cleanup functions can be registered. When the registration is successful,
+ :cfunc:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
+ function registered last is called first. Each cleanup function will be called
+ at most once. Since Python's internal finalization will have completed before
+ the cleanup function, no Python APIs should be called by *func*.
+
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. cfunction:: PyObject* PyImport_ImportModule(const char *name)
+
+ .. index::
+ single: package variable; __all__
+ single: __all__ (package variable)
+
+ This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
+ leaving the *globals* and *locals* arguments set to *NULL*. When the *name*
+ argument contains a dot (when it specifies a submodule of a package), the
+ *fromlist* argument is set to the list ``['*']`` so that the return value is the
+ named module rather than the top-level package containing it as would otherwise
+ be the case. (Unfortunately, this has an additional side effect when *name* in
+ fact specifies a subpackage instead of a submodule: the submodules specified in
+ the package's ``__all__`` variable are loaded.) Return a new reference to the
+ imported module, or *NULL* with an exception set on failure. Before Python 2.4,
+ the module may still be created in the failure case --- examine ``sys.modules``
+ to find out. Starting with Python 2.4, a failing import of a module no longer
+ leaves the module in ``sys.modules``.
+
+ .. versionchanged:: 2.4
+ failing imports remove incomplete module objects.
+
+ .. index:: single: modules (in module sys)
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+
+ .. index:: builtin: __import__
+
+ Import a module. This is best described by referring to the built-in Python
+ function :func:`__import__`, as the standard :func:`__import__` function calls
+ this function directly.
+
+ The return value is a new reference to the imported module or top-level package,
+ or *NULL* with an exception set on failure (before Python 2.4, the module may
+ still be created in this case). Like for :func:`__import__`, the return value
+ when a submodule of a package was requested is normally the top-level package,
+ unless a non-empty *fromlist* was given.
+
+ .. versionchanged:: 2.4
+ failing imports remove incomplete module objects.
+
+
+.. cfunction:: PyObject* PyImport_Import(PyObject *name)
+
+ .. index::
+ module: rexec
+ module: ihooks
+
+ This is a higher-level interface that calls the current "import hook function".
+ It invokes the :func:`__import__` function from the ``__builtins__`` of the
+ current globals. This means that the import is done using whatever import hooks
+ are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
+
+
+.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+ .. index:: builtin: reload
+
+ Reload a module. This is best described by referring to the built-in Python
+ function :func:`reload`, as the standard :func:`reload` function calls this
+ function directly. Return a new reference to the reloaded module, or *NULL*
+ with an exception set on failure (the module still exists in this case).
+
+
+.. cfunction:: PyObject* PyImport_AddModule(const char *name)
+
+ Return the module object corresponding to a module name. The *name* argument
+ may be of the form ``package.module``. First check the modules dictionary if
+ there's one there, and if not, create a new one and insert it in the modules
+ dictionary. Return *NULL* with an exception set on failure.
+
+ .. note::
+
+ This function does not load or import the module; if the module wasn't already
+ loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
+ or one of its variants to import a module. Package structures implied by a
+ dotted name for *name* are not created if not already present.
+
+
+.. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
+
+ .. index:: builtin: compile
+
+ Given a module name (possibly of the form ``package.module``) and a code object
+ read from a Python bytecode file or obtained from the built-in function
+ :func:`compile`, load the module. Return a new reference to the module object,
+ or *NULL* with an exception set if an error occurred. Before Python 2.4, the
+ module could still be created in error cases. Starting with Python 2.4, *name*
+ is removed from ``sys.modules`` in error cases, and even if *name* was already
+ in ``sys.modules`` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
+ incompletely initialized modules in ``sys.modules`` is dangerous, as imports of
+ such modules have no way to know that the module object is an unknown (and
+ probably damaged with respect to the module author's intents) state.
+
+ This function will reload the module if it was already imported. See
+ :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
+
+ If *name* points to a dotted name of the form ``package.module``, any package
+ structures not already created will still not be created.
+
+ .. versionchanged:: 2.4
+ *name* is removed from ``sys.modules`` in error cases.
+
+
+.. cfunction:: long PyImport_GetMagicNumber()
+
+ Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
+ :file:`.pyo` files). The magic number should be present in the first four bytes
+ of the bytecode file, in little-endian byte order.
+
+
+.. cfunction:: PyObject* PyImport_GetModuleDict()
+
+ Return the dictionary used for the module administration (a.k.a.
+ ``sys.modules``). Note that this is a per-interpreter variable.
+
+
+.. cfunction:: void _PyImport_Init()
+
+ Initialize the import mechanism. For internal use only.
+
+
+.. cfunction:: void PyImport_Cleanup()
+
+ Empty the module table. For internal use only.
+
+
+.. cfunction:: void _PyImport_Fini()
+
+ Finalize the import mechanism. For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
+
+ For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
+
+ For internal use only.
+
+
+.. cfunction:: int PyImport_ImportFrozenModule(char *name)
+
+ Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
+ module is not found, and ``-1`` with an exception set if the initialization
+ failed. To access the imported module on a successful load, use
+ :cfunc:`PyImport_ImportModule`. (Note the misnomer --- this function would
+ reload the module if it was already imported.)
+
+
+.. ctype:: struct _frozen
+
+ .. index:: single: freeze utility
+
+ This is the structure type definition for frozen module descriptors, as
+ generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
+ Python source distribution). Its definition, found in :file:`Include/import.h`,
+ is::
+
+ struct _frozen {
+ char *name;
+ unsigned char *code;
+ int size;
+ };
+
+
+.. cvar:: struct _frozen* PyImport_FrozenModules
+
+ This pointer is initialized to point to an array of :ctype:`struct _frozen`
+ records, terminated by one whose members are all *NULL* or zero. When a frozen
+ module is imported, it is searched in this table. Third-party code could play
+ tricks with this to provide a dynamically created collection of frozen modules.
+
+
+.. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void))
+
+ Add a single module to the existing table of built-in modules. This is a
+ convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
+ the table could not be extended. The new module can be imported by the name
+ *name*, and uses the function *initfunc* as the initialization function called
+ on the first attempted import. This should be called before
+ :cfunc:`Py_Initialize`.
+
+
+.. ctype:: struct _inittab
+
+ Structure describing a single entry in the list of built-in modules. Each of
+ these structures gives the name and initialization function for a module built
+ into the interpreter. Programs which embed Python may use an array of these
+ structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
+ additional built-in modules. The structure is defined in
+ :file:`Include/import.h` as::
+
+ struct _inittab {
+ char *name;
+ void (*initfunc)(void);
+ };
+
+
+.. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
+
+ Add a collection of modules to the table of built-in modules. The *newtab*
+ array must end with a sentinel entry which contains *NULL* for the :attr:`name`
+ field; failure to provide the sentinel value can result in a memory fault.
+ Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
+ extend the internal table. In the event of failure, no modules are added to the
+ internal table. This should be called before :cfunc:`Py_Initialize`.
+
+
+.. _marshalling-utils:
+
+Data marshalling support
+========================
+
+These routines allow C code to work with serialized objects using the same data
+format as the :mod:`marshal` module. There are functions to write data into the
+serialization format, and additional functions that can be used to read the data
+back. Files used to store marshalled data must be opened in binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the historical
+version, version 1 (new in Python 2.4) shares interned strings in the file, and
+upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
+(currently 1).
+
+
+.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+ Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
+ least-significant 32 bits of *value*; regardless of the size of the native
+ :ctype:`long` type.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+ Marshal a Python object, *value*, to *file*.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+ Return a string object containing the marshalled representation of *value*.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+XXX What about error detection? It appears that reading past the end of the
+file will always result in a negative numeric value (where that's relevant), but
+it's not clear that negative values won't be handled properly when there's no
+error. What's the right way to tell? Should only non-negative values be written
+using these routines?
+
+
+.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+ Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
+ reading. Only a 32-bit value can be read in using this function, regardless of
+ the native size of :ctype:`long`.
+
+
+.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+ Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
+ reading. Only a 16-bit value can be read in using this function, regardless of
+ the native size of :ctype:`short`.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+ Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+ reading. On error, sets the appropriate exception (:exc:`EOFError` or
+ :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+ Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+ reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
+ that no further objects will be read from the file, allowing it to aggressively
+ load file data into memory so that the de-serialization can operate from data in
+ memory rather than reading a byte at a time from the file. Only use these
+ variant if you are certain that you won't be reading anything else from the
+ file. On error, sets the appropriate exception (:exc:`EOFError` or
+ :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
+
+ Return a Python object from the data stream in a character buffer containing
+ *len* bytes pointed to by *string*. On error, sets the appropriate exception
+ (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+
+
+.. _arg-parsing:
+
+Parsing arguments and building values
+=====================================
+
+These functions are useful when creating your own extensions functions and
+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
+strings* which are used to tell the function about the expected 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
+sequence of format units. With a few exceptions, a format unit that is not a
+parenthesized sequence normally corresponds to a single address argument to
+these functions. In the following description, the quoted form is the format
+unit; the entry in (round) parentheses is the Python object type that matches
+the format unit; and the entry in [square] brackets is the type 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.
+ You must not provide storage for the string itself; a pointer to an existing
+ string is stored into the character pointer variable whose address you pass.
+ The C string is NUL-terminated. The Python string must not contain embedded NUL
+ bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are
+ converted to C strings using the default encoding. If this conversion fails, a
+ :exc:`UnicodeError` is raised.
+
+``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int]
+ This variant on ``s`` stores into two C variables, the first one a pointer to a
+ character string, the second one its length. In this case the Python string may
+ contain embedded null bytes. Unicode objects pass back a pointer to the default
+ encoded string version of the object if such a conversion is possible. All
+ other read-buffer compatible objects pass back a reference to the raw internal
+ data representation.
+
+``z`` (string or ``None``) [const char \*]
+ Like ``s``, but the Python object may also be ``None``, in which case the C
+ pointer is set to *NULL*.
+
+``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
+ This is to ``s#`` as ``z`` is to ``s``.
+
+``u`` (Unicode object) [Py_UNICODE \*]
+ Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
+ 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to provide
+ storage for the Unicode data buffer; a pointer to the existing 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
+ Unicode data buffer, the second one its length. Non-Unicode objects are handled
+ by interpreting their read-buffer pointer as pointer to a :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
+ Unicode into a character buffer. It only works for encoded data without 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
+ NUL-terminated string, or *NULL*, in which case the default encoding is used.
+ An exception is raised if the named encoding is not known to Python. The
+ second argument must be a :ctype:`char\*\*`; the value of the pointer it
+ references will be set to a buffer with the contents of the 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
+ encoded data into this buffer and adjust *\*buffer* to reference the newly
+ allocated storage. The caller is responsible for calling :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
+ 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
+ Unicode into a character buffer. Unlike the ``es`` format, this variant allows
+ input data which contains NUL characters.
+
+ It requires three 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
+ NUL-terminated string, or *NULL*, in which case the default encoding is used.
+ An exception is raised if the named encoding is not known to Python. The
+ second argument must be a :ctype:`char\*\*`; the value of the pointer it
+ references will be set to a buffer with the contents of the argument text.
+ The text will be encoded in the encoding specified by the first argument.
+ The third argument must be a pointer to an integer; the 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
+ the needed size, copy the encoded data into this buffer and set *\*buffer* to
+ reference the newly allocated storage. The caller is 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
+ initial value of *\*buffer_length* as the buffer size. It will then copy the
+ encoded data into the buffer and NUL-terminate it. If 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
+ them. Instead, the implementation assumes that the string object uses the
+ encoding passed in as parameter.
+
+``b`` (integer) [char]
+ Convert a Python integer to a tiny int, stored in a C :ctype:`char`.
+
+``B`` (integer) [unsigned char]
+ Convert a Python integer to a tiny int without overflow checking, stored in a C
+ :ctype:`unsigned char`.
+
+ .. versionadded:: 2.3
+
+``h`` (integer) [short int]
+ 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
+ checking.
+
+ .. versionadded:: 2.3
+
+``i`` (integer) [int]
+ Convert a Python integer to a plain C :ctype:`int`.
+
+``I`` (integer) [unsigned int]
+ Convert a Python integer to a C :ctype:`unsigned int`, without overflow
+ checking.
+
+ .. versionadded:: 2.3
+
+``l`` (integer) [long int]
+ 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
+ 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
+ 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).
+
+ .. versionadded:: 2.3
+
+``n`` (integer) [Py_ssize_t]
+ Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
+
+ .. versionadded:: 2.5
+
+``c`` (string of length 1) [char]
+ Convert a Python character, represented as a string of length 1, to a C
+ :ctype:`char`.
+
+``f`` (float) [float]
+ Convert a Python floating point number to a C :ctype:`float`.
+
+``d`` (float) [double]
+ Convert a Python floating point number to a C :ctype:`double`.
+
+``D`` (complex) [Py_complex]
+ 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
+ program thus receives the actual object that was passed. The object's 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
+ second is the address of the C variable (of type :ctype:`PyObject\*`) into which
+ the object pointer is stored. If the Python object does not 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
+ takes two arguments: the first is a function, the second is the address of a C
+ variable (of arbitrary type), converted to :ctype:`void \*`. 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.
+ The returned *status* should be ``1`` for a successful conversion and ``0`` if
+ the conversion has failed. When the conversion fails, the *converter* function
+ should raise an exception.
+
+``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
+ 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
+ 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
+ the buffer, and the :ctype:`int` is set to the length of the buffer. Only
+ single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+ others.
+
+``w`` (read-write character buffer) [char \*]
+ Similar to ``s``, but accepts any object which implements the read-write buffer
+ interface. The caller must determine the length of the buffer by other means,
+ or use ``w#`` instead. Only single-segment buffer objects are accepted;
+ :exc:`TypeError` is raised for all others.
+
+``w#`` (read-write character buffer) [char \*, int]
+ 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
+ the buffer, and the :ctype:`int` is set to the length of the buffer. Only
+ single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+ others.
+
+``(items)`` (tuple) [*matching-items*]
+ The object must be a Python sequence whose length is the number of format units
+ in *items*. The C arguments must correspond to the individual format 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
+ containing the individual parameters, not an arbitrary sequence. Code which
+ previously caused :exc:`TypeError` to be raised here may now 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
+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.
+ The C variables corresponding to optional arguments should be initialized to
+ their default value --- when an optional argument is not specified,
+ :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C
+ variable(s).
+
+``:``
+ The list of format units ends here; the string after the colon is used as the
+ function name in error messages (the "associated value" of the exception that
+ :cfunc:`PyArg_ParseTuple` raises).
+
+``;``
+ The list of format units ends here; the string after the semicolon is used as
+ the error message *instead* of the default error message. Clearly, ``:`` and
+ ``;`` 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
+units above, where these parameters are used as input values; they 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 and the
+format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions
+return true, otherwise they return false and raise an appropriate exception.
+
+
+.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+
+ Parse the parameters of a function that takes only positional parameters into
+ local variables. Returns true on success; on failure, it returns 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
+ than a variable number of arguments.
+
+
+.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+
+ Parse the parameters of a function that takes both positional and keyword
+ parameters into local variables. Returns true on success; on failure, it
+ returns false and raises the appropriate exception.
+
+
+.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+
+ Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+ va_list rather than a variable number of arguments.
+
+
+.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
+
+ Function used to deconstruct the argument lists of "old-style" functions ---
+ these are functions which use the :const:`METH_OLDARGS` parameter parsing
+ method. This is not recommended for use in parameter parsing in new code, and
+ most code in the standard interpreter has been modified to no longer use this
+ for that purpose. It does remain a convenient way to 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
+ their parameters should be declared as :const:`METH_VARARGS` in function or
+ method tables. The tuple containing the actual parameters should be passed as
+ *args*; it must actually be a tuple. The length of the tuple must be at least
+ *min* and no more than *max*; *min* and *max* may be equal. Additional
+ arguments must be passed to the function, each of which should be a pointer to a
+ :ctype:`PyObject\*` variable; these will be filled in with the values from
+ *args*; they will contain borrowed references. The variables which correspond
+ to optional parameters not given by *args* will not be filled in; these should
+ be initialized by the caller. This function returns true on success and false if
+ *args* is not a tuple or contains the 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
+ :mod:`_weakref` helper module for weak references::
+
+ static PyObject *
+ weakref_ref(PyObject *self, PyObject *args)
+ {
+ PyObject *object;
+ PyObject *callback = NULL;
+ PyObject *result = NULL;
+
+ if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+ result = PyWeakref_NewRef(object, callback);
+ }
+ return result;
+ }
+
+ The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to
+ this call to :cfunc:`PyArg_ParseTuple`::
+
+ PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
+
+ Create a new value based on a format string similar to those accepted by the
+ :cfunc:`PyArg_Parse\*` family of functions and a sequence of values. Returns
+ the value or *NULL* in the case of an error; an exception will be raised if
+ *NULL* is returned.
+
+ :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple only if
+ its format string contains two or more format units. If the format string is
+ empty, it returns ``None``; if it contains exactly one format unit, it returns
+ whatever object is described by that format unit. To 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
+ for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided
+ by the caller are never referenced by the objects created by
+ :cfunc:`Py_BuildValue`. In other words, if your code invokes :cfunc:`malloc`
+ and passes the allocated memory to :cfunc:`Py_BuildValue`, 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
+ (round) parentheses is the Python object type that the format unit will 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
+ not within format units such as ``s#``). This can be used to make 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
+ 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
+ is *NULL*, the length is ignored and ``None`` is returned.
+
+ ``z`` (string or ``None``) [char \*]
+ Same as ``s``.
+
+ ``z#`` (string or ``None``) [char \*, int]
+ Same as ``s#``.
+
+ ``u`` (Unicode string) [Py_UNICODE \*]
+ Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a 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
+ Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
+ and ``None`` is returned.
+
+ ``i`` (integer) [int]
+ Convert a plain C :ctype:`int` to a Python integer object.
+
+ ``b`` (integer) [char]
+ Convert a plain C :ctype:`char` to a Python integer object.
+
+ ``h`` (integer) [short int]
+ Convert a plain C :ctype:`short int` to a Python integer object.
+
+ ``l`` (integer) [long int]
+ Convert a C :ctype:`long int` to a Python integer object.
+
+ ``B`` (integer) [unsigned char]
+ Convert a C :ctype:`unsigned char` to a Python integer object.
+
+ ``H`` (integer) [unsigned short int]
+ 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
+ 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
+ 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
+ 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
+ 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.
+
+ .. versionadded:: 2.5
+
+ ``c`` (string of length 1) [char]
+ Convert a C :ctype:`int` representing a character to a Python string of length
+ 1.
+
+ ``d`` (float) [double]
+ Convert a C :ctype:`double` to a Python floating point number.
+
+ ``f`` (float) [float]
+ Same as ``d``.
+
+ ``D`` (complex) [Py_complex \*]
+ Convert a C :ctype:`Py_complex` structure to a Python complex number.
+
+ ``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
+ that this was caused because the call producing the argument found an error and
+ set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't
+ raise an exception. If no exception has 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.
+ Useful when the object is created by a call to an object constructor in the
+ argument list.
+
+ ``O&`` (object) [*converter*, *anything*]
+ Convert *anything* to a Python object through a *converter* function. The
+ function is called with *anything* (which should be compatible with :ctype:`void
+ \*`) as its argument and should return a "new" Python 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.
+
+ ``[items]`` (list) [*matching-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
+ C values adds one item to the dictionary, serving as key and value,
+ respectively.
+
+ If there is an error in the format string, the :exc:`SystemError` exception is
+ set and *NULL* returned.
+
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. cfunction:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
+
+ Output not more than *size* bytes to *str* according to the format string
+ *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
+
+
+.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+
+ Output not more than *size* bytes to *str* according to the format string
+ *format* and the variable argument list *va*. Unix man page
+ :manpage:`vsnprintf(2)`.
+
+:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
+functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C functions do
+not.
+
+The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
+never write more than *size* bytes (including the trailing ``'\0'`` into str.
+Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
+NULL``.
+
+If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to
+avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
+*Py_FatalError*.
+
+The return value (*rv*) for these functions should be interpreted as follows:
+
+* When ``0 <= rv < size``, the output conversion was successful and *rv*
+ characters were written to *str* (excluding the trailing ``'\0'`` byte at
+ *str*[*rv*]).
+
+* When ``rv >= size``, the output conversion was truncated and a buffer with
+ ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
+ in this case.
+
+* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
+ this case too, but the rest of *str* is undefined. The exact cause of the error
+ depends on the underlying platform.
+
+The following functions provide locale-independent string to number conversions.
+
+
+.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
+
+ Convert a string to a :ctype:`double`. This function behaves like the Standard C
+ function :cfunc:`strtod` does in the C locale. It does this without changing the
+ current locale, since that would not be thread-safe.
+
+ :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
+ files or other non-user input that should be locale independent.
+
+ .. versionadded:: 2.4
+
+ See the Unix man page :manpage:`strtod(2)` for details.
+
+
+.. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
+
+ Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
+ separator. *format* is a :cfunc:`printf`\ -style format string specifying the
+ number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
+ ``'F'``, ``'g'`` and ``'G'``.
+
+ The return value is a pointer to *buffer* with the converted string or NULL if
+ the conversion failed.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: double PyOS_ascii_atof(const char *nptr)
+
+ Convert a string to a :ctype:`double` in a locale-independent way.
+
+ .. versionadded:: 2.4
+
+ See the Unix man page :manpage:`atof(2)` for details.
+