cpython-lru_cache-weakref: Doc/api/utilities.tex annotate

annotate Doc/api/utilities.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	1c055171b871
children	a382263df01d

rev	line source
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1 \chapter{Utilities \label{utilities}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	2
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	3 The functions in this chapter perform various utility tasks, ranging
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	4 from helping C code be more portable across platforms, using Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	5 modules from C, and parsing function arguments and constructing Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	6 values from C values.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	7
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	8
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	9 \section{Operating System Utilities \label{os}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	10
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	11 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE fp, char filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	12 Return true (nonzero) if the standard I/O file \var{fp} with name
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	13 \var{filename} is deemed interactive. This is the case for files
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	14 for which \samp{isatty(fileno(\var{fp}))} is true. If the global
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	15 flag \cdata{Py_InteractiveFlag} is true, this function also returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	16 true if the \var{filename} pointer is \NULL{} or if the name is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	17 equal to one of the strings \code{'<stdin>'} or \code{'???'}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	18 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	19
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	20 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	21 Return the time of last modification of the file \var{filename}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	22 The result is encoded in the same way as the timestamp returned by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	23 the standard C library function \cfunction{time()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	24 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	25
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	26 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	27 Function to update some internal state after a process fork; this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	28 should be called in the new process if the Python interpreter will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	29 continue to be used. If a new executable is loaded into the new
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	30 process, this function does not need to be called.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	31 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	32
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	33 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	34 Return true when the interpreter runs out of stack space. This is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	35 reliable check, but is only available when \constant{USE_STACKCHECK}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	36 is defined (currently on Windows using the Microsoft Visual \Cpp{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	37 compiler and on the Macintosh). \constant{USE_CHECKSTACK} will be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	38 defined automatically; you should never change the definition in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	39 your own code.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	40 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	41
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	42 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	43 Return the current signal handler for signal \var{i}. This is a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	44 thin wrapper around either \cfunction{sigaction()} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	45 \cfunction{signal()}. Do not call those functions directly!
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	46 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	47 (*)(int)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	48 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	49
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	50 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	51 Set the signal handler for signal \var{i} to be \var{h}; return the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	52 old signal handler. This is a thin wrapper around either
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	53 \cfunction{sigaction()} or \cfunction{signal()}. Do not call those
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	54 functions directly! \ctype{PyOS_sighandler_t} is a typedef alias
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	55 for \ctype{void (*)(int)}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	56 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	57
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	58
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	59 \section{Process Control \label{processControl}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	60
24155 9456a2ccda61 The Py_REF_DEBUG/COUNT_ALLOCS/Py_TRACE_REFS macro minefield: added Tim Peters <tim.peters@gmail.com> parents: 23884 diff changeset	61 \begin{cfuncdesc}{void}{Py_FatalError}{const char *message}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	62 Print a fatal error message and kill the process. No cleanup is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	63 performed. This function should only be invoked when a condition is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	64 detected that would make it dangerous to continue using the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	65 interpreter; e.g., when the object administration appears to be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	66 corrupted. On \UNIX, the standard C library function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	67 \cfunction{abort()}\ttindex{abort()} is called which will attempt to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	68 produce a \file{core} file.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	69 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	70
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	71 \begin{cfuncdesc}{void}{Py_Exit}{int status}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	72 Exit the current process. This calls
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and then calls the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 standard C library function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	75 \code{exit(\var{status})}\ttindex{exit()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	76 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	77
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	78 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	79 Register a cleanup function to be called by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	80 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. The cleanup
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	81 function will be called with no arguments and should return no
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	82 value. At most 32 \index{cleanup functions}cleanup functions can be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	83 registered. When the registration is successful,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	84 \cfunction{Py_AtExit()} returns \code{0}; on failure, it returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	85 \code{-1}. The cleanup function registered last is called first.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	86 Each cleanup function will be called at most once. Since Python's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	87 internal finallization will have completed before the cleanup
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	88 function, no Python APIs should be called by \var{func}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	92 \section{Importing Modules \label{importing}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	94 \begin{cfuncdesc}{PyObject}{PyImport_ImportModule}{char name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	95 This is a simplified interface to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	96 \cfunction{PyImport_ImportModuleEx()} below, leaving the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	97 \var{globals} and \var{locals} arguments set to \NULL. When the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	98 \var{name} argument contains a dot (when it specifies a submodule of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	99 a package), the \var{fromlist} argument is set to the list
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	100 \code{['*']} so that the return value is the named module rather
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	101 than the top-level package containing it as would otherwise be the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	102 case. (Unfortunately, this has an additional side effect when
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	103 \var{name} in fact specifies a subpackage instead of a submodule:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	104 the submodules specified in the package's \code{__all__} variable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	105 are \index{package variable!\code{__all__}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107 a new reference to the imported module, or \NULL{} with an exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	108 set on failure (the module may still be created in this case ---
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	109 examine \code{sys.modules} to find out).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	110 \withsubitem{(in module sys)}{\ttindex{modules}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	111 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	112
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	113 \begin{cfuncdesc}{PyObject}{PyImport_ImportModuleEx}{char name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	114 PyObject globals, PyObject locals, PyObject *fromlist}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	115 Import a module. This is best described by referring to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116 built-in Python function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 \function{__import__()}\bifuncindex{__import__}, as the standard
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	118 \function{__import__()} function calls this function directly.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	119
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	120 The return value is a new reference to the imported module or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121 top-level package, or \NULL{} with an exception set on failure (the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122 module may still be created in this case). Like for
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	123 \function{__import__()}, the return value when a submodule of a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124 package was requested is normally the top-level package, unless a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	125 non-empty \var{fromlist} was given.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	128 \begin{cfuncdesc}{PyObject}{PyImport_Import}{PyObject name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	129 This is a higher-level interface that calls the current ``import
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	130 hook function''. It invokes the \function{__import__()} function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	131 from the \code{__builtins__} of the current globals. This means
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	132 that the import is done using whatever import hooks are installed in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	133 the current environment, e.g. by \module{rexec}\refstmodindex{rexec}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	134 or \module{ihooks}\refstmodindex{ihooks}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	135 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	136
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	137 \begin{cfuncdesc}{PyObject}{PyImport_ReloadModule}{PyObject m}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	138 Reload a module. This is best described by referring to the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	139 built-in Python function \function{reload()}\bifuncindex{reload}, as
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	140 the standard \function{reload()} function calls this function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	141 directly. Return a new reference to the reloaded module, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	142 with an exception set on failure (the module still exists in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	143 case).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	144 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	145
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	146 \begin{cfuncdesc}{PyObject}{PyImport_AddModule}{char name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	147 Return the module object corresponding to a module name. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	148 \var{name} argument may be of the form \code{package.module}).
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	149 First check the modules dictionary if there's one there, and if not,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	150 create a new one and insert in in the modules dictionary.
26176 1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	151 Return \NULL{} with an exception set on failure.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	152 \note{This function does not load or import the module; if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	153 module wasn't already loaded, you will get an empty module object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	154 Use \cfunction{PyImport_ImportModule()} or one of its variants to
26176 1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	155 import a module. Package structures implied by a dotted name for
1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	156 \var{name} are not created if not already present.}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	157 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	158
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	159 \begin{cfuncdesc}{PyObject}{PyImport_ExecCodeModule}{char name, PyObject *co}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	160 Given a module name (possibly of the form \code{package.module}) and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	161 a code object read from a Python bytecode file or obtained from the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	162 built-in function \function{compile()}\bifuncindex{compile}, load
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	163 the module. Return a new reference to the module object, or \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	164 with an exception set if an error occurred (the module may still be
26176 1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	165 created in this case). This function would reload the module if it
1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	166 was already imported. If \var{name} points to a dotted name of the
1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	167 form \code{package.module}, any package structures not already
1c055171b871 Clarify that PyImport_AddModule() and PyImport_ExecCodeModule() don't Fred Drake <fdrake@acm.org> parents: 24155 diff changeset	168 created will still not be created.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	169 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	170
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	171 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	172 Return the magic number for Python bytecode files
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	173 (a.k.a. \file{.pyc} and \file{.pyo} files). The magic number should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	174 be present in the first four bytes of the bytecode file, in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	175 little-endian byte order.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	176 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	177
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	178 \begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	179 Return the dictionary used for the module administration
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	180 (a.k.a.\ \code{sys.modules}). Note that this is a per-interpreter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	181 variable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	182 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	183
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	184 \begin{cfuncdesc}{void}{_PyImport_Init}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	185 Initialize the import mechanism. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	186 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	187
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	188 \begin{cfuncdesc}{void}{PyImport_Cleanup}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	189 Empty the module table. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	190 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	191
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	192 \begin{cfuncdesc}{void}{_PyImport_Fini}{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	193 Finalize the import mechanism. For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	194 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	195
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	196 \begin{cfuncdesc}{PyObject}{_PyImport_FindExtension}{char , char *}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	197 For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	198 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	199
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	200 \begin{cfuncdesc}{PyObject}{_PyImport_FixupExtension}{char , char *}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	201 For internal use only.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	202 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	203
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	204 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	205 Load a frozen module named \var{name}. Return \code{1} for success,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	206 \code{0} if the module is not found, and \code{-1} with an exception
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	207 set if the initialization failed. To access the imported module on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	208 a successful load, use \cfunction{PyImport_ImportModule()}. (Note
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	209 the misnomer --- this function would reload the module if it was
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	210 already imported.)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	211 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	212
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	213 \begin{ctypedesc}[_frozen]{struct _frozen}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	214 This is the structure type definition for frozen module descriptors,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	215 as generated by the \program{freeze}\index{freeze utility} utility
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	216 (see \file{Tools/freeze/} in the Python source distribution). Its
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	217 definition, found in \file{Include/import.h}, is:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	218
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	219 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	220 struct _frozen {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	221 char *name;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	222 unsigned char *code;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	223 int size;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	224 };
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	225 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	226 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	227
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	228 \begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	229 This pointer is initialized to point to an array of \ctype{struct
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	230 _frozen} records, terminated by one whose members are all \NULL{} or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	231 zero. When a frozen module is imported, it is searched in this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	232 table. Third-party code could play tricks with this to provide a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	233 dynamically created collection of frozen modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	234 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	235
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	236 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	237 void (*initfunc)(void)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	238 Add a single module to the existing table of built-in modules. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239 is a convenience wrapper around
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	240 \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	241 table could not be extended. The new module can be imported by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	242 name \var{name}, and uses the function \var{initfunc} as the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	243 initialization function called on the first attempted import. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	244 should be called before \cfunction{Py_Initialize()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	245 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	246
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	247 \begin{ctypedesc}[_inittab]{struct _inittab}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	248 Structure describing a single entry in the list of built-in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	249 modules. Each of these structures gives the name and initialization
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	250 function for a module built into the interpreter. Programs which
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	251 embed Python may use an array of these structures in conjunction
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	252 with \cfunction{PyImport_ExtendInittab()} to provide additional
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	253 built-in modules. The structure is defined in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	254 \file{Include/import.h} as:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	255
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	256 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	257 struct _inittab {
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	258 char *name;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259 void (*initfunc)(void);
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	260 };
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	261 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	262 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	263
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	264 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	265 Add a collection of modules to the table of built-in modules. The
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266 \var{newtab} array must end with a sentinel entry which contains
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267 \NULL{} for the \member{name} field; failure to provide the sentinel
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	268 value can result in a memory fault. Returns \code{0} on success or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	269 \code{-1} if insufficient memory could be allocated to extend the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	270 internal table. In the event of failure, no modules are added to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	271 the internal table. This should be called before
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	272 \cfunction{Py_Initialize()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	273 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	274
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	275
20425 7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	276 \section{Data marshalling support \label{marshalling-utils}}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	277
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	278 These routines allow C code to work with serialized objects using the
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	279 same data format as the \module{marshal} module. There are functions
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	280 to write data into the serialization format, and additional functions
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	281 that can be used to read the data back. Files used to store marshalled
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	282 data must be opened in binary mode.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	283
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	284 Numeric values are stored with the least significant byte first.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	285
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	286 \begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	287 Marshal a \ctype{long} integer, \var{value}, to \var{file}. This
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	288 will only write the least-significant 32 bits of \var{value};
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	289 regardless of the size of the native \ctype{long} type.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	290 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	291
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	292 \begin{cfuncdesc}{void}{PyMarshal_WriteShortToFile}{short value, FILE *file}
23884 ea7e717dee27 Fix documentation for PyMarshal_WriteObjectToFile() and Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	293 Marshal a \ctype{short} integer, \var{value}, to \var{file}. This
ea7e717dee27 Fix documentation for PyMarshal_WriteObjectToFile() and Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	294 will only write the least-significant 16 bits of \var{value};
ea7e717dee27 Fix documentation for PyMarshal_WriteObjectToFile() and Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	295 regardless of the size of the native \ctype{short} type.
20425 7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	296 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	297
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	298 \begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	299 FILE *file}
23884 ea7e717dee27 Fix documentation for PyMarshal_WriteObjectToFile() and Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	300 Marshal a Python object, \var{value}, to \var{file}.
20425 7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	301 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	302
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	303 \begin{cfuncdesc}{PyObject}{PyMarshal_WriteObjectToString}{PyObject value}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	304 Return a string object containing the marshalled representation of
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	305 \var{value}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	306 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	307
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	308 The following functions allow marshalled values to be read back in.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	309
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	310 XXX What about error detection? It appears that reading past the end
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	311 of the file will always result in a negative numeric value (where
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	312 that's relevant), but it's not clear that negative values won't be
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	313 handled properly when there's no error. What's the right way to tell?
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	314 Should only non-negative values be written using these routines?
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	315
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	316 \begin{cfuncdesc}{long}{PyMarshal_ReadLongFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	317 Return a C \ctype{long} from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	318 opened for reading. Only a 32-bit value can be read in using
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	319 this function, regardless of the native size of \ctype{long}.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	320 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	321
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	322 \begin{cfuncdesc}{int}{PyMarshal_ReadShortFromFile}{FILE *file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	323 Return a C \ctype{short} from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	324 opened for reading. Only a 16-bit value can be read in using
23884 ea7e717dee27 Fix documentation for PyMarshal_WriteObjectToFile() and Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	325 this function, regardless of the native size of \ctype{short}.
20425 7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	326 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	327
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	328 \begin{cfuncdesc}{PyObject}{PyMarshal_ReadObjectFromFile}{FILE file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	329 Return a Python object from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	330 opened for reading. On error, sets the appropriate exception
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	331 (\exception{EOFError} or \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	332 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	333
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	334 \begin{cfuncdesc}{PyObject}{PyMarshal_ReadLastObjectFromFile}{FILE file}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	335 Return a Python object from the data stream in a \ctype{FILE*}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	336 opened for reading. Unlike
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	337 \cfunction{PyMarshal_ReadObjectFromFile()}, this function assumes
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	338 that no further objects will be read from the file, allowing it to
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	339 aggressively load file data into memory so that the de-serialization
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	340 can operate from data in memory rather than reading a byte at a time
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	341 from the file. Only use these variant if you are certain that you
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	342 won't be reading anything else from the file. On error, sets the
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	343 appropriate exception (\exception{EOFError} or
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	344 \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	345 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	346
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	347 \begin{cfuncdesc}{PyObject}{PyMarshal_ReadObjectFromString}{char string,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	348 int len}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	349 Return a Python object from the data stream in a character buffer
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	350 containing \var{len} bytes pointed to by \var{string}. On error,
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	351 sets the appropriate exception (\exception{EOFError} or
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	352 \exception{TypeError}) and returns \NULL.
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	353 \end{cfuncdesc}
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	354
7d1f490b6cb1 Added documentation for the functions listed in marshal.h. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	355
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	356 \section{Parsing arguments and building values
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	357 \label{arg-parsing}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	358
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	359 These functions are useful when creating your own extensions functions
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	360 and methods. Additional information and examples are available in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	361 \citetitle[../ext/ext.html]{Extending and Embedding the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	362 Interpreter}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	363
22857 e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	364 The first three of these functions described,
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	365 \cfunction{PyArg_ParseTuple()},
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	366 \cfunction{PyArg_ParseTupleAndKeywords()}, and
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	367 \cfunction{PyArg_Parse()}, all use \emph{format strings} which are
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	368 used to tell the function about the expected arguments. The format
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	369 strings use the same syntax for each of these functions.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	370
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	371 A format string consists of zero or more ``format units.'' A format
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	372 unit describes one Python object; it is usually a single character or
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	373 a parenthesized sequence of format units. With a few exceptions, a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	374 format unit that is not a parenthesized sequence normally corresponds
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	375 to a single address argument to these functions. In the following
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	376 description, the quoted form is the format unit; the entry in (round)
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	377 parentheses is the Python object type that matches the format unit;
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	378 and the entry in [square] brackets is the type of the C variable(s)
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	379 whose address should be passed.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	380
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	381 \begin{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	382 \item[\samp{s} (string or Unicode object) {[char *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	383 Convert a Python string or Unicode object to a C pointer to a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	384 character string. You must not provide storage for the string
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	385 itself; a pointer to an existing string is stored into the character
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	386 pointer variable whose address you pass. The C string is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	387 NUL-terminated. The Python string must not contain embedded NUL
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	388 bytes; if it does, a \exception{TypeError} exception is raised.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	389 Unicode objects are converted to C strings using the default
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	390 encoding. If this conversion fails, a \exception{UnicodeError} is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	391 raised.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	392
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	393 \item[\samp{s\#} (string, Unicode or any read buffer compatible object)
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	394 {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	395 This variant on \samp{s} stores into two C variables, the first one
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	396 a pointer to a character string, the second one its length. In this
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	397 case the Python string may contain embedded null bytes. Unicode
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	398 objects pass back a pointer to the default encoded string version of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	399 the object if such a conversion is possible. All other read-buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	400 compatible objects pass back a reference to the raw internal data
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	401 representation.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	402
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	403 \item[\samp{z} (string or \code{None}) {[char *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	404 Like \samp{s}, but the Python object may also be \code{None}, in
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	405 which case the C pointer is set to \NULL.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	406
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	407 \item[\samp{z\#} (string or \code{None} or any read buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	408 compatible object) {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	409 This is to \samp{s\#} as \samp{z} is to \samp{s}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	410
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	411 \item[\samp{u} (Unicode object) {[Py_UNICODE *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	412 Convert a Python Unicode object to a C pointer to a NUL-terminated
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	413 buffer of 16-bit Unicode (UTF-16) data. As with \samp{s}, there is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	414 no need to provide storage for the Unicode data buffer; a pointer to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	415 the existing Unicode data is stored into the \ctype{Py_UNICODE}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	416 pointer variable whose address you pass.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	417
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	418 \item[\samp{u\#} (Unicode object) {[Py_UNICODE *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	419 This variant on \samp{u} stores into two C variables, the first one
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	420 a pointer to a Unicode data buffer, the second one its length.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	421 Non-Unicode objects are handled by interpreting their read-buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	422 pointer as pointer to a \ctype{Py_UNICODE} array.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	423
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	424 \item[\samp{es} (string, Unicode object or character buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	425 compatible object) {[const char encoding, char *buffer]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	426 This variant on \samp{s} is used for encoding Unicode and objects
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	427 convertible to Unicode into a character buffer. It only works for
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	428 encoded data without embedded NUL bytes.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	429
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	430 This format requires two arguments. The first is only used as
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	431 input, and must be a \ctype{char*} which points to the name of an
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	432 encoding as a NUL-terminated string, or \NULL, in which case the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	433 default encoding is used. An exception is raised if the named
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	434 encoding is not known to Python. The second argument must be a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	435 \ctype{char**}; the value of the pointer it references will be set
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	436 to a buffer with the contents of the argument text. The text will
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	437 be encoded in the encoding specified by the first argument.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	438
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	439 \cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	440 size, copy the encoded data into this buffer and adjust
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	441 \var{*buffer} to reference the newly allocated storage. The caller
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	442 is responsible for calling \cfunction{PyMem_Free()} to free the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	443 allocated buffer after use.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	444
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	445 \item[\samp{et} (string, Unicode object or character buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	446 compatible object) {[const char encoding, char *buffer]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	447 Same as \samp{es} except that 8-bit string objects are passed
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	448 through without recoding them. Instead, the implementation assumes
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	449 that the string object uses the encoding passed in as parameter.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	450
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	451 \item[\samp{es\#} (string, Unicode object or character buffer compatible
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	452 object) {[const char encoding, char buffer, int buffer_length]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	453 This variant on \samp{s\#} is used for encoding Unicode and objects
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	454 convertible to Unicode into a character buffer. Unlike the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	455 \samp{es} format, this variant allows input data which contains NUL
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	456 characters.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	457
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	458 It requires three arguments. The first is only used as input, and
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	459 must be a \ctype{char*} which points to the name of an encoding as a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	460 NUL-terminated string, or \NULL, in which case the default encoding
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	461 is used. An exception is raised if the named encoding is not known
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	462 to Python. The second argument must be a \ctype{char**}; the value
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	463 of the pointer it references will be set to a buffer with the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	464 contents of the argument text. The text will be encoded in the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	465 encoding specified by the first argument. The third argument must
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	466 be a pointer to an integer; the referenced integer will be set to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	467 the number of bytes in the output buffer.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	468
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	469 There are two modes of operation:
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	470
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	471 If \var{*buffer} points a \NULL{} pointer, the function will
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	472 allocate a buffer of the needed size, copy the encoded data into
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	473 this buffer and set \var{*buffer} to reference the newly allocated
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	474 storage. The caller is responsible for calling
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	475 \cfunction{PyMem_Free()} to free the allocated buffer after usage.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	476
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	477 If \var{*buffer} points to a non-\NULL{} pointer (an already
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	478 allocated buffer), \cfunction{PyArg_ParseTuple()} will use this
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	479 location as the buffer and interpret the initial value of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	480 \var{*buffer_length} as the buffer size. It will then copy the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	481 encoded data into the buffer and NUL-terminate it. If the buffer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	482 is not large enough, a \exception{ValueError} will be set.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	483
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	484 In both cases, \var{*buffer_length} is set to the length of the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	485 encoded data without the trailing NUL byte.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	486
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	487 \item[\samp{et\#} (string, Unicode object or character buffer compatible
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	488 object) {[const char encoding, char *buffer]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	489 Same as \samp{es\#} except that string objects are passed through
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	490 without recoding them. Instead, the implementation assumes that the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	491 string object uses the encoding passed in as parameter.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	492
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	493 \item[\samp{b} (integer) {[char]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	494 Convert a Python integer to a tiny int, stored in a C \ctype{char}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	495
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	496 \item[\samp{h} (integer) {[short int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	497 Convert a Python integer to a C \ctype{short int}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	498
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	499 \item[\samp{i} (integer) {[int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	500 Convert a Python integer to a plain C \ctype{int}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	501
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	502 \item[\samp{l} (integer) {[long int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	503 Convert a Python integer to a C \ctype{long int}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	504
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	505 \item[\samp{L} (integer) {[LONG_LONG]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	506 Convert a Python integer to a C \ctype{long long}. This format is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	507 only available on platforms that support \ctype{long long} (or
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	508 \ctype{_int64} on Windows).
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	509
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	510 \item[\samp{c} (string of length 1) {[char]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	511 Convert a Python character, represented as a string of length 1, to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	512 a C \ctype{char}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	513
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	514 \item[\samp{f} (float) {[float]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	515 Convert a Python floating point number to a C \ctype{float}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	516
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	517 \item[\samp{d} (float) {[double]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	518 Convert a Python floating point number to a C \ctype{double}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	519
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	520 \item[\samp{D} (complex) {[Py_complex]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	521 Convert a Python complex number to a C \ctype{Py_complex} structure.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	522
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	523 \item[\samp{O} (object) {[PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	524 Store a Python object (without any conversion) in a C object
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	525 pointer. The C program thus receives the actual object that was
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	526 passed. The object's reference count is not increased. The pointer
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	527 stored is not \NULL.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	528
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	529 \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	530 Store a Python object in a C object pointer. This is similar to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	531 \samp{O}, but takes two C arguments: the first is the address of a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	532 Python type object, the second is the address of the C variable (of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	533 type \ctype{PyObject*}) into which the object pointer is stored. If
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	534 the Python object does not have the required type,
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	535 \exception{TypeError} is raised.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	536
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	537 \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	538 Convert a Python object to a C variable through a \var{converter}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	539 function. This takes two arguments: the first is a function, the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	540 second is the address of a C variable (of arbitrary type), converted
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	541 to \ctype{void *}. The \var{converter} function in turn is called
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	542 as follows:
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	543
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	544 \var{status}\code{ = }\var{converter}\code{(}\var{object},
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	545 \var{address}\code{);}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	546
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	547 where \var{object} is the Python object to be converted and
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	548 \var{address} is the \ctype{void*} argument that was passed to the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	549 \cfunction{PyArg_Parse*()} function. The returned \var{status}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	550 should be \code{1} for a successful conversion and \code{0} if the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	551 conversion has failed. When the conversion fails, the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	552 \var{converter} function should raise an exception.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	553
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	554 \item[\samp{S} (string) {[PyStringObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	555 Like \samp{O} but requires that the Python object is a string
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	556 object. Raises \exception{TypeError} if the object is not a string
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	557 object. The C variable may also be declared as \ctype{PyObject*}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	558
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	559 \item[\samp{U} (Unicode string) {[PyUnicodeObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	560 Like \samp{O} but requires that the Python object is a Unicode
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	561 object. Raises \exception{TypeError} if the object is not a Unicode
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	562 object. The C variable may also be declared as \ctype{PyObject*}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	563
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	564 \item[\samp{t\#} (read-only character buffer) {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	565 Like \samp{s\#}, but accepts any object which implements the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	566 read-only buffer interface. The \ctype{char*} variable is set to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	567 point to the first byte of the buffer, and the \ctype{int} is set to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	568 the length of the buffer. Only single-segment buffer objects are
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	569 accepted; \exception{TypeError} is raised for all others.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	570
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	571 \item[\samp{w} (read-write character buffer) {[char *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	572 Similar to \samp{s}, but accepts any object which implements the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	573 read-write buffer interface. The caller must determine the length
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	574 of the buffer by other means, or use \samp{w\#} instead. Only
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	575 single-segment buffer objects are accepted; \exception{TypeError} is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	576 raised for all others.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	577
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	578 \item[\samp{w\#} (read-write character buffer) {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	579 Like \samp{s\#}, but accepts any object which implements the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	580 read-write buffer interface. The \ctype{char *} variable is set to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	581 point to the first byte of the buffer, and the \ctype{int} is set to
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	582 the length of the buffer. Only single-segment buffer objects are
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	583 accepted; \exception{TypeError} is raised for all others.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	584
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	585 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	586 The object must be a Python sequence whose length is the number of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	587 format units in \var{items}. The C arguments must correspond to the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	588 individual format units in \var{items}. Format units for sequences
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	589 may be nested.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	590
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	591 \note{Prior to Python version 1.5.2, this format specifier only
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	592 accepted a tuple containing the individual parameters, not an
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	593 arbitrary sequence. Code which previously caused
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	594 \exception{TypeError} to be raised here may now proceed without an
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	595 exception. This is not expected to be a problem for existing code.}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	596 \end{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	597
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	598 It is possible to pass Python long integers where integers are
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	599 requested; however no proper range checking is done --- the most
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	600 significant bits are silently truncated when the receiving field is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	601 too small to receive the value (actually, the semantics are inherited
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	602 from downcasts in C --- your mileage may vary).
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	603
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	604 A few other characters have a meaning in a format string. These may
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	605 not occur inside nested parentheses. They are:
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	606
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	607 \begin{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	608 \item[\samp{\|}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	609 Indicates that the remaining arguments in the Python argument list
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	610 are optional. The C variables corresponding to optional arguments
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	611 should be initialized to their default value --- when an optional
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	612 argument is not specified, \cfunction{PyArg_ParseTuple()} does not
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	613 touch the contents of the corresponding C variable(s).
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	614
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	615 \item[\samp{:}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	616 The list of format units ends here; the string after the colon is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	617 used as the function name in error messages (the ``associated
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	618 value'' of the exception that \cfunction{PyArg_ParseTuple()}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	619 raises).
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	620
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	621 \item[\samp{;}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	622 The list of format units ends here; the string after the semicolon
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	623 is used as the error message \emph{instead} of the default error
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	624 message. Clearly, \samp{:} and \samp{;} mutually exclude each
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	625 other.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	626 \end{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	627
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	628 Note that any Python object references which are provided to the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	629 caller are \emph{borrowed} references; do not decrement their
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	630 reference count!
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	631
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	632 Additional arguments passed to these functions must be addresses of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	633 variables whose type is determined by the format string; these are
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	634 used to store values from the input tuple. There are a few cases, as
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	635 described in the list of format units above, where these parameters
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	636 are used as input values; they should match what is specified for the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	637 corresponding format unit in that case.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	638
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	639 For the conversion to succeed, the \var{arg} object must match the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	640 format and the format must be exhausted. On success, the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	641 \cfunction{PyArg_Parse*()} functions return true, otherwise they
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	642 return false and raise an appropriate exception.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	643
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	644 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject args, char format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	645 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	646 Parse the parameters of a function that takes only positional
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	647 parameters into local variables. Returns true on success; on
22857 e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	648 failure, it returns false and raises the appropriate exception.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	649 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	650
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	651 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	652 PyObject kw, char format, char *keywords[],
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	653 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	654 Parse the parameters of a function that takes both positional and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	655 keyword parameters into local variables. Returns true on success;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	656 on failure, it returns false and raises the appropriate exception.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	657 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	658
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	659 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject args, char format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	660 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	661 Function used to deconstruct the argument lists of ``old-style''
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	662 functions --- these are functions which use the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	663 \constant{METH_OLDARGS} parameter parsing method. This is not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	664 recommended for use in parameter parsing in new code, and most code
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	665 in the standard interpreter has been modified to no longer use this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	666 for that purpose. It does remain a convenient way to decompose
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	667 other tuples, however, and may continue to be used for that
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	668 purpose.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	669 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	670
20633 fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	671 \begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject args, char name,
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	672 int min, int max, \moreargs}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	673 A simpler form of parameter retrieval which does not use a format
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	674 string to specify the types of the arguments. Functions which use
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	675 this method to retrieve their parameters should be declared as
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	676 \constant{METH_VARARGS} in function or method tables. The tuple
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	677 containing the actual parameters should be passed as \var{args}; it
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	678 must actually be a tuple. The length of the tuple must be at least
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	679 \var{min} and no more than \var{max}; \var{min} and \var{max} may be
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	680 equal. Additional arguments must be passed to the function, each of
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	681 which should be a pointer to a \ctype{PyObject*} variable; these
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	682 will be filled in with the values from \var{args}; they will contain
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	683 borrowed references. The variables which correspond to optional
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	684 parameters not given by \var{args} will not be filled in; these
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	685 should be initialized by the caller.
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	686 This function returns true on success and false if \var{args} is not
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	687 a tuple or contains the wrong number of elements; an exception will
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	688 be set if there was a failure.
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	689
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	690 This is an example of the use of this function, taken from the
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	691 sources for the \module{_weakref} helper module for weak references:
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	692
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	693 \begin{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	694 static PyObject *
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	695 weakref_ref(PyObject self, PyObject args)
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	696 {
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	697 PyObject *object;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	698 PyObject *callback = NULL;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	699 PyObject *result = NULL;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	700
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	701 if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	702 result = PyWeakref_NewRef(object, callback);
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	703 }
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	704 return result;
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	705 }
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	706 \end{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	707
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	708 The call to \cfunction{PyArg_UnpackTuple()} in this example is
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	709 entirely equivalent to this call to \cfunction{PyArg_ParseTuple()}:
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	710
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	711 \begin{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	712 PyArg_ParseTuple(args, "O\|O:ref", &object, &callback)
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	713 \end{verbatim}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	714
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	715 \versionadded{2.2}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	716 \end{cfuncdesc}
fed8a18894f5 Documentation for the new PyArg_UnpackTuple() function. Fred Drake <fdrake@acm.org> parents: 20425 diff changeset	717
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	718 \begin{cfuncdesc}{PyObject}{Py_BuildValue}{char format,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	719 \moreargs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	720 Create a new value based on a format string similar to those
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	721 accepted by the \cfunction{PyArg_Parse*()} family of functions and a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	722 sequence of values. Returns the value or \NULL{} in the case of an
22857 e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	723 error; an exception will be raised if \NULL{} is returned.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	724
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	725 \cfunction{Py_BuildValue()} does not always build a tuple. It
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	726 builds a tuple only if its format string contains two or more format
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	727 units. If the format string is empty, it returns \code{None}; if it
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	728 contains exactly one format unit, it returns whatever object is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	729 described by that format unit. To force it to return a tuple of
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	730 size 0 or one, parenthesize the format string.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	731
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	732 When memory buffers are passed as parameters to supply data to build
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	733 objects, as for the \samp{s} and \samp{s\#} formats, the required
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	734 data is copied. Buffers provided by the caller are never referenced
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	735 by the objects created by \cfunction{Py_BuildValue()}. In other
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	736 words, if your code invokes \cfunction{malloc()} and passes the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	737 allocated memory to \cfunction{Py_BuildValue()}, your code is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	738 responsible for calling \cfunction{free()} for that memory once
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	739 \cfunction{Py_BuildValue()} returns.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	740
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	741 In the following description, the quoted form is the format unit;
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	742 the entry in (round) parentheses is the Python object type that the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	743 format unit will return; and the entry in [square] brackets is the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	744 type of the C value(s) to be passed.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	745
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	746 The characters space, tab, colon and comma are ignored in format
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	747 strings (but not within format units such as \samp{s\#}). This can
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	748 be used to make long format strings a tad more readable.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	749
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	750 \begin{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	751 \item[\samp{s} (string) {[char *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	752 Convert a null-terminated C string to a Python object. If the C
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	753 string pointer is \NULL, \code{None} is used.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	754
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	755 \item[\samp{s\#} (string) {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	756 Convert a C string and its length to a Python object. If the C
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	757 string pointer is \NULL, the length is ignored and \code{None} is
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	758 returned.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	759
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	760 \item[\samp{z} (string or \code{None}) {[char *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	761 Same as \samp{s}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	762
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	763 \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	764 Same as \samp{s\#}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	765
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	766 \item[\samp{u} (Unicode string) {[Py_UNICODE *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	767 Convert a null-terminated buffer of Unicode (UCS-2) data to a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	768 Python Unicode object. If the Unicode buffer pointer is \NULL,
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	769 \code{None} is returned.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	770
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	771 \item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	772 Convert a Unicode (UCS-2) data buffer and its length to a Python
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	773 Unicode object. If the Unicode buffer pointer is \NULL, the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	774 length is ignored and \code{None} is returned.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	775
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	776 \item[\samp{i} (integer) {[int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	777 Convert a plain C \ctype{int} to a Python integer object.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	778
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	779 \item[\samp{b} (integer) {[char]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	780 Same as \samp{i}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	781
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	782 \item[\samp{h} (integer) {[short int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	783 Same as \samp{i}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	784
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	785 \item[\samp{l} (integer) {[long int]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	786 Convert a C \ctype{long int} to a Python integer object.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	787
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	788 \item[\samp{c} (string of length 1) {[char]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	789 Convert a C \ctype{int} representing a character to a Python
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	790 string of length 1.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	791
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	792 \item[\samp{d} (float) {[double]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	793 Convert a C \ctype{double} to a Python floating point number.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	794
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	795 \item[\samp{f} (float) {[float]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	796 Same as \samp{d}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	797
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	798 \item[\samp{D} (complex) {[Py_complex *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	799 Convert a C \ctype{Py_complex} structure to a Python complex
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	800 number.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	801
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	802 \item[\samp{O} (object) {[PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	803 Pass a Python object untouched (except for its reference count,
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	804 which is incremented by one). If the object passed in is a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	805 \NULL{} pointer, it is assumed that this was caused because the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	806 call producing the argument found an error and set an exception.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	807 Therefore, \cfunction{Py_BuildValue()} will return \NULL{} but
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	808 won't raise an exception. If no exception has been raised yet,
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	809 \exception{SystemError} is set.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	810
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	811 \item[\samp{S} (object) {[PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	812 Same as \samp{O}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	813
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	814 \item[\samp{U} (object) {[PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	815 Same as \samp{O}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	816
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	817 \item[\samp{N} (object) {[PyObject *]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	818 Same as \samp{O}, except it doesn't increment the reference count
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	819 on the object. Useful when the object is created by a call to an
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	820 object constructor in the argument list.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	821
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	822 \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	823 Convert \var{anything} to a Python object through a
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	824 \var{converter} function. The function is called with
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	825 \var{anything} (which should be compatible with \ctype{void *}) as
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	826 its argument and should return a ``new'' Python object, or \NULL{}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	827 if an error occurred.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	828
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	829 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	830 Convert a sequence of C values to a Python tuple with the same
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	831 number of items.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	832
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	833 \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	834 Convert a sequence of C values to a Python list with the same
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	835 number of items.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	836
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	837 \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	838 Convert a sequence of C values to a Python dictionary. Each pair
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	839 of consecutive C values adds one item to the dictionary, serving
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	840 as key and value, respectively.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	841
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	842 \end{description}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	843
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	844 If there is an error in the format string, the
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 20633 diff changeset	845 \exception{SystemError} exception is set and \NULL{} returned.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	846 \end{cfuncdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/utilities.tex @ 27998:e27f58a50737 legacy-trunk