#1189: documentation for tp_as_* structs.

This commit is contained in:
Georg Brandl 2007-09-24 18:05:08 +00:00
parent 39763a1674
commit dd6d0247e9
1 changed files with 172 additions and 21 deletions

View File

@ -592,17 +592,34 @@ type objects) *must* have the :attr:`ob_size` field.
This field is inherited by subtypes.
.. cmember:: PyNumberMethods *tp_as_number;
.. cmember:: PyNumberMethods* tp_as_number
XXX
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`.
.. cmember:: PySequenceMethods *tp_as_sequence;
The :attr:`tp_as_number` field is not inherited, but the contained fields are
inherited individually.
XXX
.. cmember:: PyMappingMethods *tp_as_mapping;
.. cmember:: PySequenceMethods* tp_as_sequence
XXX
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
@ -1401,28 +1418,106 @@ objects on the thread which called tp_dealloc will not violate any assumptions
of the library.
.. _mapping-structs:
Mapping Object Structures
=========================
.. ctype:: PyMappingMethods
Structure used to hold pointers to the functions used to implement the mapping
protocol for an extension type.
.. _number-structs:
Number Object Structures
========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. ctype:: PyNumberMethods
Structure used to hold pointers to the functions an extension type uses to
implement the number protocol.
This structure holds pointers to the functions which an object uses to
implement the number protocol. Each function is used by the function of
similar name documented in the :ref:`number` section.
Here is the structure definition::
typedef struct {
binaryfunc nb_add;
binaryfunc nb_subtract;
binaryfunc nb_multiply;
binaryfunc nb_remainder;
binaryfunc nb_divmod;
ternaryfunc nb_power;
unaryfunc nb_negative;
unaryfunc nb_positive;
unaryfunc nb_absolute;
inquiry nb_bool;
unaryfunc nb_invert;
binaryfunc nb_lshift;
binaryfunc nb_rshift;
binaryfunc nb_and;
binaryfunc nb_xor;
binaryfunc nb_or;
int nb_reserved; /* unused, must be zero */
unaryfunc nb_int;
unaryfunc nb_long;
unaryfunc nb_float;
unaryfunc nb_oct; /* not used anymore, must be zero */
unaryfunc nb_hex; /* not used anymore, must be zero */
binaryfunc nb_inplace_add;
binaryfunc nb_inplace_subtract;
binaryfunc nb_inplace_multiply;
binaryfunc nb_inplace_remainder;
ternaryfunc nb_inplace_power;
binaryfunc nb_inplace_lshift;
binaryfunc nb_inplace_rshift;
binaryfunc nb_inplace_and;
binaryfunc nb_inplace_xor;
binaryfunc nb_inplace_or;
binaryfunc nb_floor_divide;
binaryfunc nb_true_divide;
binaryfunc nb_inplace_floor_divide;
binaryfunc nb_inplace_true_divide;
unaryfunc nb_index;
} PyNumberMethods;
.. note::
Binary and ternary functions must check the type of all their operands,
and implement the necessary conversions (at least one of the operands is
an instance of the defined type). If the operation is not defined for the
given operands, binary and ternary functions must return
``Py_NotImplemented``, if another error occurred they must return ``NULL``
and set an exception.
.. _mapping-structs:
Mapping Object Structures
=========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. ctype:: PyMappingMethods
This structure holds pointers to the functions which an object uses to
implement the mapping protocol. It has three members:
.. cmember:: lenfunc PyMappingMethods.mp_length
This function is used by :cfunc:`PyMapping_Length` and
:cfunc:`PyObject_Size`, and has the same signature. This slot may be set to
*NULL* if the object has no defined length.
.. cmember:: binaryfunc PyMappingMethods.mp_subscript
This function is used by :cfunc:`PyObject_GetItem` and has the same
signature. This slot must be filled for the :cfunc:`PyMapping_Check`
function to return ``1``, it can be *NULL* otherwise.
.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript
This function is used by :cfunc:`PyObject_SetItem` and has the same
signature. If this slot is *NULL*, the object does not support item
assignment.
.. _sequence-structs:
@ -1430,12 +1525,68 @@ Number Object Structures
Sequence Object Structures
==========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. ctype:: PySequenceMethods
Structure used to hold pointers to the functions which an object uses to
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: