diff options
Diffstat (limited to 'Doc')
45 files changed, 7288 insertions, 5377 deletions
diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst index c616561..66426f7 100644 --- a/Doc/c-api/abstract.rst +++ b/Doc/c-api/abstract.rst @@ -1,6 +1,5 @@ .. highlightlang:: c - .. _abstract: ********************** @@ -16,928 +15,11 @@ It is not possible to use these functions on objects that are not properly initialized, such as a list object that has been created by :cfunc:`PyList_New`, but whose items have not been set to some non-\ ``NULL`` value yet. +.. toctree:: -.. _object: - -Object Protocol -=============== - - -.. cfunction:: 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 :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written - instead of the :func:`repr`. - - -.. cfunction:: 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. - - -.. cfunction:: int PyObject_HasAttrString(PyObject *o, const 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. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: int PyObject_SetAttrString(PyObject *o, const 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: int PyObject_DelAttrString(PyObject *o, const 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``. - - -.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid) - - Compare the values of *o1* and *o2* using the operation specified by *opid*, - which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, - :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, - ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of - the Python expression ``o1 op o2``, where ``op`` is the operator corresponding - to *opid*. Returns the value of the comparison on success, or *NULL* on failure. - - -.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid) - - Compare the values of *o1* and *o2* using the operation specified by *opid*, - which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, - :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, - ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error, - ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the - Python expression ``o1 op o2``, where ``op`` is the operator corresponding to - *opid*. - - -.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result) - - .. index:: builtin: cmp - - 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)``. - - -.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2) - - .. index:: builtin: cmp - - 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 - :cfunc:`PyErr_Occurred` to detect an error. This is equivalent to the Python - expression ``cmp(o1, o2)``. - - -.. cfunction:: PyObject* PyObject_Repr(PyObject *o) - - .. index:: builtin: repr - - 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 :func:`repr` built-in function and - by reverse quotes. - - -.. cfunction:: PyObject* PyObject_Str(PyObject *o) - - .. index:: builtin: str - - 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 :func:`str` built-in function - and, therefore, by the :func:`print` function. - - -.. cfunction:: PyObject* PyObject_Unicode(PyObject *o) - - .. index:: builtin: unicode - - 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 ``unicode(o)``. Called by the :func:`unicode` built-in - function. - - -.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls) - - Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of - *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If - *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance` - returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will - be done against every entry in *cls*. The result will be ``1`` when at least one - of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a - class instance and *cls* is neither a type object, nor a class object, nor a - tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship - of the value of that attribute with *cls* will be used to determine the result - of this function. - - -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 :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of -:class:`A` if it inherits from :class:`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*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B* -are different objects, *B*'s :attr:`__bases__` attribute is searched in a -depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute -is considered sufficient for this determination. - - -.. cfunction:: 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 *cls* - is a tuple, the check will be done against every entry in *cls*. The result will - be ``1`` when at least one of the checks returns ``1``, otherwise it will be - ``0``. If either *derived* or *cls* is not an actual class object (or tuple), - this function uses the generic algorithm described above. - - -.. cfunction:: 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. - - -.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw) - - Call a callable Python object *callable_object*, with arguments given by the - tuple *args*, and named arguments given by the dictionary *kw*. If no named - arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an - empty tuple if no arguments are needed. Returns the result of the call on - success, or *NULL* on failure. This is the equivalent of the Python expression - ``callable_object(*args, **kw)``. - - -.. cfunction:: 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 ``callable_object(*args)``. - - -.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...) - - Call a callable Python object *callable*, with a variable number of C arguments. - The C arguments are described using a :cfunc:`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 ``callable(*args)``. Note that if you only - pass :ctype:`PyObject \*` args, :cfunc:`PyObject_CallFunctionObjArgs` is a - faster alternative. - - -.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...) - - Call the method named *method* of object *o* with a variable number of C - arguments. The C arguments are described by a :cfunc:`Py_BuildValue` format - string that should produce a tuple. 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 if you only pass :ctype:`PyObject \*` args, - :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative. - - -.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) - - Call a callable Python object *callable*, with a variable number of - :ctype:`PyObject\*` arguments. The arguments are provided as a variable number - of parameters followed by *NULL*. Returns the result of the call on success, or - *NULL* on failure. - - -.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL) - - Calls a method of the object *o*, where the name of the method is given as a - Python string object in *name*. It is called with a variable number of - :ctype:`PyObject\*` arguments. The arguments are provided as a variable number - of parameters followed by *NULL*. Returns the result of the call on success, or - *NULL* on failure. - - -.. cfunction:: long PyObject_Hash(PyObject *o) - - .. index:: builtin: hash - - Compute and return the hash value of an object *o*. On failure, return ``-1``. - This is the equivalent of the Python expression ``hash(o)``. - - -.. cfunction:: 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``. On failure, return - ``-1``. - - -.. cfunction:: int PyObject_Not(PyObject *o) - - Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise. - This is equivalent to the Python expression ``not o``. On failure, return - ``-1``. - - -.. cfunction:: PyObject* PyObject_Type(PyObject *o) - - .. index:: builtin: type - - When *o* is non-*NULL*, returns a type object corresponding to the object type - of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This - is equivalent to the Python expression ``type(o)``. This function increments the - reference count of the return value. There's really no reason to use this - function instead of the common expression ``o->ob_type``, which returns a - pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference - count is needed. - - -.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type) - - Return true if the object *o* is of type *type* or a subtype of *type*. Both - parameters must be non-*NULL*. - - -.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o) - Py_ssize_t PyObject_Size(PyObject *o) - - .. index:: builtin: len - - Return the length of object *o*. If the object *o* provides either the sequence - and mapping protocols, the sequence length is returned. On error, ``-1`` is - returned. This is the equivalent to the Python expression ``len(o)``. - - -.. cfunction:: 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]``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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]``. - - -.. cfunction:: PyObject* PyObject_Dir(PyObject *o) - - This is equivalent to the Python expression ``dir(o)``, returning a (possibly - empty) list of strings appropriate for the object argument, or *NULL* if there - was an error. If the argument is *NULL*, this is like the Python ``dir()``, - returning the names of the current locals; in this case, if no execution frame - is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false. - - -.. cfunction:: PyObject* PyObject_GetIter(PyObject *o) - - This is equivalent to the Python expression ``iter(o)``. It returns a new - iterator for the object argument, or the object itself if the object is already - an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be - iterated. - - -.. _number: - -Number Protocol -=============== - - -.. cfunction:: int PyNumber_Check(PyObject *o) - - Returns ``1`` if the object *o* provides numeric protocols, and false otherwise. - This function always succeeds. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) - - Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is - equivalent to the "classic" division of integers. - - -.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2) - - Return a reasonable approximation for the mathematical value of *o1* divided by - *o2*, or *NULL* on failure. The return value is "approximate" because binary - floating point numbers are approximate; it is not possible to represent all real - numbers in base two. This function can return a floating point value when - passed two integers. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2) - - .. index:: builtin: divmod - - See the built-in function :func:`divmod`. Returns *NULL* on failure. This is - the equivalent of the Python expression ``divmod(o1, o2)``. - - -.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3) - - .. index:: builtin: pow - - See the built-in function :func:`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 :cdata:`Py_None` in its place (passing *NULL* for - *o3* would cause an illegal memory access). - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PyNumber_Positive(PyObject *o) - - Returns *o* on success, or *NULL* on failure. This is the equivalent of the - Python expression ``+o``. - - -.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o) - - .. index:: builtin: abs - - Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent - of the Python expression ``abs(o)``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2) - - Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. - This is the equivalent of the Python expression ``o1 & o2``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: 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 - statement ``o1 += o2``. - - -.. cfunction:: 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 statement ``o1 -= o2``. - - -.. cfunction:: 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 statement ``o1 *= o2``. - - -.. cfunction:: 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 statement ``o1 /= o2``. - - -.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2) - - Returns the mathematical floor 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 statement ``o1 //= o2``. - - -.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2) - - Return a reasonable approximation for the mathematical value of *o1* divided by - *o2*, or *NULL* on failure. The return value is "approximate" because binary - floating point numbers are approximate; it is not possible to represent all real - numbers in base two. This function can return a floating point value when - passed two integers. The operation is done *in-place* when *o1* supports it. - - -.. cfunction:: 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 statement ``o1 %= o2``. - - -.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3) - - .. index:: builtin: pow - - See the built-in function :func:`pow`. Returns *NULL* on failure. The operation - is done *in-place* when *o1* supports it. This is the equivalent of the Python - statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of - ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None` - in its place (passing *NULL* for *o3* would cause an illegal memory access). - - -.. cfunction:: 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 statement ``o1 <<= o2``. - - -.. cfunction:: 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 statement ``o1 >>= o2``. - - -.. cfunction:: 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 statement ``o1 &= o2``. - - -.. cfunction:: 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 statement ``o1 ^= o2``. - - -.. cfunction:: 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 statement ``o1 |= o2``. - - -.. cfunction:: PyObject* PyNumber_Int(PyObject *o) - - .. index:: builtin: int - - Returns the *o* converted to an integer object on success, or *NULL* on failure. - If the argument is outside the integer range a long object will be returned - instead. This is the equivalent of the Python expression ``int(o)``. - - -.. cfunction:: PyObject* PyNumber_Long(PyObject *o) - - .. index:: builtin: long - - Returns the *o* converted to an integer object on success, or *NULL* on - failure. This is the equivalent of the Python expression ``long(o)``. - - -.. cfunction:: PyObject* PyNumber_Float(PyObject *o) - - .. index:: builtin: float - - Returns the *o* converted to a float object on success, or *NULL* on failure. - This is the equivalent of the Python expression ``float(o)``. - - -.. cfunction:: PyObject* PyNumber_Index(PyObject *o) - - Returns the *o* converted to a Python int or long on success or *NULL* with a - TypeError exception raised on failure. - - -.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc) - - Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an - integer. If *o* can be converted to a Python int or long but the attempt to - convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the - *exc* argument is the type of exception that will be raised (usually - :exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the - exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative - integer or *PY_SSIZE_T_MAX* for a positive integer. - - -.. cfunction:: int PyIndex_Check(PyObject *o) - - Returns True if *o* is an index integer (has the nb_index slot of the - tp_as_number structure filled in). - - -.. _sequence: - -Sequence Protocol -================= - - -.. cfunction:: int PySequence_Check(PyObject *o) - - Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. - This function always succeeds. - - -.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o) - - .. index:: builtin: len - - 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)``. - - -.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o) - - Alternate name for :cfunc:`PySequence_Size`. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t 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``. - - -.. cfunction:: 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``. - - -.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t 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``. - - -.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i) - - Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of - the Python expression ``o[i]``. - - -.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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]``. - - -.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v) - - Assign object *v* to the *i*th element of *o*. Returns ``-1`` on failure. This - is the equivalent of the Python statement ``o[i] = v``. This function *does - not* steal a reference to *v*. - - -.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i) - - Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the - equivalent of the Python statement ``del o[i]``. - - -.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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``. - - -.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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]``. - - -.. cfunction:: Py_ssize_t 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)``. - - -.. cfunction:: 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``. - - -.. cfunction:: Py_ssize_t 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)``. - - -.. cfunction:: 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. - - -.. cfunction:: PyObject* PySequence_Tuple(PyObject *o) - - .. index:: builtin: tuple - - Return a tuple object with the same contents as the arbitrary sequence *o* or - *NULL* on failure. If *o* is a tuple, a new reference will be returned, - otherwise a tuple will be constructed with the appropriate contents. This is - equivalent to the Python expression ``tuple(o)``. - - -.. cfunction:: 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 :cfunc:`PySequence_Fast_GET_ITEM` to access the - members of the result. Returns *NULL* on failure. If the object is not a - sequence, raises :exc:`TypeError` with *m* as the message text. - - -.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) - - Return the *i*th element of *o*, assuming that *o* was returned by - :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds. - - -.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o) - - Return the underlying array of PyObject pointers. Assumes that *o* was returned - by :cfunc:`PySequence_Fast` and *o* is not *NULL*. - - -.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i) - - Return the *i*th element of *o* or *NULL* on failure. Macro form of - :cfunc:`PySequence_GetItem` but without checking that - :cfunc:`PySequence_Check(o)` is true and without adjustment for negative - indices. - - -.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) - - Returns the length of *o*, assuming that *o* was returned by - :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be - gotten by calling :cfunc:`PySequence_Size` on *o*, but - :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list - or tuple. - - -.. _mapping: - -Mapping Protocol -================ - - -.. cfunction:: int PyMapping_Check(PyObject *o) - - Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This - function always succeeds. - - -.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o) - - .. index:: builtin: len - - 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)``. - - -.. cfunction:: 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]``. - - -.. cfunction:: 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]``. - - -.. cfunction:: 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 ``key in o``. - This function always succeeds. - - -.. cfunction:: 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 ``key in o``. This function always - succeeds. - - -.. cfunction:: 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()``. - - -.. cfunction:: 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()``. - - -.. cfunction:: 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()``. - - -.. cfunction:: 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]``. - - -.. cfunction:: 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``. - - -.. _iterator: - -Iterator Protocol -================= - -There are only a couple of functions specifically for working with iterators. - -.. cfunction:: int PyIter_Check(PyObject *o) - - Return true if the object *o* supports the iterator protocol. - - -.. cfunction:: PyObject* PyIter_Next(PyObject *o) - - Return the next value from the iteration *o*. If the object is an iterator, - this retrieves the next value from the iteration, and returns *NULL* with no - exception set if there are no remaining items. If the object is not an - iterator, :exc:`TypeError` is raised, or if there is an error in retrieving the - item, returns *NULL* and passes along the exception. - -To write a loop which iterates over an iterator, the C code should look -something like this:: - - PyObject *iterator = PyObject_GetIter(obj); - PyObject *item; - - if (iterator == NULL) { - /* propagate error */ - } - - while (item = PyIter_Next(iterator)) { - /* do something with item */ - ... - /* release reference when done */ - Py_DECREF(item); - } - - Py_DECREF(iterator); - - if (PyErr_Occurred()) { - /* propagate error */ - } - else { - /* continue doing useful work */ - } - - -.. _abstract-buffer: - -Buffer Protocol -=============== - - -.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len) - - Returns a pointer to a read-only memory location useable as character- based - input. The *obj* argument must support the single-segment character buffer - interface. On success, returns ``0``, sets *buffer* to the memory location and - *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError` - on error. - - -.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len) - - Returns a pointer to a read-only memory location containing arbitrary data. The - *obj* argument must support the single-segment readable buffer interface. On - success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to - the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error. - - -.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o) - - Returns ``1`` if *o* supports the single-segment readable buffer interface. - Otherwise returns ``0``. - - -.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len) - - Returns a pointer to a writable memory location. The *obj* argument must - support the single-segment, character buffer interface. On success, returns - ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer - length. Returns ``-1`` and sets a :exc:`TypeError` on error. - + object.rst + number.rst + sequence.rst + mapping.rst + iter.rst + objbuffer.rst diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst new file mode 100644 index 0000000..cb78e79 --- /dev/null +++ b/Doc/c-api/allocation.rst @@ -0,0 +1,93 @@ +.. highlightlang:: c + +.. _allocating-objects: + +Allocating Objects on the Heap +============================== + + +.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type) + + +.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size) + + +.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type) + + Initialize a newly-allocated object *op* with its type and initial reference. + Returns the initialized object. If *type* indicates that the object + participates in the cyclic garbage detector, it is added to the detector's set + of observed objects. Other fields of the object are not affected. + + +.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size) + + This does everything :cfunc:`PyObject_Init` does, and also initializes the + length information for a variable-size object. + + +.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type) + + Allocate a new Python object using the C structure type *TYPE* and the Python + type object *type*. Fields not defined by the Python object header are not + initialized; the object's reference count will be one. The size of the memory + allocation is determined from the :attr:`tp_basicsize` field of the type object. + + +.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) + + Allocate a new Python object using the C structure type *TYPE* and the Python + type object *type*. Fields not defined by the Python object header are not + initialized. The allocated memory allows for the *TYPE* structure plus *size* + fields of the size given by the :attr:`tp_itemsize` field of *type*. This is + useful for implementing objects like tuples, which are able to determine their + size at construction time. Embedding the array of fields into the same + allocation decreases the number of allocations, improving the memory management + efficiency. + + +.. cfunction:: void PyObject_Del(PyObject *op) + + Releases memory allocated to an object using :cfunc:`PyObject_New` or + :cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc` + handler specified in the object's type. The fields of the object should not be + accessed after this call as the memory is no longer a valid Python object. + + +.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods) + + Create a new module object based on a name and table of functions, returning + the new module object; the *methods* argument can be *NULL* if no methods are + to be defined for the module. + + +.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc) + + Create a new module object based on a name and table of functions, returning + the new module object. The *methods* argument can be *NULL* if no methods + are to be defined for the module. If *doc* is non-*NULL*, it will be used to + define the docstring for the module. + + +.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver) + + Create a new module object based on a name and table of functions, returning + the new module object. The *methods* argument can be *NULL* if no methods + are to be defined for the module. If *doc* is non-*NULL*, it will be used to + define the docstring for the module. If *self* is non-*NULL*, it will passed + to the functions of the module as their (otherwise *NULL*) first parameter. + (This was added as an experimental feature, and there are no known uses in + the current version of Python.) For *apiver*, the only value which should be + passed is defined by the constant :const:`PYTHON_API_VERSION`. + + .. note:: + + Most uses of this function should probably be using the :cfunc:`Py_InitModule3` + instead; only use this if you are sure you need it. + + +.. cvar:: PyObject _Py_NoneStruct + + Object which is visible in Python as ``None``. This should only be accessed + using the :cmacro:`Py_None` macro, which evaluates to a pointer to this + object. diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst new file mode 100644 index 0000000..5f82904 --- /dev/null +++ b/Doc/c-api/arg.rst @@ -0,0 +1,509 @@ +.. highlightlang:: c + +.. _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. diff --git a/Doc/c-api/bool.rst b/Doc/c-api/bool.rst new file mode 100644 index 0000000..4479bc6 --- /dev/null +++ b/Doc/c-api/bool.rst @@ -0,0 +1,46 @@ +.. highlightlang:: c + +.. _boolobjects: + +Boolean Objects +--------------- + +Booleans in Python are implemented as a subclass of integers. There are only +two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal +creation and deletion functions don't apply to booleans. The following macros +are available, however. + + +.. cfunction:: int PyBool_Check(PyObject *o) + + Return true if *o* is of type :cdata:`PyBool_Type`. + + +.. cvar:: PyObject* Py_False + + The Python ``False`` object. This object has no methods. It needs to be + treated just like any other object with respect to reference counts. + + +.. cvar:: PyObject* Py_True + + The Python ``True`` object. This object has no methods. It needs to be treated + just like any other object with respect to reference counts. + + +.. cmacro:: Py_RETURN_FALSE + + Return :const:`Py_False` from a function, properly incrementing its reference + count. + + +.. cmacro:: Py_RETURN_TRUE + + Return :const:`Py_True` from a function, properly incrementing its reference + count. + + +.. cfunction:: PyObject* PyBool_FromLong(long v) + + Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the + truth value of *v*. diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst new file mode 100644 index 0000000..70e526c --- /dev/null +++ b/Doc/c-api/buffer.rst @@ -0,0 +1,119 @@ +.. highlightlang:: c + +.. _bufferobjects: + +Buffer Objects +-------------- + +.. sectionauthor:: Greg Stein <gstein@lyra.org> + + +.. index:: + object: buffer + single: buffer interface + +Python objects implemented in C can export a group of functions called the +"buffer interface." These functions can be used by an object to expose its data +in a raw, byte-oriented format. Clients of the object can use the buffer +interface to access the object data directly, without needing to copy it first. + +Two examples of objects that support the buffer interface are strings and +arrays. The string object exposes the character contents in the buffer +interface's byte-oriented form. An array can also expose its contents, but it +should be noted that array elements may be multi-byte values. + +An example user of the buffer interface is the file object's :meth:`write` +method. Any object that can export a series of bytes through the buffer +interface can be written to a file. There are a number of format codes to +:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface, +returning data from the target object. + +.. index:: single: PyBufferProcs + +More information on the buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. + +A "buffer object" is defined in the :file:`bufferobject.h` header (included by +:file:`Python.h`). These objects look very similar to string objects at the +Python programming level: they support slicing, indexing, concatenation, and +some other standard string operations. However, their data can come from one of +two sources: from a block of memory, or from another object which exports the +buffer interface. + +Buffer objects are useful as a way to expose the data from another object's +buffer interface to the Python programmer. They can also be used as a zero-copy +slicing mechanism. Using their ability to reference a block of memory, it is +possible to expose any data to the Python programmer quite easily. The memory +could be a large, constant array in a C extension, it could be a raw block of +memory for manipulation before passing to an operating system library, or it +could be used to pass around structured data in its native, in-memory format. + + +.. ctype:: PyBufferObject + + This subtype of :ctype:`PyObject` represents a buffer object. + + +.. cvar:: PyTypeObject PyBuffer_Type + + .. index:: single: BufferType (in module types) + + The instance of :ctype:`PyTypeObject` which represents the Python buffer type; + it is the same object as ``buffer`` and ``types.BufferType`` in the Python + layer. . + + +.. cvar:: int Py_END_OF_BUFFER + + This constant may be passed as the *size* parameter to + :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It + indicates that the new :ctype:`PyBufferObject` should refer to *base* object + from the specified *offset* to the end of its exported buffer. Using this + enables the caller to avoid querying the *base* object for its length. + + +.. cfunction:: int PyBuffer_Check(PyObject *p) + + Return true if the argument has type :cdata:`PyBuffer_Type`. + + +.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + + Return a new read-only buffer object. This raises :exc:`TypeError` if *base* + doesn't support the read-only buffer protocol or doesn't provide exactly one + buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero. + The buffer will hold a reference to the *base* object, and the buffer's contents + will refer to the *base* object's buffer interface, starting as position + *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`, + then the new buffer's contents extend to the length of the *base* object's + exported buffer data. + + +.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + + Return a new writable buffer object. Parameters and exceptions are similar to + those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export + the writable buffer protocol, then :exc:`TypeError` is raised. + + +.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) + + Return a new read-only buffer object that reads from a specified location in + memory, with a specified size. The caller is responsible for ensuring that the + memory buffer, passed in as *ptr*, is not deallocated while the returned buffer + object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that + :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter; + :exc:`ValueError` will be raised in that case. + + +.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) + + Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable. + + +.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size) + + Return a new writable buffer object that maintains its own memory buffer of + *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive. + Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is + not specifically aligned. diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst new file mode 100644 index 0000000..3562ed9 --- /dev/null +++ b/Doc/c-api/cell.rst @@ -0,0 +1,62 @@ +.. highlightlang:: c + +.. _cell-objects: + +Cell Objects +------------ + +"Cell" objects are used to implement variables referenced by multiple scopes. +For each such variable, a cell object is created to store the value; the local +variables of each stack frame that references the value contains a reference to +the cells from outer scopes which also use that variable. When the value is +accessed, the value contained in the cell is used instead of the cell object +itself. This de-referencing of the cell object requires support from the +generated byte-code; these are not automatically de-referenced when accessed. +Cell objects are not likely to be useful elsewhere. + + +.. ctype:: PyCellObject + + The C structure used for cell objects. + + +.. cvar:: PyTypeObject PyCell_Type + + The type object corresponding to cell objects. + + +.. cfunction:: int PyCell_Check(ob) + + Return true if *ob* is a cell object; *ob* must not be *NULL*. + + +.. cfunction:: PyObject* PyCell_New(PyObject *ob) + + Create and return a new cell object containing the value *ob*. The parameter may + be *NULL*. + + +.. cfunction:: PyObject* PyCell_Get(PyObject *cell) + + Return the contents of the cell *cell*. + + +.. cfunction:: PyObject* PyCell_GET(PyObject *cell) + + Return the contents of the cell *cell*, but without checking that *cell* is + non-*NULL* and a cell object. + + +.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value) + + Set the contents of the cell object *cell* to *value*. This releases the + reference to any current content of the cell. *value* may be *NULL*. *cell* + must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On + success, ``0`` will be returned. + + +.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value) + + Sets the value of the cell object *cell* to *value*. No reference counts are + adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must + be a cell object. diff --git a/Doc/c-api/cobject.rst b/Doc/c-api/cobject.rst new file mode 100644 index 0000000..10f7bba --- /dev/null +++ b/Doc/c-api/cobject.rst @@ -0,0 +1,56 @@ +.. highlightlang:: c + +.. _cobjects: + +CObjects +-------- + +.. index:: object: CObject + +Refer to :ref:`using-cobjects` for more information on using these objects. + + +.. ctype:: PyCObject + + This subtype of :ctype:`PyObject` represents an opaque value, useful for C + extension modules who need to pass an opaque value (as a :ctype:`void\*` + pointer) through Python code to other C code. It is often used to make a C + function pointer defined in one module available to other modules, so the + regular import mechanism can be used to access C APIs defined in dynamically + loaded modules. + + +.. cfunction:: int PyCObject_Check(PyObject *p) + + Return true if its argument is a :ctype:`PyCObject`. + + +.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) + + Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function + will be called when the object is reclaimed, unless it is *NULL*. + + +.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) + + Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. + + +.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) + + Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was + created with. + + +.. cfunction:: void* PyCObject_GetDesc(PyObject* self) + + Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was + created with. + + +.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj) + + Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not + have an associated destructor. Return true on success, false on failure. diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst new file mode 100644 index 0000000..3508a03 --- /dev/null +++ b/Doc/c-api/complex.rst @@ -0,0 +1,126 @@ +.. highlightlang:: c + +.. _complexobjects: + +Complex Number Objects +---------------------- + +.. index:: object: complex number + +Python's complex number objects are implemented as two distinct types when +viewed from the C API: one is the Python object exposed to Python programs, and +the other is a C structure which represents the actual complex number value. +The API provides functions for working with both. + + +Complex Numbers as C Structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Note that the functions which accept these structures as parameters and return +them as results do so *by value* rather than dereferencing them through +pointers. This is consistent throughout the API. + + +.. ctype:: Py_complex + + The C structure which corresponds to the value portion of a Python complex + number object. Most of the functions for dealing with complex number objects + use structures of this type as input or output values, as appropriate. It is + defined as:: + + typedef struct { + double real; + double imag; + } Py_complex; + + +.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right) + + Return the sum of two complex numbers, using the C :ctype:`Py_complex` + representation. + + +.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right) + + Return the difference between two complex numbers, using the C + :ctype:`Py_complex` representation. + + +.. cfunction:: Py_complex _Py_c_neg(Py_complex complex) + + Return the negation of the complex number *complex*, using the C + :ctype:`Py_complex` representation. + + +.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right) + + Return the product of two complex numbers, using the C :ctype:`Py_complex` + representation. + + +.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor) + + Return the quotient of two complex numbers, using the C :ctype:`Py_complex` + representation. + + +.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp) + + Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex` + representation. + + +Complex Numbers as Python Objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +.. ctype:: PyComplexObject + + This subtype of :ctype:`PyObject` represents a Python complex number object. + + +.. cvar:: PyTypeObject PyComplex_Type + + This instance of :ctype:`PyTypeObject` represents the Python complex number + type. It is the same object as ``complex`` and ``types.ComplexType``. + + +.. cfunction:: int PyComplex_Check(PyObject *p) + + Return true if its argument is a :ctype:`PyComplexObject` or a subtype of + :ctype:`PyComplexObject`. + + +.. cfunction:: int PyComplex_CheckExact(PyObject *p) + + Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of + :ctype:`PyComplexObject`. + + +.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v) + + Create a new Python complex number object from a C :ctype:`Py_complex` value. + + +.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag) + + Return a new :ctype:`PyComplexObject` object from *real* and *imag*. + + +.. cfunction:: double PyComplex_RealAsDouble(PyObject *op) + + Return the real part of *op* as a C :ctype:`double`. + + +.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op) + + Return the imaginary part of *op* as a C :ctype:`double`. + + +.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op) + + Return the :ctype:`Py_complex` value of the complex number *op*. + + If *op* is not a Python complex number object but has a :meth:`__complex__` + method, this method will first be called to convert *op* to a Python complex + number object. diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 343223c..a0dfe21 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -29,99 +29,10 @@ Fundamental Objects This section describes Python type objects and the singleton object ``None``. +.. toctree:: -.. _typeobjects: - -Type Objects ------------- - -.. index:: object: type - - -.. ctype:: PyTypeObject - - The C structure of the objects used to describe built-in types. - - -.. cvar:: PyObject* PyType_Type - - .. index:: single: TypeType (in module types) - - This is the type object for type objects; it is the same object as ``type`` and - ``types.TypeType`` in the Python layer. - - -.. cfunction:: int PyType_Check(PyObject *o) - - Return true if the object *o* is a type object, including instances of types - derived from the standard type object. Return false in all other cases. - - -.. cfunction:: int PyType_CheckExact(PyObject *o) - - Return true if the object *o* is a type object, but not a subtype of the - standard type object. Return false in all other cases. - - -.. cfunction:: int PyType_HasFeature(PyObject *o, int feature) - - Return true if the type object *o* sets the feature *feature*. Type features - are denoted by single bit flags. - - -.. cfunction:: int PyType_IS_GC(PyObject *o) - - Return true if the type object includes support for the cycle detector; this - tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. - - -.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) - - Return true if *a* is a subtype of *b*. - - -.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - XXX: Document. - - -.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) - - XXX: Document. - - -.. cfunction:: int PyType_Ready(PyTypeObject *type) - - Finalize a type object. This should be called on all type objects to finish - their initialization. This function is responsible for adding inherited slots - from a type's base class. Return ``0`` on success, or return ``-1`` and sets an - exception on error. - - -.. _noneobject: - -The None Object ---------------- - -.. index:: object: None - -Note that the :ctype:`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 :cfunc:`PyNone_Check` function for the -same reason. - - -.. cvar:: PyObject* Py_None - - The Python ``None`` object, denoting lack of value. This object has no methods. - It needs to be treated just like any other object with respect to reference - counts. - - -.. cmacro:: Py_RETURN_NONE - - Properly handle returning :cdata:`Py_None` from within a C function (that is, - increment the reference count of None and return it.) + type.rst + none.rst .. _numericobjects: @@ -131,447 +42,12 @@ Numeric Objects .. index:: object: numeric +.. toctree:: -.. _boolobjects: - -Boolean Objects ---------------- - -Booleans in Python are implemented as a subclass of integers. There are only -two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal -creation and deletion functions don't apply to booleans. The following macros -are available, however. - - -.. cfunction:: int PyBool_Check(PyObject *o) - - Return true if *o* is of type :cdata:`PyBool_Type`. - - -.. cvar:: PyObject* Py_False - - The Python ``False`` object. This object has no methods. It needs to be - treated just like any other object with respect to reference counts. - - -.. cvar:: PyObject* Py_True - - The Python ``True`` object. This object has no methods. It needs to be treated - just like any other object with respect to reference counts. - - -.. cmacro:: Py_RETURN_FALSE - - Return :const:`Py_False` from a function, properly incrementing its reference - count. - - -.. cmacro:: Py_RETURN_TRUE - - Return :const:`Py_True` from a function, properly incrementing its reference - count. - - -.. cfunction:: PyObject* PyBool_FromLong(long v) - - Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the - truth value of *v*. - - -.. _longobjects: - -Integer Objects ---------------- - -.. index:: object: long integer - object: integer - -All integers are implemented as "long" integer objects of arbitrary size. - -.. ctype:: PyLongObject - - This subtype of :ctype:`PyObject` represents a Python integer object. - - -.. cvar:: PyTypeObject PyLong_Type - - This instance of :ctype:`PyTypeObject` represents the Python integer type. - This is the same object as ``int``. - - -.. cfunction:: int PyLong_Check(PyObject *p) - - Return true if its argument is a :ctype:`PyLongObject` or a subtype of - :ctype:`PyLongObject`. - - -.. cfunction:: int PyLong_CheckExact(PyObject *p) - - Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of - :ctype:`PyLongObject`. - - -.. cfunction:: PyObject* PyLong_FromLong(long v) - - Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure. - - The current implementation keeps an array of integer objects for all integers - between ``-5`` and ``256``, when you create an int in that range you actually - just get back a reference to the existing object. So it should be possible to - change the value of ``1``. I suspect the behaviour of Python in this case is - undefined. :-) - - -.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v) - - Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or - *NULL* on failure. - - -.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) - - Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL* - on failure. - - -.. cfunction:: PyObject* PyLong_FromSize_t(size_t v) - - Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL* - on failure. - - -.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v) - - Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL* - on failure. - - -.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v) - - Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`, - or *NULL* on failure. - - -.. cfunction:: PyObject* PyLong_FromDouble(double v) - - Return a new :ctype:`PyLongObject` object from the integer part of *v*, or - *NULL* on failure. - - -.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base) - - Return a new :ctype:`PyLongObject` based on the string value in *str*, which - is interpreted according to the radix in *base*. If *pend* is non-*NULL*, - ``*pend`` will point to the first character in *str* which follows the - representation of the number. If *base* is ``0``, the radix will be - determined based on the leading characters of *str*: if *str* starts with - ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or - ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``, - radix 2 will be used; otherwise radix 10 will be used. If *base* is not - ``0``, it must be between ``2`` and ``36``, inclusive. Leading spaces are - ignored. If there are no digits, :exc:`ValueError` will be raised. - - -.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base) - - Convert a sequence of Unicode digits to a Python integer value. The Unicode - string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal` - and then converted using :cfunc:`PyLong_FromString`. - - -.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p) - - Create a Python integer from the pointer *p*. The pointer value can be - retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`. - - -.. XXX alias PyLong_AS_LONG (for now) -.. cfunction:: long PyLong_AsLong(PyObject *pylong) - - .. index:: - single: LONG_MAX - single: OverflowError (built-in exception) - - Return a C :ctype:`long` representation of the contents of *pylong*. If - *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`, - and return -1. Convert non-long objects automatically to long first, - and return -1 if that raises exceptions. - -.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow) - - Return a C :ctype:`long` representation of the contents of *pylong*. If - *pylong* is greater than :const:`LONG_MAX`, return -1 and - set `*overflow` to 1 (for overflow) or -1 (for underflow). - If an exception is set because of type errors, also return -1. - - -.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) - - .. index:: - single: ULONG_MAX - single: OverflowError (built-in exception) - - Return a C :ctype:`unsigned long` representation of the contents of *pylong*. - If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is - raised. - - -.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) - - .. index:: - single: PY_SSIZE_T_MAX - - Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*. If - *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is - raised. - - -.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong) - - Return a :ctype:`size_t` representation of the contents of *pylong*. If - *pylong* is greater than the maximum value for a :ctype:`size_t`, an - :exc:`OverflowError` is raised. - - -.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong) - - Return a C :ctype:`long long` from a Python integer. If *pylong* cannot be - represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised. - - -.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong) - - Return a C :ctype:`unsigned long long` from a Python integer. If *pylong* - cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError` - will be raised if the value is positive, or a :exc:`TypeError` will be raised if - the value is negative. - - -.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io) - - Return a C :ctype:`unsigned long` from a Python integer, without checking for - overflow. - - -.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io) - - Return a C :ctype:`unsigned long long` from a Python integer, without - checking for overflow. - - -.. cfunction:: double PyLong_AsDouble(PyObject *pylong) - - Return a C :ctype:`double` representation of the contents of *pylong*. If - *pylong* cannot be approximately represented as a :ctype:`double`, an - :exc:`OverflowError` exception is raised and ``-1.0`` will be returned. - - -.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong) - - Convert a Python integer *pylong* to a C :ctype:`void` pointer. If *pylong* - cannot be converted, an :exc:`OverflowError` will be raised. This is only - assured to produce a usable :ctype:`void` pointer for values created with - :cfunc:`PyLong_FromVoidPtr`. - - -.. _floatobjects: - -Floating Point Objects ----------------------- - -.. index:: object: floating point - - -.. ctype:: PyFloatObject - - This subtype of :ctype:`PyObject` represents a Python floating point object. - - -.. cvar:: PyTypeObject PyFloat_Type - - .. index:: single: FloatType (in modules types) - - This instance of :ctype:`PyTypeObject` represents the Python floating point - type. This is the same object as ``float`` and ``types.FloatType``. - - -.. cfunction:: int PyFloat_Check(PyObject *p) - - Return true if its argument is a :ctype:`PyFloatObject` or a subtype of - :ctype:`PyFloatObject`. - - -.. cfunction:: int PyFloat_CheckExact(PyObject *p) - - Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of - :ctype:`PyFloatObject`. - - -.. cfunction:: PyObject* PyFloat_FromString(PyObject *str) - - Create a :ctype:`PyFloatObject` object based on the string value in *str*, or - *NULL* on failure. - - -.. cfunction:: PyObject* PyFloat_FromDouble(double v) - - Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure. - - -.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat) - - Return a C :ctype:`double` representation of the contents of *pyfloat*. If - *pyfloat* is not a Python floating point object but has a :meth:`__float__` - method, this method will first be called to convert *pyfloat* into a float. - - -.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat) - - Return a C :ctype:`double` representation of the contents of *pyfloat*, but - without error checking. - - -.. cfunction:: PyObject* PyFloat_GetInfo(void) - - Return a structseq instance which contains information about the - precision, minimum and maximum values of a float. It's a thin wrapper - around the header file :file:`float.h`. - - -.. cfunction:: double PyFloat_GetMax(void) - - Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`. - - -.. cfunction:: double PyFloat_GetMin(void) - - Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`. - - -.. _complexobjects: - -Complex Number Objects ----------------------- - -.. index:: object: complex number - -Python's complex number objects are implemented as two distinct types when -viewed from the C API: one is the Python object exposed to Python programs, and -the other is a C structure which represents the actual complex number value. -The API provides functions for working with both. - - -Complex Numbers as C Structures -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Note that the functions which accept these structures as parameters and return -them as results do so *by value* rather than dereferencing them through -pointers. This is consistent throughout the API. - - -.. ctype:: Py_complex - - The C structure which corresponds to the value portion of a Python complex - number object. Most of the functions for dealing with complex number objects - use structures of this type as input or output values, as appropriate. It is - defined as:: - - typedef struct { - double real; - double imag; - } Py_complex; - - -.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right) - - Return the sum of two complex numbers, using the C :ctype:`Py_complex` - representation. - - -.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right) - - Return the difference between two complex numbers, using the C - :ctype:`Py_complex` representation. - - -.. cfunction:: Py_complex _Py_c_neg(Py_complex complex) - - Return the negation of the complex number *complex*, using the C - :ctype:`Py_complex` representation. - - -.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right) - - Return the product of two complex numbers, using the C :ctype:`Py_complex` - representation. - - -.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor) - - Return the quotient of two complex numbers, using the C :ctype:`Py_complex` - representation. - - -.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp) - - Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex` - representation. - - -Complex Numbers as Python Objects -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -.. ctype:: PyComplexObject - - This subtype of :ctype:`PyObject` represents a Python complex number object. - - -.. cvar:: PyTypeObject PyComplex_Type - - This instance of :ctype:`PyTypeObject` represents the Python complex number - type. It is the same object as ``complex`` and ``types.ComplexType``. - - -.. cfunction:: int PyComplex_Check(PyObject *p) - - Return true if its argument is a :ctype:`PyComplexObject` or a subtype of - :ctype:`PyComplexObject`. - - -.. cfunction:: int PyComplex_CheckExact(PyObject *p) - - Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of - :ctype:`PyComplexObject`. - - -.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v) - - Create a new Python complex number object from a C :ctype:`Py_complex` value. - - -.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag) - - Return a new :ctype:`PyComplexObject` object from *real* and *imag*. - - -.. cfunction:: double PyComplex_RealAsDouble(PyObject *op) - - Return the real part of *op* as a C :ctype:`double`. - - -.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op) - - Return the imaginary part of *op* as a C :ctype:`double`. - - -.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op) - - Return the :ctype:`Py_complex` value of the complex number *op*. - - If *op* is not a Python complex number object but has a :meth:`__complex__` - method, this method will first be called to convert *op* to a Python complex - number object. + long.rst + bool.rst + float.rst + complex.rst .. _sequenceobjects: @@ -587,1515 +63,13 @@ intrinsic to the Python language. .. XXX sort out unicode, str, bytes and bytearray -.. _stringobjects: - -String Objects --------------- - -These functions raise :exc:`TypeError` when expecting a string parameter and are -called with a non-string parameter. - -.. index:: object: string - - -.. ctype:: PyStringObject - - This subtype of :ctype:`PyObject` represents a Python string object. - - -.. cvar:: PyTypeObject PyString_Type - - .. index:: single: StringType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python string type; it is - the same object as ``str`` and ``types.StringType`` in the Python layer. . - - -.. cfunction:: int PyString_Check(PyObject *o) - - Return true if the object *o* is a string object or an instance of a subtype of - the string type. - - -.. cfunction:: int PyString_CheckExact(PyObject *o) - - Return true if the object *o* is a string object, but not an instance of a - subtype of the string type. - - -.. cfunction:: PyObject* PyString_FromString(const char *v) - - Return a new string object with a copy of the string *v* as value on success, - and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be - checked. - - -.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len) - - Return a new string object with a copy of the string *v* as value and length - *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the - string are uninitialized. - - -.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...) - - Take a C :cfunc:`printf`\ -style *format* string and a variable number of - arguments, calculate the size of the resulting Python string and return a string - with the values formatted into it. The variable arguments must be C types and - must correspond exactly to the format characters in the *format* string. The - following format characters are allowed: - - .. % XXX: This should be exactly the same as the table in PyErr_Format. - .. % One should just refer to the other. - .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated - .. % because not all compilers support the %z width modifier -- we fake it - .. % when necessary via interpolating PY_FORMAT_SIZE_T. - .. % %u, %lu, %zu should have "new in Python 2.5" blurbs. - - +-------------------+---------------+--------------------------------+ - | Format Characters | Type | Comment | - +===================+===============+================================+ - | :attr:`%%` | *n/a* | The literal % character. | - +-------------------+---------------+--------------------------------+ - | :attr:`%c` | int | A single character, | - | | | represented as an C int. | - +-------------------+---------------+--------------------------------+ - | :attr:`%d` | int | Exactly equivalent to | - | | | ``printf("%d")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%u` | unsigned int | Exactly equivalent to | - | | | ``printf("%u")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%ld` | long | Exactly equivalent to | - | | | ``printf("%ld")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%lu` | unsigned long | Exactly equivalent to | - | | | ``printf("%lu")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | - | | | ``printf("%zd")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%zu` | size_t | Exactly equivalent to | - | | | ``printf("%zu")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%i` | int | Exactly equivalent to | - | | | ``printf("%i")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%x` | int | Exactly equivalent to | - | | | ``printf("%x")``. | - +-------------------+---------------+--------------------------------+ - | :attr:`%s` | char\* | A null-terminated C character | - | | | array. | - +-------------------+---------------+--------------------------------+ - | :attr:`%p` | void\* | The hex representation of a C | - | | | pointer. Mostly equivalent to | - | | | ``printf("%p")`` except that | - | | | it is guaranteed to start with | - | | | the literal ``0x`` regardless | - | | | of what the platform's | - | | | ``printf`` yields. | - +-------------------+---------------+--------------------------------+ - - An unrecognized format character causes all the rest of the format string to be - copied as-is to the result string, and any extra arguments discarded. - - -.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs) - - Identical to :func:`PyString_FromFormat` except that it takes exactly two - arguments. - - -.. cfunction:: Py_ssize_t PyString_Size(PyObject *string) - - Return the length of the string in string object *string*. - - -.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string) - - Macro form of :cfunc:`PyString_Size` but without error checking. - - -.. cfunction:: char* PyString_AsString(PyObject *string) - - Return a NUL-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. If - *string* is a Unicode object, this function computes the default encoding of - *string* and operates on that. If *string* is not a string object at all, - :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`. - - -.. cfunction:: char* PyString_AS_STRING(PyObject *string) - - Macro form of :cfunc:`PyString_AsString` but without error checking. Only - string objects are supported; no Unicode objects should be passed. - - -.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) - - Return a NUL-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 - *NULL*, the resulting buffer may not contain NUL characters; if it does, the - function returns ``-1`` and a :exc:`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. If - *string* is a Unicode object, this function computes the default encoding of - *string* and operates on that. If *string* is not a string object at all, - :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`. - - -.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart) - - Create 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. - - -.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart) - - Create a new string object in *\*string* containing the contents of *newpart* - appended to *string*. This version decrements the reference count of *newpart*. - - -.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t 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. It is an error to call this function if the - refcount on the input string object is not one. Pass the address of an existing - string object as an lvalue (it may be written into), and the new size desired. - On success, *\*string* holds the resized string object and ``0`` is returned; - the address in *\*string* may differ from its input value. If the reallocation - fails, the original string object at *\*string* is deallocated, *\*string* is - set to *NULL*, a memory exception is set, and ``-1`` is returned. - - -.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args) - - Return a new string object from *format* and *args*. Analogous to ``format % - args``. The *args* argument must be a tuple. - - -.. cfunction:: 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.) - - -.. cfunction:: PyObject* PyString_InternFromString(const char *v) - - A combination of :cfunc:`PyString_FromString` and - :cfunc:`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. - - -.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) - - Create an object by decoding *size* bytes of the encoded buffer *s* using the - codec registered for *encoding*. *encoding* and *errors* have the same meaning - as the parameters of the same name in the :func:`unicode` built-in function. - The codec to be used is looked up using the Python codec registry. Return - *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors) - - Decode a string object by passing it to the codec registered for *encoding* and - return the result as Python object. *encoding* and *errors* have the same - meaning as the parameters of the same name in the string :meth:`encode` method. - The codec to be used is looked up using the Python codec registry. Return *NULL* - if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors) - - Encode a string object using the codec registered for *encoding* and return the - result as Python object. *encoding* and *errors* have the same meaning as the - parameters of the same name in the string :meth:`encode` method. The codec to be - used is looked up using the Python codec registry. Return *NULL* if an exception - was raised by the codec. - - -.. _unicodeobjects: - -Unicode Objects ---------------- - -.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com> - - -These are the basic Unicode object types used for the Unicode implementation in -Python: - -.. % --- Unicode Type ------------------------------------------------------- - - -.. ctype:: Py_UNICODE - - This type represents the storage type which is used by Python internally as - basis for holding Unicode ordinals. Python's default builds use a 16-bit type - for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also - possible to build a UCS4 version of Python (most recent Linux distributions come - with UCS4 builds of Python). These builds then use a 32-bit type for - :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms - where :ctype:`wchar_t` is available and compatible with the chosen Python - Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for - :ctype:`wchar_t` to enhance native platform compatibility. On all other - platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned - short` (UCS2) or :ctype:`unsigned long` (UCS4). - -Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep -this in mind when writing extensions or interfaces. - - -.. ctype:: PyUnicodeObject - - This subtype of :ctype:`PyObject` represents a Python Unicode object. - - -.. cvar:: PyTypeObject PyUnicode_Type - - This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It - is exposed to Python code as ``str``. - -The following APIs are really C macros and can be used to do fast checks and to -access internal read-only data of Unicode objects: - - -.. cfunction:: int PyUnicode_Check(PyObject *o) - - Return true if the object *o* is a Unicode object or an instance of a Unicode - subtype. - - -.. cfunction:: int PyUnicode_CheckExact(PyObject *o) - - Return true if the object *o* is a Unicode object, but not an instance of a - subtype. - - -.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o) - - Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not - checked). - - -.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o) - - Return the size of the object's internal buffer in bytes. *o* has to be a - :ctype:`PyUnicodeObject` (not checked). - - -.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o) - - Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. *o* - has to be a :ctype:`PyUnicodeObject` (not checked). - - -.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o) - - Return a pointer to the internal buffer of the object. *o* has to be a - :ctype:`PyUnicodeObject` (not checked). - -Unicode provides many different character properties. The most often needed ones -are available through these macros which are mapped to C functions depending on -the Python configuration. - -.. % --- Unicode character properties --------------------------------------- - - -.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a whitespace character. - - -.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a lowercase character. - - -.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is an uppercase character. - - -.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a titlecase character. - - -.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a linebreak character. - - -.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a decimal character. - - -.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a digit character. - - -.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is a numeric character. - - -.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is an alphabetic character. - - -.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch) - - Return 1 or 0 depending on whether *ch* is an alphanumeric character. - -These APIs can be used for fast direct character conversions: - - -.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch) - - Return the character *ch* converted to lower case. - - -.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch) - - Return the character *ch* converted to upper case. - - -.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch) - - Return the character *ch* converted to title case. - - -.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch) - - Return the character *ch* converted to a decimal positive integer. Return - ``-1`` if this is not possible. This macro does not raise exceptions. - - -.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch) - - Return the character *ch* converted to a single digit integer. Return ``-1`` if - this is not possible. This macro does not raise exceptions. - - -.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch) - - Return the character *ch* converted to a double. Return ``-1.0`` if this is not - possible. This macro does not raise exceptions. - -To create Unicode objects and access their basic sequence properties, use these -APIs: - -.. % --- Plain Py_UNICODE --------------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size) - - Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u* - may be *NULL* which causes the contents to be undefined. It is the user's - responsibility to fill in the needed data. The buffer is copied into the new - object. If the buffer is not *NULL*, the return value might be a shared object. - Therefore, modification of the resulting Unicode object is only allowed when *u* - is *NULL*. - - -.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size) - - Create a Unicode Object from the char buffer *u*. The bytes will be interpreted - as being UTF-8 encoded. *u* may also be *NULL* which - causes the contents to be undefined. It is the user's responsibility to fill in - the needed data. The buffer is copied into the new object. If the buffer is not - *NULL*, the return value might be a shared object. Therefore, modification of - the resulting Unicode object is only allowed when *u* is *NULL*. - - -.. cfunction:: PyObject *PyUnicode_FromString(const char *u) - - Create a Unicode object from an UTF-8 encoded null-terminated char buffer - *u*. - - -.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...) - - Take a C :cfunc:`printf`\ -style *format* string and a variable number of - arguments, calculate the size of the resulting Python unicode string and return - a string with the values formatted into it. The variable arguments must be C - types and must correspond exactly to the format characters in the *format* - string. The following format characters are allowed: - - .. % The descriptions for %zd and %zu are wrong, but the truth is complicated - .. % because not all compilers support the %z width modifier -- we fake it - .. % when necessary via interpolating PY_FORMAT_SIZE_T. - - +-------------------+---------------------+--------------------------------+ - | Format Characters | Type | Comment | - +===================+=====================+================================+ - | :attr:`%%` | *n/a* | The literal % character. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%c` | int | A single character, | - | | | represented as an C int. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%d` | int | Exactly equivalent to | - | | | ``printf("%d")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%u` | unsigned int | Exactly equivalent to | - | | | ``printf("%u")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%ld` | long | Exactly equivalent to | - | | | ``printf("%ld")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%lu` | unsigned long | Exactly equivalent to | - | | | ``printf("%lu")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | - | | | ``printf("%zd")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%zu` | size_t | Exactly equivalent to | - | | | ``printf("%zu")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%i` | int | Exactly equivalent to | - | | | ``printf("%i")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%x` | int | Exactly equivalent to | - | | | ``printf("%x")``. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%s` | char\* | A null-terminated C character | - | | | array. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%p` | void\* | The hex representation of a C | - | | | pointer. Mostly equivalent to | - | | | ``printf("%p")`` except that | - | | | it is guaranteed to start with | - | | | the literal ``0x`` regardless | - | | | of what the platform's | - | | | ``printf`` yields. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%U` | PyObject\* | A unicode object. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%V` | PyObject\*, char \* | A unicode object (which may be | - | | | *NULL*) and a null-terminated | - | | | C character array as a second | - | | | parameter (which will be used, | - | | | if the first parameter is | - | | | *NULL*). | - +-------------------+---------------------+--------------------------------+ - | :attr:`%S` | PyObject\* | The result of calling | - | | | :func:`PyObject_Unicode`. | - +-------------------+---------------------+--------------------------------+ - | :attr:`%R` | PyObject\* | The result of calling | - | | | :func:`PyObject_Repr`. | - +-------------------+---------------------+--------------------------------+ - - An unrecognized format character causes all the rest of the format string to be - copied as-is to the result string, and any extra arguments discarded. - - -.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs) - - Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two - arguments. - - -.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) - - Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE` - buffer, *NULL* if *unicode* is not a Unicode object. - - -.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode) - - Return the length of the Unicode object. - - -.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors) - - Coerce an encoded object *obj* to an Unicode object and return a reference with - incremented refcount. - - String and other char buffer compatible objects are decoded according to the - given encoding and using the error handling defined by errors. Both can be - *NULL* to have the interface use the default values (see the next section for - details). - - All other objects, including Unicode objects, cause a :exc:`TypeError` to be - set. - - The API returns *NULL* if there was an error. The caller is responsible for - decref'ing the returned objects. - - -.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj) - - Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used - throughout the interpreter whenever coercion to Unicode is needed. - -If the platform supports :ctype:`wchar_t` and provides a header file wchar.h, -Python can interface directly to this type using the following functions. -Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to -the system's :ctype:`wchar_t`. - -.. % --- wchar_t support for platforms which support it --------------------- - - -.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size) - - Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size. - Return *NULL* on failure. - - -.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size) - - Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*. At most - *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing - 0-termination character). Return the number of :ctype:`wchar_t` characters - copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t` - string may or may not be 0-terminated. It is the responsibility of the caller - to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is - required by the application. - - -.. _builtincodecs: - -Built-in Codecs -^^^^^^^^^^^^^^^ - -Python provides a set of builtin codecs which are written in C for speed. All of -these codecs are directly usable via the following functions. - -Many of the following APIs take two arguments encoding and errors. These -parameters encoding and errors have the same semantics as the ones of the -builtin unicode() Unicode object constructor. - -Setting encoding to *NULL* causes the default encoding to be used which is -ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding` -as the encoding for file names. This variable should be treated as read-only: On -some systems, it will be a pointer to a static string, on others, it will change -at run-time (such as when the application invokes setlocale). - -Error handling is set by errors which may also be set to *NULL* meaning to use -the default handling defined for the codec. Default error handling for all -builtin codecs is "strict" (:exc:`ValueError` is raised). - -The codecs all use a similar interface. Only deviation from the following -generic ones are documented for simplicity. - -These are the generic codec APIs: - -.. % --- Generic Codecs ----------------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) - - Create a Unicode object by decoding *size* bytes of the encoded string *s*. - *encoding* and *errors* have the same meaning as the parameters of the same name - in the :func:`unicode` builtin function. The codec to be used is looked up - using the Python codec registry. Return *NULL* if an exception was raised by - the codec. - - -.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python - string object. *encoding* and *errors* have the same meaning as the parameters - of the same name in the Unicode :meth:`encode` method. The codec to be used is - looked up using the Python codec registry. Return *NULL* if an exception was - raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors) - - Encode a Unicode object and return the result as Python string object. - *encoding* and *errors* have the same meaning as the parameters of the same name - in the Unicode :meth:`encode` method. The codec to be used is looked up using - the Python codec registry. Return *NULL* if an exception was raised by the - codec. - -These are the UTF-8 codec APIs: - -.. % --- UTF-8 Codecs ------------------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string - *s*. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed) - - If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If - *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be - treated as an error. Those bytes will not be decoded and the number of bytes - that have been decoded will be stored in *consumed*. - - -.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a - Python string object. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode) - - Encode a Unicode object using UTF-8 and return the result as Python string - object. Error handling is "strict". Return *NULL* if an exception was raised - by the codec. - -These are the UTF-32 codec APIs: - -.. % --- UTF-32 Codecs ------------------------------------------------------ */ - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder) - - Decode *length* bytes from a UTF-32 encoded buffer string and return the - corresponding Unicode object. *errors* (if non-*NULL*) defines the error - handling. It defaults to "strict". - - If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte - order:: - - *byteorder == -1: little endian - *byteorder == 0: native order - *byteorder == 1: big endian - - and then switches if the first four bytes of the input data are a byte order mark - (BOM) and the specified byte order is native order. This BOM is not copied into - the resulting Unicode string. After completion, *\*byteorder* is set to the - current byte order at the end of input data. - - In a narrow build codepoints outside the BMP will be decoded as surrogate pairs. - - If *byteorder* is *NULL*, the codec starts in native order mode. - - Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) - - If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If - *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat - trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible - by four) as an error. Those bytes will not be decoded and the number of bytes - that have been decoded will be stored in *consumed*. - - -.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) - - Return a Python bytes object holding the UTF-32 encoded value of the Unicode - data in *s*. If *byteorder* is not ``0``, output is written according to the - following byte order:: - - byteorder == -1: little endian - byteorder == 0: native byte order (writes a BOM mark) - byteorder == 1: big endian - - If byteorder is ``0``, the output string will always start with the Unicode BOM - mark (U+FEFF). In the other two modes, no BOM mark is prepended. - - If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output - as a single codepoint. - - Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode) - - Return a Python string using the UTF-32 encoding in native byte order. The - string always starts with a BOM mark. Error handling is "strict". Return - *NULL* if an exception was raised by the codec. - - -These are the UTF-16 codec APIs: - -.. % --- UTF-16 Codecs ------------------------------------------------------ */ - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder) - - Decode *length* bytes from a UTF-16 encoded buffer string and return the - corresponding Unicode object. *errors* (if non-*NULL*) defines the error - handling. It defaults to "strict". - - If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte - order:: - - *byteorder == -1: little endian - *byteorder == 0: native order - *byteorder == 1: big endian - - and then switches if the first two bytes of the input data are a byte order mark - (BOM) and the specified byte order is native order. This BOM is not copied into - the resulting Unicode string. After completion, *\*byteorder* is set to the - current byte order at the end of input data. - - If *byteorder* is *NULL*, the codec starts in native order mode. - - Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) - - If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If - *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat - trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a - split surrogate pair) as an error. Those bytes will not be decoded and the - number of bytes that have been decoded will be stored in *consumed*. - - -.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) - - Return a Python string object holding the UTF-16 encoded value of the Unicode - data in *s*. If *byteorder* is not ``0``, output is written according to the - following byte order:: - - byteorder == -1: little endian - byteorder == 0: native byte order (writes a BOM mark) - byteorder == 1: big endian - - If byteorder is ``0``, the output string will always start with the Unicode BOM - mark (U+FEFF). In the other two modes, no BOM mark is prepended. - - If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get - represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE` - values is interpreted as an UCS-2 character. - - Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode) - - Return a Python string using the UTF-16 encoding in native byte order. The - string always starts with a BOM mark. Error handling is "strict". Return - *NULL* if an exception was raised by the codec. - -These are the "Unicode Escape" codec APIs: - -.. % --- Unicode-Escape Codecs ---------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded - string *s*. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and - return a Python string object. Return *NULL* if an exception was raised by the - codec. - - -.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode) - - Encode a Unicode object using Unicode-Escape and return the result as Python - string object. Error handling is "strict". Return *NULL* if an exception was - raised by the codec. - -These are the "Raw Unicode Escape" codec APIs: - -.. % --- Raw-Unicode-Escape Codecs ------------------------------------------ - - -.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape - encoded string *s*. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape - and return a Python string object. Return *NULL* if an exception was raised by - the codec. - - -.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode) - - Encode a Unicode object using Raw-Unicode-Escape and return the result as - Python string object. Error handling is "strict". Return *NULL* if an exception - was raised by the codec. - -These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode -ordinals and only these are accepted by the codecs during encoding. - -.. % --- Latin-1 Codecs ----------------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string - *s*. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return - a Python string object. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode) - - Encode a Unicode object using Latin-1 and return the result as Python string - object. Error handling is "strict". Return *NULL* if an exception was raised - by the codec. - -These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other -codes generate errors. - -.. % --- ASCII Codecs ------------------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the ASCII encoded string - *s*. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a - Python string object. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode) - - Encode a Unicode object using ASCII and return the result as Python string - object. Error handling is "strict". Return *NULL* if an exception was raised - by the codec. - -These are the mapping codec APIs: - -.. % --- Character Map Codecs ----------------------------------------------- - -This codec is special in that it can be used to implement many different codecs -(and this is in fact what was done to obtain most of the standard codecs -included in the :mod:`encodings` package). The codec uses mapping to encode and -decode characters. - -Decoding mappings must map single string characters to single Unicode -characters, integers (which are then interpreted as Unicode ordinals) or None -(meaning "undefined mapping" and causing an error). - -Encoding mappings must map single Unicode characters to single string -characters, integers (which are then interpreted as Latin-1 ordinals) or None -(meaning "undefined mapping" and causing an error). - -The mapping objects provided must only support the __getitem__ mapping -interface. - -If a character lookup fails with a LookupError, the character is copied as-is -meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal -resp. Because of this, mappings only need to contain those mappings which map -characters to different code points. - - -.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors) - - Create a Unicode object by decoding *size* bytes of the encoded string *s* using - the given *mapping* object. Return *NULL* if an exception was raised by the - codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a - dictionary mapping byte or a unicode string, which is treated as a lookup table. - Byte values greater that the length of the string and U+FFFE "characters" are - treated as "undefined mapping". - - -.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using the given - *mapping* object and return a Python string object. Return *NULL* if an - exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping) - - Encode a Unicode object using the given *mapping* object and return the result - as Python string object. Error handling is "strict". Return *NULL* if an - exception was raised by the codec. - -The following codec API is special in that maps Unicode to Unicode. - - -.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors) - - Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a - character mapping *table* to it and return the resulting Unicode object. Return - *NULL* when an exception was raised by the codec. - - The *mapping* table must map Unicode ordinal integers to Unicode ordinal - integers or None (causing deletion of the character). - - Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries - and sequences work well. Unmapped character ordinals (ones which cause a - :exc:`LookupError`) are left untouched and are copied as-is. - -These are the MBCS codec APIs. They are currently only available on Windows and -use the Win32 MBCS converters to implement the conversions. Note that MBCS (or -DBCS) is a class of encodings, not just one. The target encoding is defined by -the user settings on the machine running the codec. - -.. % --- MBCS codecs for Windows -------------------------------------------- - - -.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors) - - Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*. - Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed) - - If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If - *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode - trailing lead byte and the number of bytes that have been decoded will be stored - in *consumed*. - - -.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors) - - Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a - Python string object. Return *NULL* if an exception was raised by the codec. - - -.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode) - - Encode a Unicode object using MBCS and return the result as Python string - object. Error handling is "strict". Return *NULL* if an exception was raised - by the codec. - -.. % --- Methods & Slots ---------------------------------------------------- - - -.. _unicodemethodsandslots: - -Methods and Slot Functions -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following APIs are capable of handling Unicode objects and strings on input -(we refer to them as strings in the descriptions) and return Unicode objects or -integers as appropriate. - -They all return *NULL* or ``-1`` if an exception occurs. - - -.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right) - - Concat two strings giving a new Unicode string. - - -.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit) - - Split a string giving a list of Unicode strings. If sep is *NULL*, splitting - will be done at all whitespace substrings. Otherwise, splits occur at the given - separator. At most *maxsplit* splits will be done. If negative, no limit is - set. Separators are not included in the resulting list. - - -.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend) - - Split a Unicode string at line breaks, returning a list of Unicode strings. - CRLF is considered to be one line break. If *keepend* is 0, the Line break - characters are not included in the resulting strings. - - -.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors) - - Translate a string by applying a character mapping table to it and return the - resulting Unicode object. - - The mapping table must map Unicode ordinal integers to Unicode ordinal integers - or None (causing deletion of the character). - - Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries - and sequences work well. Unmapped character ordinals (ones which cause a - :exc:`LookupError`) are left untouched and are copied as-is. - - *errors* has the usual meaning for codecs. It may be *NULL* which indicates to - use the default error handling. - - -.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) - - Join a sequence of strings using the given separator and return the resulting - Unicode string. - - -.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) - - Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end - (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match), - 0 otherwise. Return ``-1`` if an error occurred. - - -.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) - - Return the first position of *substr* in *str*[*start*:*end*] using the given - *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a - backward search). The return value is the index of the first match; a value of - ``-1`` indicates that no match was found, and ``-2`` indicates that an error - occurred and an exception has been set. - - -.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end) - - Return the number of non-overlapping occurrences of *substr* in - ``str[start:end]``. Return ``-1`` if an error occurred. - - -.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount) - - Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and - return the resulting Unicode object. *maxcount* == -1 means replace all - occurrences. - - -.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right) - - Compare two strings and return -1, 0, 1 for less than, equal, and greater than, - respectively. - - -.. cfunction:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op) - - Rich compare two unicode strings and return one of the following: - - * ``NULL`` in case an exception was raised - * :const:`Py_True` or :const:`Py_False` for successful comparisons - * :const:`Py_NotImplemented` in case the type combination is unknown - - Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a - :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails - with a :exc:`UnicodeDecodeError`. - - Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`, - :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`. - - -.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args) - - Return a new string object from *format* and *args*; this is analogous to - ``format % args``. The *args* argument must be a tuple. - - -.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element) - - Check whether *element* is contained in *container* and return true or false - accordingly. - - *element* has to coerce to a one element Unicode string. ``-1`` is returned if - there was an error. - - -.. cfunction:: void PyUnicode_InternInPlace(PyObject **string) - - Intern the argument *\*string* in place. The argument must be the address of a - pointer variable pointing to a Python unicode 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.) - - -.. cfunction:: PyObject* PyUnicode_InternFromString(const char *v) - - A combination of :cfunc:`PyUnicode_FromString` and - :cfunc:`PyUnicode_InternInPlace`, returning either a new unicode string object - that has been interned, or a new ("owned") reference to an earlier interned - string object with the same value. - - -.. _bufferobjects: - -Buffer Objects --------------- - -.. sectionauthor:: Greg Stein <gstein@lyra.org> - - -.. index:: - object: buffer - single: buffer interface - -Python objects implemented in C can export a group of functions called the -"buffer interface." These functions can be used by an object to expose its data -in a raw, byte-oriented format. Clients of the object can use the buffer -interface to access the object data directly, without needing to copy it first. - -Two examples of objects that support the buffer interface are strings and -arrays. The string object exposes the character contents in the buffer -interface's byte-oriented form. An array can also expose its contents, but it -should be noted that array elements may be multi-byte values. - -An example user of the buffer interface is the file object's :meth:`write` -method. Any object that can export a series of bytes through the buffer -interface can be written to a file. There are a number of format codes to -:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface, -returning data from the target object. - -.. index:: single: PyBufferProcs - -More information on the buffer interface is provided in the section -:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. - -A "buffer object" is defined in the :file:`bufferobject.h` header (included by -:file:`Python.h`). These objects look very similar to string objects at the -Python programming level: they support slicing, indexing, concatenation, and -some other standard string operations. However, their data can come from one of -two sources: from a block of memory, or from another object which exports the -buffer interface. - -Buffer objects are useful as a way to expose the data from another object's -buffer interface to the Python programmer. They can also be used as a zero-copy -slicing mechanism. Using their ability to reference a block of memory, it is -possible to expose any data to the Python programmer quite easily. The memory -could be a large, constant array in a C extension, it could be a raw block of -memory for manipulation before passing to an operating system library, or it -could be used to pass around structured data in its native, in-memory format. - - -.. ctype:: PyBufferObject - - This subtype of :ctype:`PyObject` represents a buffer object. - - -.. cvar:: PyTypeObject PyBuffer_Type - - .. index:: single: BufferType (in module types) - - The instance of :ctype:`PyTypeObject` which represents the Python buffer type; - it is the same object as ``buffer`` and ``types.BufferType`` in the Python - layer. . - - -.. cvar:: int Py_END_OF_BUFFER - - This constant may be passed as the *size* parameter to - :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It - indicates that the new :ctype:`PyBufferObject` should refer to *base* object - from the specified *offset* to the end of its exported buffer. Using this - enables the caller to avoid querying the *base* object for its length. - - -.. cfunction:: int PyBuffer_Check(PyObject *p) - - Return true if the argument has type :cdata:`PyBuffer_Type`. - - -.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) - - Return a new read-only buffer object. This raises :exc:`TypeError` if *base* - doesn't support the read-only buffer protocol or doesn't provide exactly one - buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero. - The buffer will hold a reference to the *base* object, and the buffer's contents - will refer to the *base* object's buffer interface, starting as position - *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`, - then the new buffer's contents extend to the length of the *base* object's - exported buffer data. - +.. toctree:: -.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) - - Return a new writable buffer object. Parameters and exceptions are similar to - those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export - the writable buffer protocol, then :exc:`TypeError` is raised. - - -.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) - - Return a new read-only buffer object that reads from a specified location in - memory, with a specified size. The caller is responsible for ensuring that the - memory buffer, passed in as *ptr*, is not deallocated while the returned buffer - object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that - :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter; - :exc:`ValueError` will be raised in that case. - - -.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) - - Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable. - - -.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size) - - Return a new writable buffer object that maintains its own memory buffer of - *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive. - Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is - not specifically aligned. - - -.. _tupleobjects: - -Tuple Objects -------------- - -.. index:: object: tuple - - -.. ctype:: PyTupleObject - - This subtype of :ctype:`PyObject` represents a Python tuple object. - - -.. cvar:: PyTypeObject PyTuple_Type - - .. index:: single: TupleType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is - the same object as ``tuple`` and ``types.TupleType`` in the Python layer.. - - -.. cfunction:: int PyTuple_Check(PyObject *p) - - Return true if *p* is a tuple object or an instance of a subtype of the tuple - type. - - -.. cfunction:: int PyTuple_CheckExact(PyObject *p) - - Return true if *p* is a tuple object, but not an instance of a subtype of the - tuple type. - - -.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len) - - Return a new tuple object of size *len*, or *NULL* on failure. - - -.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) - - Return a new tuple object of size *n*, or *NULL* on failure. The tuple values - are initialized to the subsequent *n* C arguments pointing to Python objects. - ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. - - -.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p) - - Take a pointer to a tuple object, and return the size of that tuple. - - -.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) - - Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple; - no error checking is performed. - - -.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) - - Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is - out of bounds, return *NULL* and sets an :exc:`IndexError` exception. - - -.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) - - Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments. - - -.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) - - Take a slice of the tuple pointed to by *p* from *low* to *high* and return it - as a new tuple. - - -.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) - - Insert a reference to object *o* at position *pos* of the tuple pointed to by - *p*. Return ``0`` on success. - - .. note:: - - This function "steals" a reference to *o*. - - -.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) - - Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be - used to fill in brand new tuples. - - .. note:: - - This function "steals" a reference to *o*. - - -.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) - - Can be used to resize a tuple. *newsize* will be the new length of the tuple. - Because tuples are *supposed* to be immutable, this should only be used if there - is only one reference to the object. Do *not* use this if the tuple may already - be known to some other part of the code. The tuple will always grow or shrink - at the end. Think of this as destroying the old tuple and creating a new one, - only more efficiently. Returns ``0`` on success. Client code should never - assume that the resulting value of ``*p`` will be the same as before calling - this function. If the object referenced by ``*p`` is replaced, the original - ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and - raises :exc:`MemoryError` or :exc:`SystemError`. - - -.. _listobjects: - -List Objects ------------- - -.. index:: object: list - - -.. ctype:: PyListObject - - This subtype of :ctype:`PyObject` represents a Python list object. - - -.. cvar:: PyTypeObject PyList_Type - - .. index:: single: ListType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python list type. This is - the same object as ``list`` and ``types.ListType`` in the Python layer. - - -.. cfunction:: int PyList_Check(PyObject *p) - - Return true if *p* is a list object or an instance of a subtype of the list - type. - - -.. cfunction:: int PyList_CheckExact(PyObject *p) - - Return true if *p* is a list object, but not an instance of a subtype of the - list type. - - -.. cfunction:: PyObject* PyList_New(Py_ssize_t len) - - Return a new list of length *len* on success, or *NULL* on failure. - - .. note:: - - If *length* is greater than zero, the returned list object's items are set to - ``NULL``. Thus you cannot use abstract API functions such as - :cfunc:`PySequence_SetItem` or expose the object to Python code before setting - all items to a real object with :cfunc:`PyList_SetItem`. - - -.. cfunction:: Py_ssize_t PyList_Size(PyObject *list) - - .. index:: builtin: len - - Return the length of the list object in *list*; this is equivalent to - ``len(list)`` on a list object. - - -.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list) - - Macro form of :cfunc:`PyList_Size` without error checking. - - -.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) - - Return the object at position *pos* in the list pointed to by *p*. The position - must be positive, indexing from the end of the list is not supported. If *pos* - is out of bounds, return *NULL* and set an :exc:`IndexError` exception. - - -.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) - - Macro form of :cfunc:`PyList_GetItem` without error checking. - - -.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) - - Set the item at index *index* in list to *item*. Return ``0`` on success or - ``-1`` on failure. - - .. note:: - - This function "steals" a reference to *item* and discards a reference to an item - already in the list at the affected position. - - -.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) - - Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally - only used to fill in new lists where there is no previous content. - - .. note:: - - This function "steals" a reference to *item*, and, unlike - :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it - being replaced; any reference in *list* at position *i* will be leaked. - - -.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) - - Insert the item *item* into list *list* in front of index *index*. Return ``0`` - if successful; return ``-1`` and set an exception if unsuccessful. Analogous to - ``list.insert(index, item)``. - - -.. cfunction:: int PyList_Append(PyObject *list, PyObject *item) - - Append the object *item* at the end of list *list*. Return ``0`` if successful; - return ``-1`` and set an exception if unsuccessful. Analogous to - ``list.append(item)``. - - -.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) - - Return a list of the objects in *list* containing the objects *between* *low* - and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to - ``list[low:high]``. - - -.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist) - - Set the slice of *list* between *low* and *high* to the contents of *itemlist*. - Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*, - indicating the assignment of an empty list (slice deletion). Return ``0`` on - success, ``-1`` on failure. - - -.. cfunction:: int PyList_Sort(PyObject *list) - - Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure. - This is equivalent to ``list.sort()``. - - -.. cfunction:: int PyList_Reverse(PyObject *list) - - Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on - failure. This is the equivalent of ``list.reverse()``. - - -.. cfunction:: PyObject* PyList_AsTuple(PyObject *list) - - .. index:: builtin: tuple - - Return a new tuple object containing the contents of *list*; equivalent to - ``tuple(list)``. + string.rst + unicode.rst + buffer.rst + tuple.rst + list.rst .. _mapobjects: @@ -2105,211 +79,9 @@ Mapping Objects .. index:: object: mapping +.. toctree:: -.. _dictobjects: - -Dictionary Objects ------------------- - -.. index:: object: dictionary - - -.. ctype:: PyDictObject - - This subtype of :ctype:`PyObject` represents a Python dictionary object. - - -.. cvar:: PyTypeObject PyDict_Type - - .. index:: - single: DictType (in module types) - single: DictionaryType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python dictionary type. - This is exposed to Python programs as ``dict`` and ``types.DictType``. - - -.. cfunction:: int PyDict_Check(PyObject *p) - - Return true if *p* is a dict object or an instance of a subtype of the dict - type. - - -.. cfunction:: int PyDict_CheckExact(PyObject *p) - - Return true if *p* is a dict object, but not an instance of a subtype of the - dict type. - - -.. cfunction:: PyObject* PyDict_New() - - Return a new empty dictionary, or *NULL* on failure. - - -.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict) - - Return a proxy object for a mapping which enforces read-only behavior. This is - normally used to create a proxy to prevent modification of the dictionary for - non-dynamic class types. - - -.. cfunction:: void PyDict_Clear(PyObject *p) - - Empty an existing dictionary of all key-value pairs. - - -.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key) - - Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*, - return ``1``, otherwise return ``0``. On error, return ``-1``. This is - equivalent to the Python expression ``key in p``. - - -.. cfunction:: PyObject* PyDict_Copy(PyObject *p) - - Return a new dictionary that contains the same key-value pairs as *p*. - - -.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val) - - Insert *value* into the dictionary *p* with a key of *key*. *key* must be - :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0`` - on success or ``-1`` on failure. - - -.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val) - - .. index:: single: PyString_FromString() - - Insert *value* into the dictionary *p* using *key* as a key. *key* should be a - :ctype:`char\*`. The key object is created using ``PyString_FromString(key)``. - Return ``0`` on success or ``-1`` on failure. - - -.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key) - - Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it - isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` on - failure. - - -.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key) - - Remove the entry in dictionary *p* which has a key specified by the string - *key*. Return ``0`` on success or ``-1`` on failure. - - -.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key) - - Return the object from dictionary *p* which has a key *key*. Return *NULL* if - the key *key* is not present, but *without* setting an exception. - - -.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) - - This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a - :ctype:`char\*`, rather than a :ctype:`PyObject\*`. - - -.. cfunction:: PyObject* PyDict_Items(PyObject *p) - - Return a :ctype:`PyListObject` containing all the items from the dictionary, as - in the dictionary method :meth:`dict.items`. - - -.. cfunction:: PyObject* PyDict_Keys(PyObject *p) - - Return a :ctype:`PyListObject` containing all the keys from the dictionary, as - in the dictionary method :meth:`dict.keys`. - - -.. cfunction:: PyObject* PyDict_Values(PyObject *p) - - Return a :ctype:`PyListObject` containing all the values from the dictionary - *p*, as in the dictionary method :meth:`dict.values`. - - -.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) - - .. index:: builtin: len - - Return the number of items in the dictionary. This is equivalent to ``len(p)`` - on a dictionary. - - -.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue) - - Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int` - referred to by *ppos* must be initialized to ``0`` prior to the first call to - this function to start the iteration; the function returns true for each pair in - the dictionary, and false once all pairs have been reported. The parameters - *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that - will be filled in with each key and value, respectively, or may be *NULL*. Any - references returned through them are borrowed. *ppos* should not be altered - during iteration. Its value represents offsets within the internal dictionary - structure, and since the structure is sparse, the offsets are not consecutive. - - For example:: - - PyObject *key, *value; - Py_ssize_t pos = 0; - - while (PyDict_Next(self->dict, &pos, &key, &value)) { - /* do something interesting with the values... */ - ... - } - - The dictionary *p* should not be mutated during iteration. It is safe (since - Python 2.1) to modify the values of the keys as you iterate over the dictionary, - but only so long as the set of keys does not change. For example:: - - PyObject *key, *value; - Py_ssize_t pos = 0; - - while (PyDict_Next(self->dict, &pos, &key, &value)) { - long i = PyLong_AsLong(value); - if (i == -1 && PyErr_Occurred()) { - return -1; - } - PyObject *o = PyLong_FromLong(i + 1); - if (o == NULL) - return -1; - if (PyDict_SetItem(self->dict, key, o) < 0) { - Py_DECREF(o); - return -1; - } - Py_DECREF(o); - } - - -.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override) - - Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b* - may be a dictionary, or any object supporting :func:`PyMapping_Keys` and - :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be - replaced if a matching key is found in *b*, otherwise pairs will only be added - if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an - exception was raised. - - -.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b) - - This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in - Python. Return ``0`` on success or ``-1`` if an exception was raised. - - -.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override) - - Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2* - must be an iterable object producing iterable objects of length 2, viewed as - key-value pairs. In case of duplicate keys, the last wins if *override* is - true, else the first wins. Return ``0`` on success or ``-1`` if an exception was - raised. Equivalent Python (except for the return value):: - - def PyDict_MergeFromSeq2(a, seq2, override): - for key, value in seq2: - if override or key not in a: - a[key] = value + dict.rst .. _otherobjects: @@ -2317,1089 +89,18 @@ Dictionary Objects Other Objects ============= -.. _fileobjects: - -File Objects ------------- - -.. index:: object: file - -Python's built-in file objects are implemented entirely on the :ctype:`FILE\*` -support from the C standard library. This is an implementation detail and may -change in future releases of Python. - - -.. ctype:: PyFileObject - - This subtype of :ctype:`PyObject` represents a Python file object. - - -.. cvar:: PyTypeObject PyFile_Type - - .. index:: single: FileType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python file type. This is - exposed to Python programs as ``file`` and ``types.FileType``. - - -.. cfunction:: int PyFile_Check(PyObject *p) - - Return true if its argument is a :ctype:`PyFileObject` or a subtype of - :ctype:`PyFileObject`. - - -.. cfunction:: int PyFile_CheckExact(PyObject *p) - - Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of - :ctype:`PyFileObject`. - - -.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd) - - Create a new :ctype:`PyFileObject` from the file descriptor of an already - opened file *fd*. The arguments *name*, *encoding* and *newline* can be - *NULL* to use the defaults; *buffering* can be *-1* to use the default. - Return *NULL* on failure. - - .. warning:: - - Take care when you are mixing streams and descriptors! For more - information, see `the GNU C Library docs - <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_. - - -.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p) - - Return the file descriptor associated with *p* as an :ctype:`int`. If the - object is an integer, its value is returned. If not, the - object's :meth:`fileno` method is called if it exists; the method must return - an integer, which is returned as the file descriptor value. Sets an - exception and returns ``-1`` on failure. - - -.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n) - - .. index:: single: EOFError (built-in exception) - - Equivalent to ``p.readline([n])``, this function reads one line from the - object *p*. *p* may be a file object or any object with a :meth:`readline` - method. If *n* is ``0``, exactly one line is read, regardless of the length of - the line. If *n* is greater than ``0``, no more than *n* bytes will be read - from the file; a partial line can be returned. In both cases, an empty string - is returned if the end of the file is reached immediately. If *n* is less than - ``0``, however, one line is read regardless of length, but :exc:`EOFError` is - raised if the end of the file is reached immediately. - - -.. cfunction:: PyObject* PyFile_Name(PyObject *p) - - Return the name of the file specified by *p* as a string object. - - -.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n) - - .. index:: single: setvbuf() - - Available on systems with :cfunc:`setvbuf` only. This should only be called - immediately after file object creation. - - -.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc) - - Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0 - on failure. - - -.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag) - - .. index:: single: softspace (file attribute) - - This function exists for internal use by the interpreter. Set the - :attr:`softspace` attribute of *p* to *newflag* and return the previous value. - *p* does not have to be a file object for this function to work properly; any - object is supported (thought its only interesting if the :attr:`softspace` - attribute can be set). This function clears any errors, and will return ``0`` - as the previous value if the attribute either does not exist or if there were - errors in retrieving it. There is no way to detect errors from this function, - but doing so should not be needed. - - -.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags) - - .. index:: single: Py_PRINT_RAW - - Write object *obj* to file object *p*. The only supported flag for *flags* is - :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written - instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the - appropriate exception will be set. - - -.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p) - - Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on - failure; the appropriate exception will be set. - - -.. _function-objects: - -Function Objects ----------------- - -.. index:: object: function - -There are a few functions specific to Python functions. - - -.. ctype:: PyFunctionObject - - The C structure used for functions. - - -.. cvar:: PyTypeObject PyFunction_Type - - .. index:: single: MethodType (in module types) - - This is an instance of :ctype:`PyTypeObject` and represents the Python function - type. It is exposed to Python programmers as ``types.FunctionType``. - - -.. cfunction:: int PyFunction_Check(PyObject *o) - - Return true if *o* is a function object (has type :cdata:`PyFunction_Type`). - The parameter must not be *NULL*. - - -.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals) - - Return a new function object associated with the code object *code*. *globals* - must be a dictionary with the global variables accessible to the function. - - The function's docstring, name and *__module__* are retrieved from the code - object, the argument defaults and closure are set to *NULL*. - - -.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op) - - Return the code object associated with the function object *op*. - - -.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op) - - Return the globals dictionary associated with the function object *op*. - - -.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op) - - Return the *__module__* attribute of the function object *op*. This is normally - a string containing the module name, but can be set to any other object by - Python code. - - -.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op) - - Return the argument default values of the function object *op*. This can be a - tuple of arguments or *NULL*. - - -.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) - - Set the argument default values for the function object *op*. *defaults* must be - *Py_None* or a tuple. - - Raises :exc:`SystemError` and returns ``-1`` on failure. - - -.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op) - - Return the closure associated with the function object *op*. This can be *NULL* - or a tuple of cell objects. - - -.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure) - - Set the closure associated with the function object *op*. *closure* must be - *Py_None* or a tuple of cell objects. - - Raises :exc:`SystemError` and returns ``-1`` on failure. - - -.. _instancemethod-objects: - -Instance Method Objects ------------------------ - -.. index:: object: instancemethod - -An instance method is a wrapper for a :cdata:`PyCFunction` and the new way -to bind a :cdata:`PyCFunction` to a class object. It replaces the former call -``PyMethod_New(func, NULL, class)``. - - -.. cvar:: PyTypeObject PyInstanceMethod_Type - - This instance of :ctype:`PyTypeObject` represents the Python instance - method type. It is not exposed to Python programs. - - -.. cfunction:: int PyInstanceMethod_Check(PyObject *o) - - Return true if *o* is an instance method object (has type - :cdata:`PyInstanceMethod_Type`). The parameter must not be *NULL*. - - -.. cfunction:: PyObject* PyInstanceMethod_New(PyObject *func) - - Return a new instance method object, with *func* being any callable object - *func* is is the function that will be called when the instance method is - called. - - -.. cfunction:: PyObject* PyInstanceMethod_Function(PyObject *im) - - Return the function object associated with the instance method *im*. - - -.. cfunction:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im) - - Macro version of :cfunc:`PyInstanceMethod_Function` which avoids error checking. - - -.. _method-objects: - -Method Objects --------------- - -.. index:: object: method - -Methods are bound function objects. Methods are always bound to an instance of -an user-defined class. Unbound methods (methods bound to a class object) are -no longer available. - - -.. cvar:: PyTypeObject PyMethod_Type - - .. index:: single: MethodType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python method type. This - is exposed to Python programs as ``types.MethodType``. - - -.. cfunction:: int PyMethod_Check(PyObject *o) - - Return true if *o* is a method object (has type :cdata:`PyMethod_Type`). The - parameter must not be *NULL*. - - -.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self) - - Return a new method object, with *func* being any callable object and *self* - the instance the method should be bound. *func* is is the function that will - be called when the method is called. *self* must not be *NULL*. - - -.. cfunction:: PyObject* PyMethod_Function(PyObject *meth) - - Return the function object associated with the method *meth*. - - -.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth) - - Macro version of :cfunc:`PyMethod_Function` which avoids error checking. - - -.. cfunction:: PyObject* PyMethod_Self(PyObject *meth) - - Return the instance associated with the method *meth*. - - -.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth) - - Macro version of :cfunc:`PyMethod_Self` which avoids error checking. - - -.. _moduleobjects: - -Module Objects --------------- - -.. index:: object: module - -There are only a few functions special to module objects. - - -.. cvar:: PyTypeObject PyModule_Type - - .. index:: single: ModuleType (in module types) - - This instance of :ctype:`PyTypeObject` represents the Python module type. This - is exposed to Python programs as ``types.ModuleType``. - - -.. cfunction:: int PyModule_Check(PyObject *p) - - Return true if *p* is a module object, or a subtype of a module object. - - -.. cfunction:: int PyModule_CheckExact(PyObject *p) - - Return true if *p* is a module object, but not a subtype of - :cdata:`PyModule_Type`. - - -.. cfunction:: PyObject* PyModule_New(const char *name) - - .. index:: - single: __name__ (module attribute) - single: __doc__ (module attribute) - single: __file__ (module attribute) - - Return a new module object with the :attr:`__name__` attribute set to *name*. - Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in; - the caller is responsible for providing a :attr:`__file__` attribute. - - -.. cfunction:: PyObject* PyModule_GetDict(PyObject *module) - - .. index:: single: __dict__ (module attribute) - - Return the dictionary object that implements *module*'s namespace; this object - is the same as the :attr:`__dict__` attribute of the module object. This - function never fails. It is recommended extensions use other - :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly - manipulate a module's :attr:`__dict__`. - - -.. cfunction:: char* PyModule_GetName(PyObject *module) - - .. index:: - single: __name__ (module attribute) - single: SystemError (built-in exception) - - Return *module*'s :attr:`__name__` value. If the module does not provide one, - or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned. - - -.. cfunction:: char* PyModule_GetFilename(PyObject *module) - - .. index:: - single: __file__ (module attribute) - single: SystemError (built-in exception) - - Return the name of the file from which *module* was loaded using *module*'s - :attr:`__file__` attribute. If this is not defined, or if it is not a string, - raise :exc:`SystemError` and return *NULL*. - - -.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value) - - Add an object to *module* as *name*. This is a convenience function which can - be used from the module's initialization function. This steals a reference to - *value*. Return ``-1`` on error, ``0`` on success. - - -.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value) - - Add an integer constant to *module* as *name*. This convenience function can be - used from the module's initialization function. Return ``-1`` on error, ``0`` on - success. - - -.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value) - - Add a string constant to *module* as *name*. This convenience function can be - used from the module's initialization function. The string *value* must be - null-terminated. Return ``-1`` on error, ``0`` on success. - - -.. _iterator-objects: - -Iterator Objects ----------------- - -Python provides two general-purpose iterator objects. The first, a sequence -iterator, works with an arbitrary sequence supporting the :meth:`__getitem__` -method. The second works with a callable object and a sentinel value, calling -the callable for each item in the sequence, and ending the iteration when the -sentinel value is returned. - - -.. cvar:: PyTypeObject PySeqIter_Type - - Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the - one-argument form of the :func:`iter` built-in function for built-in sequence - types. - - -.. cfunction:: int PySeqIter_Check(op) - - Return true if the type of *op* is :cdata:`PySeqIter_Type`. - - -.. cfunction:: PyObject* PySeqIter_New(PyObject *seq) - - Return an iterator that works with a general sequence object, *seq*. The - iteration ends when the sequence raises :exc:`IndexError` for the subscripting - operation. - - -.. cvar:: PyTypeObject PyCallIter_Type - - Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the - two-argument form of the :func:`iter` built-in function. - - -.. cfunction:: int PyCallIter_Check(op) - - Return true if the type of *op* is :cdata:`PyCallIter_Type`. - - -.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel) - - Return a new iterator. The first parameter, *callable*, can be any Python - callable object that can be called with no parameters; each call to it should - return the next item in the iteration. When *callable* returns a value equal to - *sentinel*, the iteration will be terminated. - - -.. _descriptor-objects: - -Descriptor Objects ------------------- - -"Descriptors" are objects that describe some attribute of an object. They are -found in the dictionary of type objects. - -.. XXX document these! - -.. cvar:: PyTypeObject PyProperty_Type - - The type object for the built-in descriptor types. - - -.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset) - - -.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth) - - -.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth) - - -.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped) - - -.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method) - - -.. cfunction:: int PyDescr_IsData(PyObject *descr) - - Return true if the descriptor objects *descr* describes a data attribute, or - false if it describes a method. *descr* must be a descriptor object; there is - no error checking. - - -.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *) - - -.. _slice-objects: - -Slice Objects -------------- - - -.. cvar:: PyTypeObject PySlice_Type - - .. index:: single: SliceType (in module types) - - The type object for slice objects. This is the same as ``slice`` and - ``types.SliceType``. - - -.. cfunction:: int PySlice_Check(PyObject *ob) - - Return true if *ob* is a slice object; *ob* must not be *NULL*. - - -.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step) - - Return a new slice object with the given values. The *start*, *stop*, and - *step* parameters are used as the values of the slice object attributes of the - same names. Any of the values may be *NULL*, in which case the ``None`` will be - used for the corresponding attribute. Return *NULL* if the new object could not - be allocated. - - -.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step) - - Retrieve the start, stop and step indices from the slice object *slice*, - assuming a sequence of length *length*. Treats indices greater than *length* as - errors. - - Returns 0 on success and -1 on error with no exception set (unless one of the - indices was not :const:`None` and failed to be converted to an integer, in which - case -1 is returned with an exception set). - - You probably do not want to use this function. If you want to use slice objects - in versions of Python prior to 2.3, you would probably do well to incorporate - the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of - your extension. - - -.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength) - - Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start, stop, - and step indices from the slice object *slice* assuming a sequence of length - *length*, and store the length of the slice in *slicelength*. Out of bounds - indices are clipped in a manner consistent with the handling of normal slices. - - Returns 0 on success and -1 on error with exception set. - - -.. _weakrefobjects: - -Weak Reference Objects ----------------------- - -Python supports *weak references* as first-class objects. There are two -specific object types which directly implement weak references. The first is a -simple reference object, and the second acts as a proxy for the original object -as much as it can. - - -.. cfunction:: int PyWeakref_Check(ob) - - Return true if *ob* is either a reference or proxy object. - - -.. cfunction:: int PyWeakref_CheckRef(ob) - - Return true if *ob* is a reference object. - - -.. cfunction:: int PyWeakref_CheckProxy(ob) - - Return true if *ob* is a proxy object. - - -.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) - - Return a weak reference object for the object *ob*. This will always return - a new reference, but is not guaranteed to create a new object; an existing - reference object may be returned. The second parameter, *callback*, can be a - callable object that receives notification when *ob* is garbage collected; it - should accept a single parameter, which will be the weak reference object - itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a - weakly-referencable object, or if *callback* is not callable, ``None``, or - *NULL*, this will return *NULL* and raise :exc:`TypeError`. - - -.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback) - - Return a weak reference proxy object for the object *ob*. This will always - return a new reference, but is not guaranteed to create a new object; an - existing proxy object may be returned. The second parameter, *callback*, can - be a callable object that receives notification when *ob* is garbage - collected; it should accept a single parameter, which will be the weak - reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* - is not a weakly-referencable object, or if *callback* is not callable, - ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`. - - -.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref) - - Return the referenced object from a weak reference, *ref*. If the referent is - no longer live, returns ``None``. - - -.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) - - Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no - error checking. - - -.. _cobjects: - -CObjects --------- - -.. index:: object: CObject - -Refer to *Extending and Embedding the Python Interpreter*, section 1.12, -"Providing a C API for an Extension Module," for more information on using these -objects. - - -.. ctype:: PyCObject - - This subtype of :ctype:`PyObject` represents an opaque value, useful for C - extension modules who need to pass an opaque value (as a :ctype:`void\*` - pointer) through Python code to other C code. It is often used to make a C - function pointer defined in one module available to other modules, so the - regular import mechanism can be used to access C APIs defined in dynamically - loaded modules. - - -.. cfunction:: int PyCObject_Check(PyObject *p) - - Return true if its argument is a :ctype:`PyCObject`. - - -.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) - - Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function - will be called when the object is reclaimed, unless it is *NULL*. - - -.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) - - Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* - function will be called when the object is reclaimed. The *desc* argument can - be used to pass extra callback data for the destructor function. - - -.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) - - Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was - created with. - - -.. cfunction:: void* PyCObject_GetDesc(PyObject* self) - - Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was - created with. - - -.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj) - - Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not - have an associated destructor. Return true on success, false on failure. - - -.. _cell-objects: - -Cell Objects ------------- - -"Cell" objects are used to implement variables referenced by multiple scopes. -For each such variable, a cell object is created to store the value; the local -variables of each stack frame that references the value contains a reference to -the cells from outer scopes which also use that variable. When the value is -accessed, the value contained in the cell is used instead of the cell object -itself. This de-referencing of the cell object requires support from the -generated byte-code; these are not automatically de-referenced when accessed. -Cell objects are not likely to be useful elsewhere. - - -.. ctype:: PyCellObject - - The C structure used for cell objects. - - -.. cvar:: PyTypeObject PyCell_Type - - The type object corresponding to cell objects. - - -.. cfunction:: int PyCell_Check(ob) - - Return true if *ob* is a cell object; *ob* must not be *NULL*. - - -.. cfunction:: PyObject* PyCell_New(PyObject *ob) - - Create and return a new cell object containing the value *ob*. The parameter may - be *NULL*. - - -.. cfunction:: PyObject* PyCell_Get(PyObject *cell) - - Return the contents of the cell *cell*. - - -.. cfunction:: PyObject* PyCell_GET(PyObject *cell) - - Return the contents of the cell *cell*, but without checking that *cell* is - non-*NULL* and a cell object. - - -.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value) - - Set the contents of the cell object *cell* to *value*. This releases the - reference to any current content of the cell. *value* may be *NULL*. *cell* - must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On - success, ``0`` will be returned. - - -.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value) - - Sets the value of the cell object *cell* to *value*. No reference counts are - adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must - be a cell object. - - -.. _gen-objects: - -Generator Objects ------------------ - -Generator objects are what Python uses to implement generator iterators. They -are normally created by iterating over a function that yields values, rather -than explicitly calling :cfunc:`PyGen_New`. - - -.. ctype:: PyGenObject - - The C structure used for generator objects. - - -.. cvar:: PyTypeObject PyGen_Type - - The type object corresponding to generator objects - - -.. cfunction:: int PyGen_Check(ob) - - Return true if *ob* is a generator object; *ob* must not be *NULL*. - - -.. cfunction:: int PyGen_CheckExact(ob) - - Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not - be *NULL*. - - -.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame) - - Create and return a new generator object based on the *frame* object. A - reference to *frame* is stolen by this function. The parameter must not be - *NULL*. - - -.. _datetimeobjects: - -DateTime Objects ----------------- - -Various date and time objects are supplied by the :mod:`datetime` module. -Before using any of these functions, the header file :file:`datetime.h` must be -included in your source (note that this is not included by :file:`Python.h`), -and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a -pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is -used by the following macros. - -Type-check macros: - -.. cfunction:: int PyDate_Check(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of - :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*. - - -.. cfunction:: int PyDate_CheckExact(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be - *NULL*. - - -.. cfunction:: int PyDateTime_Check(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of - :cdata:`PyDateTime_DateTimeType`. *ob* must not be *NULL*. - - -.. cfunction:: int PyDateTime_CheckExact(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not - be *NULL*. - - -.. cfunction:: int PyTime_Check(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of - :cdata:`PyDateTime_TimeType`. *ob* must not be *NULL*. - - -.. cfunction:: int PyTime_CheckExact(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be - *NULL*. - - -.. cfunction:: int PyDelta_Check(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of - :cdata:`PyDateTime_DeltaType`. *ob* must not be *NULL*. - - -.. cfunction:: int PyDelta_CheckExact(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be - *NULL*. - - -.. cfunction:: int PyTZInfo_Check(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of - :cdata:`PyDateTime_TZInfoType`. *ob* must not be *NULL*. - - -.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob) - - Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be - *NULL*. - - -Macros to create objects: - -.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day) - - Return a ``datetime.date`` object with the specified year, month and day. - - -.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond) - - Return a ``datetime.datetime`` object with the specified year, month, day, hour, - minute, second and microsecond. - - -.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond) - - Return a ``datetime.time`` object with the specified hour, minute, second and - microsecond. - - -.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds) - - Return a ``datetime.timedelta`` object representing the given number of days, - seconds and microseconds. Normalization is performed so that the resulting - number of microseconds and seconds lie in the ranges documented for - ``datetime.timedelta`` objects. - - -Macros to extract fields from date objects. The argument must be an instance of -:cdata:`PyDateTime_Date`, including subclasses (such as -:cdata:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is -not checked: - -.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) - - Return the year, as a positive int. - - -.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) - - Return the month, as an int from 1 through 12. - - -.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o) - - Return the day, as an int from 1 through 31. - - -Macros to extract fields from datetime objects. The argument must be an -instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument -must not be *NULL*, and the type is not checked: - -.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) - - Return the hour, as an int from 0 through 23. - - -.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) - - Return the minute, as an int from 0 through 59. - - -.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) - - Return the second, as an int from 0 through 59. - - -.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) - - Return the microsecond, as an int from 0 through 999999. - - -Macros to extract fields from time objects. The argument must be an instance of -:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*, -and the type is not checked: - -.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) - - Return the hour, as an int from 0 through 23. - - -.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) - - Return the minute, as an int from 0 through 59. - - -.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) - - Return the second, as an int from 0 through 59. - - -.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) - - Return the microsecond, as an int from 0 through 999999. - - -Macros for the convenience of modules implementing the DB API: - -.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args) - - Create and return a new ``datetime.datetime`` object given an argument tuple - suitable for passing to ``datetime.datetime.fromtimestamp()``. - - -.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args) - - Create and return a new ``datetime.date`` object given an argument tuple - suitable for passing to ``datetime.date.fromtimestamp()``. - - -.. _setobjects: - -Set Objects ------------ - -.. sectionauthor:: Raymond D. Hettinger <python@rcn.com> - - -.. index:: - object: set - object: frozenset - -This section details the public API for :class:`set` and :class:`frozenset` -objects. Any functionality not listed below is best accessed using the either -the abstract object protocol (including :cfunc:`PyObject_CallMethod`, -:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`, -:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and -:cfunc:`PyObject_GetIter`) or the abstract number protocol (including -:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`, -:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`, -:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and -:cfunc:`PyNumber_InPlaceXor`). - - -.. ctype:: PySetObject - - This subtype of :ctype:`PyObject` is used to hold the internal data for both - :class:`set` and :class:`frozenset` objects. It is like a :ctype:`PyDictObject` - in that it is a fixed size for small sets (much like tuple storage) and will - point to a separate, variable sized block of memory for medium and large sized - sets (much like list storage). None of the fields of this structure should be - considered public and are subject to change. All access should be done through - the documented API rather than by manipulating the values in the structure. - - -.. cvar:: PyTypeObject PySet_Type - - This is an instance of :ctype:`PyTypeObject` representing the Python - :class:`set` type. - - -.. cvar:: PyTypeObject PyFrozenSet_Type - - This is an instance of :ctype:`PyTypeObject` representing the Python - :class:`frozenset` type. - -The following type check macros work on pointers to any Python object. Likewise, -the constructor functions work with any iterable Python object. - - -.. cfunction:: int PyAnySet_Check(PyObject *p) - - Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an - instance of a subtype. - - -.. cfunction:: int PyAnySet_CheckExact(PyObject *p) - - Return true if *p* is a :class:`set` object or a :class:`frozenset` object but - not an instance of a subtype. - - -.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p) - - Return true if *p* is a :class:`frozenset` object but not an instance of a - subtype. - - -.. cfunction:: PyObject* PySet_New(PyObject *iterable) - - Return a new :class:`set` containing objects returned by the *iterable*. The - *iterable* may be *NULL* to create a new empty set. Return the new set on - success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not - actually iterable. The constructor is also useful for copying a set - (``c=set(s)``). - - -.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable) - - Return a new :class:`frozenset` containing objects returned by the *iterable*. - The *iterable* may be *NULL* to create a new empty frozenset. Return the new - set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is - not actually iterable. - -The following functions and macros are available for instances of :class:`set` -or :class:`frozenset` or instances of their subtypes. - - -.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset) - - .. index:: builtin: len - - Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to - ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a - :class:`set`, :class:`frozenset`, or an instance of a subtype. - - -.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) - - Macro form of :cfunc:`PySet_Size` without error checking. - - -.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key) - - Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike - the Python :meth:`__contains__` method, this function does not automatically - convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if - the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a - :class:`set`, :class:`frozenset`, or an instance of a subtype. - -The following functions are available for instances of :class:`set` or its -subtypes but not for instances of :class:`frozenset` or its subtypes. - - -.. cfunction:: int PySet_Add(PyObject *set, PyObject *key) - - Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset` - instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if - the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. - Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its - subtype. - - -.. cfunction:: int PySet_Discard(PyObject *set, PyObject *key) - - Return 1 if found and removed, 0 if not found (no action taken), and -1 if an - error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a - :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard` - method, this function does not automatically convert unhashable sets into - temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an - instance of :class:`set` or its subtype. - - -.. cfunction:: PyObject* PySet_Pop(PyObject *set) - - Return a new reference to an arbitrary object in the *set*, and removes the - object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the - set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of - :class:`set` or its subtype. - - -.. cfunction:: int PySet_Clear(PyObject *set) - - Empty an existing set of all elements. - +.. toctree:: + + set.rst + function.rst + method.rst + file.rst + module.rst + iterator.rst + descriptor.rst + slice.rst + weakref.rst + cobject.rst + cell.rst + gen.rst + datetime.rst diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst new file mode 100644 index 0000000..8fc424d --- /dev/null +++ b/Doc/c-api/conversion.rst @@ -0,0 +1,93 @@ +.. highlightlang:: c + +.. _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. diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst new file mode 100644 index 0000000..044d3e5 --- /dev/null +++ b/Doc/c-api/datetime.rst @@ -0,0 +1,183 @@ +.. highlightlang:: c + +.. _datetimeobjects: + +DateTime Objects +---------------- + +Various date and time objects are supplied by the :mod:`datetime` module. +Before using any of these functions, the header file :file:`datetime.h` must be +included in your source (note that this is not included by :file:`Python.h`), +and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a +pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is +used by the following macros. + +Type-check macros: + +.. cfunction:: int PyDate_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of + :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*. + + +.. cfunction:: int PyDate_CheckExact(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be + *NULL*. + + +.. cfunction:: int PyDateTime_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of + :cdata:`PyDateTime_DateTimeType`. *ob* must not be *NULL*. + + +.. cfunction:: int PyDateTime_CheckExact(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not + be *NULL*. + + +.. cfunction:: int PyTime_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of + :cdata:`PyDateTime_TimeType`. *ob* must not be *NULL*. + + +.. cfunction:: int PyTime_CheckExact(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be + *NULL*. + + +.. cfunction:: int PyDelta_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of + :cdata:`PyDateTime_DeltaType`. *ob* must not be *NULL*. + + +.. cfunction:: int PyDelta_CheckExact(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be + *NULL*. + + +.. cfunction:: int PyTZInfo_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of + :cdata:`PyDateTime_TZInfoType`. *ob* must not be *NULL*. + + +.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be + *NULL*. + + +Macros to create objects: + +.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day) + + Return a ``datetime.date`` object with the specified year, month and day. + + +.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond) + + Return a ``datetime.datetime`` object with the specified year, month, day, hour, + minute, second and microsecond. + + +.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond) + + Return a ``datetime.time`` object with the specified hour, minute, second and + microsecond. + + +.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds) + + Return a ``datetime.timedelta`` object representing the given number of days, + seconds and microseconds. Normalization is performed so that the resulting + number of microseconds and seconds lie in the ranges documented for + ``datetime.timedelta`` objects. + + +Macros to extract fields from date objects. The argument must be an instance of +:cdata:`PyDateTime_Date`, including subclasses (such as +:cdata:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is +not checked: + +.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) + + Return the year, as a positive int. + + +.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) + + Return the month, as an int from 1 through 12. + + +.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o) + + Return the day, as an int from 1 through 31. + + +Macros to extract fields from datetime objects. The argument must be an +instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument +must not be *NULL*, and the type is not checked: + +.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) + + Return the hour, as an int from 0 through 23. + + +.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) + + Return the minute, as an int from 0 through 59. + + +.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) + + Return the second, as an int from 0 through 59. + + +.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) + + Return the microsecond, as an int from 0 through 999999. + + +Macros to extract fields from time objects. The argument must be an instance of +:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*, +and the type is not checked: + +.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) + + Return the hour, as an int from 0 through 23. + + +.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) + + Return the minute, as an int from 0 through 59. + + +.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) + + Return the second, as an int from 0 through 59. + + +.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) + + Return the microsecond, as an int from 0 through 999999. + + +Macros for the convenience of modules implementing the DB API: + +.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args) + + Create and return a new ``datetime.datetime`` object given an argument tuple + suitable for passing to ``datetime.datetime.fromtimestamp()``. + + +.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args) + + Create and return a new ``datetime.date`` object given an argument tuple + suitable for passing to ``datetime.date.fromtimestamp()``. diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst new file mode 100644 index 0000000..5db2570 --- /dev/null +++ b/Doc/c-api/descriptor.rst @@ -0,0 +1,40 @@ +.. highlightlang:: c + +.. _descriptor-objects: + +Descriptor Objects +------------------ + +"Descriptors" are objects that describe some attribute of an object. They are +found in the dictionary of type objects. + +.. XXX document these! + +.. cvar:: PyTypeObject PyProperty_Type + + The type object for the built-in descriptor types. + + +.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset) + + +.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth) + + +.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth) + + +.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped) + + +.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method) + + +.. cfunction:: int PyDescr_IsData(PyObject *descr) + + Return true if the descriptor objects *descr* describes a data attribute, or + false if it describes a method. *descr* must be a descriptor object; there is + no error checking. + + +.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst new file mode 100644 index 0000000..b346d68 --- /dev/null +++ b/Doc/c-api/dict.rst @@ -0,0 +1,206 @@ +.. highlightlang:: c + +.. _dictobjects: + +Dictionary Objects +------------------ + +.. index:: object: dictionary + + +.. ctype:: PyDictObject + + This subtype of :ctype:`PyObject` represents a Python dictionary object. + + +.. cvar:: PyTypeObject PyDict_Type + + .. index:: + single: DictType (in module types) + single: DictionaryType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python dictionary type. + This is exposed to Python programs as ``dict`` and ``types.DictType``. + + +.. cfunction:: int PyDict_Check(PyObject *p) + + Return true if *p* is a dict object or an instance of a subtype of the dict + type. + + +.. cfunction:: int PyDict_CheckExact(PyObject *p) + + Return true if *p* is a dict object, but not an instance of a subtype of the + dict type. + + +.. cfunction:: PyObject* PyDict_New() + + Return a new empty dictionary, or *NULL* on failure. + + +.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict) + + Return a proxy object for a mapping which enforces read-only behavior. This is + normally used to create a proxy to prevent modification of the dictionary for + non-dynamic class types. + + +.. cfunction:: void PyDict_Clear(PyObject *p) + + Empty an existing dictionary of all key-value pairs. + + +.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key) + + Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*, + return ``1``, otherwise return ``0``. On error, return ``-1``. This is + equivalent to the Python expression ``key in p``. + + +.. cfunction:: PyObject* PyDict_Copy(PyObject *p) + + Return a new dictionary that contains the same key-value pairs as *p*. + + +.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val) + + Insert *value* into the dictionary *p* with a key of *key*. *key* must be + :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0`` + on success or ``-1`` on failure. + + +.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val) + + .. index:: single: PyString_FromString() + + Insert *value* into the dictionary *p* using *key* as a key. *key* should be a + :ctype:`char\*`. The key object is created using ``PyString_FromString(key)``. + Return ``0`` on success or ``-1`` on failure. + + +.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key) + + Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it + isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` on + failure. + + +.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key) + + Remove the entry in dictionary *p* which has a key specified by the string + *key*. Return ``0`` on success or ``-1`` on failure. + + +.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key) + + Return the object from dictionary *p* which has a key *key*. Return *NULL* if + the key *key* is not present, but *without* setting an exception. + + +.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) + + This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a + :ctype:`char\*`, rather than a :ctype:`PyObject\*`. + + +.. cfunction:: PyObject* PyDict_Items(PyObject *p) + + Return a :ctype:`PyListObject` containing all the items from the dictionary, as + in the dictionary method :meth:`dict.items`. + + +.. cfunction:: PyObject* PyDict_Keys(PyObject *p) + + Return a :ctype:`PyListObject` containing all the keys from the dictionary, as + in the dictionary method :meth:`dict.keys`. + + +.. cfunction:: PyObject* PyDict_Values(PyObject *p) + + Return a :ctype:`PyListObject` containing all the values from the dictionary + *p*, as in the dictionary method :meth:`dict.values`. + + +.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) + + .. index:: builtin: len + + Return the number of items in the dictionary. This is equivalent to ``len(p)`` + on a dictionary. + + +.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue) + + Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int` + referred to by *ppos* must be initialized to ``0`` prior to the first call to + this function to start the iteration; the function returns true for each pair in + the dictionary, and false once all pairs have been reported. The parameters + *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that + will be filled in with each key and value, respectively, or may be *NULL*. Any + references returned through them are borrowed. *ppos* should not be altered + during iteration. Its value represents offsets within the internal dictionary + structure, and since the structure is sparse, the offsets are not consecutive. + + For example:: + + PyObject *key, *value; + Py_ssize_t pos = 0; + + while (PyDict_Next(self->dict, &pos, &key, &value)) { + /* do something interesting with the values... */ + ... + } + + The dictionary *p* should not be mutated during iteration. It is safe (since + Python 2.1) to modify the values of the keys as you iterate over the dictionary, + but only so long as the set of keys does not change. For example:: + + PyObject *key, *value; + Py_ssize_t pos = 0; + + while (PyDict_Next(self->dict, &pos, &key, &value)) { + long i = PyLong_AsLong(value); + if (i == -1 && PyErr_Occurred()) { + return -1; + } + PyObject *o = PyLong_FromLong(i + 1); + if (o == NULL) + return -1; + if (PyDict_SetItem(self->dict, key, o) < 0) { + Py_DECREF(o); + return -1; + } + Py_DECREF(o); + } + + +.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override) + + Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b* + may be a dictionary, or any object supporting :func:`PyMapping_Keys` and + :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be + replaced if a matching key is found in *b*, otherwise pairs will only be added + if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an + exception was raised. + + +.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b) + + This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in + Python. Return ``0`` on success or ``-1`` if an exception was raised. + + +.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override) + + Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2* + must be an iterable object producing iterable objects of length 2, viewed as + key-value pairs. In case of duplicate keys, the last wins if *override* is + true, else the first wins. Return ``0`` on success or ``-1`` if an exception was + raised. Equivalent Python (except for the return value):: + + def PyDict_MergeFromSeq2(a, seq2, override): + for key, value in seq2: + if override or key not in a: + a[key] = value diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst new file mode 100644 index 0000000..f08a155 --- /dev/null +++ b/Doc/c-api/file.rst @@ -0,0 +1,123 @@ +.. highlightlang:: c + +.. _fileobjects: + +File Objects +------------ + +.. index:: object: file + +Python's built-in file objects are implemented entirely on the :ctype:`FILE\*` +support from the C standard library. This is an implementation detail and may +change in future releases of Python. + + +.. ctype:: PyFileObject + + This subtype of :ctype:`PyObject` represents a Python file object. + + +.. cvar:: PyTypeObject PyFile_Type + + .. index:: single: FileType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python file type. This is + exposed to Python programs as ``file`` and ``types.FileType``. + + +.. cfunction:: int PyFile_Check(PyObject *p) + + Return true if its argument is a :ctype:`PyFileObject` or a subtype of + :ctype:`PyFileObject`. + + +.. cfunction:: int PyFile_CheckExact(PyObject *p) + + Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of + :ctype:`PyFileObject`. + + +.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd) + + Create a new :ctype:`PyFileObject` from the file descriptor of an already + opened file *fd*. The arguments *name*, *encoding* and *newline* can be + *NULL* to use the defaults; *buffering* can be *-1* to use the default. + Return *NULL* on failure. + + .. warning:: + + Take care when you are mixing streams and descriptors! For more + information, see `the GNU C Library docs + <http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_. + + +.. cfunction:: int PyObject_AsFileDescriptor(PyObject *p) + + Return the file descriptor associated with *p* as an :ctype:`int`. If the + object is an integer, its value is returned. If not, the + object's :meth:`fileno` method is called if it exists; the method must return + an integer, which is returned as the file descriptor value. Sets an + exception and returns ``-1`` on failure. + + +.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n) + + .. index:: single: EOFError (built-in exception) + + Equivalent to ``p.readline([n])``, this function reads one line from the + object *p*. *p* may be a file object or any object with a :meth:`readline` + method. If *n* is ``0``, exactly one line is read, regardless of the length of + the line. If *n* is greater than ``0``, no more than *n* bytes will be read + from the file; a partial line can be returned. In both cases, an empty string + is returned if the end of the file is reached immediately. If *n* is less than + ``0``, however, one line is read regardless of length, but :exc:`EOFError` is + raised if the end of the file is reached immediately. + + +.. cfunction:: PyObject* PyFile_Name(PyObject *p) + + Return the name of the file specified by *p* as a string object. + + +.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n) + + .. index:: single: setvbuf() + + Available on systems with :cfunc:`setvbuf` only. This should only be called + immediately after file object creation. + + +.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc) + + Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0 + on failure. + + +.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag) + + .. index:: single: softspace (file attribute) + + This function exists for internal use by the interpreter. Set the + :attr:`softspace` attribute of *p* to *newflag* and return the previous value. + *p* does not have to be a file object for this function to work properly; any + object is supported (thought its only interesting if the :attr:`softspace` + attribute can be set). This function clears any errors, and will return ``0`` + as the previous value if the attribute either does not exist or if there were + errors in retrieving it. There is no way to detect errors from this function, + but doing so should not be needed. + + +.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags) + + .. index:: single: Py_PRINT_RAW + + Write object *obj* to file object *p*. The only supported flag for *flags* is + :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written + instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the + appropriate exception will be set. + + +.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p) + + Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on + failure; the appropriate exception will be set. diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst new file mode 100644 index 0000000..b0647bc --- /dev/null +++ b/Doc/c-api/float.rst @@ -0,0 +1,74 @@ +.. highlightlang:: c + +.. _floatobjects: + +Floating Point Objects +---------------------- + +.. index:: object: floating point + + +.. ctype:: PyFloatObject + + This subtype of :ctype:`PyObject` represents a Python floating point object. + + +.. cvar:: PyTypeObject PyFloat_Type + + .. index:: single: FloatType (in modules types) + + This instance of :ctype:`PyTypeObject` represents the Python floating point + type. This is the same object as ``float`` and ``types.FloatType``. + + +.. cfunction:: int PyFloat_Check(PyObject *p) + + Return true if its argument is a :ctype:`PyFloatObject` or a subtype of + :ctype:`PyFloatObject`. + + +.. cfunction:: int PyFloat_CheckExact(PyObject *p) + + Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of + :ctype:`PyFloatObject`. + + +.. cfunction:: PyObject* PyFloat_FromString(PyObject *str) + + Create a :ctype:`PyFloatObject` object based on the string value in *str*, or + *NULL* on failure. + + +.. cfunction:: PyObject* PyFloat_FromDouble(double v) + + Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure. + + +.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat) + + Return a C :ctype:`double` representation of the contents of *pyfloat*. If + *pyfloat* is not a Python floating point object but has a :meth:`__float__` + method, this method will first be called to convert *pyfloat* into a float. + + +.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat) + + Return a C :ctype:`double` representation of the contents of *pyfloat*, but + without error checking. + + +.. cfunction:: PyObject* PyFloat_GetInfo(void) + + Return a structseq instance which contains information about the + precision, minimum and maximum values of a float. It's a thin wrapper + around the header file :file:`float.h`. + + +.. cfunction:: double PyFloat_GetMax(void) + + Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`. + + +.. cfunction:: double PyFloat_GetMin(void) + + Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`. diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst new file mode 100644 index 0000000..e9ed2ab --- /dev/null +++ b/Doc/c-api/function.rst @@ -0,0 +1,83 @@ +.. highlightlang:: c + +.. _function-objects: + +Function Objects +---------------- + +.. index:: object: function + +There are a few functions specific to Python functions. + + +.. ctype:: PyFunctionObject + + The C structure used for functions. + + +.. cvar:: PyTypeObject PyFunction_Type + + .. index:: single: MethodType (in module types) + + This is an instance of :ctype:`PyTypeObject` and represents the Python function + type. It is exposed to Python programmers as ``types.FunctionType``. + + +.. cfunction:: int PyFunction_Check(PyObject *o) + + Return true if *o* is a function object (has type :cdata:`PyFunction_Type`). + The parameter must not be *NULL*. + + +.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals) + + Return a new function object associated with the code object *code*. *globals* + must be a dictionary with the global variables accessible to the function. + + The function's docstring, name and *__module__* are retrieved from the code + object, the argument defaults and closure are set to *NULL*. + + +.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op) + + Return the code object associated with the function object *op*. + + +.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op) + + Return the globals dictionary associated with the function object *op*. + + +.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op) + + Return the *__module__* attribute of the function object *op*. This is normally + a string containing the module name, but can be set to any other object by + Python code. + + +.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op) + + Return the argument default values of the function object *op*. This can be a + tuple of arguments or *NULL*. + + +.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults) + + Set the argument default values for the function object *op*. *defaults* must be + *Py_None* or a tuple. + + Raises :exc:`SystemError` and returns ``-1`` on failure. + + +.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op) + + Return the closure associated with the function object *op*. This can be *NULL* + or a tuple of cell objects. + + +.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure) + + Set the closure associated with the function object *op*. *closure* must be + *Py_None* or a tuple of cell objects. + + Raises :exc:`SystemError` and returns ``-1`` on failure. diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst new file mode 100644 index 0000000..03947e9 --- /dev/null +++ b/Doc/c-api/gcsupport.rst @@ -0,0 +1,147 @@ +.. highlightlang:: c + +.. _supporting-cycle-detection: + +Supporting Cyclic Garbage Collection +==================================== + +Python's support for detecting and collecting garbage which involves circular +references requires support from object types which are "containers" for other +objects which may also be containers. Types which do not store references to +other objects, or which only store references to atomic types (such as numbers +or strings), do not need to provide any explicit support for garbage collection. + +To create a container type, the :attr:`tp_flags` field of the type object must +include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the +:attr:`tp_traverse` handler. If instances of the type are mutable, a +:attr:`tp_clear` implementation must also be provided. + + +.. data:: Py_TPFLAGS_HAVE_GC + + Objects with a type with this flag set must conform with the rules documented + here. For convenience these objects will be referred to as container objects. + +Constructors for container types must conform to two rules: + +#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or + :cfunc:`PyObject_GC_VarNew`. + +#. Once all the fields which may contain references to other containers are + initialized, it must call :cfunc:`PyObject_GC_Track`. + + +.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type) + + Analogous to :cfunc:`PyObject_New` but for container objects with the + :const:`Py_TPFLAGS_HAVE_GC` flag set. + + +.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) + + Analogous to :cfunc:`PyObject_NewVar` but for container objects with the + :const:`Py_TPFLAGS_HAVE_GC` flag set. + + +.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t) + + Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized + object or *NULL* on failure. + + +.. cfunction:: void PyObject_GC_Track(PyObject *op) + + Adds the object *op* to the set of container objects tracked by the collector. + The collector can run at unexpected times so objects must be valid while being + tracked. This should be called once all the fields followed by the + :attr:`tp_traverse` handler become valid, usually near the end of the + constructor. + + +.. cfunction:: void _PyObject_GC_TRACK(PyObject *op) + + A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for + extension modules. + +Similarly, the deallocator for the object must conform to a similar pair of +rules: + +#. Before fields which refer to other containers are invalidated, + :cfunc:`PyObject_GC_UnTrack` must be called. + +#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`. + + +.. cfunction:: void PyObject_GC_Del(void *op) + + Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or + :cfunc:`PyObject_GC_NewVar`. + + +.. cfunction:: void PyObject_GC_UnTrack(void *op) + + Remove the object *op* from the set of container objects tracked by the + collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this + object to add it back to the set of tracked objects. The deallocator + (:attr:`tp_dealloc` handler) should call this for the object before any of the + fields used by the :attr:`tp_traverse` handler become invalid. + + +.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op) + + A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for + extension modules. + +The :attr:`tp_traverse` handler accepts a function parameter of this type: + + +.. ctype:: int (*visitproc)(PyObject *object, void *arg) + + Type of the visitor function passed to the :attr:`tp_traverse` handler. The + function should be called with an object to traverse as *object* and the third + parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses + several visitor functions to implement cyclic garbage detection; it's not + expected that users will need to write their own visitor functions. + +The :attr:`tp_traverse` handler must have the following type: + + +.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg) + + Traversal function for a container object. Implementations must call the + *visit* function for each object directly contained by *self*, with the + parameters to *visit* being the contained object and the *arg* value passed to + the handler. The *visit* function must not be called with a *NULL* object + argument. If *visit* returns a non-zero value that value should be returned + immediately. + +To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is +provided. In order to use this macro, the :attr:`tp_traverse` implementation +must name its arguments exactly *visit* and *arg*: + + +.. cfunction:: void Py_VISIT(PyObject *o) + + Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a + non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers + look like:: + + static int + my_traverse(Noddy *self, visitproc visit, void *arg) + { + Py_VISIT(self->foo); + Py_VISIT(self->bar); + return 0; + } + +The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if +the object is immutable. + + +.. ctype:: int (*inquiry)(PyObject *self) + + Drop references that may have created reference cycles. Immutable objects do + not have to define this method since they can never directly create reference + cycles. Note that the object must still be valid after calling this method + (don't just call :cfunc:`Py_DECREF` on a reference). The collector will call + this method if it detects that this object is involved in a reference cycle. diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst new file mode 100644 index 0000000..0d3789a --- /dev/null +++ b/Doc/c-api/gen.rst @@ -0,0 +1,38 @@ +.. highlightlang:: c + +.. _gen-objects: + +Generator Objects +----------------- + +Generator objects are what Python uses to implement generator iterators. They +are normally created by iterating over a function that yields values, rather +than explicitly calling :cfunc:`PyGen_New`. + + +.. ctype:: PyGenObject + + The C structure used for generator objects. + + +.. cvar:: PyTypeObject PyGen_Type + + The type object corresponding to generator objects + + +.. cfunction:: int PyGen_Check(ob) + + Return true if *ob* is a generator object; *ob* must not be *NULL*. + + +.. cfunction:: int PyGen_CheckExact(ob) + + Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not + be *NULL*. + + +.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame) + + Create and return a new generator object based on the *frame* object. A + reference to *frame* is stolen by this function. The parameter must not be + *NULL*. diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst new file mode 100644 index 0000000..907f531 --- /dev/null +++ b/Doc/c-api/import.rst @@ -0,0 +1,227 @@ +.. highlightlang:: c + +.. _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`. diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst new file mode 100644 index 0000000..ba7e9e3 --- /dev/null +++ b/Doc/c-api/iter.rst @@ -0,0 +1,47 @@ +.. highlightlang:: c + +.. _iterator: + +Iterator Protocol +================= + +There are only a couple of functions specifically for working with iterators. + +.. cfunction:: int PyIter_Check(PyObject *o) + + Return true if the object *o* supports the iterator protocol. + + +.. cfunction:: PyObject* PyIter_Next(PyObject *o) + + Return the next value from the iteration *o*. If the object is an iterator, + this retrieves the next value from the iteration, and returns *NULL* with no + exception set if there are no remaining items. If the object is not an + iterator, :exc:`TypeError` is raised, or if there is an error in retrieving the + item, returns *NULL* and passes along the exception. + +To write a loop which iterates over an iterator, the C code should look +something like this:: + + PyObject *iterator = PyObject_GetIter(obj); + PyObject *item; + + if (iterator == NULL) { + /* propagate error */ + } + + while (item = PyIter_Next(iterator)) { + /* do something with item */ + ... + /* release reference when done */ + Py_DECREF(item); + } + + Py_DECREF(iterator); + + if (PyErr_Occurred()) { + /* propagate error */ + } + else { + /* continue doing useful work */ + } diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst new file mode 100644 index 0000000..8665080 --- /dev/null +++ b/Doc/c-api/iterator.rst @@ -0,0 +1,50 @@ +.. highlightlang:: c + +.. _iterator-objects: + +Iterator Objects +---------------- + +Python provides two general-purpose iterator objects. The first, a sequence +iterator, works with an arbitrary sequence supporting the :meth:`__getitem__` +method. The second works with a callable object and a sentinel value, calling +the callable for each item in the sequence, and ending the iteration when the +sentinel value is returned. + + +.. cvar:: PyTypeObject PySeqIter_Type + + Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the + one-argument form of the :func:`iter` built-in function for built-in sequence + types. + + +.. cfunction:: int PySeqIter_Check(op) + + Return true if the type of *op* is :cdata:`PySeqIter_Type`. + + +.. cfunction:: PyObject* PySeqIter_New(PyObject *seq) + + Return an iterator that works with a general sequence object, *seq*. The + iteration ends when the sequence raises :exc:`IndexError` for the subscripting + operation. + + +.. cvar:: PyTypeObject PyCallIter_Type + + Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the + two-argument form of the :func:`iter` built-in function. + + +.. cfunction:: int PyCallIter_Check(op) + + Return true if the type of *op* is :cdata:`PyCallIter_Type`. + + +.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel) + + Return a new iterator. The first parameter, *callable*, can be any Python + callable object that can be called with no parameters; each call to it should + return the next item in the iteration. When *callable* returns a value equal to + *sentinel*, the iteration will be terminated. diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst new file mode 100644 index 0000000..7909be8 --- /dev/null +++ b/Doc/c-api/list.rst @@ -0,0 +1,142 @@ +.. highlightlang:: c + +.. _listobjects: + +List Objects +------------ + +.. index:: object: list + + +.. ctype:: PyListObject + + This subtype of :ctype:`PyObject` represents a Python list object. + + +.. cvar:: PyTypeObject PyList_Type + + .. index:: single: ListType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python list type. This is + the same object as ``list`` and ``types.ListType`` in the Python layer. + + +.. cfunction:: int PyList_Check(PyObject *p) + + Return true if *p* is a list object or an instance of a subtype of the list + type. + + +.. cfunction:: int PyList_CheckExact(PyObject *p) + + Return true if *p* is a list object, but not an instance of a subtype of the + list type. + + +.. cfunction:: PyObject* PyList_New(Py_ssize_t len) + + Return a new list of length *len* on success, or *NULL* on failure. + + .. note:: + + If *length* is greater than zero, the returned list object's items are set to + ``NULL``. Thus you cannot use abstract API functions such as + :cfunc:`PySequence_SetItem` or expose the object to Python code before setting + all items to a real object with :cfunc:`PyList_SetItem`. + + +.. cfunction:: Py_ssize_t PyList_Size(PyObject *list) + + .. index:: builtin: len + + Return the length of the list object in *list*; this is equivalent to + ``len(list)`` on a list object. + + +.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list) + + Macro form of :cfunc:`PyList_Size` without error checking. + + +.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) + + Return the object at position *pos* in the list pointed to by *p*. The position + must be positive, indexing from the end of the list is not supported. If *pos* + is out of bounds, return *NULL* and set an :exc:`IndexError` exception. + + +.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) + + Macro form of :cfunc:`PyList_GetItem` without error checking. + + +.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) + + Set the item at index *index* in list to *item*. Return ``0`` on success or + ``-1`` on failure. + + .. note:: + + This function "steals" a reference to *item* and discards a reference to an item + already in the list at the affected position. + + +.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o) + + Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally + only used to fill in new lists where there is no previous content. + + .. note:: + + This function "steals" a reference to *item*, and, unlike + :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it + being replaced; any reference in *list* at position *i* will be leaked. + + +.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item) + + Insert the item *item* into list *list* in front of index *index*. Return ``0`` + if successful; return ``-1`` and set an exception if unsuccessful. Analogous to + ``list.insert(index, item)``. + + +.. cfunction:: int PyList_Append(PyObject *list, PyObject *item) + + Append the object *item* at the end of list *list*. Return ``0`` if successful; + return ``-1`` and set an exception if unsuccessful. Analogous to + ``list.append(item)``. + + +.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high) + + Return a list of the objects in *list* containing the objects *between* *low* + and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to + ``list[low:high]``. + + +.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist) + + Set the slice of *list* between *low* and *high* to the contents of *itemlist*. + Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*, + indicating the assignment of an empty list (slice deletion). Return ``0`` on + success, ``-1`` on failure. + + +.. cfunction:: int PyList_Sort(PyObject *list) + + Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure. + This is equivalent to ``list.sort()``. + + +.. cfunction:: int PyList_Reverse(PyObject *list) + + Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on + failure. This is the equivalent of ``list.reverse()``. + + +.. cfunction:: PyObject* PyList_AsTuple(PyObject *list) + + .. index:: builtin: tuple + + Return a new tuple object containing the contents of *list*; equivalent to + ``tuple(list)``. diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst new file mode 100644 index 0000000..421ec15 --- /dev/null +++ b/Doc/c-api/long.rst @@ -0,0 +1,196 @@ +.. highlightlang:: c + +.. _longobjects: + +Integer Objects +--------------- + +.. index:: object: long integer + object: integer + +All integers are implemented as "long" integer objects of arbitrary size. + +.. ctype:: PyLongObject + + This subtype of :ctype:`PyObject` represents a Python integer object. + + +.. cvar:: PyTypeObject PyLong_Type + + This instance of :ctype:`PyTypeObject` represents the Python integer type. + This is the same object as ``int``. + + +.. cfunction:: int PyLong_Check(PyObject *p) + + Return true if its argument is a :ctype:`PyLongObject` or a subtype of + :ctype:`PyLongObject`. + + +.. cfunction:: int PyLong_CheckExact(PyObject *p) + + Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of + :ctype:`PyLongObject`. + + +.. cfunction:: PyObject* PyLong_FromLong(long v) + + Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure. + + The current implementation keeps an array of integer objects for all integers + between ``-5`` and ``256``, when you create an int in that range you actually + just get back a reference to the existing object. So it should be possible to + change the value of ``1``. I suspect the behaviour of Python in this case is + undefined. :-) + + +.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v) + + Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or + *NULL* on failure. + + +.. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) + + Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL* + on failure. + + +.. cfunction:: PyObject* PyLong_FromSize_t(size_t v) + + Return a new :ctype:`PyLongObject` object with a value of *v*, or *NULL* + on failure. + + +.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v) + + Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL* + on failure. + + +.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v) + + Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`, + or *NULL* on failure. + + +.. cfunction:: PyObject* PyLong_FromDouble(double v) + + Return a new :ctype:`PyLongObject` object from the integer part of *v*, or + *NULL* on failure. + + +.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base) + + Return a new :ctype:`PyLongObject` based on the string value in *str*, which + is interpreted according to the radix in *base*. If *pend* is non-*NULL*, + ``*pend`` will point to the first character in *str* which follows the + representation of the number. If *base* is ``0``, the radix will be + determined based on the leading characters of *str*: if *str* starts with + ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or + ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``, + radix 2 will be used; otherwise radix 10 will be used. If *base* is not + ``0``, it must be between ``2`` and ``36``, inclusive. Leading spaces are + ignored. If there are no digits, :exc:`ValueError` will be raised. + + +.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base) + + Convert a sequence of Unicode digits to a Python integer value. The Unicode + string is first encoded to a byte string using :cfunc:`PyUnicode_EncodeDecimal` + and then converted using :cfunc:`PyLong_FromString`. + + +.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p) + + Create a Python integer from the pointer *p*. The pointer value can be + retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`. + + +.. XXX alias PyLong_AS_LONG (for now) +.. cfunction:: long PyLong_AsLong(PyObject *pylong) + + .. index:: + single: LONG_MAX + single: OverflowError (built-in exception) + + Return a C :ctype:`long` representation of the contents of *pylong*. If + *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`, + and return -1. Convert non-long objects automatically to long first, + and return -1 if that raises exceptions. + +.. cfunction:: long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow) + + Return a C :ctype:`long` representation of the contents of *pylong*. If + *pylong* is greater than :const:`LONG_MAX`, return -1 and + set `*overflow` to 1 (for overflow) or -1 (for underflow). + If an exception is set because of type errors, also return -1. + + +.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) + + .. index:: + single: ULONG_MAX + single: OverflowError (built-in exception) + + Return a C :ctype:`unsigned long` representation of the contents of *pylong*. + If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is + raised. + + +.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) + + .. index:: + single: PY_SSIZE_T_MAX + + Return a :ctype:`Py_ssize_t` representation of the contents of *pylong*. If + *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is + raised. + + +.. cfunction:: size_t PyLong_AsSize_t(PyObject *pylong) + + Return a :ctype:`size_t` representation of the contents of *pylong*. If + *pylong* is greater than the maximum value for a :ctype:`size_t`, an + :exc:`OverflowError` is raised. + + +.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong) + + Return a C :ctype:`long long` from a Python integer. If *pylong* cannot be + represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised. + + +.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong) + + Return a C :ctype:`unsigned long long` from a Python integer. If *pylong* + cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError` + will be raised if the value is positive, or a :exc:`TypeError` will be raised if + the value is negative. + + +.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io) + + Return a C :ctype:`unsigned long` from a Python integer, without checking for + overflow. + + +.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io) + + Return a C :ctype:`unsigned long long` from a Python integer, without + checking for overflow. + + +.. cfunction:: double PyLong_AsDouble(PyObject *pylong) + + Return a C :ctype:`double` representation of the contents of *pylong*. If + *pylong* cannot be approximately represented as a :ctype:`double`, an + :exc:`OverflowError` exception is raised and ``-1.0`` will be returned. + + +.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong) + + Convert a Python integer *pylong* to a C :ctype:`void` pointer. If *pylong* + cannot be converted, an :exc:`OverflowError` will be raised. This is only + assured to produce a usable :ctype:`void` pointer for values created with + :cfunc:`PyLong_FromVoidPtr`. diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst new file mode 100644 index 0000000..177b215 --- /dev/null +++ b/Doc/c-api/mapping.rst @@ -0,0 +1,78 @@ +.. highlightlang:: c + +.. _mapping: + +Mapping Protocol +================ + + +.. cfunction:: int PyMapping_Check(PyObject *o) + + Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This + function always succeeds. + + +.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o) + + .. index:: builtin: len + + 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)``. + + +.. cfunction:: 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]``. + + +.. cfunction:: 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]``. + + +.. cfunction:: 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 ``key in o``. + This function always succeeds. + + +.. cfunction:: 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 ``key in o``. This function always + succeeds. + + +.. cfunction:: 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()``. + + +.. cfunction:: 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()``. + + +.. cfunction:: 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()``. + + +.. cfunction:: 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]``. + + +.. cfunction:: 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``. diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst new file mode 100644 index 0000000..e7b5c13 --- /dev/null +++ b/Doc/c-api/marshal.rst @@ -0,0 +1,86 @@ +.. highlightlang:: c + +.. _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*. diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst new file mode 100644 index 0000000..9d25571 --- /dev/null +++ b/Doc/c-api/method.rst @@ -0,0 +1,94 @@ +.. highlightlang:: c + +.. _instancemethod-objects: + +Instance Method Objects +----------------------- + +.. index:: object: instancemethod + +An instance method is a wrapper for a :cdata:`PyCFunction` and the new way +to bind a :cdata:`PyCFunction` to a class object. It replaces the former call +``PyMethod_New(func, NULL, class)``. + + +.. cvar:: PyTypeObject PyInstanceMethod_Type + + This instance of :ctype:`PyTypeObject` represents the Python instance + method type. It is not exposed to Python programs. + + +.. cfunction:: int PyInstanceMethod_Check(PyObject *o) + + Return true if *o* is an instance method object (has type + :cdata:`PyInstanceMethod_Type`). The parameter must not be *NULL*. + + +.. cfunction:: PyObject* PyInstanceMethod_New(PyObject *func) + + Return a new instance method object, with *func* being any callable object + *func* is is the function that will be called when the instance method is + called. + + +.. cfunction:: PyObject* PyInstanceMethod_Function(PyObject *im) + + Return the function object associated with the instance method *im*. + + +.. cfunction:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im) + + Macro version of :cfunc:`PyInstanceMethod_Function` which avoids error checking. + + +.. _method-objects: + +Method Objects +-------------- + +.. index:: object: method + +Methods are bound function objects. Methods are always bound to an instance of +an user-defined class. Unbound methods (methods bound to a class object) are +no longer available. + + +.. cvar:: PyTypeObject PyMethod_Type + + .. index:: single: MethodType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python method type. This + is exposed to Python programs as ``types.MethodType``. + + +.. cfunction:: int PyMethod_Check(PyObject *o) + + Return true if *o* is a method object (has type :cdata:`PyMethod_Type`). The + parameter must not be *NULL*. + + +.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self) + + Return a new method object, with *func* being any callable object and *self* + the instance the method should be bound. *func* is is the function that will + be called when the method is called. *self* must not be *NULL*. + + +.. cfunction:: PyObject* PyMethod_Function(PyObject *meth) + + Return the function object associated with the method *meth*. + + +.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth) + + Macro version of :cfunc:`PyMethod_Function` which avoids error checking. + + +.. cfunction:: PyObject* PyMethod_Self(PyObject *meth) + + Return the instance associated with the method *meth*. + + +.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth) + + Macro version of :cfunc:`PyMethod_Self` which avoids error checking. diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst new file mode 100644 index 0000000..9894aca --- /dev/null +++ b/Doc/c-api/module.rst @@ -0,0 +1,94 @@ +.. highlightlang:: c + +.. _moduleobjects: + +Module Objects +-------------- + +.. index:: object: module + +There are only a few functions special to module objects. + + +.. cvar:: PyTypeObject PyModule_Type + + .. index:: single: ModuleType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python module type. This + is exposed to Python programs as ``types.ModuleType``. + + +.. cfunction:: int PyModule_Check(PyObject *p) + + Return true if *p* is a module object, or a subtype of a module object. + + +.. cfunction:: int PyModule_CheckExact(PyObject *p) + + Return true if *p* is a module object, but not a subtype of + :cdata:`PyModule_Type`. + + +.. cfunction:: PyObject* PyModule_New(const char *name) + + .. index:: + single: __name__ (module attribute) + single: __doc__ (module attribute) + single: __file__ (module attribute) + + Return a new module object with the :attr:`__name__` attribute set to *name*. + Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in; + the caller is responsible for providing a :attr:`__file__` attribute. + + +.. cfunction:: PyObject* PyModule_GetDict(PyObject *module) + + .. index:: single: __dict__ (module attribute) + + Return the dictionary object that implements *module*'s namespace; this object + is the same as the :attr:`__dict__` attribute of the module object. This + function never fails. It is recommended extensions use other + :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly + manipulate a module's :attr:`__dict__`. + + +.. cfunction:: char* PyModule_GetName(PyObject *module) + + .. index:: + single: __name__ (module attribute) + single: SystemError (built-in exception) + + Return *module*'s :attr:`__name__` value. If the module does not provide one, + or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned. + + +.. cfunction:: char* PyModule_GetFilename(PyObject *module) + + .. index:: + single: __file__ (module attribute) + single: SystemError (built-in exception) + + Return the name of the file from which *module* was loaded using *module*'s + :attr:`__file__` attribute. If this is not defined, or if it is not a string, + raise :exc:`SystemError` and return *NULL*. + + +.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value) + + Add an object to *module* as *name*. This is a convenience function which can + be used from the module's initialization function. This steals a reference to + *value*. Return ``-1`` on error, ``0`` on success. + + +.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value) + + Add an integer constant to *module* as *name*. This convenience function can be + used from the module's initialization function. Return ``-1`` on error, ``0`` on + success. + + +.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value) + + Add a string constant to *module* as *name*. This convenience function can be + used from the module's initialization function. The string *value* must be + null-terminated. Return ``-1`` on error, ``0`` on success. diff --git a/Doc/c-api/none.rst b/Doc/c-api/none.rst new file mode 100644 index 0000000..70e2c04 --- /dev/null +++ b/Doc/c-api/none.rst @@ -0,0 +1,26 @@ +.. highlightlang:: c + +.. _noneobject: + +The None Object +--------------- + +.. index:: object: None + +Note that the :ctype:`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 :cfunc:`PyNone_Check` function for the +same reason. + + +.. cvar:: PyObject* Py_None + + The Python ``None`` object, denoting lack of value. This object has no methods. + It needs to be treated just like any other object with respect to reference + counts. + + +.. cmacro:: Py_RETURN_NONE + + Properly handle returning :cdata:`Py_None` from within a C function (that is, + increment the reference count of None and return it.) diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst new file mode 100644 index 0000000..6c73bfa --- /dev/null +++ b/Doc/c-api/number.rst @@ -0,0 +1,276 @@ +.. highlightlang:: c + +.. _number: + +Number Protocol +=============== + + +.. cfunction:: int PyNumber_Check(PyObject *o) + + Returns ``1`` if the object *o* provides numeric protocols, and false otherwise. + This function always succeeds. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) + + Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is + equivalent to the "classic" division of integers. + + +.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2) + + Return a reasonable approximation for the mathematical value of *o1* divided by + *o2*, or *NULL* on failure. The return value is "approximate" because binary + floating point numbers are approximate; it is not possible to represent all real + numbers in base two. This function can return a floating point value when + passed two integers. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2) + + .. index:: builtin: divmod + + See the built-in function :func:`divmod`. Returns *NULL* on failure. This is + the equivalent of the Python expression ``divmod(o1, o2)``. + + +.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3) + + .. index:: builtin: pow + + See the built-in function :func:`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 :cdata:`Py_None` in its place (passing *NULL* for + *o3* would cause an illegal memory access). + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PyNumber_Positive(PyObject *o) + + Returns *o* on success, or *NULL* on failure. This is the equivalent of the + Python expression ``+o``. + + +.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o) + + .. index:: builtin: abs + + Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent + of the Python expression ``abs(o)``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2) + + Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. + This is the equivalent of the Python expression ``o1 & o2``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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 + statement ``o1 += o2``. + + +.. cfunction:: 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 statement ``o1 -= o2``. + + +.. cfunction:: 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 statement ``o1 *= o2``. + + +.. cfunction:: 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 statement ``o1 /= o2``. + + +.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2) + + Returns the mathematical floor 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 statement ``o1 //= o2``. + + +.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2) + + Return a reasonable approximation for the mathematical value of *o1* divided by + *o2*, or *NULL* on failure. The return value is "approximate" because binary + floating point numbers are approximate; it is not possible to represent all real + numbers in base two. This function can return a floating point value when + passed two integers. The operation is done *in-place* when *o1* supports it. + + +.. cfunction:: 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 statement ``o1 %= o2``. + + +.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3) + + .. index:: builtin: pow + + See the built-in function :func:`pow`. Returns *NULL* on failure. The operation + is done *in-place* when *o1* supports it. This is the equivalent of the Python + statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of + ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None` + in its place (passing *NULL* for *o3* would cause an illegal memory access). + + +.. cfunction:: 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 statement ``o1 <<= o2``. + + +.. cfunction:: 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 statement ``o1 >>= o2``. + + +.. cfunction:: 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 statement ``o1 &= o2``. + + +.. cfunction:: 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 statement ``o1 ^= o2``. + + +.. cfunction:: 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 statement ``o1 |= o2``. + + +.. cfunction:: PyObject* PyNumber_Int(PyObject *o) + + .. index:: builtin: int + + Returns the *o* converted to an integer object on success, or *NULL* on failure. + If the argument is outside the integer range a long object will be returned + instead. This is the equivalent of the Python expression ``int(o)``. + + +.. cfunction:: PyObject* PyNumber_Long(PyObject *o) + + .. index:: builtin: long + + Returns the *o* converted to an integer object on success, or *NULL* on + failure. This is the equivalent of the Python expression ``long(o)``. + + +.. cfunction:: PyObject* PyNumber_Float(PyObject *o) + + .. index:: builtin: float + + Returns the *o* converted to a float object on success, or *NULL* on failure. + This is the equivalent of the Python expression ``float(o)``. + + +.. cfunction:: PyObject* PyNumber_Index(PyObject *o) + + Returns the *o* converted to a Python int or long on success or *NULL* with a + TypeError exception raised on failure. + + +.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc) + + Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an + integer. If *o* can be converted to a Python int or long but the attempt to + convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the + *exc* argument is the type of exception that will be raised (usually + :exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the + exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative + integer or *PY_SSIZE_T_MAX* for a positive integer. + + +.. cfunction:: int PyIndex_Check(PyObject *o) + + Returns True if *o* is an index integer (has the nb_index slot of the + tp_as_number structure filled in). diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst new file mode 100644 index 0000000..2ce0d97 --- /dev/null +++ b/Doc/c-api/objbuffer.rst @@ -0,0 +1,37 @@ +.. highlightlang:: c + +.. _abstract-buffer: + +Buffer Protocol +=============== + + +.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len) + + Returns a pointer to a read-only memory location useable as character- based + input. The *obj* argument must support the single-segment character buffer + interface. On success, returns ``0``, sets *buffer* to the memory location and + *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError` + on error. + + +.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len) + + Returns a pointer to a read-only memory location containing arbitrary data. The + *obj* argument must support the single-segment readable buffer interface. On + success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to + the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error. + + +.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o) + + Returns ``1`` if *o* supports the single-segment readable buffer interface. + Otherwise returns ``0``. + + +.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len) + + Returns a pointer to a writable memory location. The *obj* argument must + support the single-segment, character buffer interface. On success, returns + ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer + length. Returns ``-1`` and sets a :exc:`TypeError` on error. diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst new file mode 100644 index 0000000..c9c4a42 --- /dev/null +++ b/Doc/c-api/object.rst @@ -0,0 +1,325 @@ +.. highlightlang:: c + +.. _object: + +Object Protocol +=============== + + +.. cfunction:: 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 :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written + instead of the :func:`repr`. + + +.. cfunction:: 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. + + +.. cfunction:: int PyObject_HasAttrString(PyObject *o, const 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. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: int PyObject_SetAttrString(PyObject *o, const 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: int PyObject_DelAttrString(PyObject *o, const 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``. + + +.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid) + + Compare the values of *o1* and *o2* using the operation specified by *opid*, + which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, + :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, + ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of + the Python expression ``o1 op o2``, where ``op`` is the operator corresponding + to *opid*. Returns the value of the comparison on success, or *NULL* on failure. + + +.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid) + + Compare the values of *o1* and *o2* using the operation specified by *opid*, + which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, + :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, + ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error, + ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the + Python expression ``o1 op o2``, where ``op`` is the operator corresponding to + *opid*. + + +.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result) + + .. index:: builtin: cmp + + 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)``. + + +.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2) + + .. index:: builtin: cmp + + 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 + :cfunc:`PyErr_Occurred` to detect an error. This is equivalent to the Python + expression ``cmp(o1, o2)``. + + +.. cfunction:: PyObject* PyObject_Repr(PyObject *o) + + .. index:: builtin: repr + + 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 :func:`repr` built-in function and + by reverse quotes. + + +.. cfunction:: PyObject* PyObject_Str(PyObject *o) + + .. index:: builtin: str + + 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 :func:`str` built-in function + and, therefore, by the :func:`print` function. + + +.. cfunction:: PyObject* PyObject_Unicode(PyObject *o) + + .. index:: builtin: unicode + + 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 ``unicode(o)``. Called by the :func:`unicode` built-in + function. + + +.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls) + + Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of + *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If + *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance` + returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will + be done against every entry in *cls*. The result will be ``1`` when at least one + of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a + class instance and *cls* is neither a type object, nor a class object, nor a + tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship + of the value of that attribute with *cls* will be used to determine the result + of this function. + + +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 :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of +:class:`A` if it inherits from :class:`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*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B* +are different objects, *B*'s :attr:`__bases__` attribute is searched in a +depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute +is considered sufficient for this determination. + + +.. cfunction:: 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 *cls* + is a tuple, the check will be done against every entry in *cls*. The result will + be ``1`` when at least one of the checks returns ``1``, otherwise it will be + ``0``. If either *derived* or *cls* is not an actual class object (or tuple), + this function uses the generic algorithm described above. + + +.. cfunction:: 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. + + +.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw) + + Call a callable Python object *callable_object*, with arguments given by the + tuple *args*, and named arguments given by the dictionary *kw*. If no named + arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an + empty tuple if no arguments are needed. Returns the result of the call on + success, or *NULL* on failure. This is the equivalent of the Python expression + ``callable_object(*args, **kw)``. + + +.. cfunction:: 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 ``callable_object(*args)``. + + +.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...) + + Call a callable Python object *callable*, with a variable number of C arguments. + The C arguments are described using a :cfunc:`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 ``callable(*args)``. Note that if you only + pass :ctype:`PyObject \*` args, :cfunc:`PyObject_CallFunctionObjArgs` is a + faster alternative. + + +.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...) + + Call the method named *method* of object *o* with a variable number of C + arguments. The C arguments are described by a :cfunc:`Py_BuildValue` format + string that should produce a tuple. 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 if you only pass :ctype:`PyObject \*` args, + :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative. + + +.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) + + Call a callable Python object *callable*, with a variable number of + :ctype:`PyObject\*` arguments. The arguments are provided as a variable number + of parameters followed by *NULL*. Returns the result of the call on success, or + *NULL* on failure. + + +.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL) + + Calls a method of the object *o*, where the name of the method is given as a + Python string object in *name*. It is called with a variable number of + :ctype:`PyObject\*` arguments. The arguments are provided as a variable number + of parameters followed by *NULL*. Returns the result of the call on success, or + *NULL* on failure. + + +.. cfunction:: long PyObject_Hash(PyObject *o) + + .. index:: builtin: hash + + Compute and return the hash value of an object *o*. On failure, return ``-1``. + This is the equivalent of the Python expression ``hash(o)``. + + +.. cfunction:: 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``. On failure, return + ``-1``. + + +.. cfunction:: int PyObject_Not(PyObject *o) + + Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise. + This is equivalent to the Python expression ``not o``. On failure, return + ``-1``. + + +.. cfunction:: PyObject* PyObject_Type(PyObject *o) + + .. index:: builtin: type + + When *o* is non-*NULL*, returns a type object corresponding to the object type + of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This + is equivalent to the Python expression ``type(o)``. This function increments the + reference count of the return value. There's really no reason to use this + function instead of the common expression ``o->ob_type``, which returns a + pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference + count is needed. + + +.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type) + + Return true if the object *o* is of type *type* or a subtype of *type*. Both + parameters must be non-*NULL*. + + +.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o) + Py_ssize_t PyObject_Size(PyObject *o) + + .. index:: builtin: len + + Return the length of object *o*. If the object *o* provides either the sequence + and mapping protocols, the sequence length is returned. On error, ``-1`` is + returned. This is the equivalent to the Python expression ``len(o)``. + + +.. cfunction:: 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]``. + + +.. cfunction:: 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``. + + +.. cfunction:: 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]``. + + +.. cfunction:: PyObject* PyObject_Dir(PyObject *o) + + This is equivalent to the Python expression ``dir(o)``, returning a (possibly + empty) list of strings appropriate for the object argument, or *NULL* if there + was an error. If the argument is *NULL*, this is like the Python ``dir()``, + returning the names of the current locals; in this case, if no execution frame + is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false. + + +.. cfunction:: PyObject* PyObject_GetIter(PyObject *o) + + This is equivalent to the Python expression ``iter(o)``. It returns a new + iterator for the object argument, or the object itself if the object is already + an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be + iterated. diff --git a/Doc/c-api/objimpl.rst b/Doc/c-api/objimpl.rst new file mode 100644 index 0000000..7023e51 --- /dev/null +++ b/Doc/c-api/objimpl.rst @@ -0,0 +1,17 @@ +.. highlightlang:: c + +.. _newtypes: + +***************************** +Object Implementation Support +***************************** + +This chapter describes the functions, types, and macros used when defining new +object types. + +.. toctree:: + + allocation.rst + structures.rst + typeobj.rst + gcsupport.rst diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst new file mode 100644 index 0000000..8a96ce3 --- /dev/null +++ b/Doc/c-api/reflection.rst @@ -0,0 +1,50 @@ +.. highlightlang:: c + +.. _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*. diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst new file mode 100644 index 0000000..6d3ef71 --- /dev/null +++ b/Doc/c-api/sequence.rst @@ -0,0 +1,162 @@ +.. highlightlang:: c + +.. _sequence: + +Sequence Protocol +================= + + +.. cfunction:: int PySequence_Check(PyObject *o) + + Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. + This function always succeeds. + + +.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o) + + .. index:: builtin: len + + 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)``. + + +.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o) + + Alternate name for :cfunc:`PySequence_Size`. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t 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``. + + +.. cfunction:: 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``. + + +.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t 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``. + + +.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i) + + Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of + the Python expression ``o[i]``. + + +.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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]``. + + +.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v) + + Assign object *v* to the *i*th element of *o*. Returns ``-1`` on failure. This + is the equivalent of the Python statement ``o[i] = v``. This function *does + not* steal a reference to *v*. + + +.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i) + + Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the + equivalent of the Python statement ``del o[i]``. + + +.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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``. + + +.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t 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]``. + + +.. cfunction:: Py_ssize_t 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)``. + + +.. cfunction:: 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``. + + +.. cfunction:: Py_ssize_t 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)``. + + +.. cfunction:: 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. + + +.. cfunction:: PyObject* PySequence_Tuple(PyObject *o) + + .. index:: builtin: tuple + + Return a tuple object with the same contents as the arbitrary sequence *o* or + *NULL* on failure. If *o* is a tuple, a new reference will be returned, + otherwise a tuple will be constructed with the appropriate contents. This is + equivalent to the Python expression ``tuple(o)``. + + +.. cfunction:: 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 :cfunc:`PySequence_Fast_GET_ITEM` to access the + members of the result. Returns *NULL* on failure. If the object is not a + sequence, raises :exc:`TypeError` with *m* as the message text. + + +.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) + + Return the *i*th element of *o*, assuming that *o* was returned by + :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds. + + +.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o) + + Return the underlying array of PyObject pointers. Assumes that *o* was returned + by :cfunc:`PySequence_Fast` and *o* is not *NULL*. + + +.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i) + + Return the *i*th element of *o* or *NULL* on failure. Macro form of + :cfunc:`PySequence_GetItem` but without checking that + :cfunc:`PySequence_Check(o)` is true and without adjustment for negative + indices. + + +.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) + + Returns the length of *o*, assuming that *o* was returned by + :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be + gotten by calling :cfunc:`PySequence_Size` on *o*, but + :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list + or tuple. diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst new file mode 100644 index 0000000..3d8cf87 --- /dev/null +++ b/Doc/c-api/set.rst @@ -0,0 +1,146 @@ +.. highlightlang:: c + +.. _setobjects: + +Set Objects +----------- + +.. sectionauthor:: Raymond D. Hettinger <python@rcn.com> + + +.. index:: + object: set + object: frozenset + +This section details the public API for :class:`set` and :class:`frozenset` +objects. Any functionality not listed below is best accessed using the either +the abstract object protocol (including :cfunc:`PyObject_CallMethod`, +:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`, +:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and +:cfunc:`PyObject_GetIter`) or the abstract number protocol (including +:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`, +:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`, +:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and +:cfunc:`PyNumber_InPlaceXor`). + + +.. ctype:: PySetObject + + This subtype of :ctype:`PyObject` is used to hold the internal data for both + :class:`set` and :class:`frozenset` objects. It is like a :ctype:`PyDictObject` + in that it is a fixed size for small sets (much like tuple storage) and will + point to a separate, variable sized block of memory for medium and large sized + sets (much like list storage). None of the fields of this structure should be + considered public and are subject to change. All access should be done through + the documented API rather than by manipulating the values in the structure. + + +.. cvar:: PyTypeObject PySet_Type + + This is an instance of :ctype:`PyTypeObject` representing the Python + :class:`set` type. + + +.. cvar:: PyTypeObject PyFrozenSet_Type + + This is an instance of :ctype:`PyTypeObject` representing the Python + :class:`frozenset` type. + +The following type check macros work on pointers to any Python object. Likewise, +the constructor functions work with any iterable Python object. + + +.. cfunction:: int PyAnySet_Check(PyObject *p) + + Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an + instance of a subtype. + + +.. cfunction:: int PyAnySet_CheckExact(PyObject *p) + + Return true if *p* is a :class:`set` object or a :class:`frozenset` object but + not an instance of a subtype. + + +.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p) + + Return true if *p* is a :class:`frozenset` object but not an instance of a + subtype. + + +.. cfunction:: PyObject* PySet_New(PyObject *iterable) + + Return a new :class:`set` containing objects returned by the *iterable*. The + *iterable* may be *NULL* to create a new empty set. Return the new set on + success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not + actually iterable. The constructor is also useful for copying a set + (``c=set(s)``). + + +.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable) + + Return a new :class:`frozenset` containing objects returned by the *iterable*. + The *iterable* may be *NULL* to create a new empty frozenset. Return the new + set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is + not actually iterable. + +The following functions and macros are available for instances of :class:`set` +or :class:`frozenset` or instances of their subtypes. + + +.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset) + + .. index:: builtin: len + + Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to + ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a + :class:`set`, :class:`frozenset`, or an instance of a subtype. + + +.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset) + + Macro form of :cfunc:`PySet_Size` without error checking. + + +.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key) + + Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike + the Python :meth:`__contains__` method, this function does not automatically + convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if + the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a + :class:`set`, :class:`frozenset`, or an instance of a subtype. + +The following functions are available for instances of :class:`set` or its +subtypes but not for instances of :class:`frozenset` or its subtypes. + + +.. cfunction:: int PySet_Add(PyObject *set, PyObject *key) + + Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset` + instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if + the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. + Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its + subtype. + + +.. cfunction:: int PySet_Discard(PyObject *set, PyObject *key) + + Return 1 if found and removed, 0 if not found (no action taken), and -1 if an + error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a + :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard` + method, this function does not automatically convert unhashable sets into + temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an + instance of :class:`set` or its subtype. + + +.. cfunction:: PyObject* PySet_Pop(PyObject *set) + + Return a new reference to an arbitrary object in the *set*, and removes the + object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the + set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of + :class:`set` or its subtype. + + +.. cfunction:: int PySet_Clear(PyObject *set) + + Empty an existing set of all elements. diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst new file mode 100644 index 0000000..ea2b5d6 --- /dev/null +++ b/Doc/c-api/slice.rst @@ -0,0 +1,54 @@ +.. highlightlang:: c + +.. _slice-objects: + +Slice Objects +------------- + + +.. cvar:: PyTypeObject PySlice_Type + + .. index:: single: SliceType (in module types) + + The type object for slice objects. This is the same as ``slice`` and + ``types.SliceType``. + + +.. cfunction:: int PySlice_Check(PyObject *ob) + + Return true if *ob* is a slice object; *ob* must not be *NULL*. + + +.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step) + + Return a new slice object with the given values. The *start*, *stop*, and + *step* parameters are used as the values of the slice object attributes of the + same names. Any of the values may be *NULL*, in which case the ``None`` will be + used for the corresponding attribute. Return *NULL* if the new object could not + be allocated. + + +.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step) + + Retrieve the start, stop and step indices from the slice object *slice*, + assuming a sequence of length *length*. Treats indices greater than *length* as + errors. + + Returns 0 on success and -1 on error with no exception set (unless one of the + indices was not :const:`None` and failed to be converted to an integer, in which + case -1 is returned with an exception set). + + You probably do not want to use this function. If you want to use slice objects + in versions of Python prior to 2.3, you would probably do well to incorporate + the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of + your extension. + + +.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength) + + Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start, stop, + and step indices from the slice object *slice* assuming a sequence of length + *length*, and store the length of the slice in *slicelength*. Out of bounds + indices are clipped in a manner consistent with the handling of normal slices. + + Returns 0 on success and -1 on error with exception set. diff --git a/Doc/c-api/string.rst b/Doc/c-api/string.rst new file mode 100644 index 0000000..d57757a --- /dev/null +++ b/Doc/c-api/string.rst @@ -0,0 +1,246 @@ +.. highlightlang:: c + +.. _stringobjects: + +String Objects +-------------- + +These functions raise :exc:`TypeError` when expecting a string parameter and are +called with a non-string parameter. + +.. index:: object: string + + +.. ctype:: PyStringObject + + This subtype of :ctype:`PyObject` represents a Python string object. + + +.. cvar:: PyTypeObject PyString_Type + + .. index:: single: StringType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python string type; it is + the same object as ``str`` and ``types.StringType`` in the Python layer. . + + +.. cfunction:: int PyString_Check(PyObject *o) + + Return true if the object *o* is a string object or an instance of a subtype of + the string type. + + +.. cfunction:: int PyString_CheckExact(PyObject *o) + + Return true if the object *o* is a string object, but not an instance of a + subtype of the string type. + + +.. cfunction:: PyObject* PyString_FromString(const char *v) + + Return a new string object with a copy of the string *v* as value on success, + and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be + checked. + + +.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len) + + Return a new string object with a copy of the string *v* as value and length + *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the + string are uninitialized. + + +.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...) + + Take a C :cfunc:`printf`\ -style *format* string and a variable number of + arguments, calculate the size of the resulting Python string and return a string + with the values formatted into it. The variable arguments must be C types and + must correspond exactly to the format characters in the *format* string. The + following format characters are allowed: + + .. % XXX: This should be exactly the same as the table in PyErr_Format. + .. % One should just refer to the other. + .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated + .. % because not all compilers support the %z width modifier -- we fake it + .. % when necessary via interpolating PY_FORMAT_SIZE_T. + .. % %u, %lu, %zu should have "new in Python 2.5" blurbs. + + +-------------------+---------------+--------------------------------+ + | Format Characters | Type | Comment | + +===================+===============+================================+ + | :attr:`%%` | *n/a* | The literal % character. | + +-------------------+---------------+--------------------------------+ + | :attr:`%c` | int | A single character, | + | | | represented as an C int. | + +-------------------+---------------+--------------------------------+ + | :attr:`%d` | int | Exactly equivalent to | + | | | ``printf("%d")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%u` | unsigned int | Exactly equivalent to | + | | | ``printf("%u")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%ld` | long | Exactly equivalent to | + | | | ``printf("%ld")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%lu` | unsigned long | Exactly equivalent to | + | | | ``printf("%lu")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | + | | | ``printf("%zd")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%zu` | size_t | Exactly equivalent to | + | | | ``printf("%zu")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%i` | int | Exactly equivalent to | + | | | ``printf("%i")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%x` | int | Exactly equivalent to | + | | | ``printf("%x")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%s` | char\* | A null-terminated C character | + | | | array. | + +-------------------+---------------+--------------------------------+ + | :attr:`%p` | void\* | The hex representation of a C | + | | | pointer. Mostly equivalent to | + | | | ``printf("%p")`` except that | + | | | it is guaranteed to start with | + | | | the literal ``0x`` regardless | + | | | of what the platform's | + | | | ``printf`` yields. | + +-------------------+---------------+--------------------------------+ + + An unrecognized format character causes all the rest of the format string to be + copied as-is to the result string, and any extra arguments discarded. + + +.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs) + + Identical to :func:`PyString_FromFormat` except that it takes exactly two + arguments. + + +.. cfunction:: Py_ssize_t PyString_Size(PyObject *string) + + Return the length of the string in string object *string*. + + +.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string) + + Macro form of :cfunc:`PyString_Size` but without error checking. + + +.. cfunction:: char* PyString_AsString(PyObject *string) + + Return a NUL-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. If + *string* is a Unicode object, this function computes the default encoding of + *string* and operates on that. If *string* is not a string object at all, + :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`. + + +.. cfunction:: char* PyString_AS_STRING(PyObject *string) + + Macro form of :cfunc:`PyString_AsString` but without error checking. Only + string objects are supported; no Unicode objects should be passed. + + +.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) + + Return a NUL-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 + *NULL*, the resulting buffer may not contain NUL characters; if it does, the + function returns ``-1`` and a :exc:`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. If + *string* is a Unicode object, this function computes the default encoding of + *string* and operates on that. If *string* is not a string object at all, + :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`. + + +.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart) + + Create 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. + + +.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart) + + Create a new string object in *\*string* containing the contents of *newpart* + appended to *string*. This version decrements the reference count of *newpart*. + + +.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t 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. It is an error to call this function if the + refcount on the input string object is not one. Pass the address of an existing + string object as an lvalue (it may be written into), and the new size desired. + On success, *\*string* holds the resized string object and ``0`` is returned; + the address in *\*string* may differ from its input value. If the reallocation + fails, the original string object at *\*string* is deallocated, *\*string* is + set to *NULL*, a memory exception is set, and ``-1`` is returned. + + +.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args) + + Return a new string object from *format* and *args*. Analogous to ``format % + args``. The *args* argument must be a tuple. + + +.. cfunction:: 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.) + + +.. cfunction:: PyObject* PyString_InternFromString(const char *v) + + A combination of :cfunc:`PyString_FromString` and + :cfunc:`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. + + +.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Create an object by decoding *size* bytes of the encoded buffer *s* using the + codec registered for *encoding*. *encoding* and *errors* have the same meaning + as the parameters of the same name in the :func:`unicode` built-in function. + The codec to be used is looked up using the Python codec registry. Return + *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors) + + Decode a string object by passing it to the codec registered for *encoding* and + return the result as Python object. *encoding* and *errors* have the same + meaning as the parameters of the same name in the string :meth:`encode` method. + The codec to be used is looked up using the Python codec registry. Return *NULL* + if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors) + + Encode a string object using the codec registered for *encoding* and return the + result as Python object. *encoding* and *errors* have the same meaning as the + parameters of the same name in the string :meth:`encode` method. The codec to be + used is looked up using the Python codec registry. Return *NULL* if an exception + was raised by the codec. diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst new file mode 100644 index 0000000..7d47cf8 --- /dev/null +++ b/Doc/c-api/structures.rst @@ -0,0 +1,206 @@ +.. highlightlang:: c + +.. _common-structs: + +Common Object Structures +======================== + +There are a large number of structures which are used in the definition of +object types for Python. This section describes these structures and how they +are used. + +All Python objects ultimately share a small number of fields at the beginning of +the object's representation in memory. These are represented by the +:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by +the expansions of some macros also used, whether directly or indirectly, in the +definition of all other Python objects. + + +.. ctype:: PyObject + + All object types are extensions of this type. This is a type which contains the + information Python needs to treat a pointer to an object as an object. In a + normal "release" build, it contains only the objects reference count and a + pointer to the corresponding type object. It corresponds to the fields defined + by the expansion of the ``PyObject_HEAD`` macro. + + +.. ctype:: PyVarObject + + This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field. + This is only used for objects that have some notion of *length*. This type does + not often appear in the Python/C API. It corresponds to the fields defined by + the expansion of the ``PyObject_VAR_HEAD`` macro. + +These macros are used in the definition of :ctype:`PyObject` and +:ctype:`PyVarObject`: + +.. XXX need to document PEP 3123 changes here + +.. cmacro:: PyObject_HEAD + + This is a macro which expands to the declarations of the fields of the + :ctype:`PyObject` type; it is used when declaring new types which represent + objects without a varying length. The specific fields it expands to depend on + the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not + defined, and :cmacro:`PyObject_HEAD` expands to:: + + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + When :cmacro:`Py_TRACE_REFS` is defined, it expands to:: + + PyObject *_ob_next, *_ob_prev; + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + +.. cmacro:: PyObject_VAR_HEAD + + This is a macro which expands to the declarations of the fields of the + :ctype:`PyVarObject` type; it is used when declaring new types which represent + objects with a length that varies from instance to instance. This macro always + expands to:: + + PyObject_HEAD + Py_ssize_t ob_size; + + Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own + expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`. + +.. cmacro:: PyObject_HEAD_INIT + + +.. ctype:: PyCFunction + + Type of the functions used to implement most Python callables in C. Functions of + this type take two :ctype:`PyObject\*` parameters and return one such value. If + the return value is *NULL*, an exception shall have been set. If not *NULL*, + the return value is interpreted as the return value of the function as exposed + in Python. The function must return a new reference. + + +.. ctype:: PyCFunctionWithKeywords + + Type of the functions used to implement Python callables in C that take + keyword arguments: they take three :ctype:`PyObject\*` parameters and return + one such value. See :ctype:`PyCFunction` above for the meaning of the return + value. + + +.. ctype:: PyMethodDef + + Structure used to describe a method of an extension type. This structure has + four fields: + + +------------------+-------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+=============+===============================+ + | :attr:`ml_name` | char \* | name of the method | + +------------------+-------------+-------------------------------+ + | :attr:`ml_meth` | PyCFunction | pointer to the C | + | | | implementation | + +------------------+-------------+-------------------------------+ + | :attr:`ml_flags` | int | flag bits indicating how the | + | | | call should be constructed | + +------------------+-------------+-------------------------------+ + | :attr:`ml_doc` | char \* | points to the contents of the | + | | | docstring | + +------------------+-------------+-------------------------------+ + +The :attr:`ml_meth` is a C function pointer. The functions may be of different +types, but they always return :ctype:`PyObject\*`. If the function is not of +the :ctype:`PyCFunction`, the compiler will require a cast in the method table. +Even though :ctype:`PyCFunction` defines the first parameter as +:ctype:`PyObject\*`, it is common that the method implementation uses a the +specific C type of the *self* object. + +The :attr:`ml_flags` field is a bitfield which can include the following flags. +The individual flags indicate either a calling convention or a binding +convention. Of the calling convention flags, only :const:`METH_VARARGS` and +:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS` +alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling +convention flags can be combined with a binding flag. + + +.. data:: METH_VARARGS + + This is the typical calling convention, where the methods have the type + :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The + first one is the *self* object for methods; for module functions, it has the + value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was + used). The second parameter (often called *args*) is a tuple object + representing all arguments. This parameter is typically processed using + :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`. + + +.. data:: METH_KEYWORDS + + Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The + function expects three parameters: *self*, *args*, and a dictionary of all the + keyword arguments. The flag is typically combined with :const:`METH_VARARGS`, + and the parameters are typically processed using + :cfunc:`PyArg_ParseTupleAndKeywords`. + + +.. data:: METH_NOARGS + + Methods without parameters don't need to check whether arguments are given if + they are listed with the :const:`METH_NOARGS` flag. They need to be of type + :ctype:`PyCFunction`. When used with object methods, the first parameter is + typically named ``self`` and will hold a reference to the object instance. In + all cases the second parameter will be *NULL*. + + +.. data:: METH_O + + Methods with a single object argument can be listed with the :const:`METH_O` + flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument. + They have the type :ctype:`PyCFunction`, with the *self* parameter, and a + :ctype:`PyObject\*` parameter representing the single argument. + + +These two constants are not used to indicate the calling convention but the +binding when use with methods of classes. These may not be used for functions +defined for modules. At most one of these flags may be set for any given +method. + + +.. data:: METH_CLASS + + .. index:: builtin: classmethod + + The method will be passed the type object as the first parameter rather than an + instance of the type. This is used to create *class methods*, similar to what + is created when using the :func:`classmethod` built-in function. + + +.. data:: METH_STATIC + + .. index:: builtin: staticmethod + + The method will be passed *NULL* as the first parameter rather than an instance + of the type. This is used to create *static methods*, similar to what is + created when using the :func:`staticmethod` built-in function. + +One other constant controls whether a method is loaded in place of another +definition with the same method name. + + +.. data:: METH_COEXIST + + The method will be loaded in place of existing definitions. Without + *METH_COEXIST*, the default is to skip repeated definitions. Since slot + wrappers are loaded before the method table, the existence of a *sq_contains* + slot, for example, would generate a wrapped method named :meth:`__contains__` + and preclude the loading of a corresponding PyCFunction with the same name. + With the flag defined, the PyCFunction will be loaded in place of the wrapper + object and will co-exist with the slot. This is helpful because calls to + PyCFunctions are optimized more than wrapper object calls. + + +.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name) + + Return a bound method object for an extension type implemented in C. This can + be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr` + handler that does not use the :cfunc:`PyObject_GenericGetAttr` function. diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst new file mode 100644 index 0000000..7696811 --- /dev/null +++ b/Doc/c-api/sys.rst @@ -0,0 +1,158 @@ +.. highlightlang:: c + +.. _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*. diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst new file mode 100644 index 0000000..eb661fb --- /dev/null +++ b/Doc/c-api/tuple.rst @@ -0,0 +1,107 @@ +.. highlightlang:: c + +.. _tupleobjects: + +Tuple Objects +------------- + +.. index:: object: tuple + + +.. ctype:: PyTupleObject + + This subtype of :ctype:`PyObject` represents a Python tuple object. + + +.. cvar:: PyTypeObject PyTuple_Type + + .. index:: single: TupleType (in module types) + + This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is + the same object as ``tuple`` and ``types.TupleType`` in the Python layer.. + + +.. cfunction:: int PyTuple_Check(PyObject *p) + + Return true if *p* is a tuple object or an instance of a subtype of the tuple + type. + + +.. cfunction:: int PyTuple_CheckExact(PyObject *p) + + Return true if *p* is a tuple object, but not an instance of a subtype of the + tuple type. + + +.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len) + + Return a new tuple object of size *len*, or *NULL* on failure. + + +.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) + + Return a new tuple object of size *n*, or *NULL* on failure. The tuple values + are initialized to the subsequent *n* C arguments pointing to Python objects. + ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. + + +.. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p) + + Take a pointer to a tuple object, and return the size of that tuple. + + +.. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) + + Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple; + no error checking is performed. + + +.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) + + Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is + out of bounds, return *NULL* and sets an :exc:`IndexError` exception. + + +.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) + + Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments. + + +.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) + + Take a slice of the tuple pointed to by *p* from *low* to *high* and return it + as a new tuple. + + +.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) + + Insert a reference to object *o* at position *pos* of the tuple pointed to by + *p*. Return ``0`` on success. + + .. note:: + + This function "steals" a reference to *o*. + + +.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) + + Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be + used to fill in brand new tuples. + + .. note:: + + This function "steals" a reference to *o*. + + +.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) + + Can be used to resize a tuple. *newsize* will be the new length of the tuple. + Because tuples are *supposed* to be immutable, this should only be used if there + is only one reference to the object. Do *not* use this if the tuple may already + be known to some other part of the code. The tuple will always grow or shrink + at the end. Think of this as destroying the old tuple and creating a new one, + only more efficiently. Returns ``0`` on success. Client code should never + assume that the resulting value of ``*p`` will be the same as before calling + this function. If the object referenced by ``*p`` is replaced, the original + ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and + raises :exc:`MemoryError` or :exc:`SystemError`. diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst new file mode 100644 index 0000000..01a94bb --- /dev/null +++ b/Doc/c-api/type.rst @@ -0,0 +1,68 @@ +.. highlightlang:: c + +.. _typeobjects: + +Type Objects +------------ + +.. index:: object: type + + +.. ctype:: PyTypeObject + + The C structure of the objects used to describe built-in types. + + +.. cvar:: PyObject* PyType_Type + + .. index:: single: TypeType (in module types) + + This is the type object for type objects; it is the same object as ``type`` and + ``types.TypeType`` in the Python layer. + + +.. cfunction:: int PyType_Check(PyObject *o) + + Return true if the object *o* is a type object, including instances of types + derived from the standard type object. Return false in all other cases. + + +.. cfunction:: int PyType_CheckExact(PyObject *o) + + Return true if the object *o* is a type object, but not a subtype of the + standard type object. Return false in all other cases. + + +.. cfunction:: int PyType_HasFeature(PyObject *o, int feature) + + Return true if the type object *o* sets the feature *feature*. Type features + are denoted by single bit flags. + + +.. cfunction:: int PyType_IS_GC(PyObject *o) + + Return true if the type object includes support for the cycle detector; this + tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. + + +.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) + + Return true if *a* is a subtype of *b*. + + +.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + XXX: Document. + + +.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) + + XXX: Document. + + +.. cfunction:: int PyType_Ready(PyTypeObject *type) + + Finalize a type object. This should be called on all type objects to finish + their initialization. This function is responsible for adding inherited slots + from a type's base class. Return ``0`` on success, or return ``-1`` and sets an + exception on error. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst new file mode 100644 index 0000000..b3433e1 --- /dev/null +++ b/Doc/c-api/typeobj.rst @@ -0,0 +1,1391 @@ +.. highlightlang:: c + +.. _type-structs: + +Type Objects +============ + +Perhaps one of the most important structures of the Python object system is the +structure that defines a new type: the :ctype:`PyTypeObject` structure. Type +objects can be handled using any of the :cfunc:`PyObject_\*` or +:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most +Python applications. These objects are fundamental to how objects behave, so +they are very important to the interpreter itself and to any extension module +that implements new types. + +Type objects are fairly large compared to most of the standard types. The reason +for the size is that each type object stores a large number of values, mostly C +function pointers, each of which implements a small part of the type's +functionality. The fields of the type object are examined in detail in this +section. The fields will be described in the order in which they occur in the +structure. + +Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, +intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, +freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, +cmpfunc, reprfunc, hashfunc + +The structure definition for :ctype:`PyTypeObject` can be found in +:file:`Include/object.h`. For convenience of reference, this repeats the +definition found there: + +.. literalinclude:: ../includes/typestruct.h + + +The type object structure extends the :ctype:`PyVarObject` structure. The +:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, +usually called from a class statement). Note that :cdata:`PyType_Type` (the +metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e. +type objects) *must* have the :attr:`ob_size` field. + + +.. cmember:: PyObject* PyObject._ob_next + PyObject* PyObject._ob_prev + + These fields are only present when the macro ``Py_TRACE_REFS`` is defined. + Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT`` + macro. For statically allocated objects, these fields always remain *NULL*. + For dynamically allocated objects, these two fields are used to link the object + into a doubly-linked list of *all* live objects on the heap. This could be used + for various debugging purposes; currently the only use is to print the objects + that are still alive at the end of a run when the environment variable + :envvar:`PYTHONDUMPREFS` is set. + + These fields are not inherited by subtypes. + + +.. cmember:: Py_ssize_t PyObject.ob_refcnt + + This is the type object's reference count, initialized to ``1`` by the + ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, + the type's instances (objects whose :attr:`ob_type` points back to the type) do + *not* count as references. But for dynamically allocated type objects, the + instances *do* count as references. + + This field is not inherited by subtypes. + + +.. cmember:: PyTypeObject* PyObject.ob_type + + This is the type's type, in other words its metatype. It is initialized by the + argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be + ``&PyType_Type``. However, for dynamically loadable extension modules that must + be usable on Windows (at least), the compiler complains that this is not a valid + initializer. Therefore, the convention is to pass *NULL* to the + ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the + start of the module's initialization function, before doing anything else. This + is typically done like this:: + + Foo_Type.ob_type = &PyType_Type; + + This should be done before any instances of the type are created. + :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, + initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1 + and later it is initialized to the :attr:`ob_type` field of the base class. + :cfunc:`PyType_Ready` will not change this field if it is non-zero. + + In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3 + and beyond, it is inherited by subtypes. + + +.. cmember:: Py_ssize_t PyVarObject.ob_size + + For statically allocated type objects, this should be initialized to zero. For + dynamically allocated type objects, this field has a special internal meaning. + + This field is not inherited by subtypes. + + +.. cmember:: char* PyTypeObject.tp_name + + Pointer to a NUL-terminated string containing the name of the type. For types + that are accessible as module globals, the string should be the full module + name, followed by a dot, followed by the type name; for built-in types, it + should be just the type name. If the module is a submodule of a package, the + full package name is part of the full module name. For example, a type named + :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P` + should have the :attr:`tp_name` initializer ``"P.Q.M.T"``. + + For dynamically allocated type objects, this should just be the type name, and + the module name explicitly stored in the type dict as the value for key + ``'__module__'``. + + For statically allocated type objects, the tp_name field should contain a dot. + Everything before the last dot is made accessible as the :attr:`__module__` + attribute, and everything after the last dot is made accessible as the + :attr:`__name__` attribute. + + If no dot is present, the entire :attr:`tp_name` field is made accessible as the + :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined + (unless explicitly set in the dictionary, as explained above). This means your + type will be impossible to pickle. + + This field is not inherited by subtypes. + + +.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize + Py_ssize_t PyTypeObject.tp_itemsize + + These fields allow calculating the size in bytes of instances of the type. + + There are two kinds of types: types with fixed-length instances have a zero + :attr:`tp_itemsize` field, types with variable-length instances have a non-zero + :attr:`tp_itemsize` field. For a type with fixed-length instances, all + instances have the same size, given in :attr:`tp_basicsize`. + + For a type with variable-length instances, the instances must have an + :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N + times :attr:`tp_itemsize`, where N is the "length" of the object. The value of + N is typically stored in the instance's :attr:`ob_size` field. There are + exceptions: for example, long ints use a negative :attr:`ob_size` to indicate a + negative number, and N is ``abs(ob_size)`` there. Also, the presence of an + :attr:`ob_size` field in the instance layout doesn't mean that the instance + structure is variable-length (for example, the structure for the list type has + fixed-length instances, yet those instances have a meaningful :attr:`ob_size` + field). + + The basic size includes the fields in the instance declared by the macro + :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to + declare the instance struct) and this in turn includes the :attr:`_ob_prev` and + :attr:`_ob_next` fields if they are present. This means that the only correct + way to get an initializer for the :attr:`tp_basicsize` is to use the + ``sizeof`` operator on the struct used to declare the instance layout. + The basic size does not include the GC header size (this is new in Python 2.2; + in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`). + + These fields are inherited separately by subtypes. If the base type has a + non-zero :attr:`tp_itemsize`, it is generally not safe to set + :attr:`tp_itemsize` to a different non-zero value in a subtype (though this + depends on the implementation of the base type). + + A note about alignment: if the variable items require a particular alignment, + this should be taken care of by the value of :attr:`tp_basicsize`. Example: + suppose a type implements an array of ``double``. :attr:`tp_itemsize` is + ``sizeof(double)``. It is the programmer's responsibility that + :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the + alignment requirement for ``double``). + + +.. cmember:: destructor PyTypeObject.tp_dealloc + + A pointer to the instance destructor function. This function must be defined + unless the type guarantees that its instances will never be deallocated (as is + the case for the singletons ``None`` and ``Ellipsis``). + + The destructor function is called by the :cfunc:`Py_DECREF` and + :cfunc:`Py_XDECREF` macros when the new reference count is zero. At this point, + the instance is still in existence, but there are no references to it. The + destructor function should free all references which the instance owns, free all + memory buffers owned by the instance (using the freeing function corresponding + to the allocation function used to allocate the buffer), and finally (as its + last action) call the type's :attr:`tp_free` function. If the type is not + subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is + permissible to call the object deallocator directly instead of via + :attr:`tp_free`. The object deallocator should be the one used to allocate the + instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated + using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or + :cfunc:`PyObject_GC_Del` if the instance was allocated using + :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`. + + This field is inherited by subtypes. + + +.. cmember:: printfunc PyTypeObject.tp_print + + An optional pointer to the instance print function. + + The print function is only called when the instance is printed to a *real* file; + when it is printed to a pseudo-file (like a :class:`StringIO` instance), the + instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to + a string. These are also called when the type's :attr:`tp_print` field is + *NULL*. A type should never implement :attr:`tp_print` in a way that produces + different output than :attr:`tp_repr` or :attr:`tp_str` would. + + The print function is called with the same signature as :cfunc:`PyObject_Print`: + ``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is + the instance to be printed. The *file* argument is the stdio file to which it + is to be printed. The *flags* argument is composed of flag bits. The only flag + bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW` + flag bit is set, the instance should be printed the same way as :attr:`tp_str` + would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance + should be printed the same was as :attr:`tp_repr` would format it. It should + return ``-1`` and set an exception condition when an error occurred during the + comparison. + + It is possible that the :attr:`tp_print` field will be deprecated. In any case, + it is recommended not to define :attr:`tp_print`, but instead to rely on + :attr:`tp_repr` and :attr:`tp_str` for printing. + + This field is inherited by subtypes. + + +.. cmember:: getattrfunc PyTypeObject.tp_getattr + + An optional pointer to the get-attribute-string function. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :attr:`tp_getattro` function, but taking a C string + instead of a Python string object to give the attribute name. The signature is + the same as for :cfunc:`PyObject_GetAttrString`. + + This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype + inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when + the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. + + +.. cmember:: setattrfunc PyTypeObject.tp_setattr + + An optional pointer to the set-attribute-string function. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :attr:`tp_setattro` function, but taking a C string + instead of a Python string object to give the attribute name. The signature is + the same as for :cfunc:`PyObject_SetAttrString`. + + This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype + inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when + the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. + + +.. cmember:: cmpfunc PyTypeObject.tp_compare + + An optional pointer to the three-way comparison function. + + The signature is the same as for :cfunc:`PyObject_Compare`. The function should + return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to + *other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and + set an exception condition when an error occurred during the comparison. + + This field is inherited by subtypes together with :attr:`tp_richcompare` and + :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. + + +.. cmember:: reprfunc PyTypeObject.tp_repr + + .. index:: builtin: repr + + An optional pointer to a function that implements the built-in function + :func:`repr`. + + The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string + or a Unicode object. Ideally, this function should return a string that, when + passed to :func:`eval`, given a suitable environment, returns an object with the + same value. If this is not feasible, it should return a string starting with + ``'<'`` and ending with ``'>'`` from which both the type and the value of the + object can be deduced. + + When this field is not set, a string of the form ``<%s object at %p>`` is + returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's + memory address. + + This field is inherited by subtypes. + +.. cmember:: PyNumberMethods* tp_as_number + + Pointer to an additional structure that contains fields relevant only to + objects which implement the number protocol. These fields are documented in + :ref:`number-structs`. + + The :attr:`tp_as_number` field is not inherited, but the contained fields are + inherited individually. + + +.. cmember:: PySequenceMethods* tp_as_sequence + + Pointer to an additional structure that contains fields relevant only to + objects which implement the sequence protocol. These fields are documented + in :ref:`sequence-structs`. + + The :attr:`tp_as_sequence` field is not inherited, but the contained fields + are inherited individually. + + +.. cmember:: PyMappingMethods* tp_as_mapping + + Pointer to an additional structure that contains fields relevant only to + objects which implement the mapping protocol. These fields are documented in + :ref:`mapping-structs`. + + The :attr:`tp_as_mapping` field is not inherited, but the contained fields + are inherited individually. + + +.. cmember:: hashfunc PyTypeObject.tp_hash + + .. index:: builtin: hash + + An optional pointer to a function that implements the built-in function + :func:`hash`. + + The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C + long. The value ``-1`` should not be returned as a normal return value; when an + error occurs during the computation of the hash value, the function should set + an exception and return ``-1``. + + When this field is not set, two possibilities exist: if the :attr:`tp_compare` + and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on + the object's address is returned; otherwise, a :exc:`TypeError` is raised. + + This field is inherited by subtypes together with :attr:`tp_richcompare` and + :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*. + + +.. cmember:: ternaryfunc PyTypeObject.tp_call + + An optional pointer to a function that implements calling the object. This + should be *NULL* if the object is not callable. The signature is the same as + for :cfunc:`PyObject_Call`. + + This field is inherited by subtypes. + + +.. cmember:: reprfunc PyTypeObject.tp_str + + An optional pointer to a function that implements the built-in operation + :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the + constructor for that type. This constructor calls :cfunc:`PyObject_Str` to do + the actual work, and :cfunc:`PyObject_Str` will call this handler.) + + The signature is the same as for :cfunc:`PyObject_Str`; it must return a string + or a Unicode object. This function should return a "friendly" string + representation of the object, as this is the representation that will be used, + among other things, by the :func:`print` function. + + When this field is not set, :cfunc:`PyObject_Repr` is called to return a string + representation. + + This field is inherited by subtypes. + + +.. cmember:: getattrofunc PyTypeObject.tp_getattro + + An optional pointer to the get-attribute function. + + The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually + convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which + implements the normal way of looking for object attributes. + + This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype + inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when + the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. + + +.. cmember:: setattrofunc PyTypeObject.tp_setattro + + An optional pointer to the set-attribute function. + + The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually + convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which + implements the normal way of setting object attributes. + + This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype + inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when + the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. + + +.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer + + Pointer to an additional structure that contains fields relevant only to objects + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. + + The :attr:`tp_as_buffer` field is not inherited, but the contained fields are + inherited individually. + + +.. cmember:: long PyTypeObject.tp_flags + + This field is a bit mask of various flags. Some flags indicate variant + semantics for certain situations; others are used to indicate that certain + fields in the type object (or in the extension structures referenced via + :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and + :attr:`tp_as_buffer`) that were historically not always present are valid; if + such a flag bit is clear, the type fields it guards must not be accessed and + must be considered to have a zero or *NULL* value instead. + + Inheritance of this field is complicated. Most flag bits are inherited + individually, i.e. if the base type has a flag bit set, the subtype inherits + this flag bit. The flag bits that pertain to extension structures are strictly + inherited if the extension structure is inherited, i.e. the base type's value of + the flag bit is copied into the subtype together with a pointer to the extension + structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with + the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the + :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the + :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as + indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL* + values. + + The following bit masks are currently defined; these can be ORed together using + the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro + :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and + checks whether ``tp->tp_flags & f`` is non-zero. + + + .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER + + If this bit is set, the :ctype:`PyBufferProcs` struct referenced by + :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field. + + + .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN + + If this bit is set, the :ctype:`PySequenceMethods` struct referenced by + :attr:`tp_as_sequence` has the :attr:`sq_contains` field. + + + .. data:: Py_TPFLAGS_GC + + This bit is obsolete. The bit it used to name is no longer in use. The symbol + is now defined as zero. + + + .. data:: Py_TPFLAGS_HAVE_INPLACEOPS + + If this bit is set, the :ctype:`PySequenceMethods` struct referenced by + :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by + :attr:`tp_as_number` contain the fields for in-place operators. In particular, + this means that the :ctype:`PyNumberMethods` structure has the fields + :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`, + :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`, + :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`, + :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`, + :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the + :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and + :attr:`sq_inplace_repeat`. + + + .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE + + If this bit is set, the type object has the :attr:`tp_richcompare` field, as + well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields. + + + .. data:: Py_TPFLAGS_HAVE_WEAKREFS + + If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances + of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field + has a value greater than zero. + + + .. data:: Py_TPFLAGS_HAVE_ITER + + If this bit is set, the type object has the :attr:`tp_iter` and + :attr:`tp_iternext` fields. + + + .. data:: Py_TPFLAGS_HAVE_CLASS + + If this bit is set, the type object has several new fields defined starting in + Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`, + :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`, + :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`, + :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`, + :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`. + + + .. data:: Py_TPFLAGS_HEAPTYPE + + This bit is set when the type object itself is allocated on the heap. In this + case, the :attr:`ob_type` field of its instances is considered a reference to + the type, and the type object is INCREF'ed when a new instance is created, and + DECREF'ed when an instance is destroyed (this does not apply to instances of + subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or + DECREF'ed). + + + .. data:: Py_TPFLAGS_BASETYPE + + This bit is set when the type can be used as the base type of another type. If + this bit is clear, the type cannot be subtyped (similar to a "final" class in + Java). + + + .. data:: Py_TPFLAGS_READY + + This bit is set when the type object has been fully initialized by + :cfunc:`PyType_Ready`. + + + .. data:: Py_TPFLAGS_READYING + + This bit is set while :cfunc:`PyType_Ready` is in the process of initializing + the type object. + + + .. data:: Py_TPFLAGS_HAVE_GC + + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :cfunc:`PyObject_GC_New` and + destroyed using :cfunc:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but + :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. + + + .. data:: Py_TPFLAGS_DEFAULT + + This is a bitmask of all the bits that pertain to the existence of certain + fields in the type object and its extension structures. Currently, it includes + the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`, + :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`, + :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`, + :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`. + + +.. cmember:: char* PyTypeObject.tp_doc + + An optional pointer to a NUL-terminated C string giving the docstring for this + type object. This is exposed as the :attr:`__doc__` attribute on the type and + instances of the type. + + This field is *not* inherited by subtypes. + +The following three fields only exist if the +:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set. + + +.. cmember:: traverseproc PyTypeObject.tp_traverse + + An optional pointer to a traversal function for the garbage collector. This is + only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information + about Python's garbage collection scheme can be found in section + :ref:`supporting-cycle-detection`. + + The :attr:`tp_traverse` pointer is used by the garbage collector to detect + reference cycles. A typical implementation of a :attr:`tp_traverse` function + simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python + objects. For exampe, this is function :cfunc:`local_traverse` from the + :mod:`thread` extension module:: + + static int + local_traverse(localobject *self, visitproc visit, void *arg) + { + Py_VISIT(self->args); + Py_VISIT(self->kw); + Py_VISIT(self->dict); + return 0; + } + + Note that :cfunc:`Py_VISIT` is called only on those members that can participate + in reference cycles. Although there is also a ``self->key`` member, it can only + be *NULL* or a Python string and therefore cannot be part of a reference cycle. + + On the other hand, even if you know a member can never be part of a cycle, as a + debugging aid you may want to visit it anyway just so the :mod:`gc` module's + :func:`get_referents` function will include it. + + Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to + :cfunc:`local_traverse` to have these specific names; don't name them just + anything. + + This field is inherited by subtypes together with :attr:`tp_clear` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and + :attr:`tp_clear` are all inherited from the base type if they are all zero in + the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag + bit set. + + +.. cmember:: inquiry PyTypeObject.tp_clear + + An optional pointer to a clear function for the garbage collector. This is only + used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. + + The :attr:`tp_clear` member function is used to break reference cycles in cyclic + garbage detected by the garbage collector. Taken together, all :attr:`tp_clear` + functions in the system must combine to break all reference cycles. This is + subtle, and if in any doubt supply a :attr:`tp_clear` function. For example, + the tuple type does not implement a :attr:`tp_clear` function, because it's + possible to prove that no reference cycle can be composed entirely of tuples. + Therefore the :attr:`tp_clear` functions of other types must be sufficient to + break any cycle containing a tuple. This isn't immediately obvious, and there's + rarely a good reason to avoid implementing :attr:`tp_clear`. + + Implementations of :attr:`tp_clear` should drop the instance's references to + those of its members that may be Python objects, and set its pointers to those + members to *NULL*, as in the following example:: + + static int + local_clear(localobject *self) + { + Py_CLEAR(self->key); + Py_CLEAR(self->args); + Py_CLEAR(self->kw); + Py_CLEAR(self->dict); + return 0; + } + + The :cfunc:`Py_CLEAR` macro should be used, because clearing references is + delicate: the reference to the contained object must not be decremented until + after the pointer to the contained object is set to *NULL*. This is because + decrementing the reference count may cause the contained object to become trash, + triggering a chain of reclamation activity that may include invoking arbitrary + Python code (due to finalizers, or weakref callbacks, associated with the + contained object). If it's possible for such code to reference *self* again, + it's important that the pointer to the contained object be *NULL* at that time, + so that *self* knows the contained object can no longer be used. The + :cfunc:`Py_CLEAR` macro performs the operations in a safe order. + + Because the goal of :attr:`tp_clear` functions is to break reference cycles, + it's not necessary to clear contained objects like Python strings or Python + integers, which can't participate in reference cycles. On the other hand, it may + be convenient to clear all contained Python objects, and write the type's + :attr:`tp_dealloc` function to invoke :attr:`tp_clear`. + + More information about Python's garbage collection scheme can be found in + section :ref:`supporting-cycle-detection`. + + This field is inherited by subtypes together with :attr:`tp_traverse` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and + :attr:`tp_clear` are all inherited from the base type if they are all zero in + the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag + bit set. + + +.. cmember:: richcmpfunc PyTypeObject.tp_richcompare + + An optional pointer to the rich comparison function. + + The signature is the same as for :cfunc:`PyObject_RichCompare`. The function + should return the result of the comparison (usually ``Py_True`` or + ``Py_False``). If the comparison is undefined, it must return + ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and set + an exception condition. + + This field is inherited by subtypes together with :attr:`tp_compare` and + :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. + + The following constants are defined to be used as the third argument for + :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`: + + +----------------+------------+ + | Constant | Comparison | + +================+============+ + | :const:`Py_LT` | ``<`` | + +----------------+------------+ + | :const:`Py_LE` | ``<=`` | + +----------------+------------+ + | :const:`Py_EQ` | ``==`` | + +----------------+------------+ + | :const:`Py_NE` | ``!=`` | + +----------------+------------+ + | :const:`Py_GT` | ``>`` | + +----------------+------------+ + | :const:`Py_GE` | ``>=`` | + +----------------+------------+ + +The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is +set. + + +.. cmember:: long PyTypeObject.tp_weaklistoffset + + If the instances of this type are weakly referenceable, this field is greater + than zero and contains the offset in the instance structure of the weak + reference list head (ignoring the GC header, if present); this offset is used by + :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The + instance structure needs to include a field of type :ctype:`PyObject\*` which is + initialized to *NULL*. + + Do not confuse this field with :attr:`tp_weaklist`; that is the list head for + weak references to the type object itself. + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype uses a different weak + reference list head than the base type. Since the list head is always found via + :attr:`tp_weaklistoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`__slots__` declaration, + and none of its base types are weakly referenceable, the type is made weakly + referenceable by adding a weak reference list head slot to the instance layout + and setting the :attr:`tp_weaklistoffset` of that slot's offset. + + When a type's :attr:`__slots__` declaration contains a slot named + :attr:`__weakref__`, that slot becomes the weak reference list head for + instances of the type, and the slot's offset is stored in the type's + :attr:`tp_weaklistoffset`. + + When a type's :attr:`__slots__` declaration does not contain a slot named + :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its + base type. + +The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is +set. + + +.. cmember:: getiterfunc PyTypeObject.tp_iter + + An optional pointer to a function that returns an iterator for the object. Its + presence normally signals that the instances of this type are iterable (although + sequences may be iterable without this function, and classic instances always + have this function, even if they don't define an :meth:`__iter__` method). + + This function has the same signature as :cfunc:`PyObject_GetIter`. + + This field is inherited by subtypes. + + +.. cmember:: iternextfunc PyTypeObject.tp_iternext + + An optional pointer to a function that returns the next item in an iterator, or + raises :exc:`StopIteration` when the iterator is exhausted. Its presence + normally signals that the instances of this type are iterators (although classic + instances always have this function, even if they don't define a + :meth:`__next__` method). + + Iterator types should also define the :attr:`tp_iter` function, and that + function should return the iterator instance itself (not a new iterator + instance). + + This function has the same signature as :cfunc:`PyIter_Next`. + + This field is inherited by subtypes. + +The next fields, up to and including :attr:`tp_weaklist`, only exist if the +:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set. + + +.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods + + An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef` + structures, declaring regular methods of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a method descriptor. + + This field is not inherited by subtypes (methods are inherited through a + different mechanism). + + +.. cmember:: struct PyMemberDef* PyTypeObject.tp_members + + An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef` + structures, declaring regular data members (fields or slots) of instances of + this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a member descriptor. + + This field is not inherited by subtypes (members are inherited through a + different mechanism). + + +.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset + + An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef` + structures, declaring computed attributes of instances of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a getset descriptor. + + This field is not inherited by subtypes (computed attributes are inherited + through a different mechanism). + + Docs for PyGetSetDef (XXX belong elsewhere):: + + typedef PyObject *(*getter)(PyObject *, void *); + typedef int (*setter)(PyObject *, PyObject *, void *); + + typedef struct PyGetSetDef { + char *name; /* attribute name */ + getter get; /* C function to get the attribute */ + setter set; /* C function to set the attribute */ + char *doc; /* optional doc string */ + void *closure; /* optional additional data for getter and setter */ + } PyGetSetDef; + + +.. cmember:: PyTypeObject* PyTypeObject.tp_base + + An optional pointer to a base type from which type properties are inherited. At + this level, only single inheritance is supported; multiple inheritance require + dynamically creating a type object by calling the metatype. + + This field is not inherited by subtypes (obviously), but it defaults to + ``&PyBaseObject_Type`` (which to Python programmers is known as the type + :class:`object`). + + +.. cmember:: PyObject* PyTypeObject.tp_dict + + The type's dictionary is stored here by :cfunc:`PyType_Ready`. + + This field should normally be initialized to *NULL* before PyType_Ready is + called; it may also be initialized to a dictionary containing initial attributes + for the type. Once :cfunc:`PyType_Ready` has initialized the type, extra + attributes for the type may be added to this dictionary only if they don't + correspond to overloaded operations (like :meth:`__add__`). + + This field is not inherited by subtypes (though the attributes defined in here + are inherited through a different mechanism). + + +.. cmember:: descrgetfunc PyTypeObject.tp_descr_get + + An optional pointer to a "descriptor get" function. + + The function signature is :: + + PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); + + XXX explain. + + This field is inherited by subtypes. + + +.. cmember:: descrsetfunc PyTypeObject.tp_descr_set + + An optional pointer to a "descriptor set" function. + + The function signature is :: + + int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); + + This field is inherited by subtypes. + + XXX explain. + + +.. cmember:: long PyTypeObject.tp_dictoffset + + If the instances of this type have a dictionary containing instance variables, + this field is non-zero and contains the offset in the instances of the type of + the instance variable dictionary; this offset is used by + :cfunc:`PyObject_GenericGetAttr`. + + Do not confuse this field with :attr:`tp_dict`; that is the dictionary for + attributes of the type object itself. + + If the value of this field is greater than zero, it specifies the offset from + the start of the instance structure. If the value is less than zero, it + specifies the offset from the *end* of the instance structure. A negative + offset is more expensive to use, and should only be used when the instance + structure contains a variable-length part. This is used for example to add an + instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note + that the :attr:`tp_basicsize` field should account for the dictionary added to + the end in that case, even though the dictionary is not included in the basic + object layout. On a system with a pointer size of 4 bytes, + :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is + at the very end of the structure. + + The real dictionary offset in an instance can be computed from a negative + :attr:`tp_dictoffset` as follows:: + + dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset + if dictoffset is not aligned on sizeof(void*): + round up to sizeof(void*) + + where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are + taken from the type object, and :attr:`ob_size` is taken from the instance. The + absolute value is taken because long ints use the sign of :attr:`ob_size` to + store the sign of the number. (There's never a need to do this calculation + yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.) + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype instances store the + dictionary at a difference offset than the base type. Since the dictionary is + always found via :attr:`tp_dictoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`__slots__` declaration, + and none of its base types has an instance variable dictionary, a dictionary + slot is added to the instance layout and the :attr:`tp_dictoffset` is set to + that slot's offset. + + When a type defined by a class statement has a :attr:`__slots__` declaration, + the type inherits its :attr:`tp_dictoffset` from its base type. + + (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does + not have the expected effect, it just causes confusion. Maybe this should be + added as a feature just like :attr:`__weakref__` though.) + + +.. cmember:: initproc PyTypeObject.tp_init + + An optional pointer to an instance initialization function. + + This function corresponds to the :meth:`__init__` method of classes. Like + :meth:`__init__`, it is possible to create an instance without calling + :meth:`__init__`, and it is possible to reinitialize an instance by calling its + :meth:`__init__` method again. + + The function signature is :: + + int tp_init(PyObject *self, PyObject *args, PyObject *kwds) + + The self argument is the instance to be initialized; the *args* and *kwds* + arguments represent positional and keyword arguments of the call to + :meth:`__init__`. + + The :attr:`tp_init` function, if not *NULL*, is called when an instance is + created normally by calling its type, after the type's :attr:`tp_new` function + has returned an instance of the type. If the :attr:`tp_new` function returns an + instance of some other type that is not a subtype of the original type, no + :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a + subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION + NOTE: described here is what is implemented in Python 2.2.1 and later. In + Python 2.2, the :attr:`tp_init` of the type of the object returned by + :attr:`tp_new` was always called, if not *NULL*.) + + This field is inherited by subtypes. + + +.. cmember:: allocfunc PyTypeObject.tp_alloc + + An optional pointer to an instance allocation function. + + The function signature is :: + + PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) + + The purpose of this function is to separate memory allocation from memory + initialization. It should return a pointer to a block of memory of adequate + length for the instance, suitably aligned, and initialized to zeros, but with + :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If + the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field + should be initialized to *nitems* and the length of the allocated memory block + should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of + ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block + should be :attr:`tp_basicsize`. + + Do not use this function to do any other instance initialization, not even to + allocate additional memory; that should be done by :attr:`tp_new`. + + This field is inherited by static subtypes, but not by dynamic subtypes + (subtypes created by a class statement); in the latter, this field is always set + to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy. + That is also the recommended value for statically defined types. + + +.. cmember:: newfunc PyTypeObject.tp_new + + An optional pointer to an instance creation function. + + If this function is *NULL* for a particular type, that type cannot be called to + create new instances; presumably there is some other way to create instances, + like a factory function. + + The function signature is :: + + PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds) + + The subtype argument is the type of the object being created; the *args* and + *kwds* arguments represent positional and keyword arguments of the call to the + type. Note that subtype doesn't have to equal the type whose :attr:`tp_new` + function is called; it may be a subtype of that type (but not an unrelated + type). + + The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)`` + to allocate space for the object, and then do only as much further + initialization as is absolutely necessary. Initialization that can safely be + ignored or repeated should be placed in the :attr:`tp_init` handler. A good + rule of thumb is that for immutable types, all initialization should take place + in :attr:`tp_new`, while for mutable types, most initialization should be + deferred to :attr:`tp_init`. + + This field is inherited by subtypes, except it is not inherited by static types + whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception + is a precaution so that old extension types don't become callable simply by + being linked with Python 2.2. + + +.. cmember:: destructor PyTypeObject.tp_free + + An optional pointer to an instance deallocation function. + + The signature of this function has changed slightly: in Python 2.2 and 2.2.1, + its signature is :ctype:`destructor`:: + + void tp_free(PyObject *) + + In Python 2.3 and beyond, its signature is :ctype:`freefunc`:: + + void tp_free(void *) + + The only initializer that is compatible with both versions is ``PyObject_Free``, + whose definition has suitably adapted in Python 2.3. + + This field is inherited by static subtypes, but not by dynamic subtypes + (subtypes created by a class statement); in the latter, this field is set to a + deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the + :const:`Py_TPFLAGS_HAVE_GC` flag bit. + + +.. cmember:: inquiry PyTypeObject.tp_is_gc + + An optional pointer to a function called by the garbage collector. + + The garbage collector needs to know whether a particular object is collectible + or not. Normally, it is sufficient to look at the object's type's + :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But + some types have a mixture of statically and dynamically allocated instances, and + the statically allocated instances are not collectible. Such types should + define this function; it should return ``1`` for a collectible instance, and + ``0`` for a non-collectible instance. The signature is :: + + int tp_is_gc(PyObject *self) + + (The only example of this are types themselves. The metatype, + :cdata:`PyType_Type`, defines this function to distinguish between statically + and dynamically allocated types.) + + This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not + inherited. It is inherited in 2.2.1 and later versions.) + + +.. cmember:: PyObject* PyTypeObject.tp_bases + + Tuple of base types. + + This is set for types created by a class statement. It should be *NULL* for + statically defined types. + + This field is not inherited. + + +.. cmember:: PyObject* PyTypeObject.tp_mro + + Tuple containing the expanded set of base types, starting with the type itself + and ending with :class:`object`, in Method Resolution Order. + + This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`. + + +.. cmember:: PyObject* PyTypeObject.tp_cache + + Unused. Not inherited. Internal use only. + + +.. cmember:: PyObject* PyTypeObject.tp_subclasses + + List of weak references to subclasses. Not inherited. Internal use only. + + +.. cmember:: PyObject* PyTypeObject.tp_weaklist + + Weak reference list head, for weak references to this type object. Not + inherited. Internal use only. + +The remaining fields are only defined if the feature test macro +:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are +documented here for completeness. None of these fields are inherited by +subtypes. + + +.. cmember:: Py_ssize_t PyTypeObject.tp_allocs + + Number of allocations. + + +.. cmember:: Py_ssize_t PyTypeObject.tp_frees + + Number of frees. + + +.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc + + Maximum simultaneously allocated objects. + + +.. cmember:: PyTypeObject* PyTypeObject.tp_next + + Pointer to the next type object with a non-zero :attr:`tp_allocs` field. + +Also, note that, in a garbage collected Python, tp_dealloc may be called from +any Python thread, not just the thread which created the object (if the object +becomes part of a refcount cycle, that cycle might be collected by a garbage +collection on any thread). This is not a problem for Python API calls, since +the thread on which tp_dealloc is called will own the Global Interpreter Lock +(GIL). However, if the object being destroyed in turn destroys objects from some +other C or C++ library, care should be taken to ensure that destroying those +objects on the thread which called tp_dealloc will not violate any assumptions +of the library. + + +.. _number-structs: + +Number Object Structures +======================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. ctype:: PyNumberMethods + + This structure holds pointers to the functions which an object uses to + implement the number protocol. Each function is used by the function of + similar name documented in the :ref:`number` section. + + Here is the structure definition:: + + typedef struct { + binaryfunc nb_add; + binaryfunc nb_subtract; + binaryfunc nb_multiply; + binaryfunc nb_remainder; + binaryfunc nb_divmod; + ternaryfunc nb_power; + unaryfunc nb_negative; + unaryfunc nb_positive; + unaryfunc nb_absolute; + inquiry nb_bool; + unaryfunc nb_invert; + binaryfunc nb_lshift; + binaryfunc nb_rshift; + binaryfunc nb_and; + binaryfunc nb_xor; + binaryfunc nb_or; + int nb_reserved; /* unused, must be zero */ + unaryfunc nb_int; + unaryfunc nb_long; + unaryfunc nb_float; + + unaryfunc nb_oct; /* not used anymore, must be zero */ + unaryfunc nb_hex; /* not used anymore, must be zero */ + + binaryfunc nb_inplace_add; + binaryfunc nb_inplace_subtract; + binaryfunc nb_inplace_multiply; + binaryfunc nb_inplace_remainder; + ternaryfunc nb_inplace_power; + binaryfunc nb_inplace_lshift; + binaryfunc nb_inplace_rshift; + binaryfunc nb_inplace_and; + binaryfunc nb_inplace_xor; + binaryfunc nb_inplace_or; + + binaryfunc nb_floor_divide; + binaryfunc nb_true_divide; + binaryfunc nb_inplace_floor_divide; + binaryfunc nb_inplace_true_divide; + + unaryfunc nb_index; + } PyNumberMethods; + + .. note:: + + Binary and ternary functions must check the type of all their operands, + and implement the necessary conversions (at least one of the operands is + an instance of the defined type). If the operation is not defined for the + given operands, binary and ternary functions must return + ``Py_NotImplemented``, if another error occurred they must return ``NULL`` + and set an exception. + + +.. _mapping-structs: + +Mapping Object Structures +========================= + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. ctype:: PyMappingMethods + + This structure holds pointers to the functions which an object uses to + implement the mapping protocol. It has three members: + +.. cmember:: lenfunc PyMappingMethods.mp_length + + This function is used by :cfunc:`PyMapping_Length` and + :cfunc:`PyObject_Size`, and has the same signature. This slot may be set to + *NULL* if the object has no defined length. + +.. cmember:: binaryfunc PyMappingMethods.mp_subscript + + This function is used by :cfunc:`PyObject_GetItem` and has the same + signature. This slot must be filled for the :cfunc:`PyMapping_Check` + function to return ``1``, it can be *NULL* otherwise. + +.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript + + This function is used by :cfunc:`PyObject_SetItem` and has the same + signature. If this slot is *NULL*, the object does not support item + assignment. + + +.. _sequence-structs: + +Sequence Object Structures +========================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. ctype:: PySequenceMethods + + This structure holds pointers to the functions which an object uses to + implement the sequence protocol. + +.. cmember:: lenfunc PySequenceMethods.sq_length + + This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`, + and has the same signature. + +.. cmember:: binaryfunc PySequenceMethods.sq_concat + + This function is used by :cfunc:`PySequence_Concat` and has the same + signature. It is also used by the ``+`` operator, after trying the numeric + addition via the :attr:`tp_as_number.nb_add` slot. + +.. cmember:: ssizeargfunc PySequenceMethods.sq_repeat + + This function is used by :cfunc:`PySequence_Repeat` and has the same + signature. It is also used by the ``*`` operator, after trying numeric + multiplication via the :attr:`tp_as_number.nb_mul` slot. + +.. cmember:: ssizeargfunc PySequenceMethods.sq_item + + This function is used by :cfunc:`PySequence_GetItem` and has the same + signature. This slot must be filled for the :cfunc:`PySequence_Check` + function to return ``1``, it can be *NULL* otherwise. + + Negative indexes are handled as follows: if the :attr:`sq_length` slot is + filled, it is called and the sequence length is used to compute a positive + index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, + the index is passed as is to the function. + +.. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item + + This function is used by :cfunc:`PySequence_SetItem` and has the same + signature. This slot may be left to *NULL* if the object does not support + item assignment. + +.. cmember:: objobjproc PySequenceMethods.sq_contains + + This function may be used by :cfunc:`PySequence_Contains` and has the same + signature. This slot may be left to *NULL*, in this case + :cfunc:`PySequence_Contains` simply traverses the sequence until it finds a + match. + +.. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat + + This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same + signature. It should modify its first operand, and return it. + +.. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat + + This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same + signature. It should modify its first operand, and return it. + +.. XXX need to explain precedence between mapping and sequence +.. XXX explains when to implement the sq_inplace_* slots + + +.. _buffer-structs: + +Buffer Object Structures +======================== + +.. sectionauthor:: Greg J. Stein <greg@lyra.org> + + +The buffer interface exports a model where an object can expose its internal +data as a set of chunks of data, where each chunk is specified as a +pointer/length pair. These chunks are called :dfn:`segments` and are presumed +to be non-contiguous in memory. + +If an object does not export the buffer interface, then its :attr:`tp_as_buffer` +member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the +:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure. + +.. note:: + + It is very important that your :ctype:`PyTypeObject` structure uses + :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather + than ``0``. This tells the Python runtime that your :ctype:`PyBufferProcs` + structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python + did not have this member, so a new Python interpreter using an old extension + needs to be able to test for its presence before using it. + + +.. ctype:: PyBufferProcs + + Structure used to hold the function pointers which define an implementation of + the buffer protocol. + + The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`getreadbufferproc`. + If this slot is *NULL*, then the object does not support reading from the + internal data. This is non-sensical, so implementors should fill this in, but + callers should test that the slot contains a non-*NULL* value. + + The next slot is :attr:`bf_getwritebuffer` having type + :ctype:`getwritebufferproc`. This slot may be *NULL* if the object does not + allow writing into its returned buffers. + + The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`. + This slot must not be *NULL* and is used to inform the caller how many segments + the object contains. Simple objects such as :ctype:`PyString_Type` and + :ctype:`PyBuffer_Type` objects contain a single segment. + + .. index:: single: PyType_HasFeature() + + The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`. + This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER` + flag is present in the :attr:`tp_flags` field of the object's + :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it + is present by using the :cfunc:`PyType_HasFeature` function. If the flag is + present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's + contents cannot be used as *8-bit characters*. The slot function may also raise + an error if the object's contents cannot be interpreted as 8-bit characters. + For example, if the object is an array which is configured to hold floating + point values, an exception may be raised if a caller attempts to use + :attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of + exporting the internal buffers as "text" is used to distinguish between objects + that are binary in nature, and those which have character-based content. + + .. note:: + + The current policy seems to state that these characters may be multi-byte + characters. This implies that a buffer size of *N* does not mean there are *N* + characters present. + + +.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER + + Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer` + slot is known. This being set does not indicate that the object supports the + buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*. + + +.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) + + Return a pointer to a readable segment of the buffer in ``*ptrptr``. This + function is allowed to raise an exception, in which case it must return ``-1``. + The *segment* which is specified must be zero or positive, and strictly less + than the number of segments returned by the :attr:`bf_getsegcount` slot + function. On success, it returns the length of the segment, and sets + ``*ptrptr`` to a pointer to that memory. + + +.. ctype:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) + + Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of + that segment as the function return value. The memory buffer must correspond to + buffer segment *segment*. Must return ``-1`` and set an exception on error. + :exc:`TypeError` should be raised if the object only supports read-only buffers, + and :exc:`SystemError` should be raised when *segment* specifies a segment that + doesn't exist. + + .. Why doesn't it raise ValueError for this one? + GJS: because you shouldn't be calling it with an invalid + segment. That indicates a blatant programming error in the C code. + + +.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp) + + Return the number of memory segments which comprise the buffer. If *lenp* is + not *NULL*, the implementation must report the sum of the sizes (in bytes) of + all segments in ``*lenp``. The function cannot fail. + + +.. ctype:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr) + + Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr`` + is set to the memory buffer. Returns ``-1`` on error. diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst new file mode 100644 index 0000000..886ba65 --- /dev/null +++ b/Doc/c-api/unicode.rst @@ -0,0 +1,900 @@ +.. highlightlang:: c + +.. _unicodeobjects: + +Unicode Objects and Codecs +-------------------------- + +.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com> + +Unicode Objects +^^^^^^^^^^^^^^^ + +These are the basic Unicode object types used for the Unicode implementation in +Python: + +.. % --- Unicode Type ------------------------------------------------------- + + +.. ctype:: Py_UNICODE + + This type represents the storage type which is used by Python internally as + basis for holding Unicode ordinals. Python's default builds use a 16-bit type + for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also + possible to build a UCS4 version of Python (most recent Linux distributions come + with UCS4 builds of Python). These builds then use a 32-bit type for + :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms + where :ctype:`wchar_t` is available and compatible with the chosen Python + Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for + :ctype:`wchar_t` to enhance native platform compatibility. On all other + platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned + short` (UCS2) or :ctype:`unsigned long` (UCS4). + +Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep +this in mind when writing extensions or interfaces. + + +.. ctype:: PyUnicodeObject + + This subtype of :ctype:`PyObject` represents a Python Unicode object. + + +.. cvar:: PyTypeObject PyUnicode_Type + + This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It + is exposed to Python code as ``str``. + +The following APIs are really C macros and can be used to do fast checks and to +access internal read-only data of Unicode objects: + + +.. cfunction:: int PyUnicode_Check(PyObject *o) + + Return true if the object *o* is a Unicode object or an instance of a Unicode + subtype. + + +.. cfunction:: int PyUnicode_CheckExact(PyObject *o) + + Return true if the object *o* is a Unicode object, but not an instance of a + subtype. + + +.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o) + + Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not + checked). + + +.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o) + + Return the size of the object's internal buffer in bytes. *o* has to be a + :ctype:`PyUnicodeObject` (not checked). + + +.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o) + + Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. *o* + has to be a :ctype:`PyUnicodeObject` (not checked). + + +.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o) + + Return a pointer to the internal buffer of the object. *o* has to be a + :ctype:`PyUnicodeObject` (not checked). + +Unicode provides many different character properties. The most often needed ones +are available through these macros which are mapped to C functions depending on +the Python configuration. + +.. % --- Unicode character properties --------------------------------------- + + +.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a whitespace character. + + +.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a lowercase character. + + +.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an uppercase character. + + +.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a titlecase character. + + +.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a linebreak character. + + +.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a decimal character. + + +.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a digit character. + + +.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a numeric character. + + +.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an alphabetic character. + + +.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an alphanumeric character. + +These APIs can be used for fast direct character conversions: + + +.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch) + + Return the character *ch* converted to lower case. + + +.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch) + + Return the character *ch* converted to upper case. + + +.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch) + + Return the character *ch* converted to title case. + + +.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch) + + Return the character *ch* converted to a decimal positive integer. Return + ``-1`` if this is not possible. This macro does not raise exceptions. + + +.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch) + + Return the character *ch* converted to a single digit integer. Return ``-1`` if + this is not possible. This macro does not raise exceptions. + + +.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch) + + Return the character *ch* converted to a double. Return ``-1.0`` if this is not + possible. This macro does not raise exceptions. + +To create Unicode objects and access their basic sequence properties, use these +APIs: + +.. % --- Plain Py_UNICODE --------------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size) + + Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u* + may be *NULL* which causes the contents to be undefined. It is the user's + responsibility to fill in the needed data. The buffer is copied into the new + object. If the buffer is not *NULL*, the return value might be a shared object. + Therefore, modification of the resulting Unicode object is only allowed when *u* + is *NULL*. + + +.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size) + + Create a Unicode Object from the char buffer *u*. The bytes will be interpreted + as being UTF-8 encoded. *u* may also be *NULL* which + causes the contents to be undefined. It is the user's responsibility to fill in + the needed data. The buffer is copied into the new object. If the buffer is not + *NULL*, the return value might be a shared object. Therefore, modification of + the resulting Unicode object is only allowed when *u* is *NULL*. + + +.. cfunction:: PyObject *PyUnicode_FromString(const char *u) + + Create a Unicode object from an UTF-8 encoded null-terminated char buffer + *u*. + + +.. cfunction:: PyObject* PyUnicode_FromFormat(const char *format, ...) + + Take a C :cfunc:`printf`\ -style *format* string and a variable number of + arguments, calculate the size of the resulting Python unicode string and return + a string with the values formatted into it. The variable arguments must be C + types and must correspond exactly to the format characters in the *format* + string. The following format characters are allowed: + + .. % The descriptions for %zd and %zu are wrong, but the truth is complicated + .. % because not all compilers support the %z width modifier -- we fake it + .. % when necessary via interpolating PY_FORMAT_SIZE_T. + + +-------------------+---------------------+--------------------------------+ + | Format Characters | Type | Comment | + +===================+=====================+================================+ + | :attr:`%%` | *n/a* | The literal % character. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%c` | int | A single character, | + | | | represented as an C int. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%d` | int | Exactly equivalent to | + | | | ``printf("%d")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%u` | unsigned int | Exactly equivalent to | + | | | ``printf("%u")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%ld` | long | Exactly equivalent to | + | | | ``printf("%ld")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%lu` | unsigned long | Exactly equivalent to | + | | | ``printf("%lu")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | + | | | ``printf("%zd")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%zu` | size_t | Exactly equivalent to | + | | | ``printf("%zu")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%i` | int | Exactly equivalent to | + | | | ``printf("%i")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%x` | int | Exactly equivalent to | + | | | ``printf("%x")``. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%s` | char\* | A null-terminated C character | + | | | array. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%p` | void\* | The hex representation of a C | + | | | pointer. Mostly equivalent to | + | | | ``printf("%p")`` except that | + | | | it is guaranteed to start with | + | | | the literal ``0x`` regardless | + | | | of what the platform's | + | | | ``printf`` yields. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%U` | PyObject\* | A unicode object. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%V` | PyObject\*, char \* | A unicode object (which may be | + | | | *NULL*) and a null-terminated | + | | | C character array as a second | + | | | parameter (which will be used, | + | | | if the first parameter is | + | | | *NULL*). | + +-------------------+---------------------+--------------------------------+ + | :attr:`%S` | PyObject\* | The result of calling | + | | | :func:`PyObject_Unicode`. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%R` | PyObject\* | The result of calling | + | | | :func:`PyObject_Repr`. | + +-------------------+---------------------+--------------------------------+ + + An unrecognized format character causes all the rest of the format string to be + copied as-is to the result string, and any extra arguments discarded. + + +.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs) + + Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two + arguments. + + +.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) + + Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE` + buffer, *NULL* if *unicode* is not a Unicode object. + + +.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode) + + Return the length of the Unicode object. + + +.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors) + + Coerce an encoded object *obj* to an Unicode object and return a reference with + incremented refcount. + + String and other char buffer compatible objects are decoded according to the + given encoding and using the error handling defined by errors. Both can be + *NULL* to have the interface use the default values (see the next section for + details). + + All other objects, including Unicode objects, cause a :exc:`TypeError` to be + set. + + The API returns *NULL* if there was an error. The caller is responsible for + decref'ing the returned objects. + + +.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj) + + Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used + throughout the interpreter whenever coercion to Unicode is needed. + +If the platform supports :ctype:`wchar_t` and provides a header file wchar.h, +Python can interface directly to this type using the following functions. +Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to +the system's :ctype:`wchar_t`. + +.. % --- wchar_t support for platforms which support it --------------------- + + +.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size) + + Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size. + Return *NULL* on failure. + + +.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size) + + Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*. At most + *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing + 0-termination character). Return the number of :ctype:`wchar_t` characters + copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t` + string may or may not be 0-terminated. It is the responsibility of the caller + to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is + required by the application. + + +.. _builtincodecs: + +Built-in Codecs +^^^^^^^^^^^^^^^ + +Python provides a set of builtin codecs which are written in C for speed. All of +these codecs are directly usable via the following functions. + +Many of the following APIs take two arguments encoding and errors. These +parameters encoding and errors have the same semantics as the ones of the +builtin unicode() Unicode object constructor. + +Setting encoding to *NULL* causes the default encoding to be used which is +ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding` +as the encoding for file names. This variable should be treated as read-only: On +some systems, it will be a pointer to a static string, on others, it will change +at run-time (such as when the application invokes setlocale). + +Error handling is set by errors which may also be set to *NULL* meaning to use +the default handling defined for the codec. Default error handling for all +builtin codecs is "strict" (:exc:`ValueError` is raised). + +The codecs all use a similar interface. Only deviation from the following +generic ones are documented for simplicity. + +These are the generic codec APIs: + +.. % --- Generic Codecs ----------------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Create a Unicode object by decoding *size* bytes of the encoded string *s*. + *encoding* and *errors* have the same meaning as the parameters of the same name + in the :func:`unicode` builtin function. The codec to be used is looked up + using the Python codec registry. Return *NULL* if an exception was raised by + the codec. + + +.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python + string object. *encoding* and *errors* have the same meaning as the parameters + of the same name in the Unicode :meth:`encode` method. The codec to be used is + looked up using the Python codec registry. Return *NULL* if an exception was + raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors) + + Encode a Unicode object and return the result as Python string object. + *encoding* and *errors* have the same meaning as the parameters of the same name + in the Unicode :meth:`encode` method. The codec to be used is looked up using + the Python codec registry. Return *NULL* if an exception was raised by the + codec. + +These are the UTF-8 codec APIs: + +.. % --- UTF-8 Codecs ------------------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If + *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be + treated as an error. Those bytes will not be decoded and the number of bytes + that have been decoded will be stored in *consumed*. + + +.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode) + + Encode a Unicode object using UTF-8 and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + +These are the UTF-32 codec APIs: + +.. % --- UTF-32 Codecs ------------------------------------------------------ */ + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder) + + Decode *length* bytes from a UTF-32 encoded buffer string and return the + corresponding Unicode object. *errors* (if non-*NULL*) defines the error + handling. It defaults to "strict". + + If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte + order:: + + *byteorder == -1: little endian + *byteorder == 0: native order + *byteorder == 1: big endian + + and then switches if the first four bytes of the input data are a byte order mark + (BOM) and the specified byte order is native order. This BOM is not copied into + the resulting Unicode string. After completion, *\*byteorder* is set to the + current byte order at the end of input data. + + In a narrow build codepoints outside the BMP will be decoded as surrogate pairs. + + If *byteorder* is *NULL*, the codec starts in native order mode. + + Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF32`. If + *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF32Stateful` will not treat + trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible + by four) as an error. Those bytes will not be decoded and the number of bytes + that have been decoded will be stored in *consumed*. + + +.. cfunction:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) + + Return a Python bytes object holding the UTF-32 encoded value of the Unicode + data in *s*. If *byteorder* is not ``0``, output is written according to the + following byte order:: + + byteorder == -1: little endian + byteorder == 0: native byte order (writes a BOM mark) + byteorder == 1: big endian + + If byteorder is ``0``, the output string will always start with the Unicode BOM + mark (U+FEFF). In the other two modes, no BOM mark is prepended. + + If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output + as a single codepoint. + + Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode) + + Return a Python string using the UTF-32 encoding in native byte order. The + string always starts with a BOM mark. Error handling is "strict". Return + *NULL* if an exception was raised by the codec. + + +These are the UTF-16 codec APIs: + +.. % --- UTF-16 Codecs ------------------------------------------------------ */ + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder) + + Decode *length* bytes from a UTF-16 encoded buffer string and return the + corresponding Unicode object. *errors* (if non-*NULL*) defines the error + handling. It defaults to "strict". + + If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte + order:: + + *byteorder == -1: little endian + *byteorder == 0: native order + *byteorder == 1: big endian + + and then switches if the first two bytes of the input data are a byte order mark + (BOM) and the specified byte order is native order. This BOM is not copied into + the resulting Unicode string. After completion, *\*byteorder* is set to the + current byte order at the end of input data. + + If *byteorder* is *NULL*, the codec starts in native order mode. + + Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If + *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat + trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a + split surrogate pair) as an error. Those bytes will not be decoded and the + number of bytes that have been decoded will be stored in *consumed*. + + +.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) + + Return a Python string object holding the UTF-16 encoded value of the Unicode + data in *s*. If *byteorder* is not ``0``, output is written according to the + following byte order:: + + byteorder == -1: little endian + byteorder == 0: native byte order (writes a BOM mark) + byteorder == 1: big endian + + If byteorder is ``0``, the output string will always start with the Unicode BOM + mark (U+FEFF). In the other two modes, no BOM mark is prepended. + + If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get + represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE` + values is interpreted as an UCS-2 character. + + Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode) + + Return a Python string using the UTF-16 encoding in native byte order. The + string always starts with a BOM mark. Error handling is "strict". Return + *NULL* if an exception was raised by the codec. + +These are the "Unicode Escape" codec APIs: + +.. % --- Unicode-Escape Codecs ---------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded + string *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and + return a Python string object. Return *NULL* if an exception was raised by the + codec. + + +.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode) + + Encode a Unicode object using Unicode-Escape and return the result as Python + string object. Error handling is "strict". Return *NULL* if an exception was + raised by the codec. + +These are the "Raw Unicode Escape" codec APIs: + +.. % --- Raw-Unicode-Escape Codecs ------------------------------------------ + + +.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape + encoded string *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape + and return a Python string object. Return *NULL* if an exception was raised by + the codec. + + +.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode) + + Encode a Unicode object using Raw-Unicode-Escape and return the result as + Python string object. Error handling is "strict". Return *NULL* if an exception + was raised by the codec. + +These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode +ordinals and only these are accepted by the codecs during encoding. + +.. % --- Latin-1 Codecs ----------------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return + a Python string object. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode) + + Encode a Unicode object using Latin-1 and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + +These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other +codes generate errors. + +.. % --- ASCII Codecs ------------------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the ASCII encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode) + + Encode a Unicode object using ASCII and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + +These are the mapping codec APIs: + +.. % --- Character Map Codecs ----------------------------------------------- + +This codec is special in that it can be used to implement many different codecs +(and this is in fact what was done to obtain most of the standard codecs +included in the :mod:`encodings` package). The codec uses mapping to encode and +decode characters. + +Decoding mappings must map single string characters to single Unicode +characters, integers (which are then interpreted as Unicode ordinals) or None +(meaning "undefined mapping" and causing an error). + +Encoding mappings must map single Unicode characters to single string +characters, integers (which are then interpreted as Latin-1 ordinals) or None +(meaning "undefined mapping" and causing an error). + +The mapping objects provided must only support the __getitem__ mapping +interface. + +If a character lookup fails with a LookupError, the character is copied as-is +meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal +resp. Because of this, mappings only need to contain those mappings which map +characters to different code points. + + +.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors) + + Create a Unicode object by decoding *size* bytes of the encoded string *s* using + the given *mapping* object. Return *NULL* if an exception was raised by the + codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a + dictionary mapping byte or a unicode string, which is treated as a lookup table. + Byte values greater that the length of the string and U+FFFE "characters" are + treated as "undefined mapping". + + +.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using the given + *mapping* object and return a Python string object. Return *NULL* if an + exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping) + + Encode a Unicode object using the given *mapping* object and return the result + as Python string object. Error handling is "strict". Return *NULL* if an + exception was raised by the codec. + +The following codec API is special in that maps Unicode to Unicode. + + +.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors) + + Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a + character mapping *table* to it and return the resulting Unicode object. Return + *NULL* when an exception was raised by the codec. + + The *mapping* table must map Unicode ordinal integers to Unicode ordinal + integers or None (causing deletion of the character). + + Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries + and sequences work well. Unmapped character ordinals (ones which cause a + :exc:`LookupError`) are left untouched and are copied as-is. + +These are the MBCS codec APIs. They are currently only available on Windows and +use the Win32 MBCS converters to implement the conversions. Note that MBCS (or +DBCS) is a class of encodings, not just one. The target encoding is defined by +the user settings on the machine running the codec. + +.. % --- MBCS codecs for Windows -------------------------------------------- + + +.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*. + Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed) + + If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If + *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode + trailing lead byte and the number of bytes that have been decoded will be stored + in *consumed*. + + +.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + +.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode) + + Encode a Unicode object using MBCS and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + +.. % --- Methods & Slots ---------------------------------------------------- + + +.. _unicodemethodsandslots: + +Methods and Slot Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following APIs are capable of handling Unicode objects and strings on input +(we refer to them as strings in the descriptions) and return Unicode objects or +integers as appropriate. + +They all return *NULL* or ``-1`` if an exception occurs. + + +.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right) + + Concat two strings giving a new Unicode string. + + +.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit) + + Split a string giving a list of Unicode strings. If sep is *NULL*, splitting + will be done at all whitespace substrings. Otherwise, splits occur at the given + separator. At most *maxsplit* splits will be done. If negative, no limit is + set. Separators are not included in the resulting list. + + +.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend) + + Split a Unicode string at line breaks, returning a list of Unicode strings. + CRLF is considered to be one line break. If *keepend* is 0, the Line break + characters are not included in the resulting strings. + + +.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors) + + Translate a string by applying a character mapping table to it and return the + resulting Unicode object. + + The mapping table must map Unicode ordinal integers to Unicode ordinal integers + or None (causing deletion of the character). + + Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries + and sequences work well. Unmapped character ordinals (ones which cause a + :exc:`LookupError`) are left untouched and are copied as-is. + + *errors* has the usual meaning for codecs. It may be *NULL* which indicates to + use the default error handling. + + +.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) + + Join a sequence of strings using the given separator and return the resulting + Unicode string. + + +.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) + + Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end + (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match), + 0 otherwise. Return ``-1`` if an error occurred. + + +.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) + + Return the first position of *substr* in *str*[*start*:*end*] using the given + *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a + backward search). The return value is the index of the first match; a value of + ``-1`` indicates that no match was found, and ``-2`` indicates that an error + occurred and an exception has been set. + + +.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end) + + Return the number of non-overlapping occurrences of *substr* in + ``str[start:end]``. Return ``-1`` if an error occurred. + + +.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount) + + Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and + return the resulting Unicode object. *maxcount* == -1 means replace all + occurrences. + + +.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right) + + Compare two strings and return -1, 0, 1 for less than, equal, and greater than, + respectively. + + +.. cfunction:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op) + + Rich compare two unicode strings and return one of the following: + + * ``NULL`` in case an exception was raised + * :const:`Py_True` or :const:`Py_False` for successful comparisons + * :const:`Py_NotImplemented` in case the type combination is unknown + + Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a + :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails + with a :exc:`UnicodeDecodeError`. + + Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`, + :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`. + + +.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args) + + Return a new string object from *format* and *args*; this is analogous to + ``format % args``. The *args* argument must be a tuple. + + +.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element) + + Check whether *element* is contained in *container* and return true or false + accordingly. + + *element* has to coerce to a one element Unicode string. ``-1`` is returned if + there was an error. + + +.. cfunction:: void PyUnicode_InternInPlace(PyObject **string) + + Intern the argument *\*string* in place. The argument must be the address of a + pointer variable pointing to a Python unicode 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.) + + +.. cfunction:: PyObject* PyUnicode_InternFromString(const char *v) + + A combination of :cfunc:`PyUnicode_FromString` and + :cfunc:`PyUnicode_InternInPlace`, returning either a new unicode string object + that has been interned, or a new ("owned") reference to an earlier interned + string object with the same value. + 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 diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst new file mode 100644 index 0000000..081419d --- /dev/null +++ b/Doc/c-api/weakref.rst @@ -0,0 +1,62 @@ +.. highlightlang:: c + +.. _weakrefobjects: + +Weak Reference Objects +---------------------- + +Python supports *weak references* as first-class objects. There are two +specific object types which directly implement weak references. The first is a +simple reference object, and the second acts as a proxy for the original object +as much as it can. + + +.. cfunction:: int PyWeakref_Check(ob) + + Return true if *ob* is either a reference or proxy object. + + +.. cfunction:: int PyWeakref_CheckRef(ob) + + Return true if *ob* is a reference object. + + +.. cfunction:: int PyWeakref_CheckProxy(ob) + + Return true if *ob* is a proxy object. + + +.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) + + Return a weak reference object for the object *ob*. This will always return + a new reference, but is not guaranteed to create a new object; an existing + reference object may be returned. The second parameter, *callback*, can be a + callable object that receives notification when *ob* is garbage collected; it + should accept a single parameter, which will be the weak reference object + itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a + weakly-referencable object, or if *callback* is not callable, ``None``, or + *NULL*, this will return *NULL* and raise :exc:`TypeError`. + + +.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback) + + Return a weak reference proxy object for the object *ob*. This will always + return a new reference, but is not guaranteed to create a new object; an + existing proxy object may be returned. The second parameter, *callback*, can + be a callable object that receives notification when *ob* is garbage + collected; it should accept a single parameter, which will be the weak + reference object itself. *callback* may also be ``None`` or *NULL*. If *ob* + is not a weakly-referencable object, or if *callback* is not callable, + ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`. + + +.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref) + + Return the referenced object from a weak reference, *ref*. If the referent is + no longer live, returns ``None``. + + +.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) + + Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no + error checking. |