Index: Doc/c-api/newtypes.rst =================================================================== --- Doc/c-api/newtypes.rst (revision 58227) +++ Doc/c-api/newtypes.rst (working copy) @@ -592,19 +592,36 @@ 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 .. index:: builtin: hash @@ -1401,6 +1418,74 @@ of the library. +.. _number-structs: + +Number Object Structures +======================== + + +.. ctype:: PyNumberMethods + + This structure holds pointers to the functions which an object uses to + implement the number protocol. Each function is used by the function of + similar name documented in the :ref:`number` section. + + Here is the structure definition:: + + typedef struct { + binaryfunc nb_add; + binaryfunc nb_subtract; + binaryfunc nb_multiply; + binaryfunc nb_remainder; + binaryfunc nb_divmod; + ternaryfunc nb_power; + unaryfunc nb_negative; + unaryfunc nb_positive; + unaryfunc nb_absolute; + inquiry nb_bool; + unaryfunc nb_invert; + binaryfunc nb_lshift; + binaryfunc nb_rshift; + binaryfunc nb_and; + binaryfunc nb_xor; + binaryfunc nb_or; + int nb_reserved; /* unused, must be zero */ + unaryfunc nb_int; + unaryfunc nb_long; + unaryfunc nb_float; + + unaryfunc nb_oct; /* not used anymore, must be zero */ + unaryfunc nb_hex; /* not used anymore, must be zero */ + + binaryfunc nb_inplace_add; + binaryfunc nb_inplace_subtract; + binaryfunc nb_inplace_multiply; + binaryfunc nb_inplace_remainder; + ternaryfunc nb_inplace_power; + binaryfunc nb_inplace_lshift; + binaryfunc nb_inplace_rshift; + binaryfunc nb_inplace_and; + binaryfunc nb_inplace_xor; + binaryfunc nb_inplace_or; + + binaryfunc nb_floor_divide; + binaryfunc nb_true_divide; + binaryfunc nb_inplace_floor_divide; + binaryfunc nb_inplace_true_divide; + + unaryfunc nb_index; + } PyNumberMethods; + + .. note:: + + Binary and ternary functions must check the type of all their operands, + and implement the necessary conversions (at least one of the operands is + an instance of the defined type). If the operation is not defined for the + given operands, binary and ternary functions must return + ``Py_NotImplemented``, if another error occurred they must return ``NULL`` + and set an exception condition. + + .. _mapping-structs: Mapping Object Structures @@ -1409,20 +1494,26 @@ .. ctype:: PyMappingMethods - Structure used to hold pointers to the functions used to implement the mapping - protocol for an extension type. + 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 -.. _number-structs: + This function is used by :cfunc:`PyMapping_Length` and + :cfunc:`PyObject_Size`, and has the same signature. This slot may be left to + *NULL* if the object has no defined length. -Number Object Structures -======================== +.. 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``. -.. ctype:: PyNumberMethods +.. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript - Structure used to hold pointers to the functions an extension type uses to - implement the number protocol. + 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: @@ -1433,10 +1524,64 @@ .. 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. If this slot is *NULL*, *nb_add* is tried instead. + +.. 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 the numeric + multiplication. + +.. 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``. + + 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