| \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, 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 and on the Macintosh). \constant{USE_CHECKSTACK} 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 finallization 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}{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 (the module may still be created in this case --- |
| examine \code{sys.modules} to find out). |
| \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 (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. |
| \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}{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 in 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 (the module may still be |
| created in this case). This function would reload the module if it |
| was already imported. 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. |
| \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. |
| |
| \begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file} |
| 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. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value, |
| FILE *file} |
| Marshal a Python object, \var{value}, to \var{file}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value} |
| Return a string object containing the marshalled representation of |
| \var{value}. |
| \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, |
| int 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) {[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) |
| {[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}) {[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) {[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{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{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{h} (integer) {[short int]}] |
| Convert a Python integer to a C \ctype{short int}. |
| |
| \item[\samp{i} (integer) {[int]}] |
| Convert a Python integer to a plain C \ctype{int}. |
| |
| \item[\samp{l} (integer) {[long int]}] |
| Convert a Python integer to a C \ctype{long int}. |
| |
| \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{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, 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_ParseTupleAndKeywords}{PyObject *args, |
| PyObject *kw, 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_Parse}{PyObject *args, 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, char *name, |
| int min, int 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}{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) 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) 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]}] |
| Same as \samp{i}. |
| |
| \item[\samp{h} (integer) {[short int]}] |
| Same as \samp{i}. |
| |
| \item[\samp{l} (integer) {[long int]}] |
| Convert a C \ctype{long int} to a Python integer object. |
| |
| \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{U} (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} |