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