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