Skip to content

C
cpython
Commit 54a3faae authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

Split C API docs in Py3k branch.

parent 135bf209
Show whitespace changes
Inline Side-by-side
Showing with 7295 additions and 5384 deletions
Doc/c-api/abstract.rst
View file @ 54a3faae
.. 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
Doc/c-api/allocation.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/arg.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/bool.rst 0 → 100644
View file @ 54a3faae
.. 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*.
Doc/c-api/buffer.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/cell.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/cobject.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/complex.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/concrete.rst
View file @ 54a3faae
This source diff could not be displayed because it is too large. You can view the blob instead.
Doc/c-api/conversion.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/datetime.rst 0 → 100644
View file @ 54a3faae
.. 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()``.
Doc/c-api/descriptor.rst 0 → 100644
View file @ 54a3faae
.. 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 *)
Doc/c-api/dict.rst 0 → 100644
View file @ 54a3faae
.. 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
Doc/c-api/file.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/float.rst 0 → 100644
View file @ 54a3faae
.. 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`.
Doc/c-api/function.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/gcsupport.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/gen.rst 0 → 100644
View file @ 54a3faae
.. 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*.
Doc/c-api/import.rst 0 → 100644
View file @ 54a3faae
.. 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`.
Doc/c-api/iter.rst 0 → 100644
View file @ 54a3faae
.. 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 */
}
Doc/c-api/iterator.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/list.rst 0 → 100644
View file @ 54a3faae
.. 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)``.
Doc/c-api/long.rst 0 → 100644
View file @ 54a3faae
.. 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`.
Doc/c-api/mapping.rst 0 → 100644
View file @ 54a3faae
.. 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``.
Doc/c-api/marshal.rst 0 → 100644
View file @ 54a3faae
.. 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*.
Doc/c-api/method.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/module.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/none.rst 0 → 100644
View file @ 54a3faae
.. 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.)
Doc/c-api/number.rst 0 → 100644
View file @ 54a3faae
.. 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).
Doc/c-api/objbuffer.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/object.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/objimpl.rst 0 → 100644
View file @ 54a3faae
.. 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
Doc/c-api/reflection.rst 0 → 100644
View file @ 54a3faae
.. 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*.
Doc/c-api/sequence.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/set.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/slice.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/string.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/structures.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/sys.rst 0 → 100644
View file @ 54a3faae
.. 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*.
Doc/c-api/tuple.rst 0 → 100644
View file @ 54a3faae
.. 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`.
Doc/c-api/type.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/typeobj.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/unicode.rst 0 → 100644
View file @ 54a3faae
.. 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.
Doc/c-api/utilities.rst
View file @ 54a3faae
.. 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
Doc/c-api/weakref.rst 0 → 100644
View file @ 54a3faae
.. 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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7