Split C API docs in Py3k branch.

1 files changed, 7 insertions, 1122 deletions

diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst
index 6138c63..6cb4d0d 100644
--- a/Doc/c-api/utilities.rst
+++ b/Doc/c-api/utilities.rst
@@ -1,6 +1,5 @@
 .. highlightlang:: c
 
-
 .. _utilities:
 
 *********
@@ -11,1125 +10,11 @@ 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.
 
+.. toctree::
 
-.. _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)`.
-
-.. _systemfunctions:
-
-System Functions
-================
-
-These are utility functions that make functionality from the :mod:`sys` module
-accessible to C code.  They all work with the current interpreter thread's
-:mod:`sys` module's dict, which is contained in the internal thread state structure.
-
-.. cfunction:: PyObject *PySys_GetObject(char *name)
-
-   Return the object *name* from the :mod:`sys` module or *NULL* if it does
-   not exist, without setting an exception.
-
-.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)
-
-   Return the :ctype:`FILE*` associated with the object *name* in the
-   :mod:`sys` module, or *def* if *name* is not in the module or is not associated
-   with a :ctype:`FILE*`.
-
-.. cfunction:: int PySys_SetObject(char *name, PyObject *v)
-
-   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
-   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
-   on error.
-
-.. cfunction:: void PySys_ResetWarnOptions(void)
-
-   Reset :data:`sys.warnoptions` to an empty list.
-
-.. cfunction:: void PySys_AddWarnOption(char *s)
-
-   Append *s* to :data:`sys.warnoptions`.
-
-.. cfunction:: void PySys_SetPath(char *path)
-
-   Set :data:`sys.path` to a list object of paths found in *path* which should
-   be a list of paths separated with the platform's search path delimiter
-   (``:`` on Unix, ``;`` on Windows).
-
-.. cfunction:: void PySys_WriteStdout(const char *format, ...)
-
-   Write the output string described by *format* to :data:`sys.stdout`.  No
-   exceptions are raised, even if truncation occurs (see below).
-
-   *format* should limit the total size of the formatted output string to
-   1000 bytes or less -- after 1000 bytes, the output string is truncated.
-   In particular, this means that no unrestricted "%s" formats should occur;
-   these should be limited using "%.<N>s" where <N> is a decimal number
-   calculated so that <N> plus the maximum size of other formatted text does not
-   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
-   digits for very large numbers.
-
-   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
-   is written to the real (C level) *stdout*.
-
-.. cfunction:: void PySys_WriteStderr(const char *format, ...)
-
-   As above, but write to :data:`sys.stderr` or *stderr* instead.
-
-
-.. _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)
-      single: modules (in module sys)
-
-   This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
-   leaving the *globals* and *locals* arguments set to *NULL* and *level* set
-   to 0.  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``.
-
-
-.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
-
-   This version of :cfunc:`PyImport_ImportModule` does not block. It's intended
-   to be used in C functions that import other modules to execute a function.
-   The import may block if another thread holds the import lock. The function
-   :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
-   the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule`
-   unless the lock is held, in which case the function will raise an
-   :exc:`ImportError`.
-
-
-.. 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.
-
-   Failing imports remove incomplete module objects, like with
-   :cfunc:`PyImport_ImportModule`.
-
-
-.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
-
-   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.  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.
-
-
-.. cfunction:: PyObject* PyImport_Import(PyObject *name)
-
-   This is a higher-level interface that calls the current "import hook
-   function" (with an explicit *level* of 0, meaning absolute import).  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.
-
-
-.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
-
-   Reload a module.  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 :attr:`sys.modules` in error cases, and even if *name* was already
-   in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`.  Leaving
-   incompletely initialized modules in :attr:`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.
-
-
-.. 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.  *version* indicates the file format.
-
-
-.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
-
-   Marshal a Python object, *value*, to *file*.
-   *version* indicates the file format.
-
-
-.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
-
-   Return a string object containing the marshalled representation of *value*.
-   *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.
-
-``y`` (bytes object) [const char \*]
-   This variant on ``s`` convert a Python bytes object to a C pointer to a
-   character string. The bytes object must not contain embedded NUL bytes; if it
-   does, a :exc:`TypeError` exception is raised.
-
-``y#`` (bytes 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.  This only accepts bytes objects.
-
-``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.
-
-``Z`` (Unicode or ``None``) [Py_UNICODE \*]
-   Like ``s``, but the Python object may also be ``None``, in which case the C
-   pointer is set to *NULL*.
-
-``Z#`` (Unicode or ``None``) [Py_UNICODE \*, int]
-   This is to ``u#`` as ``Z`` is to ``u``.
-
-``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`.
-
-``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.
-
-``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.
-
-``l`` (integer) [long int]
-   Convert a Python integer to a C :ctype:`long int`.
-
-``k`` (integer) [unsigned long]
-   Convert a Python integer to a C :ctype:`unsigned long` without
-   overflow checking.
-
-``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 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).
-
-``n`` (integer) [Py_ssize_t]
-   Convert a Python integer to a C :ctype:`Py_ssize_t`.
-
-``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.
-
-It is possible to pass "long" integers (integers whose value exceeds the
-platform's :const:`LONG_MAX`) 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.
-
-
-.. XXX deprecated, will be removed
-.. 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)
-
-
-.. 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.
-
-   ``U`` (string) [char \*]
-      Convert a null-terminated C string to a Python unicode object. If the C string
-      pointer is *NULL*, ``None`` is used.
-
-   ``U#`` (string) [char \*, int]
-      Convert a C string and its length to a Python unicode object. If the C string
-      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 long integer object.
-
-   ``k`` (integer/long) [unsigned long]
-      Convert a C :ctype:`unsigned long` to a Python long integer object.
-
-   ``L`` (long) [PY_LONG_LONG]
-      Convert a C :ctype:`long long` to a Python 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 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.
-
-   ``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.
-
-   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.
-
-
-.. cfunction:: double PyOS_ascii_atof(const char *nptr)
-
-   Convert a string to a :ctype:`double` in a locale-independent way.
-
-   See the Unix man page :manpage:`atof(2)` for details.
-
-   
-.. cfunction:: char * PyOS_stricmp(char *s1, char *s2)
-
-   Case insensitive comparsion of strings. The functions works almost
-   identical to :cfunc:`strcmp` except that it ignores the case.
-
-
-.. cfunction:: char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t  size)
-
-   Case insensitive comparsion of strings. The functions works almost
-   identical to :cfunc:`strncmp` except that it ignores the case.
-
-
-.. _reflection:
-
-Reflection
-==========
-
-.. cfunction:: PyObject* PyEval_GetBuiltins()
-
-   Return a dictionary of the builtins in the current execution frame,
-   or the interpreter of the thread state if no frame is currently executing.
-
-
-.. cfunction:: PyObject* PyEval_GetLocals()
-
-   Return a dictionary of the local variables in the current execution frame,
-   or *NULL* if no frame is currently executing.
-   
-
-.. cfunction:: PyObject* PyEval_GetGlobals()
-
-   Return a dictionary of the global variables in the current execution frame,
-   or *NULL* if no frame is currently executing.
-
-
-.. cfunction:: PyFrameObject* PyEval_GetFrame()
-
-   Return the current thread state's frame, which is *NULL* if no frame is
-   currently executing.
-
-
-.. cfunction:: int PyEval_GetRestricted()
-
-   If there is a current frame and it is executing in restricted mode, return true,
-   otherwise false.
-
-
-.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
-
-   Return the name of *func* if it is a function, class or instance object, else the
-   name of *func*\s type.
-
-
-.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
-
-   Return a description string, depending on the type of *func*.
-   Return values include "()" for functions and methods, " constructor",
-   " instance", and " object".  Concatenated with the result of
-   :cfunc:`PyEval_GetFuncName`, the result will be a description of
-   *func*.
+   sys.rst
+   import.rst
+   marshal.rst
+   arg.rst
+   conversion.rst
+   reflection.rst