[Python-3000-checkins] r58246 - python/branches/py3k/Doc/c-api/newtypes.rst
georg.brandl
python-3000-checkins at python.org
Mon Sep 24 20:05:09 CEST 2007
Author: georg.brandl
Date: Mon Sep 24 20:05:08 2007
New Revision: 58246
Modified:
python/branches/py3k/Doc/c-api/newtypes.rst
Log:
#1189: documentation for tp_as_* structs.
Modified: python/branches/py3k/Doc/c-api/newtypes.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/newtypes.rst (original)
+++ python/branches/py3k/Doc/c-api/newtypes.rst Mon Sep 24 20:05:08 2007
@@ -592,17 +592,34 @@
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 @@
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 @@
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:
More information about the Python-3000-checkins
mailing list