add hg and python

1 files changed, 1023 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/api/utilities.tex b/sys/src/cmd/python/Doc/api/utilities.tex
new file mode 100644
index 000000000..93e379645
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/utilities.tex
@@ -0,0 +1,1023 @@
+\chapter{Utilities \label{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.
+
+
+\section{Operating System Utilities \label{os}}
+
+\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, const char *filename}
+  Return true (nonzero) if the standard I/O file \var{fp} with name
+  \var{filename} is deemed interactive.  This is the case for files
+  for which \samp{isatty(fileno(\var{fp}))} is true.  If the global
+  flag \cdata{Py_InteractiveFlag} is true, this function also returns
+  true if the \var{filename} pointer is \NULL{} or if the name is
+  equal to one of the strings \code{'<stdin>'} or \code{'???'}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
+  Return the time of last modification of the file \var{filename}.
+  The result is encoded in the same way as the timestamp returned by
+  the standard C library function \cfunction{time()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyOS_CheckStack}{}
+  Return true when the interpreter runs out of stack space.  This is a
+  reliable check, but is only available when \constant{USE_STACKCHECK}
+  is defined (currently on Windows using the Microsoft Visual \Cpp{}
+  compiler).  \constant{USE_STACKCHECK} will be
+  defined automatically; you should never change the definition in
+  your own code.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
+  Return the current signal handler for signal \var{i}.  This is a
+  thin wrapper around either \cfunction{sigaction()} or
+  \cfunction{signal()}.  Do not call those functions directly!
+  \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void
+  (*)(int)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
+  Set the signal handler for signal \var{i} to be \var{h}; return the
+  old signal handler.  This is a thin wrapper around either
+  \cfunction{sigaction()} or \cfunction{signal()}.  Do not call those
+  functions directly!  \ctype{PyOS_sighandler_t} is a typedef alias
+  for \ctype{void (*)(int)}.
+\end{cfuncdesc}
+
+
+\section{Process Control \label{processControl}}
+
+\begin{cfuncdesc}{void}{Py_FatalError}{const char *message}
+  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
+  \cfunction{abort()}\ttindex{abort()} is called which will attempt to
+  produce a \file{core} file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Exit}{int status}
+  Exit the current process.  This calls
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and then calls the
+  standard C library function
+  \code{exit(\var{status})}\ttindex{exit()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
+  Register a cleanup function to be called by
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.  The cleanup
+  function will be called with no arguments and should return no
+  value.  At most 32 \index{cleanup functions}cleanup functions can be
+  registered.  When the registration is successful,
+  \cfunction{Py_AtExit()} returns \code{0}; on failure, it returns
+  \code{-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 \var{func}.
+\end{cfuncdesc}
+
+
+\section{Importing Modules \label{importing}}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{const char *name}
+  This is a simplified interface to
+  \cfunction{PyImport_ImportModuleEx()} below, leaving the
+  \var{globals} and \var{locals} arguments set to \NULL.  When the
+  \var{name} argument contains a dot (when it specifies a submodule of
+  a package), the \var{fromlist} argument is set to the list
+  \code{['*']} 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
+  \var{name} in fact specifies a subpackage instead of a submodule:
+  the submodules specified in the package's \code{__all__} variable
+  are \index{package variable!\code{__all__}}
+  \withsubitem{(package variable)}{\ttindex{__all__}}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 \code{sys.modules} to find out.  Starting
+  with Python 2.4, a failing import of a module no longer leaves the
+  module in \code{sys.modules}.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
+  \withsubitem{(in module sys)}{\ttindex{modules}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
+                       PyObject *globals, PyObject *locals, PyObject *fromlist}
+  Import a module.  This is best described by referring to the
+  built-in Python function
+  \function{__import__()}\bifuncindex{__import__}, as the standard
+  \function{__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
+  \function{__import__()}, the return value when a submodule of a
+  package was requested is normally the top-level package, unless a
+  non-empty \var{fromlist} was given.
+  \versionchanged[failing imports remove incomplete module objects]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
+  This is a higher-level interface that calls the current ``import
+  hook function''.  It invokes the \function{__import__()} function
+  from the \code{__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 \module{rexec}\refstmodindex{rexec}
+  or \module{ihooks}\refstmodindex{ihooks}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
+  Reload a module.  This is best described by referring to the
+  built-in Python function \function{reload()}\bifuncindex{reload}, as
+  the standard \function{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).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{const char *name}
+  Return the module object corresponding to a module name.  The
+  \var{name} argument may be of the form \code{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 \cfunction{PyImport_ImportModule()} or one of its variants to
+  import a module.  Package structures implied by a dotted name for
+  \var{name} are not created if not already present.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
+  Given a module name (possibly of the form \code{package.module}) and
+  a code object read from a Python bytecode file or obtained from the
+  built-in function \function{compile()}\bifuncindex{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,
+  \var{name} is removed from \code{sys.modules} in error cases, and even
+  if \var{name} was already in \code{sys.modules} on entry to
+  \cfunction{PyImport_ExecCodeModule()}.  Leaving incompletely initialized
+  modules in \code{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
+  \cfunction{PyImport_ReloadModule()} for the intended way to reload a
+  module.
+
+  If \var{name} points to a dotted name of the
+  form \code{package.module}, any package structures not already
+  created will still not be created.
+
+  \versionchanged[\var{name} is removed from \code{sys.modules} in error cases]{2.4}
+
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
+  Return the dictionary used for the module administration
+  (a.k.a.\ \code{sys.modules}).  Note that this is a per-interpreter
+  variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Init}{}
+  Initialize the import mechanism.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
+  Empty the module table.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Fini}{}
+  Finalize the import mechanism.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
+  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
+  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
+  Load a frozen module named \var{name}.  Return \code{1} for success,
+  \code{0} if the module is not found, and \code{-1} with an exception
+  set if the initialization failed.  To access the imported module on
+  a successful load, use \cfunction{PyImport_ImportModule()}.  (Note
+  the misnomer --- this function would reload the module if it was
+  already imported.)
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_frozen]{struct _frozen}
+  This is the structure type definition for frozen module descriptors,
+  as generated by the \program{freeze}\index{freeze utility} utility
+  (see \file{Tools/freeze/} in the Python source distribution).  Its
+  definition, found in \file{Include/import.h}, is:
+
+\begin{verbatim}
+struct _frozen {
+    char *name;
+    unsigned char *code;
+    int size;
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cvardesc}{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.
+\end{cvardesc}
+
+\begin{cfuncdesc}{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
+  \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the
+  table could not be extended.  The new module can be imported by the
+  name \var{name}, and uses the function \var{initfunc} as the
+  initialization function called on the first attempted import.  This
+  should be called before \cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_inittab]{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 \cfunction{PyImport_ExtendInittab()} to provide additional
+  built-in modules.  The structure is defined in
+  \file{Include/import.h} as:
+
+\begin{verbatim}
+struct _inittab {
+    char *name;
+    void (*initfunc)(void);
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
+  Add a collection of modules to the table of built-in modules.  The
+  \var{newtab} array must end with a sentinel entry which contains
+  \NULL{} for the \member{name} field; failure to provide the sentinel
+  value can result in a memory fault.  Returns \code{0} on success or
+  \code{-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
+  \cfunction{Py_Initialize()}.
+\end{cfuncdesc}
+
+
+\section{Data marshalling support \label{marshalling-utils}}
+
+These routines allow C code to work with serialized objects using the
+same data format as the \module{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. \var{Py_MARSHAL_VERSION}
+indicates the current file format (currently 1).
+
+\begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file, int version}
+  Marshal a \ctype{long} integer, \var{value}, to \var{file}.  This
+  will only write the least-significant 32 bits of \var{value};
+  regardless of the size of the native \ctype{long} type.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
+                                                     FILE *file, int version}
+  Marshal a Python object, \var{value}, to \var{file}.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value, int version}
+  Return a string object containing the marshalled representation of
+  \var{value}.
+
+  \versionchanged[\var{version} indicates the file format]{2.4}
+\end{cfuncdesc}
+
+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?
+
+\begin{cfuncdesc}{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}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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
+  (\exception{EOFError} or \exception{TypeError}) and returns \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadLastObjectFromFile}{FILE *file}
+  Return a Python object from the data stream in a \ctype{FILE*}
+  opened for reading.  Unlike
+  \cfunction{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 (\exception{EOFError} or
+  \exception{TypeError}) and returns \NULL.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string,
+                                                             Py_ssize_t len}
+  Return a Python object from the data stream in a character buffer
+  containing \var{len} bytes pointed to by \var{string}.  On error,
+  sets the appropriate exception (\exception{EOFError} or
+  \exception{TypeError}) and returns \NULL.
+\end{cfuncdesc}
+
+
+\section{Parsing arguments and building values
+         \label{arg-parsing}}
+
+These functions are useful when creating your own extensions functions
+and methods.  Additional information and examples are available in
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}.
+
+The first three of these functions described,
+\cfunction{PyArg_ParseTuple()},
+\cfunction{PyArg_ParseTupleAndKeywords()}, and
+\cfunction{PyArg_Parse()}, all use \emph{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.
+
+\begin{description}
+  \item[\samp{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 \exception{TypeError} exception is raised.
+  Unicode objects are converted to C strings using the default
+  encoding.  If this conversion fails, a \exception{UnicodeError} is
+  raised.
+
+  \item[\samp{s\#} (string, Unicode or any read buffer compatible object)
+  {[const char *, int]}]
+  This variant on \samp{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.
+
+  \item[\samp{z} (string or \code{None}) {[const char *]}]
+  Like \samp{s}, but the Python object may also be \code{None}, in
+  which case the C pointer is set to \NULL.
+
+  \item[\samp{z\#} (string or \code{None} or any read buffer
+  compatible object) {[const char *, int]}]
+  This is to \samp{s\#} as \samp{z} is to \samp{s}.
+
+  \item[\samp{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 \samp{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.
+
+  \item[\samp{u\#} (Unicode object) {[Py_UNICODE *, int]}]
+  This variant on \samp{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.
+
+  \item[\samp{es} (string, Unicode object or character buffer
+  compatible object) {[const char *encoding, char **buffer]}]
+  This variant on \samp{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.
+
+  \cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
+  size, copy the encoded data into this buffer and adjust
+  \var{*buffer} to reference the newly allocated storage.  The caller
+  is responsible for calling \cfunction{PyMem_Free()} to free the
+  allocated buffer after use.
+
+  \item[\samp{et} (string, Unicode object or character buffer
+  compatible object) {[const char *encoding, char **buffer]}]
+  Same as \samp{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.
+
+  \item[\samp{es\#} (string, Unicode object or character buffer compatible
+  object) {[const char *encoding, char **buffer, int *buffer_length]}]
+  This variant on \samp{s\#} is used for encoding Unicode and objects
+  convertible to Unicode into a character buffer.  Unlike the
+  \samp{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 \var{*buffer} points a \NULL{} pointer, the function will
+  allocate a buffer of the needed size, copy the encoded data into
+  this buffer and set \var{*buffer} to reference the newly allocated
+  storage.  The caller is responsible for calling
+  \cfunction{PyMem_Free()} to free the allocated buffer after usage.
+
+  If \var{*buffer} points to a non-\NULL{} pointer (an already
+  allocated buffer), \cfunction{PyArg_ParseTuple()} will use this
+  location as the buffer and interpret the initial value of
+  \var{*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 \exception{ValueError} will be set.
+
+  In both cases, \var{*buffer_length} is set to the length of the
+  encoded data without the trailing NUL byte.
+
+  \item[\samp{et\#} (string, Unicode object or character buffer compatible
+  object) {[const char *encoding, char **buffer]}]
+  Same as \samp{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.
+
+  \item[\samp{b} (integer) {[char]}]
+  Convert a Python integer to a tiny int, stored in a C \ctype{char}.
+
+  \item[\samp{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}
+
+  \item[\samp{h} (integer) {[short int]}]
+  Convert a Python integer to a C \ctype{short int}.
+
+  \item[\samp{H} (integer) {[unsigned short int]}]
+  Convert a Python integer to a C \ctype{unsigned short int}, without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{i} (integer) {[int]}]
+  Convert a Python integer to a plain C \ctype{int}.
+
+  \item[\samp{I} (integer) {[unsigned int]}]
+  Convert a Python integer to a C \ctype{unsigned int}, without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{l} (integer) {[long int]}]
+  Convert a Python integer to a C \ctype{long int}.
+
+  \item[\samp{k} (integer) {[unsigned long]}]
+  Convert a Python integer or long integer to a C \ctype{unsigned long} without
+  overflow checking.  \versionadded{2.3}
+
+  \item[\samp{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).
+
+  \item[\samp{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}
+
+  \item[\samp{n} (integer) {[Py_ssize_t]}]
+  Convert a Python integer or long integer to a C \ctype{Py_ssize_t}.
+  \versionadded{2.5}
+
+  \item[\samp{c} (string of length 1) {[char]}]
+  Convert a Python character, represented as a string of length 1, to
+  a C \ctype{char}.
+
+  \item[\samp{f} (float) {[float]}]
+  Convert a Python floating point number to a C \ctype{float}.
+
+  \item[\samp{d} (float) {[double]}]
+  Convert a Python floating point number to a C \ctype{double}.
+
+  \item[\samp{D} (complex) {[Py_complex]}]
+  Convert a Python complex number to a C \ctype{Py_complex} structure.
+
+  \item[\samp{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.
+
+  \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
+  Store a Python object in a C object pointer.  This is similar to
+  \samp{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,
+  \exception{TypeError} is raised.
+
+  \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
+  Convert a Python object to a C variable through a \var{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 \var{converter} function in turn is called
+  as follows:
+
+  \var{status}\code{ = }\var{converter}\code{(}\var{object},
+  \var{address}\code{);}
+
+  where \var{object} is the Python object to be converted and
+  \var{address} is the \ctype{void*} argument that was passed to the
+  \cfunction{PyArg_Parse*()} function.  The returned \var{status}
+  should be \code{1} for a successful conversion and \code{0} if the
+  conversion has failed.  When the conversion fails, the
+  \var{converter} function should raise an exception.
+
+  \item[\samp{S} (string) {[PyStringObject *]}]
+  Like \samp{O} but requires that the Python object is a string
+  object.  Raises \exception{TypeError} if the object is not a string
+  object.  The C variable may also be declared as \ctype{PyObject*}.
+
+  \item[\samp{U} (Unicode string) {[PyUnicodeObject *]}]
+  Like \samp{O} but requires that the Python object is a Unicode
+  object.  Raises \exception{TypeError} if the object is not a Unicode
+  object.  The C variable may also be declared as \ctype{PyObject*}.
+
+  \item[\samp{t\#} (read-only character buffer) {[char *, int]}]
+  Like \samp{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; \exception{TypeError} is raised for all others.
+
+  \item[\samp{w} (read-write character buffer) {[char *]}]
+  Similar to \samp{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 \samp{w\#} instead.  Only
+  single-segment buffer objects are accepted; \exception{TypeError} is
+  raised for all others.
+
+  \item[\samp{w\#} (read-write character buffer) {[char *, int]}]
+  Like \samp{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; \exception{TypeError} is raised for all others.
+
+  \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
+  The object must be a Python sequence whose length is the number of
+  format units in \var{items}.  The C arguments must correspond to the
+  individual format units in \var{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
+  \exception{TypeError} to be raised here may now proceed without an
+  exception.  This is not expected to be a problem for existing code.}
+\end{description}
+
+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:
+
+\begin{description}
+  \item[\samp{|}]
+  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, \cfunction{PyArg_ParseTuple()} does not
+  touch the contents of the corresponding C variable(s).
+
+  \item[\samp{:}]
+  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 \cfunction{PyArg_ParseTuple()}
+  raises).
+
+  \item[\samp{;}]
+  The list of format units ends here; the string after the semicolon
+  is used as the error message \emph{instead} of the default error
+  message.  Clearly, \samp{:} and \samp{;} mutually exclude each
+  other.
+\end{description}
+
+Note that any Python object references which are provided to the
+caller are \emph{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 \var{arg} object must match the
+format and the format must be exhausted.  On success, the
+\cfunction{PyArg_Parse*()} functions return true, otherwise they
+return false and raise an appropriate exception.
+
+\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, const char *format,
+                                         \moreargs}
+  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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, const char *format,
+                                         va_list vargs}
+  Identical to \cfunction{PyArg_ParseTuple()}, except that it accepts a
+  va_list rather than a variable number of arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, const char *format, char *keywords[],
+                       \moreargs}
+  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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_VaParseTupleAndKeywords}{PyObject *args,
+                       PyObject *kw, const char *format, char *keywords[],
+                       va_list vargs}
+  Identical to \cfunction{PyArg_ParseTupleAndKeywords()}, except that it
+  accepts a va_list rather than a variable number of arguments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, const char *format,
+                                    \moreargs}
+  Function used to deconstruct the argument lists of ``old-style''
+  functions --- these are functions which use the
+  \constant{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, const char *name,
+                                          Py_ssize_t min, Py_ssize_t max, \moreargs}
+  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
+  \constant{METH_VARARGS} in function or method tables.  The tuple
+  containing the actual parameters should be passed as \var{args}; it
+  must actually be a tuple.  The length of the tuple must be at least
+  \var{min} and no more than \var{max}; \var{min} and \var{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 \var{args}; they will contain
+  borrowed references.  The variables which correspond to optional
+  parameters not given by \var{args} will not be filled in; these
+  should be initialized by the caller.
+  This function returns true on success and false if \var{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 \module{_weakref} helper module for weak references:
+
+\begin{verbatim}
+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;
+}
+\end{verbatim}
+
+  The call to \cfunction{PyArg_UnpackTuple()} in this example is
+  entirely equivalent to this call to \cfunction{PyArg_ParseTuple()}:
+
+\begin{verbatim}
+PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+\end{verbatim}
+
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{const char *format,
+                                            \moreargs}
+  Create a new value based on a format string similar to those
+  accepted by the \cfunction{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.
+
+  \cfunction{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 \code{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 \samp{s} and \samp{s\#} formats, the required
+  data is copied.  Buffers provided by the caller are never referenced
+  by the objects created by \cfunction{Py_BuildValue()}.  In other
+  words, if your code invokes \cfunction{malloc()} and passes the
+  allocated memory to \cfunction{Py_BuildValue()}, your code is
+  responsible for calling \cfunction{free()} for that memory once
+  \cfunction{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 \samp{s\#}).  This can
+  be used to make long format strings a tad more readable.
+
+  \begin{description}
+    \item[\samp{s} (string) {[char *]}]
+    Convert a null-terminated C string to a Python object.  If the C
+    string pointer is \NULL, \code{None} is used.
+
+    \item[\samp{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 \code{None} is
+    returned.
+
+    \item[\samp{z} (string or \code{None}) {[char *]}]
+    Same as \samp{s}.
+
+    \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
+    Same as \samp{s\#}.
+
+    \item[\samp{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, \code{None} is returned.
+
+    \item[\samp{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 \code{None} is returned.
+
+    \item[\samp{i} (integer) {[int]}]
+    Convert a plain C \ctype{int} to a Python integer object.
+
+    \item[\samp{b} (integer) {[char]}]
+    Convert a plain C \ctype{char} to a Python integer object.
+
+    \item[\samp{h} (integer) {[short int]}]
+    Convert a plain C \ctype{short int} to a Python integer object.
+
+    \item[\samp{l} (integer) {[long int]}]
+    Convert a C \ctype{long int} to a Python integer object.
+
+    \item[\samp{B} (integer) {[unsigned char]}]
+    Convert a C \ctype{unsigned char} to a Python integer object.
+
+    \item[\samp{H} (integer) {[unsigned short int]}]
+    Convert a C \ctype{unsigned short int} to a Python integer object.
+
+    \item[\samp{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 \code{sys.maxint}.
+
+    \item[\samp{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 \code{sys.maxint}.
+
+    \item[\samp{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}.
+
+    \item[\samp{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}.
+
+    \item[\samp{n} (int) {[Py_ssize_t]}]
+    Convert a C \ctype{Py_ssize_t} to a Python integer or long integer.
+    \versionadded{2.5}
+
+    \item[\samp{c} (string of length 1) {[char]}]
+    Convert a C \ctype{int} representing a character to a Python
+    string of length 1.
+
+    \item[\samp{d} (float) {[double]}]
+    Convert a C \ctype{double} to a Python floating point number.
+
+    \item[\samp{f} (float) {[float]}]
+    Same as \samp{d}.
+
+    \item[\samp{D} (complex) {[Py_complex *]}]
+    Convert a C \ctype{Py_complex} structure to a Python complex
+    number.
+
+    \item[\samp{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, \cfunction{Py_BuildValue()} will return \NULL{} but
+    won't raise an exception.  If no exception has been raised yet,
+    \exception{SystemError} is set.
+
+    \item[\samp{S} (object) {[PyObject *]}]
+    Same as \samp{O}.
+
+    \item[\samp{N} (object) {[PyObject *]}]
+    Same as \samp{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.
+
+    \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
+    Convert \var{anything} to a Python object through a
+    \var{converter} function.  The function is called with
+    \var{anything} (which should be compatible with \ctype{void *}) as
+    its argument and should return a ``new'' Python object, or \NULL{}
+    if an error occurred.
+
+    \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
+    Convert a sequence of C values to a Python tuple with the same
+    number of items.
+
+    \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
+    Convert a sequence of C values to a Python list with the same
+    number of items.
+
+    \item[\samp{\{\var{items}\}} (dictionary) {[\var{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.
+
+  \end{description}
+
+  If there is an error in the format string, the
+  \exception{SystemError} exception is set and \NULL{} returned.
+\end{cfuncdesc}
+
+\section{String conversion and formatting \label{string-formatting}}
+
+Functions for number conversion and formatted string output.
+
+\begin{cfuncdesc}{int}{PyOS_snprintf}{char *str, size_t size, 
+                                      const char *format, \moreargs}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the extra arguments. See the \UNIX{} man
+page \manpage{snprintf}{2}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyOS_vsnprintf}{char *str, size_t size,
+                                       const char *format, va_list va}
+Output not more than \var{size} bytes to \var{str} according to the format
+string \var{format} and the variable argument list \var{va}. \UNIX{}
+man page \manpage{vsnprintf}{2}.
+\end{cfuncdesc}
+
+\cfunction{PyOS_snprintf} and \cfunction{PyOS_vsnprintf} wrap the
+Standard C library functions \cfunction{snprintf()} and
+\cfunction{vsnprintf()}. Their purpose is to guarantee consistent
+behavior in corner cases, which the Standard C functions do not.
+
+The wrappers ensure that \var{str}[\var{size}-1] is always
+\character{\textbackslash0} upon return. They never write more than
+\var{size} bytes (including the trailing \character{\textbackslash0}
+into str. Both functions require that \code{\var{str} != NULL},
+\code{\var{size} > 0} and \code{\var{format} != NULL}.
+
+If the platform doesn't have \cfunction{vsnprintf()} and the buffer
+size needed to avoid truncation exceeds \var{size} by more than 512
+bytes, Python aborts with a \var{Py_FatalError}.
+
+The return value (\var{rv}) for these functions should be interpreted
+as follows:
+
+\begin{itemize}
+
+\item When \code{0 <= \var{rv} < \var{size}}, the output conversion
+  was successful and \var{rv} characters were written to \var{str}
+  (excluding the trailing \character{\textbackslash0} byte at
+  \var{str}[\var{rv}]).
+
+\item When \code{\var{rv} >= \var{size}}, the output conversion was
+  truncated and a buffer with \code{\var{rv} + 1} bytes would have
+  been needed to succeed. \var{str}[\var{size}-1] is
+  \character{\textbackslash0} in this case.
+
+\item When \code{\var{rv} < 0}, ``something bad happened.''
+  \var{str}[\var{size}-1] is \character{\textbackslash0} in this case
+  too, but the rest of \var{str} is undefined. The exact cause of the
+  error depends on the underlying platform.
+
+\end{itemize}
+
+The following functions provide locale-independent string to number
+conversions.
+
+\begin{cfuncdesc}{double}{PyOS_ascii_strtod}{const char *nptr, char **endptr}
+Convert a string to a \ctype{double}. This function behaves like the
+Standard C function \cfunction{strtod()} does in the C locale. It does
+this without changing the current locale, since that would not be
+thread-safe.
+
+\cfunction{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.
+
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char *}{PyOS_ascii_formatd}{char *buffer, size_t buf_len,
+                                              const char *format, double d}
+Convert a \ctype{double} to a string using the \character{.} as the
+decimal separator. \var{format} is a \cfunction{printf()}-style format
+string specifying the number format. Allowed conversion characters are
+\character{e}, \character{E}, \character{f}, \character{F},
+\character{g} and \character{G}.
+
+The return value is a pointer to \var{buffer} with the converted
+string or NULL if the conversion failed. \versionadded{2.4}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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.
+\end{cfuncdesc}