#1189: documentation for tp_as_* structs.

1 files changed, 166 insertions, 15 deletions

diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst
index 7adf969..1d4bfaa 100644
--- a/Doc/c-api/newtypes.rst
+++ b/Doc/c-api/newtypes.rst
@@ -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`.
+
+   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:: PySequenceMethods *tp_as_sequence;
 
-   XXX
+.. cmember:: PyMappingMethods* tp_as_mapping
 
-.. 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`.
 
-   XXX
+   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.
 
 
+.. _number-structs:
+
+Number Object Structures
+========================
+
+.. sectionauthor:: Amaury Forgeot d'Arc
+
+
+.. ctype:: PyNumberMethods
+
+   This structure holds pointers to the functions which an object uses to
+   implement the number protocol.  Each function is used by the function of
+   similar name documented in the :ref:`number` section.
+
+   Here is the structure definition::
+
+       typedef struct {
+            binaryfunc nb_add;
+            binaryfunc nb_subtract;
+            binaryfunc nb_multiply;
+            binaryfunc nb_remainder;
+            binaryfunc nb_divmod;
+            ternaryfunc nb_power;
+            unaryfunc nb_negative;
+            unaryfunc nb_positive;
+            unaryfunc nb_absolute;
+            inquiry nb_bool;
+            unaryfunc nb_invert;
+            binaryfunc nb_lshift;
+            binaryfunc nb_rshift;
+            binaryfunc nb_and;
+            binaryfunc nb_xor;
+            binaryfunc nb_or;
+            int nb_reserved;  /* unused, must be zero */
+            unaryfunc nb_int;
+            unaryfunc nb_long;
+            unaryfunc nb_float;
+            
+            unaryfunc nb_oct; /* not used anymore, must be zero */
+            unaryfunc nb_hex; /* not used anymore, must be zero */
+
+            binaryfunc nb_inplace_add;
+            binaryfunc nb_inplace_subtract;
+            binaryfunc nb_inplace_multiply;
+            binaryfunc nb_inplace_remainder;
+            ternaryfunc nb_inplace_power;
+            binaryfunc nb_inplace_lshift;
+            binaryfunc nb_inplace_rshift;
+            binaryfunc nb_inplace_and;
+            binaryfunc nb_inplace_xor;
+            binaryfunc nb_inplace_or;
+
+            binaryfunc nb_floor_divide;
+            binaryfunc nb_true_divide;
+            binaryfunc nb_inplace_floor_divide;
+            binaryfunc nb_inplace_true_divide;
+
+            unaryfunc nb_index;
+       } PyNumberMethods;
+
+   .. note::
+
+      Binary and ternary functions must check the type of all their operands,
+      and implement the necessary conversions (at least one of the operands is
+      an instance of the defined type).  If the operation is not defined for the
+      given operands, binary and ternary functions must return
+      ``Py_NotImplemented``, if another error occurred they must return ``NULL``
+      and set an exception.
+
+
 .. _mapping-structs:
 
 Mapping Object Structures
 =========================
 
+.. sectionauthor:: Amaury Forgeot d'Arc
+
 
 .. ctype:: PyMappingMethods
 
-   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 set 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``, it can be *NULL* otherwise.
 
-.. 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:
@@ -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: