This is /home/pdm/install/Python-2.1/Doc/api/python-api.info, produced by makeinfo version 4.0 from api.texi. April 15, 2001 2.1  File: python-api.info, Node: Standard Exceptions, Next: Deprecation of String Exceptions, Prev: Exception Handling, Up: Exception Handling Standard Exceptions =================== All standard Python exceptions are available as global variables whose names are `PyExc_' followed by the Python exception name. These have the type `PyObject*'; they are all class objects. For completeness, here are all the variables: C Name Python Name Notes ------ ----- ----- PyExc_Exception `Exception' (1) PyExc_StandardError `StandardError' (1) PyExc_ArithmeticError `ArithmeticError' (1) PyExc_LookupError `LookupError' (1) PyExc_AssertionError `AssertionError' PyExc_AttributeError `AttributeError' PyExc_EOFError `EOFError' PyExc_EnvironmentError `EnvironmentError' (1) PyExc_FloatingPointError `FloatingPointError' PyExc_IOError `IOError' PyExc_ImportError `ImportError' PyExc_IndexError `IndexError' PyExc_KeyError `KeyError' PyExc_KeyboardInterrupt `KeyboardInterrupt' PyExc_MemoryError `MemoryError' PyExc_NameError `NameError' PyExc_NotImplementedError`NotImplementedError' PyExc_OSError `OSError' PyExc_OverflowError `OverflowError' PyExc_RuntimeError `RuntimeError' PyExc_SyntaxError `SyntaxError' PyExc_SystemError `SystemError' PyExc_SystemExit `SystemExit' PyExc_TypeError `TypeError' PyExc_ValueError `ValueError' PyExc_WindowsError `WindowsError' (2) PyExc_ZeroDivisionError `ZeroDivisionError' Notes: `(1)' This is a base class for other standard exceptions. `(2)' Only defined on Windows; protect code that uses this by testing that the preprocessor macro `MS_WINDOWS' is defined.  File: python-api.info, Node: Deprecation of String Exceptions, Prev: Standard Exceptions, Up: Exception Handling Deprecation of String Exceptions ================================ All exceptions built into Python or provided in the standard library are derived from `Exception'. String exceptions are still supported in the interpreter to allow existing code to run unmodified, but this will also change in a future release.  File: python-api.info, Node: Utilities, Next: Abstract Objects Layer, Prev: Exception Handling, Up: Top Utilities ********* The functions in this chapter perform various utility tasks, such as parsing function arguments and constructing Python values from C values. * Menu: * OS Utilities:: * Process Control:: * Importing Modules::  File: python-api.info, Node: OS Utilities, Next: Process Control, Prev: Utilities, Up: Utilities OS Utilities ============ `int Py_FdIsInteractive(FILE *fp, 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 `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 `''' or `'???''. `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 `time()'. `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. `int PyOS_CheckStack()' Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when `USE_STACKCHECK' is defined (currently on Windows using the Microsoft Visual C++ compiler and on the Macintosh). `USE_CHECKSTACK' will be defined automatically; you should never change the definition in your own code. `PyOS_sighandler_t PyOS_getsig(int i)' Return the current signal handler for signal I. This is a thin wrapper around either `sigaction' or `signal'. Do not call those functions directly! `PyOS_sighandler_t' is a typedef alias for `void (*)(int)'. `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 `sigaction' or `signal'. Do not call those functions directly! `PyOS_sighandler_t' is a typedef alias for `void (*)(int)'.  File: python-api.info, Node: Process Control, Next: Importing Modules, Prev: OS Utilities, Up: Utilities Process Control =============== `void Py_FatalError(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 `abort()' is called which will attempt to produce a `core' file. `void Py_Exit(int status)' Exit the current process. This calls `Py_Finalize()' and then calls the standard C library function `exit(STATUS)'. `int Py_AtExit(void (*func) ())' Register a cleanup function to be called by `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, `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 finallization will have completed before the cleanup function, no Python APIs should be called by FUNC.  File: python-api.info, Node: Importing Modules, Prev: Process Control, Up: Utilities Importing Modules ================= `PyObject* PyImport_ImportModule(char *name)' This is a simplified interface to `PyImport_ImportModuleEx()' below, leaving the GLOBALS and LOCALS arguments set to `NULL'. When the NAME argument contains a dot (i.e., 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 (the module may still be created in this case -- examine `sys.modules' to find out). `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 `__import__()', as the standard `__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 `__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. `PyObject* PyImport_Import(PyObject *name)' This is a higher-level interface that calls the current "import hook function". It invokes the `__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, e.g. by `rexec' or `ihooks'. `PyObject* PyImport_ReloadModule(PyObject *m)' Reload a module. This is best described by referring to the built-in Python function `reload()', as the standard `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). `PyObject* PyImport_AddModule(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 in in the modules dictionary. Warning: this function does not load or import the module; if the module wasn't already loaded, you will get an empty module object. Use `PyImport_ImportModule()' or one of its variants to import a module. Return `NULL' with an exception set on failure. `PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)' 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 `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.) `long PyImport_GetMagicNumber()' Return the magic number for Python bytecode files (a.k.a. `.pyc' and `.pyo' files). The magic number should be present in the first four bytes of the bytecode file, in little-endian byte order. `PyObject* PyImport_GetModuleDict()' Return the dictionary used for the module administration (a.k.a. `sys.modules'). Note that this is a per-interpreter variable. `void _PyImport_Init()' Initialize the import mechanism. For internal use only. `void PyImport_Cleanup()' Empty the module table. For internal use only. `void _PyImport_Fini()' Finalize the import mechanism. For internal use only. `PyObject* _PyImport_FindExtension(char *, char *)' For internal use only. `PyObject* _PyImport_FixupExtension(char *, char *)' For internal use only. `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 `PyImport_ImportModule()'. (Note the misnomer -- this function would reload the module if it was already imported.) `struct _frozen' This is the structure type definition for frozen module descriptors, as generated by the `freeze' utility (see `Tools/freeze/' in the Python source distribution). Its definition, found in `Include/import.h', is: struct _frozen { char *name; unsigned char *code; int size; }; `struct _frozen* PyImport_FrozenModules' This pointer is initialized to point to an array of `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. `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 `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 `Py_Initialize()'. `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 `PyImport_ExtendInittab()' to provide additional built-in modules. The structure is defined in `Include/import.h' as: struct _inittab { char *name; void (*initfunc)(void); }; `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 `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 `Py_Initialize()'.  File: python-api.info, Node: Abstract Objects Layer, Next: Concrete Objects Layer, Prev: Utilities, Up: Top Abstract Objects Layer ********************** The functions in this chapter interact with Python objects regardless of their type, or with wide classes of object types (e.g. all numerical types, or all sequence types). When used on object types for which they do not apply, they will raise a Python exception. * Menu: * Object Protocol:: * Number Protocol:: * Sequence Protocol:: * Mapping Protocol::  File: python-api.info, Node: Object Protocol, Next: Number Protocol, Prev: Abstract Objects Layer, Up: Abstract Objects Layer Object Protocol =============== `int PyObject_Print(PyObject *o, FILE *fp, int flags)' Print an object O, on file FP. Returns `-1' on error. The flags argument is used to enable certain printing options. The only option currently supported is `Py_PRINT_RAW'; if given, the `str()' of the object is written instead of the `repr()'. `int PyObject_HasAttrString(PyObject *o, char *attr_name)' Returns `1' if O has the attribute ATTR_NAME, and `0' otherwise. This is equivalent to the Python expression `hasattr(O, ATTR_NAME)'. This function always succeeds. `PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name)' Retrieve an attribute named ATTR_NAME from object O. Returns the attribute value on success, or `NULL' on failure. This is the equivalent of the Python expression `O.ATTR_NAME'. `int PyObject_HasAttr(PyObject *o, PyObject *attr_name)' Returns `1' if O has the attribute ATTR_NAME, and `0' otherwise. This is equivalent to the Python expression `hasattr(O, ATTR_NAME)'. This function always succeeds. `PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)' Retrieve an attribute named ATTR_NAME from object O. Returns the attribute value on success, or `NULL' on failure. This is the equivalent of the Python expression `O.ATTR_NAME'. `int PyObject_SetAttrString(PyObject *o, char *attr_name, PyObject *v)' Set the value of the attribute named ATTR_NAME, for object O, to the value V. Returns `-1' on failure. This is the equivalent of the Python statement `O.ATTR_NAME = V'. `int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)' Set the value of the attribute named ATTR_NAME, for object O, to the value V. Returns `-1' on failure. This is the equivalent of the Python statement `O.ATTR_NAME = V'. `int PyObject_DelAttrString(PyObject *o, char *attr_name)' Delete attribute named ATTR_NAME, for object O. Returns `-1' on failure. This is the equivalent of the Python statement: `del O.ATTR_NAME'. `int PyObject_DelAttr(PyObject *o, PyObject *attr_name)' Delete attribute named ATTR_NAME, for object O. Returns `-1' on failure. This is the equivalent of the Python statement `del O.ATTR_NAME'. `int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)' Compare the values of O1 and O2 using a routine provided by O1, if one exists, otherwise with a routine provided by O2. The result of the comparison is returned in RESULT. Returns `-1' on failure. This is the equivalent of the Python statement `RESULT = cmp(O1, O2)'. `int PyObject_Compare(PyObject *o1, PyObject *o2)' Compare the values of O1 and O2 using a routine provided by O1, if one exists, otherwise with a routine provided by O2. Returns the result of the comparison on success. On error, the value returned is undefined; use `PyErr_Occurred()' to detect an error. This is equivalent to the Python expression `cmp(O1, O2)'. `PyObject* PyObject_Repr(PyObject *o)' Compute a string representation of object O. Returns the string representation on success, `NULL' on failure. This is the equivalent of the Python expression `repr(O)'. Called by the `repr()' built-in function and by reverse quotes. `PyObject* PyObject_Str(PyObject *o)' Compute a string representation of object O. Returns the string representation on success, `NULL' on failure. This is the equivalent of the Python expression `str(O)'. Called by the `str()' built-in function and by the `print' statement. `PyObject* PyObject_Unicode(PyObject *o)' Compute a Unicode string representation of object O. Returns the Unicode string representation on success, `NULL' on failure. This is the equivalent of the Python expression `unistr(O)'. Called by the `unistr()' built-in function. `int PyObject_IsInstance(PyObject *inst, PyObject *cls)' Return `1' if INST is an instance of the class CLS or a subclass of CLS. If CLS is a type object rather than a class object, `PyObject_IsInstance()' returns `1' if INST is of type CLS. If INST is not a class instance and CLS is neither a type object or class object, INST must have a `__class__' attribute -- the class relationship of the value of that attribute with CLS will be used to determine the result of this function. _Added in Python version 2.1_ Subclass determination is done in a fairly straightforward way, but includes a wrinkle that implementors of extensions to the class system may want to be aware of. If `A' and `B' are class objects, `B' is a subclass of `A' if it inherits from `A' either directly or indirectly. If either is not a class object, a more general mechanism is used to determine the class relationship of the two objects. When testing if B is a subclass of A, if A is B, `PyObject_IsSubclass()' returns true. If A and B are different objects, B's `__bases__' attribute is searched in a depth-first fashion for A -- the presence of the `__bases__' attribute is considered sufficient for this determination. `int PyObject_IsSubclass(PyObject *derived, PyObject *cls)' Returns `1' if the class DERIVED is identical to or derived from the class CLS, otherwise returns `0'. In case of an error, returns `-1'. If either DERIVED or CLS is not an actual class object, this function uses the generic algorithm described above. _Added in Python version 2.1_ `int PyCallable_Check(PyObject *o)' Determine if the object O is callable. Return `1' if the object is callable and `0' otherwise. This function always succeeds. `PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)' Call a callable Python object CALLABLE_OBJECT, with arguments given by the tuple ARGS. If no arguments are needed, then ARGS may be `NULL'. Returns the result of the call on success, or `NULL' on failure. This is the equivalent of the Python expression `apply(CALLABLE_OBJECT, ARGS)'. `PyObject* PyObject_CallFunction(PyObject *callable_object, char *format, ...)' Call a callable Python object CALLABLE_OBJECT, with a variable number of C arguments. The C arguments are described using a `Py_BuildValue()' style format string. The format may be `NULL', indicating that no arguments are provided. Returns the result of the call on success, or `NULL' on failure. This is the equivalent of the Python expression `apply(CALLABLE_OBJECT, ARGS)'. `PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)' Call the method named M of object O with a variable number of C arguments. The C arguments are described by a `Py_BuildValue()' format string. The format may be `NULL', indicating that no arguments are provided. Returns the result of the call on success, or `NULL' on failure. This is the equivalent of the Python expression `O.METHOD(ARGS)'. Note that special method names, such as `__add__()', `__getitem__()', and so on are not supported. The specific abstract-object routines for these must be used. `int PyObject_Hash(PyObject *o)' Compute and return the hash value of an object O. On failure, return `-1'. This is the equivalent of the Python expression `hash(O)'. `int PyObject_IsTrue(PyObject *o)' Returns `1' if the object O is considered to be true, and `0' otherwise. This is equivalent to the Python expression `not not O'. This function always succeeds. `PyObject* PyObject_Type(PyObject *o)' On success, returns a type object corresponding to the object type of object O. On failure, returns `NULL'. This is equivalent to the Python expression `type(O)'. `int PyObject_Length(PyObject *o)' Return the length of object O. If the object O provides both sequence and mapping protocols, the sequence length is returned. On error, `-1' is returned. This is the equivalent to the Python expression `len(O)'. `PyObject* PyObject_GetItem(PyObject *o, PyObject *key)' Return element of O corresponding to the object KEY or `NULL' on failure. This is the equivalent of the Python expression `O[KEY]'. `int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)' Map the object KEY to the value V. Returns `-1' on failure. This is the equivalent of the Python statement `O[KEY] = V'. `int PyObject_DelItem(PyObject *o, PyObject *key)' Delete the mapping for KEY from O. Returns `-1' on failure. This is the equivalent of the Python statement `del O[KEY]'. `int PyObject_AsFileDescriptor(PyObject *o)' Derives a file-descriptor from a Python object. If the object is an integer or long integer, its value is returned. If not, the object's `fileno()' method is called if it exists; the method must return an integer or long integer, which is returned as the file descriptor value. Returns `-1' on failure.  File: python-api.info, Node: Number Protocol, Next: Sequence Protocol, Prev: Object Protocol, Up: Abstract Objects Layer Number Protocol =============== `int PyNumber_Check(PyObject *o)' Returns `1' if the object O provides numeric protocols, and false otherwise. This function always succeeds. `PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)' Returns the result of adding O1 and O2, or `NULL' on failure. This is the equivalent of the Python expression `O1 + O2'. `PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)' Returns the result of subtracting O2 from O1, or `NULL' on failure. This is the equivalent of the Python expression `O1 - O2'. `PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)' Returns the result of multiplying O1 and O2, or `NULL' on failure. This is the equivalent of the Python expression `O1 * O2'. `PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)' Returns the result of dividing O1 by O2, or `NULL' on failure. This is the equivalent of the Python expression `O1 / O2'. `PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)' Returns the remainder of dividing O1 by O2, or `NULL' on failure. This is the equivalent of the Python expression `O1 % O2'. `PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)' See the built-in function `divmod()'. Returns `NULL' on failure. This is the equivalent of the Python expression `divmod(O1, O2)'. `PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)' See the built-in function `pow()'. Returns `NULL' on failure. This is the equivalent of the Python expression `pow(O1, O2, O3)', where O3 is optional. If O3 is to be ignored, pass `Py_None' in its place (passing `NULL' for O3 would cause an illegal memory access). `PyObject* PyNumber_Negative(PyObject *o)' Returns the negation of O on success, or `NULL' on failure. This is the equivalent of the Python expression `-O'. `PyObject* PyNumber_Positive(PyObject *o)' Returns O on success, or `NULL' on failure. This is the equivalent of the Python expression `+O'. `PyObject* PyNumber_Absolute(PyObject *o)' Returns the absolute value of O, or `NULL' on failure. This is the equivalent of the Python expression `abs(O)'. `PyObject* PyNumber_Invert(PyObject *o)' Returns the bitwise negation of O on success, or `NULL' on failure. This is the equivalent of the Python expression `~O'. `PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)' Returns the result of left shifting O1 by O2 on success, or `NULL' on failure. This is the equivalent of the Python expression `O1 <`<' O2'. `PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)' Returns the result of right shifting O1 by O2 on success, or `NULL' on failure. This is the equivalent of the Python expression `O1 >`>' O2'. `PyObject* PyNumber_And(PyObject *o1, PyObject *o2)' Returns the "bitwise and" of O2 and O2 on success and `NULL' on failure. This is the equivalent of the Python expression `O1 & O2'. `PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)' Returns the "bitwise exclusive or" of O1 by O2 on success, or `NULL' on failure. This is the equivalent of the Python expression `O1 ^{ }O2'. `PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)' Returns the "bitwise or" of O1 and O2 on success, or `NULL' on failure. This is the equivalent of the Python expression `O1 | O2'. `PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)' Returns the result of adding O1 and O2, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 += O2'. `PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)' Returns the result of subtracting O2 from O1, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 -= O2'. `PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)' Returns the result of multiplying O1 and O2, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 *= O2'. `PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)' Returns the result of dividing O1 by O2, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 /= O2'. `PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)' Returns the remainder of dividing O1 by O2, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 %= O2'. `PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)' See the built-in function `pow()'. Returns `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 **= O2' when o3 is `Py_None', or an in-place variant of `pow(O1, O2, O3)' otherwise. If O3 is to be ignored, pass `Py_None' in its place (passing `NULL' for O3 would cause an illegal memory access). `PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)' Returns the result of left shifting O1 by O2 on success, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 <`<=' O2'. `PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)' Returns the result of right shifting O1 by O2 on success, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 >`>=' O2'. `PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)' Returns the "bitwise and" of O1 and O2 on success and `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 &= O2'. `PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)' Returns the "bitwise exclusive or" of O1 by O2 on success, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 ^= O2'. `PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)' Returns the "bitwise or" of O1 and O2 on success, or `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 |= O2'. `int PyNumber_Coerce(PyObject **p1, PyObject **p2)' This function takes the addresses of two variables of type `PyObject*'. If the objects pointed to by `*P1' and `*P2' have the same type, increment their reference count and return `0' (success). If the objects can be converted to a common numeric type, replace `*p1' and `*p2' by their converted value (with 'new' reference counts), and return `0'. If no conversion is possible, or if some other error occurs, return `-1' (failure) and don't increment the reference counts. The call `PyNumber_Coerce(&o1, &o2)' is equivalent to the Python statement `O1, O2 = coerce(O1, O2)'. `PyObject* PyNumber_Int(PyObject *o)' Returns the O converted to an integer object on success, or `NULL' on failure. This is the equivalent of the Python expression `int(O)'. `PyObject* PyNumber_Long(PyObject *o)' Returns the O converted to a long integer object on success, or `NULL' on failure. This is the equivalent of the Python expression `long(O)'. `PyObject* PyNumber_Float(PyObject *o)' Returns the O converted to a float object on success, or `NULL' on failure. This is the equivalent of the Python expression `float(O)'.  File: python-api.info, Node: Sequence Protocol, Next: Mapping Protocol, Prev: Number Protocol, Up: Abstract Objects Layer Sequence Protocol ================= `int PySequence_Check(PyObject *o)' Return `1' if the object provides sequence protocol, and `0' otherwise. This function always succeeds. `int PySequence_Size(PyObject *o)' Returns the number of objects in sequence O on success, and `-1' on failure. For objects that do not provide sequence protocol, this is equivalent to the Python expression `len(O)'. `int PySequence_Length(PyObject *o)' Alternate name for `PySequence_Size()'. `PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)' Return the concatenation of O1 and O2 on success, and `NULL' on failure. This is the equivalent of the Python expression `O1 + O2'. `PyObject* PySequence_Repeat(PyObject *o, int count)' Return the result of repeating sequence object O COUNT times, or `NULL' on failure. This is the equivalent of the Python expression `O * COUNT'. `PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)' Return the concatenation of O1 and O2 on success, and `NULL' on failure. The operation is done _in-place_ when O1 supports it. This is the equivalent of the Python expression `O1 += O2'. `PyObject* PySequence_InPlaceRepeat(PyObject *o, int count)' Return the result of repeating sequence object O COUNT times, or `NULL' on failure. The operation is done _in-place_ when O supports it. This is the equivalent of the Python expression `O *= COUNT'. `PyObject* PySequence_GetItem(PyObject *o, int i)' Return the Ith element of O, or `NULL' on failure. This is the equivalent of the Python expression `O[I]'. `PyObject* PySequence_GetSlice(PyObject *o, int i1, int i2)' Return the slice of sequence object O between I1 and I2, or `NULL' on failure. This is the equivalent of the Python expression `O[I1:I2]'. `int PySequence_SetItem(PyObject *o, int i, PyObject *v)' Assign object V to the Ith element of O. Returns `-1' on failure. This is the equivalent of the Python statement `O[I] = V'. `int PySequence_DelItem(PyObject *o, int i)' Delete the Ith element of object O. Returns `-1' on failure. This is the equivalent of the Python statement `del O[I]'. `int PySequence_SetSlice(PyObject *o, int i1, int i2, PyObject *v)' Assign the sequence object V to the slice in sequence object O from I1 to I2. This is the equivalent of the Python statement `O[I1:I2] = V'. `int PySequence_DelSlice(PyObject *o, int i1, int i2)' Delete the slice in sequence object O from I1 to I2. Returns `-1' on failure. This is the equivalent of the Python statement `del O[I1:I2]'. `PyObject* PySequence_Tuple(PyObject *o)' Returns the O as a tuple on success, and `NULL' on failure. This is equivalent to the Python expression `tuple(O)'. `int PySequence_Count(PyObject *o, PyObject *value)' Return the number of occurrences of VALUE in O, that is, return the number of keys for which `O[KEY] == VALUE'. On failure, return `-1'. This is equivalent to the Python expression `O.count(VALUE)'. `int PySequence_Contains(PyObject *o, PyObject *value)' Determine if O contains VALUE. If an item in O is equal to VALUE, return `1', otherwise return `0'. On error, return `-1'. This is equivalent to the Python expression `VALUE in O'. `int PySequence_Index(PyObject *o, PyObject *value)' Return the first index I for which `O[I] == VALUE'. On error, return `-1'. This is equivalent to the Python expression `O.index(VALUE)'. `PyObject* PySequence_List(PyObject *o)' Return a list object with the same contents as the arbitrary sequence O. The returned list is guaranteed to be new. `PyObject* PySequence_Tuple(PyObject *o)' Return a tuple object with the same contents as the arbitrary sequence O. If O is a tuple, a new reference will be returned, otherwise a tuple will be constructed with the appropriate contents. `PyObject* PySequence_Fast(PyObject *o, const char *m)' Returns the sequence O as a tuple, unless it is already a tuple or list, in which case O is returned. Use `PySequence_Fast_GET_ITEM()' to access the members of the result. Returns `NULL' on failure. If the object is not a sequence, raises `TypeError' with M as the message text. `PyObject* PySequence_Fast_GET_ITEM(PyObject *o, int i)' Return the Ith element of O, assuming that O was returned by `PySequence_Fast()', and that I is within bounds. The caller is expected to get the length of the sequence by calling `PyObject_Size()' on O, since lists and tuples are guaranteed to always return their true length.  File: python-api.info, Node: Mapping Protocol, Prev: Sequence Protocol, Up: Abstract Objects Layer Mapping Protocol ================ `int PyMapping_Check(PyObject *o)' Return `1' if the object provides mapping protocol, and `0' otherwise. This function always succeeds. `int PyMapping_Length(PyObject *o)' Returns the number of keys in object O on success, and `-1' on failure. For objects that do not provide mapping protocol, this is equivalent to the Python expression `len(O)'. `int PyMapping_DelItemString(PyObject *o, char *key)' Remove the mapping for object KEY from the object O. Return `-1' on failure. This is equivalent to the Python statement `del O[KEY]'. `int PyMapping_DelItem(PyObject *o, PyObject *key)' Remove the mapping for object KEY from the object O. Return `-1' on failure. This is equivalent to the Python statement `del O[KEY]'. `int PyMapping_HasKeyString(PyObject *o, char *key)' On success, return `1' if the mapping object has the key KEY and `0' otherwise. This is equivalent to the Python expression `O.has_key(KEY)'. This function always succeeds. `int PyMapping_HasKey(PyObject *o, PyObject *key)' Return `1' if the mapping object has the key KEY and `0' otherwise. This is equivalent to the Python expression `O.has_key(KEY)'. This function always succeeds. `PyObject* PyMapping_Keys(PyObject *o)' On success, return a list of the keys in object O. On failure, return `NULL'. This is equivalent to the Python expression `O.keys()'. `PyObject* PyMapping_Values(PyObject *o)' On success, return a list of the values in object O. On failure, return `NULL'. This is equivalent to the Python expression `O.values()'. `PyObject* PyMapping_Items(PyObject *o)' On success, return a list of the items in object O, where each item is a tuple containing a key-value pair. On failure, return `NULL'. This is equivalent to the Python expression `O.items()'. `PyObject* PyMapping_GetItemString(PyObject *o, char *key)' Return element of O corresponding to the object KEY or `NULL' on failure. This is the equivalent of the Python expression `O[KEY]'. `int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)' Map the object KEY to the value V in object O. Returns `-1' on failure. This is the equivalent of the Python statement `O[KEY] = V'.  File: python-api.info, Node: Concrete Objects Layer, Next: Initialization, Prev: Abstract Objects Layer, Up: Top Concrete Objects Layer ********************** The functions in this chapter are specific to certain Python object types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; for example, to check that an object is a dictionary, use `PyDict_Check()'. The chapter is structured like the "family tree" of Python object types. *Warning:* While the functions described in this chapter carefully check the type of the objects which are passed in, many of them do not check for `NULL' being passed instead of a valid object. Allowing `NULL' to be passed in can cause memory access violations and immediate termination of the interpreter. * Menu: * Fundamental Objects:: * Sequence Objects:: * Mapping Objects:: * Numeric Objects:: * Other Objects::  File: python-api.info, Node: Fundamental Objects, Next: Sequence Objects, Prev: Concrete Objects Layer, Up: Concrete Objects Layer Fundamental Objects =================== This section describes Python type objects and the singleton object `None'. * Menu: * Type Objects:: * None Object::  File: python-api.info, Node: Type Objects, Next: None Object, Prev: Fundamental Objects, Up: Fundamental Objects Type Objects ------------ `PyTypeObject' The C structure of the objects used to describe built-in types. `PyObject* PyType_Type' This is the type object for type objects; it is the same object as `types.TypeType' in the Python layer. `int PyType_Check(PyObject *o)' Returns true is the object O is a type object. `int PyType_HasFeature(PyObject *o, int feature)' Returns true if the type object O sets the feature FEATURE. Type features are denoted by single bit flags.  File: python-api.info, Node: None Object, Prev: Type Objects, Up: Fundamental Objects The None Object --------------- Note that the `PyTypeObject' for `None' is not directly exposed in the Python/C API. Since `None' is a singleton, testing for object identity (using `==' in C) is sufficient. There is no `PyNone_Check()' function for the same reason. `PyObject* Py_None' The Python `None' object, denoting lack of value. This object has no methods.  File: python-api.info, Node: Sequence Objects, Next: Mapping Objects, Prev: Fundamental Objects, Up: Concrete Objects Layer Sequence Objects ================ Generic operations on sequence objects were discussed in the previous chapter; this section deals with the specific kinds of sequence objects that are intrinsic to the Python language. * Menu: * String Objects:: * Unicode Objects:: * Buffer Objects:: * Tuple Objects:: * List Objects::  File: python-api.info, Node: String Objects, Next: Unicode Objects, Prev: Sequence Objects, Up: Sequence Objects String Objects -------------- These functions raise `TypeError' when expecting a string parameter and are called with a non-string parameter. `PyStringObject' This subtype of `PyObject' represents a Python string object. `PyTypeObject PyString_Type' This instance of `PyTypeObject' represents the Python string type; it is the same object as `types.TypeType' in the Python layer.. `int PyString_Check(PyObject *o)' Returns true if the object O is a string object. `PyObject* PyString_FromString(const char *v)' Returns a new string object with the value V on success, and `NULL' on failure. `PyObject* PyString_FromStringAndSize(const char *v, int len)' Returns a new string object with the value V and length LEN on success, and `NULL' on failure. If V is `NULL', the contents of the string are uninitialized. `int PyString_Size(PyObject *string)' Returns the length of the string in string object STRING. `int PyString_GET_SIZE(PyObject *string)' Macro form of `PyString_Size()' but without error checking. `char* PyString_AsString(PyObject *string)' Returns a null-terminated representation of the contents of STRING. The pointer refers to the internal buffer of STRING, not a copy. The data must not be modified in any way, unless the string was just created using `PyString_FromStringAndSize(NULL, SIZE)'. It must not be deallocated. `char* PyString_AS_STRING(PyObject *string)' Macro form of `PyString_AsString()' but without error checking. `int PyString_AsStringAndSize(PyObject *obj, char **buffer, int *length)' Returns a null-terminated representation of the contents of the object OBJ through the output variables BUFFER and LENGTH. The function accepts both string and Unicode objects as input. For Unicode objects it returns the default encoded version of the object. If LENGTH is set to `NULL', the resulting buffer may not contain null characters; if it does, the function returns -1 and a TypeError is raised. The buffer refers to an internal string buffer of OBJ, not a copy. The data must not be modified in any way, unless the string was just created using `PyString_FromStringAndSize(NULL, SIZE)'. It must not be deallocated. `void PyString_Concat(PyObject **string, PyObject *newpart)' Creates a new string object in *STRING containing the contents of NEWPART appended to STRING; the caller will own the new reference. The reference to the old value of STRING will be stolen. If the new string cannot be created, the old reference to STRING will still be discarded and the value of *STRING will be set to `NULL'; the appropriate exception will be set. `void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)' Creates a new string object in *STRING containing the contents of NEWPART appended to STRING. This version decrements the reference count of NEWPART. `int _PyString_Resize(PyObject **string, int newsize)' A way to resize a string object even though it is "immutable". Only use this to build up a brand new string object; don't use this if the string may already be known in other parts of the code. `PyObject* PyString_Format(PyObject *format, PyObject *args)' Returns a new string object from FORMAT and ARGS. Analogous to `FORMAT % ARGS'. The ARGS argument must be a tuple. `void PyString_InternInPlace(PyObject **string)' Intern the argument *STRING in place. The argument must be the address of a pointer variable pointing to a Python string object. If there is an existing interned string that is the same as *STRING, it sets *STRING to it (decrementing the reference count of the old string object and incrementing the reference count of the interned string object), otherwise it leaves *STRING alone and interns it (incrementing its reference count). (Clarification: even though there is a lot of talk about reference counts, think of this function as reference-count-neutral; you own the object after the call if and only if you owned it before the call.) `PyObject* PyString_InternFromString(const char *v)' A combination of `PyString_FromString()' and `PyString_InternInPlace()', returning either a new string object that has been interned, or a new ("owned") reference to an earlier interned string object with the same value. `PyObject* PyString_Decode(const char *s, int size, const char *encoding, const char *errors)' Create a string object by decoding SIZE bytes of the encoded buffer S. ENCODING and ERRORS have the same meaning as the parameters of the same name in the unicode() builtin function. The codec to be used is looked up using the Python codec registry. Returns `NULL' in case an exception was raised by the codec. `PyObject* PyString_Encode(const Py_UNICODE *s, int size, const char *encoding, const char *errors)' Encodes the `Py_UNICODE' buffer of the given size and returns a Python string object. ENCODING and ERRORS have the same meaning as the parameters of the same name in the string .encode() method. The codec to be used is looked up using the Python codec registry. Returns `NULL' in case an exception was raised by the codec. `PyObject* PyString_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)' Encodes a string object and returns the result as Python string object. ENCODING and ERRORS have the same meaning as the parameters of the same name in the string .encode() method. The codec to be used is looked up using the Python codec registry. Returns `NULL' in case an exception was raised by the codec.