2.2.5 Abstract Protocol SupportPython supports a variety of abstract `protocols;' the specific interfaces provided to use these interfaces are documented in the Python/C API Reference Manual in the chapter ``Abstract Objects Layer.'' A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence protocols have been part of Python since the beginning. Other protocols have been added over time. For protocols which depend on several handler routines from the type implementation, the older protocols have been defined as optional blocks of handlers referenced by the type object. For newer protocols there are additional slots in the main type object, with a flag bit being set to indicate that the slots are present and should be checked by the interpreter. (The flag bit does not indicate that the slot values are non-NULL. The flag may be set to indicate the presence of a slot, but a slot may still be unfilled.)
PyNumberMethods tp_as_number; PySequenceMethods tp_as_sequence; PyMappingMethods tp_as_mapping; If you wish your object to be able to act like a number, a sequence, or a mapping object, then you place the address of a structure that implements the C type PyNumberMethods, PySequenceMethods, or PyMappingMethods, respectively. It is up to you to fill in this structure with appropriate values. You can find examples of the use of each of these in the Objects directory of the Python source distribution.
hashfunc tp_hash; This function, if you choose to provide it, should return a hash number for an instance of your data type. Here is a moderately pointless example:
static long newdatatype_hash(newdatatypeobject *obj) { long result; result = obj->obj_UnderlyingDatatypePtr->size; result = result * 3; return result; }
ternaryfunc tp_call;
This function is called when an instance of your data type is "called",
for example, if This function takes three arguments:
Here is a desultory example of the implementation of the call function.
/* Implement the call function. * obj1 is the instance receiving the call. * obj2 is a tuple containing the arguments to the call, in this * case 3 strings. */ static PyObject * newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other) { PyObject *result; char *arg1; char *arg2; char *arg3; if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) { return NULL; } result = PyString_FromFormat( "Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n", obj->obj_UnderlyingDatatypePtr->size, arg1, arg2, arg3); printf("\%s", PyString_AS_STRING(result)); return result; } XXX some fields need to be added here...
/* Added in release 2.2 */ /* Iterators */ getiterfunc tp_iter; iternextfunc tp_iternext;
These functions provide support for the iterator protocol. Any object
which wishes to support iteration over its contents (which may be
generated during iteration) must implement the
For an object which represents an iterable collection, the
Iterator objects should implement both handlers. The See About this document... for information on suggesting changes. |