mirror of https://github.com/python/cpython
#1189: documentation for tp_as_* structs.
This commit is contained in:
Georg Brandl
parent
39763a1674
commit
dd6d0247e9
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue