Sat Jan 19 23:08:24 CET 2008

Author: georg.brandl
Date: Sat Jan 19 23:08:21 2008
New Revision: 60109
Added:
 python/trunk/Doc/c-api/allocation.rst
 python/trunk/Doc/c-api/bool.rst
 python/trunk/Doc/c-api/buffer.rst
 python/trunk/Doc/c-api/cell.rst
 python/trunk/Doc/c-api/class.rst
 python/trunk/Doc/c-api/cobject.rst
 python/trunk/Doc/c-api/complex.rst
 python/trunk/Doc/c-api/datetime.rst
 python/trunk/Doc/c-api/descriptor.rst
 python/trunk/Doc/c-api/dict.rst
 python/trunk/Doc/c-api/file.rst
 python/trunk/Doc/c-api/float.rst
 python/trunk/Doc/c-api/function.rst
 python/trunk/Doc/c-api/gcsupport.rst
 python/trunk/Doc/c-api/gen.rst
 python/trunk/Doc/c-api/int.rst
 python/trunk/Doc/c-api/iter.rst
 python/trunk/Doc/c-api/iterator.rst
 python/trunk/Doc/c-api/list.rst
 python/trunk/Doc/c-api/long.rst
 python/trunk/Doc/c-api/mapping.rst
 python/trunk/Doc/c-api/method.rst
 python/trunk/Doc/c-api/module.rst
 python/trunk/Doc/c-api/none.rst
 python/trunk/Doc/c-api/number.rst
 python/trunk/Doc/c-api/objbuffer.rst
 python/trunk/Doc/c-api/object.rst
 python/trunk/Doc/c-api/objimpl.rst
 - copied, changed from r60093, python/trunk/Doc/c-api/newtypes.rst
 python/trunk/Doc/c-api/sequence.rst
 python/trunk/Doc/c-api/set.rst
 python/trunk/Doc/c-api/slice.rst
 python/trunk/Doc/c-api/string.rst
 python/trunk/Doc/c-api/structures.rst
 python/trunk/Doc/c-api/tuple.rst
 python/trunk/Doc/c-api/type.rst
 python/trunk/Doc/c-api/typeobj.rst
 python/trunk/Doc/c-api/unicode.rst
 python/trunk/Doc/c-api/weakref.rst
Removed:
 python/trunk/Doc/c-api/newtypes.rst
Modified:
 python/trunk/Doc/c-api/abstract.rst
 python/trunk/Doc/c-api/concrete.rst
 python/trunk/Doc/c-api/index.rst
Log:
Split the monstrous C API manual files in smaller parts.
Modified: python/trunk/Doc/c-api/abstract.rst
==============================================================================

--- python/trunk/Doc/c-api/abstract.rst	(original)
+++ python/trunk/Doc/c-api/abstract.rst	Sat Jan 19 23:08:21 2008
@@ -16,1010 +16,11 @@
 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
- by the :keyword:`print` statement.
-
-
-.. 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.
-
- .. versionadded:: 2.1
-
- .. versionchanged:: 2.2
- Support for a tuple as the second argument added.
-
-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.
-
- .. versionadded:: 2.1
-
- .. versionchanged:: 2.3
- Older versions of Python did not support a tuple as the second argument.
-
-
-.. 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)
-
- .. index:: builtin: apply
-
- 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
- ``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
-
- .. index:: builtin: apply
-
- Call a callable Python object *callable_object*, with arguments given by the
- tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
- the result of the call on success, or *NULL* on failure. This is the equivalent
- of the Python expression ``apply(callable_object, args)`` or
- ``callable_object(*args)``.
-
-
-.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
-
- .. index:: builtin: apply
-
- 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 ``apply(callable, args)`` or
- ``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.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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*.
-
- .. versionadded:: 2.2
-
-
-.. 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:: int PyObject_AsFileDescriptor(PyObject *o)
-
- Derives a file descriptor from a Python object. If the object is an integer or
- long integer, its value is returned. If not, the object's :meth:`fileno` method
- is called if it exists; the method must return an integer or long integer, which
- is returned as the file descriptor value. Returns ``-1`` on failure.
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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``.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)
-
- .. index:: builtin: coerce
-
- This function takes the addresses of two variables of type :ctype:`PyObject\*`.
- If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment
- their reference count and return ``0`` (success). If the objects can be
- converted to a common numeric type, replace ``*p1`` and ``*p2`` by their
- converted value (with 'new' reference counts), and return ``0``. If no
- conversion is possible, or if some other error occurs, return ``-1`` (failure)
- and don't increment the reference counts. The call ``PyNumber_Coerce(&o1,
- &o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.
-
-
-.. cfunction:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)
-
- This function is similar to :cfunc:`PyNumber_Coerce`, except that it returns
- ``1`` when the conversion is not possible and when no error is raised.
- Reference counts are still not increased in this case.
-
-
-.. 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 a long 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.
-
- .. versionadded:: 2.5
-
-
-.. 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.
-
- .. versionadded:: 2.5
-
-
-.. 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).
-
- .. versionadded:: 2.5
-
-
-.. _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*.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.3
-
-
-.. 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 ``o.has_key(key)``.
- 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 ``o.has_key(key)``. 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
-=================
-
-.. versionadded:: 2.2
-
-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.
-
- .. versionadded:: 1.6
-
-
-.. 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.
-
- .. versionadded:: 1.6
-
-
-.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
-
- Returns ``1`` if *o* supports the single-segment readable buffer interface.
- Otherwise returns ``0``.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
-
- Returns a pointer to a writeable 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.
-
- .. versionadded:: 1.6
-
+ object.rst
+ number.rst
+ sequence.rst
+ mapping.rst
+ iter.rst
+ objbuffer.rst
Added: python/trunk/Doc/c-api/allocation.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/allocation.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,104 @@
+.. 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:: void _PyObject_Del(PyObject *op)
+
+
+.. 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.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the *methods*
+ argument.
+
+
+.. 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. If *doc* is non-*NULL*, it will be used to define the
+ docstring for the module.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the *methods*
+ argument.
+
+
+.. 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. 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.
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support *NULL* as the value for the *methods*
+ argument.
+
+
+.. cvar:: PyObject _Py_NoneStruct
+
+ Object which is visible in Python as ``None``. This should only be accessed
+ using the ``Py_None`` macro, which evaluates to a pointer to this object.
Added: python/trunk/Doc/c-api/bool.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/bool.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,54 @@
+.. 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`.
+
+ .. versionadded:: 2.3
+
+
+.. 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.
+
+ .. versionadded:: 2.4
+
+
+.. cmacro:: Py_RETURN_TRUE
+
+ Return :const:`Py_True` from a function, properly incrementing its reference
+ count.
+
+ .. versionadded:: 2.4
+
+
+.. 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*.
+
+ .. versionadded:: 2.3
Added: python/trunk/Doc/c-api/buffer.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/buffer.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,119 @@
+.. highlightlang:: c
+
+.. _bufferobjects:
+
+Buffer Objects
+--------------
+
+.. sectionauthor:: Greg Stein <gstein at 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 writeable 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.
Added: python/trunk/Doc/c-api/cell.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/cell.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,62 @@
+.. highlightlang:: c
+
+.. _cell-objects:
+
+Cell Objects
+------------
+
+"Cell" objects are used to implement variables referenced by multiple scopes.
+For each such variable, a cell object is created to store the value; the local
+variables of each stack frame that references the value contains a reference to
+the cells from outer scopes which also use that variable. When the value is
+accessed, the value contained in the cell is used instead of the cell object
+itself. This de-referencing of the cell object requires support from the
+generated byte-code; these are not automatically de-referenced when accessed.
+Cell objects are not likely to be useful elsewhere.
+
+
+.. ctype:: PyCellObject
+
+ The C structure used for cell objects.
+
+
+.. cvar:: PyTypeObject PyCell_Type
+
+ The type object corresponding to cell objects.
+
+
+.. cfunction:: int PyCell_Check(ob)
+
+ Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_New(PyObject *ob)
+
+ Create and return a new cell object containing the value *ob*. The parameter may
+ be *NULL*.
+
+
+.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
+
+ Return the contents of the cell *cell*.
+
+
+.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
+
+ Return the contents of the cell *cell*, but without checking that *cell* is
+ non-*NULL* and a cell object.
+
+
+.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
+
+ Set the contents of the cell object *cell* to *value*. This releases the
+ reference to any current content of the cell. *value* may be *NULL*. *cell*
+ must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
+ success, ``0`` will be returned.
+
+
+.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
+
+ Sets the value of the cell object *cell* to *value*. No reference counts are
+ adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
+ be a cell object.
Added: python/trunk/Doc/c-api/class.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/class.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,65 @@
+.. highlightlang:: c
+
+.. _classobjects:
+
+Class and Instance Objects
+--------------------------
+
+.. index:: object: class
+
+Note that the class objects described here represent old-style classes, which
+will go away in Python 3. When creating new types for extension modules, you
+will want to work with type objects (section :ref:`typeobjects`).
+
+
+.. ctype:: PyClassObject
+
+ The C structure of the objects used to describe built-in classes.
+
+
+.. cvar:: PyObject* PyClass_Type
+
+ .. index:: single: ClassType (in module types)
+
+ This is the type object for class objects; it is the same object as
+ ``types.ClassType`` in the Python layer.
+
+
+.. cfunction:: int PyClass_Check(PyObject *o)
+
+ Return true if the object *o* is a class object, including instances of types
+ derived from the standard class object. Return false in all other cases.
+
+
+.. cfunction:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
+
+ Return true if *klass* is a subclass of *base*. Return false in all other cases.
+
+
+.. index:: object: instance
+
+There are very few functions specific to instance objects.
+
+
+.. cvar:: PyTypeObject PyInstance_Type
+
+ Type object for class instances.
+
+
+.. cfunction:: int PyInstance_Check(PyObject *obj)
+
+ Return true if *obj* is an instance.
+
+
+.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
+
+ Create a new instance of a specific class. The parameters *arg* and *kw* are
+ used as the positional and keyword parameters to the object's constructor.
+
+
+.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
+
+ Create a new instance of a specific class without calling its constructor.
+ *class* is the class of new object. The *dict* parameter will be used as the
+ object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
+ instance.
Added: python/trunk/Doc/c-api/cobject.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/cobject.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,56 @@
+.. highlightlang:: c
+
+.. _cobjects:
+
+CObjects
+--------
+
+.. index:: object: CObject
+
+Refer to :ref:`using-cobjects` for more information on using these objects.
+
+
+.. ctype:: PyCObject
+
+ This subtype of :ctype:`PyObject` represents an opaque value, useful for C
+ extension modules who need to pass an opaque value (as a :ctype:`void\*`
+ pointer) through Python code to other C code. It is often used to make a C
+ function pointer defined in one module available to other modules, so the
+ regular import mechanism can be used to access C APIs defined in dynamically
+ loaded modules.
+
+
+.. cfunction:: int PyCObject_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyCObject`.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
+
+ Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function
+ will be called when the object is reclaimed, unless it is *NULL*.
+
+
+.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
+
+ Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr*
+ function will be called when the object is reclaimed. The *desc* argument can
+ be used to pass extra callback data for the destructor function.
+
+
+.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
+
+ Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+ created with.
+
+
+.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
+
+ Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
+ created with.
+
+
+.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
+
+ Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
+ have an associated destructor. Return true on success, false on failure.
Added: python/trunk/Doc/c-api/complex.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/complex.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,132 @@
+.. 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`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyComplex_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
+ :ctype:`PyComplexObject`.
+
+ .. versionadded:: 2.2
+
+
+.. 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*.
+
+ .. versionchanged:: 2.6
+ 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.
Modified: python/trunk/Doc/c-api/concrete.rst
==============================================================================
--- python/trunk/Doc/c-api/concrete.rst	(original)
+++ python/trunk/Doc/c-api/concrete.rst	Sat Jan 19 23:08:21 2008
@@ -29,108 +29,10 @@
 
 This section describes Python type objects and the singleton object ``None``.
 
+.. toctree::
 
-.. _typeobjects:
-
-Type Objects
-------------
-
-.. index:: object: type
-
-
-.. ctype:: PyTypeObject
-
- The C structure of the objects used to describe built-in types.
-
-
-.. cvar:: PyObject* PyType_Type
-
- .. index:: single: TypeType (in module types)
-
- This is the type object for type objects; it is the same object as ``type`` and
- ``types.TypeType`` in the Python layer.
-
-
-.. cfunction:: int PyType_Check(PyObject *o)
-
- Return true if the object *o* is a type object, including instances of types
- derived from the standard type object. Return false in all other cases.
-
-
-.. cfunction:: int PyType_CheckExact(PyObject *o)
-
- Return true if the object *o* is a type object, but not a subtype of the
- standard type object. Return false in all other cases.
-
- .. versionadded:: 2.2
-
-
-.. 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`.
-
- .. versionadded:: 2.0
-
-
-.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
-
- Return true if *a* is a subtype of *b*.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. _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.
-
- .. versionadded:: 2.4
+ type.rst
+ none.rst
 
 
 .. _numericobjects:
@@ -140,3508 +42,65 @@
 
 .. index:: object: numeric
 
+.. toctree::
 
-.. _intobjects:
-
-Plain Integer Objects
----------------------
-
-.. index:: object: integer
-
-
-.. ctype:: PyIntObject
-
- This subtype of :ctype:`PyObject` represents a Python integer object.
-
-
-.. cvar:: PyTypeObject PyInt_Type
-
- .. index:: single: IntType (in modules types)
-
- This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
- This is the same object as ``int`` and ``types.IntType``.
-
-
-.. cfunction:: int PyInt_Check(PyObject *o)
-
- Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
- :cdata:`PyInt_Type`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyInt_CheckExact(PyObject *o)
-
- Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
- :cdata:`PyInt_Type`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
-
- Return a new :ctype:`PyIntObject` or :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 ``'0'``, radix
- 8 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. If the string represents
- a number too large to be contained within the machine's :ctype:`long int` type
- and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
- returned. If overflow warnings are not being suppressed, *NULL* will be
- returned in this case.
-
-
-.. cfunction:: PyObject* PyInt_FromLong(long ival)
-
- Create a new integer object with a value of *ival*.
-
- 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* PyInt_FromSsize_t(Py_ssize_t ival)
-
- Create a new integer object with a value of *ival*. If the value exceeds
- ``LONG_MAX``, a long integer object is returned.
-
- .. versionadded:: 2.5
-
-
-.. cfunction:: long PyInt_AsLong(PyObject *io)
-
- Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
- already one, and then return its value. If there is an error, ``-1`` is
- returned, and the caller should check ``PyErr_Occurred()`` to find out whether
- there was an error, or whether the value just happened to be -1.
-
-
-.. cfunction:: long PyInt_AS_LONG(PyObject *io)
-
- Return the value of the object *io*. No error checking is performed.
-
-
-.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
-
- Will first attempt to cast the object to a :ctype:`PyIntObject` or
- :ctype:`PyLongObject`, if it is not already one, and then return its value as
- unsigned long. This function does not check for overflow.
-
- .. versionadded:: 2.3
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
-
- Will first attempt to cast the object to a :ctype:`PyIntObject` or
- :ctype:`PyLongObject`, if it is not already one, and then return its value as
- unsigned long long, without checking for overflow.
-
- .. versionadded:: 2.3
-
-
-.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
-
- Will first attempt to cast the object to a :ctype:`PyIntObject` or
- :ctype:`PyLongObject`, if it is not already one, and then return its value as
- :ctype:`Py_ssize_t`.
-
- .. versionadded:: 2.5
-
-
-.. cfunction:: long PyInt_GetMax()
-
- .. index:: single: LONG_MAX
-
- Return the system's idea of the largest integer it can handle
- (:const:`LONG_MAX`, as defined in the system header files).
-
-
-.. _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`.
-
- .. versionadded:: 2.3
-
-
-.. 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.
-
- .. versionadded:: 2.4
-
-
-.. cmacro:: Py_RETURN_TRUE
-
- Return :const:`Py_True` from a function, properly incrementing its reference
- count.
-
- .. versionadded:: 2.4
-
-
-.. 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*.
-
- .. versionadded:: 2.3
-
-
-.. _longobjects:
-
-Long Integer Objects
---------------------
+ int.rst
+ bool.rst
+ long.rst
+ float.rst
+ complex.rst
 
-.. index:: object: long integer
 
+.. _sequenceobjects:
 
-.. ctype:: PyLongObject
-
- This subtype of :ctype:`PyObject` represents a Python long integer object.
-
-
-.. cvar:: PyTypeObject PyLong_Type
-
- .. index:: single: LongType (in modules types)
-
- This instance of :ctype:`PyTypeObject` represents the Python long integer type.
- This is the same object as ``long`` and ``types.LongType``.
-
-
-.. cfunction:: int PyLong_Check(PyObject *p)
-
- Return true if its argument is a :ctype:`PyLongObject` or a subtype of
- :ctype:`PyLongObject`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyLong_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
- :ctype:`PyLongObject`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyLong_FromLong(long v)
-
- Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
-
-
-.. 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_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 ``'0'``, radix 8 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 long integer value. The first
- parameter, *u*, points to the first character of the Unicode string, *length*
- gives the number of characters, and *base* is the radix for the conversion. The
- radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
- will be raised.
-
- .. versionadded:: 1.6
-
-
-.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
-
- Create a Python integer or long integer from the pointer *p*. The pointer value
- can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
-
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.5
- If the integer is larger than LONG_MAX, a positive long integer is returned.
-
-
-.. 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`, an :exc:`OverflowError` is raised.
-
-
-.. 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_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
-
- Return a C :ctype:`long long` from a Python long integer. If *pylong* cannot be
- represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
-
- Return a C :ctype:`unsigned long long` from a Python long 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.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
-
- Return a C :ctype:`unsigned long` from a Python long integer, without checking
- for overflow.
-
- .. versionadded:: 2.3
-
-
-.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
-
- Return a C :ctype:`unsigned long long` from a Python long integer, without
- checking for overflow.
-
- .. versionadded:: 2.3
-
-
-.. 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 or long 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`.
-
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.5
- For values outside 0..LONG_MAX, both signed and unsigned integers are acccepted.
-
-
-.. _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`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyFloat_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
- :ctype:`PyFloatObject`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
-
- Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
- *NULL* on failure. The *pend* argument is ignored. It remains only for
- backward compatibility.
-
-
-.. 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`.
-
- .. versionadded:: 2.6
-
-
-.. cfunction:: double PyFloat_GetMax(void)
-
- Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
-
- .. versionadded:: 2.6
-
-
-.. cfunction:: double PyFloat_GetMin(void)
-
- Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
-
- .. versionadded:: 2.6
-
+Sequence Objects
+================
 
-.. _complexobjects:
+.. index:: object: sequence
 
-Complex Number Objects
-----------------------
+Generic operations on sequence objects were discussed in the previous chapter;
+this section deals with the specific kinds of sequence objects that are
+intrinsic to the Python language.
 
-.. index:: object: complex number
+.. toctree::
 
-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.
+ string.rst
+ unicode.rst
+ buffer.rst
+ tuple.rst
+ list.rst
 
 
-Complex Numbers as C Structures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _mapobjects:
 
-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.
+Mapping Objects
+===============
 
+.. index:: object: mapping
 
-.. ctype:: Py_complex
+.. toctree::
 
- 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::
+ dict.rst
 
- typedef struct {
- double real;
- double imag;
- } Py_complex;
 
+.. _otherobjects:
 
-.. 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`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyComplex_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
- :ctype:`PyComplexObject`.
-
- .. versionadded:: 2.2
-
-
-.. 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*.
-
- .. versionchanged:: 2.6
- 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.
-
-
-.. _sequenceobjects:
-
-Sequence Objects
-================
-
-.. index:: object: sequence
-
-Generic operations on sequence objects were discussed in the previous chapter;
-this section deals with the specific kinds of sequence objects that are
-intrinsic to the Python language.
-
-
-.. _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.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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:
-
- .. % This should be exactly the same as the table in PyErr_Format.
- .. % One should just refer to the other.
- .. % 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_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
-
- Encode the :ctype:`char` buffer of the given size by passing it to the codec
- registered for *encoding* and return a Python object. *encoding* and *errors*
- have the same meaning as the parameters of the same name in the string
- :meth:`encode` method. The codec to be used is looked up using the Python codec
- registry. Return *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
-
- Encode a string object using the codec registered for *encoding* and return the
- result as Python object. *encoding* and *errors* have the same meaning as the
- parameters of the same name in the string :meth:`encode` method. The codec to be
- used is looked up using the Python codec registry. Return *NULL* if an exception
- was raised by the codec.
-
-
-.. _unicodeobjects:
-
-Unicode Objects
----------------
-
-.. sectionauthor:: Marc-Andre Lemburg <mal at lemburg.com>
-
-
-These are the basic Unicode object types used for the Unicode implementation in
-Python:
-
-.. % --- Unicode Type -------------------------------------------------------
-
-
-.. ctype:: Py_UNICODE
-
- This type represents the storage type which is used by Python internally as
- basis for holding Unicode ordinals. Python's default builds use a 16-bit type
- for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
- possible to build a UCS4 version of Python (most recent Linux distributions come
- with UCS4 builds of Python). These builds then use a 32-bit type for
- :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
- where :ctype:`wchar_t` is available and compatible with the chosen Python
- Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for
- :ctype:`wchar_t` to enhance native platform compatibility. On all other
- platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned
- short` (UCS2) or :ctype:`unsigned long` (UCS4).
-
-Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
-this in mind when writing extensions or interfaces.
-
-
-.. ctype:: PyUnicodeObject
-
- This subtype of :ctype:`PyObject` represents a Python Unicode object.
-
-
-.. cvar:: PyTypeObject PyUnicode_Type
-
- This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It
- is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
-
-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.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
-
- Return true if the object *o* is a Unicode object, but not an instance of a
- subtype.
-
- .. versionadded:: 2.2
-
-
-.. 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:: 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*.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.6
-
-
-.. 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*.
-
- .. versionadded:: 2.6
-
-
-.. 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.
-
- .. versionadded:: 2.6
-
-
-.. 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.
-
- .. versionadded:: 2.6
-
-
-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.
-
- 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*.
-
- .. versionadded:: 2.4
-
-
-.. 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".
-
- .. versionchanged:: 2.4
- Allowed unicode string as mapping argument.
-
-
-.. 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*.
-
- .. versionadded:: 2.5
-
-
-.. 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.
-
-
-.. _bufferobjects:
-
-Buffer Objects
---------------
-
-.. sectionauthor:: Greg Stein <gstein at 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 writeable buffer protocol, then :exc:`TypeError` is raised.
-
-
-.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
-
- Return a new read-only buffer object that reads from a specified location in
- memory, with a specified size. The caller is responsible for ensuring that the
- memory buffer, passed in as *ptr*, is not deallocated while the returned buffer
- object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that
- :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;
- :exc:`ValueError` will be raised in that case.
-
-
-.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
-
- Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
-
-
-.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)
-
- Return a new writable buffer object that maintains its own memory buffer of
- *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive.
- Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is
- not specifically aligned.
-
-
-.. _tupleobjects:
-
-Tuple Objects
--------------
-
-.. index:: object: tuple
-
-
-.. ctype:: PyTupleObject
-
- This subtype of :ctype:`PyObject` represents a Python tuple object.
-
-
-.. cvar:: PyTypeObject PyTuple_Type
-
- .. index:: single: TupleType (in module types)
-
- This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
- the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
-
-
-.. cfunction:: int PyTuple_Check(PyObject *p)
-
- Return true if *p* is a tuple object or an instance of a subtype of the tuple
- type.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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)``.
-
- .. versionadded:: 2.4
-
-
-.. 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`.
-
- .. versionchanged:: 2.2
- Removed unused third parameter, *last_is_sticky*.
-
-
-.. _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.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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)``.
-
-
-.. _mapobjects:
-
-Mapping Objects
-===============
-
-.. index:: object: mapping
-
-
-.. _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.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. 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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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``.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
-
- Return a new dictionary that contains the same key-value pairs as *p*.
-
- .. versionadded:: 1.6
-
-
-.. 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)) {
- int i = PyInt_AS_LONG(value) + 1;
- PyObject *o = PyInt_FromLong(i);
- 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.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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
-
- .. versionadded:: 2.2
-
-
-.. _otherobjects:
-
-Other Objects
-=============
-
-
-.. _classobjects:
-
-Class Objects
--------------
-
-.. index:: object: class
-
-Note that the class objects described here represent old-style classes, which
-will go away in Python 3. When creating new types for extension modules, you
-will want to work with type objects (section :ref:`typeobjects`).
-
-
-.. ctype:: PyClassObject
-
- The C structure of the objects used to describe built-in classes.
-
-
-.. cvar:: PyObject* PyClass_Type
-
- .. index:: single: ClassType (in module types)
-
- This is the type object for class objects; it is the same object as
- ``types.ClassType`` in the Python layer.
-
-
-.. cfunction:: int PyClass_Check(PyObject *o)
-
- Return true if the object *o* is a class object, including instances of types
- derived from the standard class object. Return false in all other cases.
-
-
-.. cfunction:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
-
- Return true if *klass* is a subclass of *base*. Return false in all other cases.
-
-
-.. _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`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyFile_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
- :ctype:`PyFileObject`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
-
- .. index:: single: fopen()
-
- On success, return a new file object that is opened on the file given by
- *filename*, with a file mode given by *mode*, where *mode* has the same
- semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.
-
-
-.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
-
- Create a new :ctype:`PyFileObject` from the already-open standard C file
- pointer, *fp*. The function *close* will be called when the file should be
- closed. Return *NULL* on failure.
-
-
-.. cfunction:: FILE* PyFile_AsFile(PyObject *p)
-
- Return the file object associated with *p* as a :ctype:`FILE\*`.
-
-
-.. 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.
-
- .. versionadded:: 2.3
-
-
-.. 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.
-
-
-.. _instanceobjects:
-
-Instance Objects
-----------------
-
-.. index:: object: instance
-
-There are very few functions specific to instance objects.
-
-
-.. cvar:: PyTypeObject PyInstance_Type
-
- Type object for class instances.
-
-
-.. cfunction:: int PyInstance_Check(PyObject *obj)
-
- Return true if *obj* is an instance.
-
-
-.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
-
- Create a new instance of a specific class. The parameters *arg* and *kw* are
- used as the positional and keyword parameters to the object's constructor.
-
-
-.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
-
- Create a new instance of a specific class without calling its constructor.
- *class* is the class of new object. The *dict* parameter will be used as the
- object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
- instance.
-
-
-.. _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.
-
-
-.. _method-objects:
-
-Method Objects
---------------
-
-.. index:: object: method
-
-There are some useful functions that are useful for working with method objects.
-
-
-.. 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, PyObject *class)
-
- Return a new method object, with *func* being any callable object; this is the
- function that will be called when the method is called. If this method should
- be bound to an instance, *self* should be the instance and *class* should be the
- class of *self*, otherwise *self* should be *NULL* and *class* should be the
- class which provides the unbound method..
-
-
-.. cfunction:: PyObject* PyMethod_Class(PyObject *meth)
-
- Return the class object from which the method *meth* was created; if this was
- created from an instance, it will be the class of the instance.
-
-
-.. cfunction:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
-
- Macro version of :cfunc:`PyMethod_Class` which avoids error checking.
-
-
-.. 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* if it is bound, otherwise
- return *NULL*.
-
-
-.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
-
- Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
-
-
-.. _moduleobjects:
-
-Module Objects
---------------
-
-.. index:: object: module
-
-There are only a few functions special to module objects.
-
-
-.. cvar:: PyTypeObject PyModule_Type
-
- .. index:: single: ModuleType (in module types)
-
- This instance of :ctype:`PyTypeObject` represents the Python module type. This
- is exposed to Python programs as ``types.ModuleType``.
-
-
-.. cfunction:: int PyModule_Check(PyObject *p)
-
- Return true if *p* is a module object, or a subtype of a module object.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyModule_CheckExact(PyObject *p)
-
- Return true if *p* is a module object, but not a subtype of
- :cdata:`PyModule_Type`.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.0
-
-
-.. 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.
-
- .. versionadded:: 2.0
-
-
-.. 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.
-
- .. versionadded:: 2.0
-
-
-.. _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.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: int PySeqIter_Check(op)
-
- Return true if the type of *op* is :cdata:`PySeqIter_Type`.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: int PyCallIter_Check(op)
-
- Return true if the type of *op* is :cdata:`PyCallIter_Type`.
-
- .. versionadded:: 2.2
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. _descriptor-objects:
-
-Descriptor Objects
-------------------
-
-"Descriptors" are objects that describe some attribute of an object. They are
-found in the dictionary of type objects.
-
-
-.. cvar:: PyTypeObject PyProperty_Type
-
- The type object for the built-in descriptor types.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
-
- .. versionadded:: 2.3
-
-
-.. 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.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
-
- .. versionadded:: 2.2
-
-
-.. _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.
-
- .. versionadded:: 2.3
-
-
-.. _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.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: int PyWeakref_CheckRef(ob)
-
- Return true if *ob* is a reference object.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: int PyWeakref_CheckProxy(ob)
-
- Return true if *ob* is a proxy object.
-
- .. versionadded:: 2.2
-
-
-.. 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`.
-
- .. versionadded:: 2.2
-
-
-.. 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`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
-
- Return the referenced object from a weak reference, *ref*. If the referent is
- no longer live, returns ``None``.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
-
- Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
- error checking.
-
- .. versionadded:: 2.2
-
-
-.. _cobjects:
-
-CObjects
---------
-
-.. index:: object: CObject
-
-Refer to *Extending and Embedding the Python Interpreter*, section 1.12,
-"Providing a C API for an Extension Module," for more information on using these
-objects.
-
-
-.. ctype:: PyCObject
-
- This subtype of :ctype:`PyObject` represents an opaque value, useful for C
- extension modules who need to pass an opaque value (as a :ctype:`void\*`
- pointer) through Python code to other C code. It is often used to make a C
- function pointer defined in one module available to other modules, so the
- regular import mechanism can be used to access C APIs defined in dynamically
- loaded modules.
-
-
-.. cfunction:: int PyCObject_Check(PyObject *p)
-
- Return true if its argument is a :ctype:`PyCObject`.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
-
- Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function
- will be called when the object is reclaimed, unless it is *NULL*.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
-
- Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr*
- function will be called when the object is reclaimed. The *desc* argument can
- be used to pass extra callback data for the destructor function.
-
-
-.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
-
- Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
- created with.
-
-
-.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
-
- Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
- created with.
-
-
-.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
-
- Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
- have an associated destructor. Return true on success, false on failure.
-
-
-.. _cell-objects:
-
-Cell Objects
-------------
-
-"Cell" objects are used to implement variables referenced by multiple scopes.
-For each such variable, a cell object is created to store the value; the local
-variables of each stack frame that references the value contains a reference to
-the cells from outer scopes which also use that variable. When the value is
-accessed, the value contained in the cell is used instead of the cell object
-itself. This de-referencing of the cell object requires support from the
-generated byte-code; these are not automatically de-referenced when accessed.
-Cell objects are not likely to be useful elsewhere.
-
-
-.. ctype:: PyCellObject
-
- The C structure used for cell objects.
-
-
-.. cvar:: PyTypeObject PyCell_Type
-
- The type object corresponding to cell objects.
-
-
-.. cfunction:: int PyCell_Check(ob)
-
- Return true if *ob* is a cell object; *ob* must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_New(PyObject *ob)
-
- Create and return a new cell object containing the value *ob*. The parameter may
- be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
-
- Return the contents of the cell *cell*.
-
-
-.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
-
- Return the contents of the cell *cell*, but without checking that *cell* is
- non-*NULL* and a cell object.
-
-
-.. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)
-
- Set the contents of the cell object *cell* to *value*. This releases the
- reference to any current content of the cell. *value* may be *NULL*. *cell*
- must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
- success, ``0`` will be returned.
-
-
-.. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)
-
- Sets the value of the cell object *cell* to *value*. No reference counts are
- adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
- be a cell object.
-
-
-.. _gen-objects:
-
-Generator Objects
------------------
-
-Generator objects are what Python uses to implement generator iterators. They
-are normally created by iterating over a function that yields values, rather
-than explicitly calling :cfunc:`PyGen_New`.
-
-
-.. ctype:: PyGenObject
-
- The C structure used for generator objects.
-
-
-.. cvar:: PyTypeObject PyGen_Type
-
- The type object corresponding to generator objects
-
-
-.. cfunction:: int PyGen_Check(ob)
-
- Return true if *ob* is a generator object; *ob* must not be *NULL*.
-
-
-.. cfunction:: int PyGen_CheckExact(ob)
-
- Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
- be *NULL*.
-
-
-.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
-
- Create and return a new generator object based on the *frame* object. A
- reference to *frame* is stolen by this function. The parameter must not be
- *NULL*.
-
-
-.. _datetimeobjects:
-
-DateTime Objects
-----------------
-
-Various date and time objects are supplied by the :mod:`datetime` module.
-Before using any of these functions, the header file :file:`datetime.h` must be
-included in your source (note that this is not included by :file:`Python.h`),
-and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a
-pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is
-used by the following macros.
-
-Type-check macros:
-
-
-.. cfunction:: int PyDate_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
- :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDate_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. 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*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
- be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. 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*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTime_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. 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*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. 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*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
- .. versionadded:: 2.4
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
-
- Return the month, as an int from 1 through 12.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
-
- Return the day, as an int from 1 through 31.
-
- .. versionadded:: 2.4
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
-
- Return the minute, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
-
- Return the second, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
-
- Return the microsecond, as an int from 0 through 999999.
-
- .. versionadded:: 2.4
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
-
- Return the minute, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
-
- Return the second, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
-
- Return the microsecond, as an int from 0 through 999999.
-
- .. versionadded:: 2.4
-
-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()``.
-
- .. versionadded:: 2.4
-
-
-.. 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()``.
-
- .. versionadded:: 2.4
-
-
-.. _setobjects:
-
-Set Objects
------------
-
-.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
-
-
-.. index::
- object: set
- object: frozenset
-
-.. versionadded:: 2.5
-
-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)
+Other Objects
+=============
 
- Empty an existing set of all elements.
+.. toctree::
 
+ class.rst
+ function.rst
+ method.rst
+ file.rst
+ module.rst
+ iterator.rst
+ descriptor.rst
+ slice.rst
+ weakref.rst
+ cobject.rst
+ cell.rst
+ gen.rst
+ datetime.rst
+ set.rst
Added: python/trunk/Doc/c-api/datetime.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/datetime.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,238 @@
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDate_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
+ be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTime_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+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.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.4
+
+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.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+ Return the month, as an int from 1 through 12.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+ Return the day, as an int from 1 through 31.
+
+ .. versionadded:: 2.4
+
+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.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+ Return the minute, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+ Return the second, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+ Return the microsecond, as an int from 0 through 999999.
+
+ .. versionadded:: 2.4
+
+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.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+ Return the minute, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+ Return the second, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+ Return the microsecond, as an int from 0 through 999999.
+
+ .. versionadded:: 2.4
+
+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()``.
+
+ .. versionadded:: 2.4
+
+
+.. 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()``.
+
+ .. versionadded:: 2.4
Added: python/trunk/Doc/c-api/descriptor.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/descriptor.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,55 @@
+.. 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.
+
+
+.. cvar:: PyTypeObject PyProperty_Type
+
+ The type object for the built-in descriptor types.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+ .. versionadded:: 2.3
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
+
+ .. versionadded:: 2.2
Added: python/trunk/Doc/c-api/dict.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/dict.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,220 @@
+.. 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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. 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.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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``.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
+
+ Return a new dictionary that contains the same key-value pairs as *p*.
+
+ .. versionadded:: 1.6
+
+
+.. 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)) {
+ int i = PyInt_AS_LONG(value) + 1;
+ PyObject *o = PyInt_FromLong(i);
+ 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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
+
+ .. versionadded:: 2.2
Added: python/trunk/Doc/c-api/file.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/file.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,128 @@
+.. 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`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyFile_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
+ :ctype:`PyFileObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
+
+ .. index:: single: fopen()
+
+ On success, return a new file object that is opened on the file given by
+ *filename*, with a file mode given by *mode*, where *mode* has the same
+ semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.
+
+
+.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
+
+ Create a new :ctype:`PyFileObject` from the already-open standard C file
+ pointer, *fp*. The function *close* will be called when the file should be
+ closed. Return *NULL* on failure.
+
+
+.. cfunction:: FILE* PyFile_AsFile(PyObject *p)
+
+ Return the file object associated with *p* as a :ctype:`FILE\*`.
+
+
+.. 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.
+
+ .. versionadded:: 2.3
+
+
+.. 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.
Added: python/trunk/Doc/c-api/float.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/float.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,86 @@
+.. 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`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyFloat_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
+ :ctype:`PyFloatObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
+
+ Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
+ *NULL* on failure. The *pend* argument is ignored. It remains only for
+ backward compatibility.
+
+
+.. 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`.
+
+ .. versionadded:: 2.6
+
+
+.. cfunction:: double PyFloat_GetMax(void)
+
+ Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
+
+ .. versionadded:: 2.6
+
+
+.. cfunction:: double PyFloat_GetMin(void)
+
+ Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
+
+ .. versionadded:: 2.6
Added: python/trunk/Doc/c-api/function.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/function.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,83 @@
+.. highlightlang:: c
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. ctype:: PyFunctionObject
+
+ The C structure used for functions.
+
+
+.. cvar:: PyTypeObject PyFunction_Type
+
+ .. index:: single: MethodType (in module types)
+
+ This is an instance of :ctype:`PyTypeObject` and represents the Python function
+ type. It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. cfunction:: int PyFunction_Check(PyObject *o)
+
+ Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
+ The parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
+
+ Return a new function object associated with the code object *code*. *globals*
+ must be a dictionary with the global variables accessible to the function.
+
+ The function's docstring, name and *__module__* are retrieved from the code
+ object, the argument defaults and closure are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
+
+ Return the code object associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+ Return the globals dictionary associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
+
+ Return the *__module__* attribute of the function object *op*. This is normally
+ a string containing the module name, but can be set to any other object by
+ Python code.
+
+
+.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+ Return the argument default values of the function object *op*. This can be a
+ tuple of arguments or *NULL*.
+
+
+.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+ Set the argument default values for the function object *op*. *defaults* must be
+ *Py_None* or a tuple.
+
+ Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+ Return the closure associated with the function object *op*. This can be *NULL*
+ or a tuple of cell objects.
+
+
+.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+ Set the closure associated with the function object *op*. *closure* must be
+ *Py_None* or a tuple of cell objects.
+
+ Raises :exc:`SystemError` and returns ``-1`` on failure.
Added: python/trunk/Doc/c-api/gcsupport.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/gcsupport.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,153 @@
+.. 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.
+
+.. An example showing the use of these interfaces can be found in "Supporting the
+.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
+
+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
+ :noindex:
+
+ 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;
+ }
+
+ .. versionadded:: 2.4
+
+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.
Added: python/trunk/Doc/c-api/gen.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/gen.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,38 @@
+.. highlightlang:: c
+
+.. _gen-objects:
+
+Generator Objects
+-----------------
+
+Generator objects are what Python uses to implement generator iterators. They
+are normally created by iterating over a function that yields values, rather
+than explicitly calling :cfunc:`PyGen_New`.
+
+
+.. ctype:: PyGenObject
+
+ The C structure used for generator objects.
+
+
+.. cvar:: PyTypeObject PyGen_Type
+
+ The type object corresponding to generator objects
+
+
+.. cfunction:: int PyGen_Check(ob)
+
+ Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyGen_CheckExact(ob)
+
+ Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
+ be *NULL*.
+
+
+.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
+
+ Create and return a new generator object based on the *frame* object. A
+ reference to *frame* is stolen by this function. The parameter must not be
+ *NULL*.
Modified: python/trunk/Doc/c-api/index.rst
==============================================================================
--- python/trunk/Doc/c-api/index.rst	(original)
+++ python/trunk/Doc/c-api/index.rst	Sat Jan 19 23:08:21 2008
@@ -24,4 +24,4 @@
 concrete.rst
 init.rst
 memory.rst
- newtypes.rst
+ objimpl.rst
Added: python/trunk/Doc/c-api/int.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/int.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,122 @@
+.. highlightlang:: c
+
+.. _intobjects:
+
+Plain Integer Objects
+---------------------
+
+.. index:: object: integer
+
+
+.. ctype:: PyIntObject
+
+ This subtype of :ctype:`PyObject` represents a Python integer object.
+
+
+.. cvar:: PyTypeObject PyInt_Type
+
+ .. index:: single: IntType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
+ This is the same object as ``int`` and ``types.IntType``.
+
+
+.. cfunction:: int PyInt_Check(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyInt_CheckExact(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
+
+ Return a new :ctype:`PyIntObject` or :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 ``'0'``, radix
+ 8 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. If the string represents
+ a number too large to be contained within the machine's :ctype:`long int` type
+ and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
+ returned. If overflow warnings are not being suppressed, *NULL* will be
+ returned in this case.
+
+
+.. cfunction:: PyObject* PyInt_FromLong(long ival)
+
+ Create a new integer object with a value of *ival*.
+
+ 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* PyInt_FromSsize_t(Py_ssize_t ival)
+
+ Create a new integer object with a value of *ival*. If the value exceeds
+ ``LONG_MAX``, a long integer object is returned.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_AsLong(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
+ already one, and then return its value. If there is an error, ``-1`` is
+ returned, and the caller should check ``PyErr_Occurred()`` to find out whether
+ there was an error, or whether the value just happened to be -1.
+
+
+.. cfunction:: long PyInt_AS_LONG(PyObject *io)
+
+ Return the value of the object *io*. No error checking is performed.
+
+
+.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long. This function does not check for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long long, without checking for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ :ctype:`Py_ssize_t`.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_GetMax()
+
+ .. index:: single: LONG_MAX
+
+ Return the system's idea of the largest integer it can handle
+ (:const:`LONG_MAX`, as defined in the system header files).
Added: python/trunk/Doc/c-api/iter.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/iter.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+.. versionadded:: 2.2
+
+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 */
+ }
Added: python/trunk/Doc/c-api/iterator.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/iterator.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,62 @@
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PySeqIter_Check(op)
+
+ Return true if the type of *op* is :cdata:`PySeqIter_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyCallIter_Check(op)
+
+ Return true if the type of *op* is :cdata:`PyCallIter_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
Added: python/trunk/Doc/c-api/list.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/list.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,147 @@
+.. 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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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)``.
Added: python/trunk/Doc/c-api/long.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/long.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,179 @@
+.. highlightlang:: c
+
+.. _longobjects:
+
+Long Integer Objects
+--------------------
+
+.. index:: object: long integer
+
+
+.. ctype:: PyLongObject
+
+ This subtype of :ctype:`PyObject` represents a Python long integer object.
+
+
+.. cvar:: PyTypeObject PyLong_Type
+
+ .. index:: single: LongType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python long integer type.
+ This is the same object as ``long`` and ``types.LongType``.
+
+
+.. cfunction:: int PyLong_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyLongObject` or a subtype of
+ :ctype:`PyLongObject`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyLong_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
+ :ctype:`PyLongObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyLong_FromLong(long v)
+
+ Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
+
+
+.. 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_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 ``'0'``, radix 8 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 long integer value. The first
+ parameter, *u*, points to the first character of the Unicode string, *length*
+ gives the number of characters, and *base* is the radix for the conversion. The
+ radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
+ will be raised.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
+
+ Create a Python integer or long integer from the pointer *p*. The pointer value
+ can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
+
+ .. versionadded:: 1.5.2
+
+ .. versionchanged:: 2.5
+ If the integer is larger than LONG_MAX, a positive long integer is returned.
+
+
+.. 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`, an :exc:`OverflowError` is raised.
+
+
+.. 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_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
+
+ Return a C :ctype:`long long` from a Python long integer. If *pylong* cannot be
+ represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+ Return a C :ctype:`unsigned long long` from a Python long 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.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+
+ Return a C :ctype:`unsigned long` from a Python long integer, without checking
+ for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
+
+ Return a C :ctype:`unsigned long long` from a Python long integer, without
+ checking for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. 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 or long 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`.
+
+ .. versionadded:: 1.5.2
+
+ .. versionchanged:: 2.5
+ For values outside 0..LONG_MAX, both signed and unsigned integers are acccepted.
+
+
Added: python/trunk/Doc/c-api/mapping.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/mapping.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,78 @@
+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+
+.. cfunction:: int PyMapping_Check(PyObject *o)
+
+ Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
+ function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
+
+ .. index:: builtin: len
+
+ Returns the number of keys in object *o* on success, and ``-1`` on failure. For
+ objects that do not provide mapping protocol, this is equivalent to the Python
+ expression ``len(o)``.
+
+
+.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key)
+
+ On success, return ``1`` if the mapping object has the key *key* and ``0``
+ otherwise. This is equivalent to the Python expression ``o.has_key(key)``.
+ 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 ``o.has_key(key)``. 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``.
Added: python/trunk/Doc/c-api/method.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/method.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,65 @@
+.. highlightlang:: c
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+There are some useful functions that are useful for working with method objects.
+
+
+.. 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, PyObject *class)
+
+ Return a new method object, with *func* being any callable object; this is the
+ function that will be called when the method is called. If this method should
+ be bound to an instance, *self* should be the instance and *class* should be the
+ class of *self*, otherwise *self* should be *NULL* and *class* should be the
+ class which provides the unbound method..
+
+
+.. cfunction:: PyObject* PyMethod_Class(PyObject *meth)
+
+ Return the class object from which the method *meth* was created; if this was
+ created from an instance, it will be the class of the instance.
+
+
+.. cfunction:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
+
+ Macro version of :cfunc:`PyMethod_Class` which avoids error checking.
+
+
+.. 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* if it is bound, otherwise
+ return *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+ Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
Added: python/trunk/Doc/c-api/module.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/module.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,105 @@
+.. 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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyModule_CheckExact(PyObject *p)
+
+ Return true if *p* is a module object, but not a subtype of
+ :cdata:`PyModule_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.0
+
+
+.. 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.
+
+ .. versionadded:: 2.0
+
+
+.. 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.
+
+ .. versionadded:: 2.0
Deleted: /python/trunk/Doc/c-api/newtypes.rst
==============================================================================
--- /python/trunk/Doc/c-api/newtypes.rst	Sat Jan 19 23:08:21 2008
+++ (empty file)
@@ -1,1911 +0,0 @@
-.. highlightlang:: c
-
-
-.. _newtypes:
-
-*****************************
-Object Implementation Support
-*****************************
-
-This chapter describes the functions, types, and macros used when defining new
-object types.
-
-
-.. _allocating-objects:
-
-Allocating Objects on the Heap
-==============================
-
-
-.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
-
-
-.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
-
-
-.. cfunction:: void _PyObject_Del(PyObject *op)
-
-
-.. 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.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. 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. If *doc* is non-*NULL*, it will be used to define the
- docstring for the module.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. 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. 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.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. cvar:: PyObject _Py_NoneStruct
-
- Object which is visible in Python as ``None``. This should only be accessed
- using the ``Py_None`` macro, which evaluates to a pointer to this object.
-
-
-.. _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`:
-
-
-.. 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`.
-
-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:: 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.
-
-
-.. data:: METH_OLDARGS
-
- This calling convention is deprecated. The method must be of type
- :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given,
- a single object if exactly one argument is given, and a tuple of objects if more
- than one argument is given. There is no way for a function using this
- convention to distinguish between a call with multiple arguments and a call with
- a tuple as the only 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.
-
- .. versionadded:: 2.3
-
-
-.. 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.
-
- .. versionadded:: 2.3
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
-
-.. _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, coercion, 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 by
- the print statement.
-
- 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_CHECKTYPES
-
- If this bit is set, the binary and ternary operations in the
- :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
- arguments of arbitrary object types, and do their own type conversions if
- needed. If this bit is clear, those operations require that all arguments have
- the current type as their type, and the caller is supposed to perform a coercion
- operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
- :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
- :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
- :attr:`nb_xor`, and :attr:`nb_or`.
-
-
- .. 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_Del``,
- 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. Almost every function below 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_nonzero; /* Used by PyObject_IsTrue */
- unaryfunc nb_invert;
- binaryfunc nb_lshift;
- binaryfunc nb_rshift;
- binaryfunc nb_and;
- binaryfunc nb_xor;
- binaryfunc nb_or;
- coercion nb_coerce; /* Used by the coerce() funtion */
- unaryfunc nb_int;
- unaryfunc nb_long;
- unaryfunc nb_float;
- unaryfunc nb_oct;
- unaryfunc nb_hex;
-
- /* Added in release 2.0 */
- 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;
-
- /* Added in release 2.2 */
- binaryfunc nb_floor_divide;
- binaryfunc nb_true_divide;
- binaryfunc nb_inplace_floor_divide;
- binaryfunc nb_inplace_true_divide;
-
- /* Added in release 2.5 */
- unaryfunc nb_index;
- } PyNumberMethods;
-
-
-Binary and ternary functions may receive different kinds of arguments, depending
-on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
-
-- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
- guaranteed to be of the object's type; the caller is responsible for calling
- the coercion method specified by the :attr:`nb_coerce` member to convert the
- arguments:
-
- .. cmember:: coercion PyNumberMethods.nb_coerce
-
- This function is used by :cfunc:`PyNumber_CoerceEx` and has the same
- signature. The first argument is always a pointer to an object of the
- defined type. If the conversion to a common "larger" type is possible, the
- function replaces the pointers with new references to the converted objects
- and returns ``0``. If the conversion is not possible, the function returns
- ``1``. If an error condition is set, it will return ``-1``.
-
-- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, 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). This is the recommended way; with Python 3.0 coercion will
- disappear completely.
-
-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 at 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.
-
-
-.. _supporting-iteration:
-
-Supporting the Iterator Protocol
-================================
-
-
-.. _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.
-
-.. An example showing the use of these interfaces can be found in "Supporting the
-.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
-
-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;
- }
-
- .. versionadded:: 2.4
-
-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.
-
Added: python/trunk/Doc/c-api/none.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/none.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,28 @@
+.. 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.
+
+ .. versionadded:: 2.4
+
Added: python/trunk/Doc/c-api/number.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/number.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,311 @@
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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``.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)
+
+ .. index:: builtin: coerce
+
+ This function takes the addresses of two variables of type :ctype:`PyObject\*`.
+ If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment
+ their reference count and return ``0`` (success). If the objects can be
+ converted to a common numeric type, replace ``*p1`` and ``*p2`` by their
+ converted value (with 'new' reference counts), and return ``0``. If no
+ conversion is possible, or if some other error occurs, return ``-1`` (failure)
+ and don't increment the reference counts. The call ``PyNumber_Coerce(&o1,
+ &o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.
+
+
+.. cfunction:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)
+
+ This function is similar to :cfunc:`PyNumber_Coerce`, except that it returns
+ ``1`` when the conversion is not possible and when no error is raised.
+ Reference counts are still not increased in this case.
+
+
+.. 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 a long 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.
+
+ .. versionadded:: 2.5
+
+
+.. 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.
+
+ .. versionadded:: 2.5
+
+
+.. 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).
+
+ .. versionadded:: 2.5
Added: python/trunk/Doc/c-api/objbuffer.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/objbuffer.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,46 @@
+.. 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.
+
+ .. versionadded:: 1.6
+
+
+.. 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.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
+
+ Returns ``1`` if *o* supports the single-segment readable buffer interface.
+ Otherwise returns ``0``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a writeable 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.
+
+ .. versionadded:: 1.6
+
Added: python/trunk/Doc/c-api/object.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/object.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,357 @@
+.. 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
+ by the :keyword:`print` statement.
+
+
+.. 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.
+
+ .. versionadded:: 2.1
+
+ .. versionchanged:: 2.2
+ Support for a tuple as the second argument added.
+
+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.
+
+ .. versionadded:: 2.1
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support a tuple as the second argument.
+
+
+.. 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)
+
+ .. index:: builtin: apply
+
+ 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
+ ``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+
+ .. index:: builtin: apply
+
+ Call a callable Python object *callable_object*, with arguments given by the
+ tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
+ the result of the call on success, or *NULL* on failure. This is the equivalent
+ of the Python expression ``apply(callable_object, args)`` or
+ ``callable_object(*args)``.
+
+
+.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
+
+ .. index:: builtin: apply
+
+ 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 ``apply(callable, args)`` or
+ ``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.
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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*.
+
+ .. versionadded:: 2.2
+
+
+.. 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:: int PyObject_AsFileDescriptor(PyObject *o)
+
+ Derives a file descriptor from a Python object. If the object is an integer or
+ long integer, its value is returned. If not, the object's :meth:`fileno` method
+ is called if it exists; the method must return an integer or long integer, which
+ is returned as the file descriptor value. Returns ``-1`` on failure.
+
+
+.. 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.
Copied: python/trunk/Doc/c-api/objimpl.rst (from r60093, python/trunk/Doc/c-api/newtypes.rst)
==============================================================================
--- python/trunk/Doc/c-api/newtypes.rst	(original)
+++ python/trunk/Doc/c-api/objimpl.rst	Sat Jan 19 23:08:21 2008
@@ -10,1902 +10,9 @@
 This chapter describes the functions, types, and macros used when defining new
 object types.
 
+.. toctree::
 
-.. _allocating-objects:
-
-Allocating Objects on the Heap
-==============================
-
-
-.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
-
-
-.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
-
-
-.. cfunction:: void _PyObject_Del(PyObject *op)
-
-
-.. 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.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. 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. If *doc* is non-*NULL*, it will be used to define the
- docstring for the module.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. 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. 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.
-
- .. versionchanged:: 2.3
- Older versions of Python did not support *NULL* as the value for the *methods*
- argument.
-
-
-.. cvar:: PyObject _Py_NoneStruct
-
- Object which is visible in Python as ``None``. This should only be accessed
- using the ``Py_None`` macro, which evaluates to a pointer to this object.
-
-
-.. _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`:
-
-
-.. 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`.
-
-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:: 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.
-
-
-.. data:: METH_OLDARGS
-
- This calling convention is deprecated. The method must be of type
- :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given,
- a single object if exactly one argument is given, and a tuple of objects if more
- than one argument is given. There is no way for a function using this
- convention to distinguish between a call with multiple arguments and a call with
- a tuple as the only 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.
-
- .. versionadded:: 2.3
-
-
-.. 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.
-
- .. versionadded:: 2.3
-
-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.
-
- .. versionadded:: 2.4
-
-
-.. 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.
-
-
-.. _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, coercion, 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 by
- the print statement.
-
- 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_CHECKTYPES
-
- If this bit is set, the binary and ternary operations in the
- :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
- arguments of arbitrary object types, and do their own type conversions if
- needed. If this bit is clear, those operations require that all arguments have
- the current type as their type, and the caller is supposed to perform a coercion
- operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
- :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
- :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
- :attr:`nb_xor`, and :attr:`nb_or`.
-
-
- .. 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_Del``,
- 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. Almost every function below 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_nonzero; /* Used by PyObject_IsTrue */
- unaryfunc nb_invert;
- binaryfunc nb_lshift;
- binaryfunc nb_rshift;
- binaryfunc nb_and;
- binaryfunc nb_xor;
- binaryfunc nb_or;
- coercion nb_coerce; /* Used by the coerce() funtion */
- unaryfunc nb_int;
- unaryfunc nb_long;
- unaryfunc nb_float;
- unaryfunc nb_oct;
- unaryfunc nb_hex;
-
- /* Added in release 2.0 */
- 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;
-
- /* Added in release 2.2 */
- binaryfunc nb_floor_divide;
- binaryfunc nb_true_divide;
- binaryfunc nb_inplace_floor_divide;
- binaryfunc nb_inplace_true_divide;
-
- /* Added in release 2.5 */
- unaryfunc nb_index;
- } PyNumberMethods;
-
-
-Binary and ternary functions may receive different kinds of arguments, depending
-on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
-
-- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
- guaranteed to be of the object's type; the caller is responsible for calling
- the coercion method specified by the :attr:`nb_coerce` member to convert the
- arguments:
-
- .. cmember:: coercion PyNumberMethods.nb_coerce
-
- This function is used by :cfunc:`PyNumber_CoerceEx` and has the same
- signature. The first argument is always a pointer to an object of the
- defined type. If the conversion to a common "larger" type is possible, the
- function replaces the pointers with new references to the converted objects
- and returns ``0``. If the conversion is not possible, the function returns
- ``1``. If an error condition is set, it will return ``-1``.
-
-- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, 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). This is the recommended way; with Python 3.0 coercion will
- disappear completely.
-
-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 at 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.
-
-
-.. _supporting-iteration:
-
-Supporting the Iterator Protocol
-================================
-
-
-.. _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.
-
-.. An example showing the use of these interfaces can be found in "Supporting the
-.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
-
-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;
- }
-
- .. versionadded:: 2.4
-
-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.
-
+ allocation.rst
+ structures.rst
+ typeobj.rst
+ gcsupport.rst
Added: python/trunk/Doc/c-api/sequence.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/sequence.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,166 @@
+.. 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*.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.3
+
+
+.. 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.
Added: python/trunk/Doc/c-api/set.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/set.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,148 @@
+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
+
+
+.. index::
+ object: set
+ object: frozenset
+
+.. versionadded:: 2.5
+
+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.
Added: python/trunk/Doc/c-api/slice.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/slice.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,56 @@
+.. 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.
+
+ .. versionadded:: 2.3
Added: python/trunk/Doc/c-api/string.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/string.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,260 @@
+.. 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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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:
+
+ .. % This should be exactly the same as the table in PyErr_Format.
+ .. % One should just refer to the other.
+ .. % 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_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+ Encode the :ctype:`char` buffer of the given size by passing it to the codec
+ registered for *encoding* and return a 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.
Added: python/trunk/Doc/c-api/structures.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/structures.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,212 @@
+.. 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`:
+
+
+.. 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`.
+
+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:: 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.
+
+
+.. data:: METH_OLDARGS
+
+ This calling convention is deprecated. The method must be of type
+ :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given,
+ a single object if exactly one argument is given, and a tuple of objects if more
+ than one argument is given. There is no way for a function using this
+ convention to distinguish between a call with multiple arguments and a call with
+ a tuple as the only 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.
+
+ .. versionadded:: 2.3
+
+
+.. 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.
+
+ .. versionadded:: 2.3
+
+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.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
Added: python/trunk/Doc/c-api/tuple.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/tuple.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,117 @@
+.. 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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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)``.
+
+ .. versionadded:: 2.4
+
+
+.. 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`.
+
+ .. versionchanged:: 2.2
+ Removed unused third parameter, *last_is_sticky*.
Added: python/trunk/Doc/c-api/type.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/type.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,76 @@
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. 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`.
+
+ .. versionadded:: 2.0
+
+
+.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
+
+ Return true if *a* is a subtype of *b*.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
+
+ .. versionadded:: 2.2
+
+
+.. 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.
+
+ .. versionadded:: 2.2
Added: python/trunk/Doc/c-api/typeobj.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/typeobj.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,1425 @@
+.. 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, coercion, 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 by
+ the print statement.
+
+ 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_CHECKTYPES
+
+ If this bit is set, the binary and ternary operations in the
+ :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
+ arguments of arbitrary object types, and do their own type conversions if
+ needed. If this bit is clear, those operations require that all arguments have
+ the current type as their type, and the caller is supposed to perform a coercion
+ operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
+ :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
+ :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
+ :attr:`nb_xor`, and :attr:`nb_or`.
+
+
+ .. 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_Del``,
+ 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. Almost every function below 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_nonzero; /* Used by PyObject_IsTrue */
+ unaryfunc nb_invert;
+ binaryfunc nb_lshift;
+ binaryfunc nb_rshift;
+ binaryfunc nb_and;
+ binaryfunc nb_xor;
+ binaryfunc nb_or;
+ coercion nb_coerce; /* Used by the coerce() funtion */
+ unaryfunc nb_int;
+ unaryfunc nb_long;
+ unaryfunc nb_float;
+ unaryfunc nb_oct;
+ unaryfunc nb_hex;
+
+ /* Added in release 2.0 */
+ 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;
+
+ /* Added in release 2.2 */
+ binaryfunc nb_floor_divide;
+ binaryfunc nb_true_divide;
+ binaryfunc nb_inplace_floor_divide;
+ binaryfunc nb_inplace_true_divide;
+
+ /* Added in release 2.5 */
+ unaryfunc nb_index;
+ } PyNumberMethods;
+
+
+Binary and ternary functions may receive different kinds of arguments, depending
+on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
+
+- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
+ guaranteed to be of the object's type; the caller is responsible for calling
+ the coercion method specified by the :attr:`nb_coerce` member to convert the
+ arguments:
+
+ .. cmember:: coercion PyNumberMethods.nb_coerce
+
+ This function is used by :cfunc:`PyNumber_CoerceEx` and has the same
+ signature. The first argument is always a pointer to an object of the
+ defined type. If the conversion to a common "larger" type is possible, the
+ function replaces the pointers with new references to the converted objects
+ and returns ``0``. If the conversion is not possible, the function returns
+ ``1``. If an error condition is set, it will return ``-1``.
+
+- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, 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). This is the recommended way; with Python 3.0 coercion will
+ disappear completely.
+
+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 at 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.
Added: python/trunk/Doc/c-api/unicode.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/unicode.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,804 @@
+.. highlightlang:: c
+
+.. _unicodeobjects:
+
+Unicode Objects and Codecs
+--------------------------
+
+.. sectionauthor:: Marc-Andre Lemburg <mal at 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 ``unicode`` and ``types.UnicodeType``.
+
+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.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
+
+ Return true if the object *o* is a Unicode object, but not an instance of a
+ subtype.
+
+ .. versionadded:: 2.2
+
+
+.. 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:: 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*.
+
+ .. versionadded:: 2.4
+
+
+.. 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.
+
+ .. versionadded:: 2.6
+
+
+.. 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*.
+
+ .. versionadded:: 2.6
+
+
+.. 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.
+
+ .. versionadded:: 2.6
+
+
+.. 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.
+
+ .. versionadded:: 2.6
+
+
+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.
+
+ 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*.
+
+ .. versionadded:: 2.4
+
+
+.. 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".
+
+ .. versionchanged:: 2.4
+ Allowed unicode string as mapping argument.
+
+
+.. 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*.
+
+ .. versionadded:: 2.5
+
+
+.. 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.
Added: python/trunk/Doc/c-api/weakref.rst
==============================================================================
--- (empty file)
+++ python/trunk/Doc/c-api/weakref.rst	Sat Jan 19 23:08:21 2008
@@ -0,0 +1,76 @@
+.. 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.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyWeakref_CheckRef(ob)
+
+ Return true if *ob* is a reference object.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyWeakref_CheckProxy(ob)
+
+ Return true if *ob* is a proxy object.
+
+ .. versionadded:: 2.2
+
+
+.. 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`.
+
+ .. versionadded:: 2.2
+
+
+.. 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`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
+
+ Return the referenced object from a weak reference, *ref*. If the referent is
+ no longer live, returns ``None``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
+
+ Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
+ error checking.
+
+ .. versionadded:: 2.2
