3.1.Finalization and De-allocation¶

destructortp_dealloc;

This function is called when the reference count of the instance of your type isreduced to zero and the Python interpreter wants to reclaim it. If your typehas memory to free or other clean-up to perform, you can put it here. Theobject itself needs to be freed here as well. Here is an example of thisfunction:

staticvoidnewdatatype_dealloc(newdatatypeobject*obj){free(obj->obj_UnderlyingDatatypePtr);Py_TYPE(obj)->tp_free((PyObject*)obj);}

If your type supports garbage collection, the destructor should callPyObject_GC_UnTrack() before clearing any member fields:

staticvoidnewdatatype_dealloc(newdatatypeobject*obj){PyObject_GC_UnTrack(obj);Py_CLEAR(obj->other_obj);...Py_TYPE(obj)->tp_free((PyObject*)obj);}

One important requirement of the deallocator function is that it leaves anypending exceptions alone. This is important since deallocators are frequentlycalled as the interpreter unwinds the Python stack; when the stack is unwounddue to an exception (rather than normal returns), nothing is done to protect thedeallocators from seeing that an exception has already been set. Any actionswhich a deallocator performs which may cause additional Python code to beexecuted may detect that an exception has been set. This can lead to misleadingerrors from the interpreter. The proper way to protect against this is to savea pending exception before performing the unsafe action, and restoring it whendone. This can be done using thePyErr_Fetch() andPyErr_Restore() functions:

staticvoidmy_dealloc(PyObject*obj){MyObject*self=(MyObject*)obj;PyObject*cbresult;if(self->my_callback!=NULL){PyObject*err_type,*err_value,*err_traceback;/* This saves the current exception state */PyErr_Fetch(&err_type,&err_value,&err_traceback);cbresult=PyObject_CallNoArgs(self->my_callback);if(cbresult==NULL)PyErr_WriteUnraisable(self->my_callback);elsePy_DECREF(cbresult);/* This restores the saved exception state */PyErr_Restore(err_type,err_value,err_traceback);Py_DECREF(self->my_callback);}Py_TYPE(obj)->tp_free((PyObject*)self);}

3.2.Object Presentation¶

In Python, there are two ways to generate a textual representation of an object:therepr() function, and thestr() function. (Theprint()function just callsstr().) These handlers are both optional.

reprfunctp_repr;reprfunctp_str;

Thetp_repr handler should return a string object containing arepresentation of the instance for which it is called. Here is a simpleexample:

staticPyObject*newdatatype_repr(newdatatypeobject*obj){returnPyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",obj->obj_UnderlyingDatatypePtr->size);}

If notp_repr handler is specified, the interpreter will supply arepresentation that uses the type’stp_name and a uniquely identifyingvalue for the object.

Thetp_str handler is tostr() what thetp_repr handlerdescribed above is torepr(); that is, it is called when Python code callsstr() on an instance of your object. Its implementation is very similarto thetp_repr function, but the resulting string is intended for humanconsumption. Iftp_str is not specified, thetp_repr handler isused instead.

Here is a simple example:

staticPyObject*newdatatype_str(newdatatypeobject*obj){returnPyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",obj->obj_UnderlyingDatatypePtr->size);}

3.3.Attribute Management¶

For every object which can support attributes, the corresponding type mustprovide the functions that control how the attributes are resolved. There needsto be a function which can retrieve attributes (if any are defined), and anotherto set attributes (if setting attributes is allowed). Removing an attribute isa special case, for which the new value passed to the handler isNULL.

Python supports two pairs of attribute handlers; a type that supports attributesonly needs to implement the functions for one pair. The difference is that onepair takes the name of the attribute as achar*, while the otheraccepts aPyObject*. Each type can use whichever pair makes moresense for the implementation’s convenience.

getattrfunctp_getattr;/* char * version */setattrfunctp_setattr;/* ... */getattrofunctp_getattro;/* PyObject * version */setattrofunctp_setattro;

If accessing attributes of an object is always a simple operation (this will beexplained shortly), there are generic implementations which can be used toprovide thePyObject* version of the attribute management functions.The actual need for type-specific attribute handlers almost completelydisappeared starting with Python 2.2, though there are many examples which havenot been updated to use some of the new generic mechanism that is available.

structPyMethodDef*tp_methods;structPyMemberDef*tp_members;structPyGetSetDef*tp_getset;

typedefstructPyMethodDef{constchar*ml_name;/* method name */PyCFunctionml_meth;/* implementation function */intml_flags;/* flags */constchar*ml_doc;/* docstring */}PyMethodDef;

typedefstructPyMemberDef{constchar*name;inttype;intoffset;intflags;constchar*doc;}PyMemberDef;

staticPyObject*newdatatype_getattr(newdatatypeobject*obj,char*name){if(strcmp(name,"data")==0){returnPyLong_FromLong(obj->data);}PyErr_Format(PyExc_AttributeError,"'%.100s' object has no attribute '%.400s'",Py_TYPE(obj)->tp_name,name);returnNULL;}

staticintnewdatatype_setattr(newdatatypeobject*obj,char*name,PyObject*v){PyErr_Format(PyExc_RuntimeError,"Read-only attribute: %s",name);return-1;}

3.4.Object Comparison¶

richcmpfunctp_richcompare;

Thetp_richcompare handler is called when comparisons are needed. It isanalogous to therich comparison methods, like__lt__(), and also called byPyObject_RichCompare() andPyObject_RichCompareBool().

This function is called with two Python objects and the operator as arguments,where the operator is one ofPy_EQ,Py_NE,Py_LE,Py_GE,Py_LT orPy_GT. It should compare the two objects with respect to thespecified operator and returnPy_True orPy_False if the comparison issuccessful,Py_NotImplemented to indicate that comparison is notimplemented and the other object’s comparison method should be tried, orNULLif an exception was set.

Here is a sample implementation, for a datatype that is considered equal if thesize of an internal pointer is equal:

staticPyObject*newdatatype_richcmp(newdatatypeobject*obj1,newdatatypeobject*obj2,intop){PyObject*result;intc,size1,size2;/* code to make sure that both arguments are of type       newdatatype omitted */size1=obj1->obj_UnderlyingDatatypePtr->size;size2=obj2->obj_UnderlyingDatatypePtr->size;switch(op){casePy_LT:c=size1<size2;break;casePy_LE:c=size1<=size2;break;casePy_EQ:c=size1==size2;break;casePy_NE:c=size1!=size2;break;casePy_GT:c=size1>size2;break;casePy_GE:c=size1>=size2;break;}result=c?Py_True:Py_False;Py_INCREF(result);returnresult;}

3.5.Abstract Protocol Support¶

Python supports a variety ofabstract ‘protocols;’ the specific interfacesprovided to use these interfaces are documented inAbstract Objects Layer.

A number of these abstract interfaces were defined early in the development ofthe Python implementation. In particular, the number, mapping, and sequenceprotocols have been part of Python since the beginning. Other protocols havebeen added over time. For protocols which depend on several handler routinesfrom the type implementation, the older protocols have been defined as optionalblocks of handlers referenced by the type object. For newer protocols there areadditional slots in the main type object, with a flag bit being set to indicatethat the slots are present and should be checked by the interpreter. (The flagbit does not indicate that the slot values are non-NULL. The flag may be setto 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 amapping object, then you place the address of a structure that implements the CtypePyNumberMethods,PySequenceMethods, orPyMappingMethods, respectively. It is up to you to fill in thisstructure with appropriate values. You can find examples of the use of each ofthese in theObjects directory of the Python source distribution.

hashfunctp_hash;

This function, if you choose to provide it, should return a hash number for aninstance of your data type. Here is a simple example:

staticPy_hash_tnewdatatype_hash(newdatatypeobject*obj){Py_hash_tresult;result=obj->some_size+32767*obj->some_number;if(result==-1)result=-2;returnresult;}

Py_hash_t is a signed integer type with a platform-varying width.Returning-1 fromtp_hash indicates an error,which is why you should be careful to avoid returning it when hash computationis successful, as seen above.

ternaryfunctp_call;

This function is called when an instance of your data type is “called”, forexample, ifobj1 is an instance of your data type and the Python scriptcontainsobj1('hello'), thetp_call handler is invoked.

This function takes three arguments:

1. self is the instance of the data type which is the subject of the call.If the call isobj1('hello'), thenself isobj1.

2. args is a tuple containing the arguments to the call. You can usePyArg_ParseTuple() to extract the arguments.

3. kwds is a dictionary of keyword arguments that were passed. If this isnon-NULL and you support keyword arguments, usePyArg_ParseTupleAndKeywords() to extract the arguments. If youdo not want to support keyword arguments and this is non-NULL, raise aTypeError with a message saying that keyword arguments are not supported.

Here is a toytp_call implementation:

staticPyObject*newdatatype_call(newdatatypeobject*obj,PyObject*args,PyObject*kwds){PyObject*result;constchar*arg1;constchar*arg2;constchar*arg3;if(!PyArg_ParseTuple(args,"sss:call",&arg1,&arg2,&arg3)){returnNULL;}result=PyUnicode_FromFormat("Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",obj->obj_UnderlyingDatatypePtr->size,arg1,arg2,arg3);returnresult;}

/* Iterators */getiterfunctp_iter;iternextfunctp_iternext;

These functions provide support for the iterator protocol. Both handlerstake exactly one parameter, the instance for which they are being called,and return a new reference. In the case of an error, they should set anexception and returnNULL.tp_iter correspondsto the Python__iter__() method, whiletp_iternextcorresponds to the Python__next__() method.

Anyiterable object must implement thetp_iterhandler, which must return aniterator object. Here the same guidelinesapply as for Python classes:

• For collections (such as lists and tuples) which can support multipleindependent iterators, a new iterator should be created and returned byeach call totp_iter.

• Objects which can only be iterated over once (usually due to side effects ofiteration, such as file objects) can implementtp_iterby returning a new reference to themselves – and should also thereforeimplement thetp_iternext handler.

Anyiterator object should implement bothtp_iterandtp_iternext. An iterator’stp_iter handler should return a new referenceto the iterator. Itstp_iternext handler shouldreturn a new reference to the next object in the iteration, if there is one.If the iteration has reached the end,tp_iternextmay returnNULL without setting an exception, or it may setStopIterationin addition to returningNULL; avoidingthe exception can yield slightly better performance. If an actual erroroccurs,tp_iternext should always set an exceptionand returnNULL.

3.6.Weak Reference Support¶

One of the goals of Python’s weak reference implementation is to allow any typeto participate in the weak reference mechanism without incurring the overhead onperformance-critical objects (such as numbers).

For an object to be weakly referenceable, the extension type must set thePy_TPFLAGS_MANAGED_WEAKREF bit of thetp_flagsfield. The legacytp_weaklistoffset field shouldbe left as zero.

Concretely, here is how the statically declared type object would look:

staticPyTypeObjectTrivialType={PyVarObject_HEAD_INIT(NULL,0)/* ... other members omitted for brevity ... */.tp_flags=Py_TPFLAGS_MANAGED_WEAKREF|...,};

The only further addition is thattp_dealloc needs to clear any weakreferences (by callingPyObject_ClearWeakRefs()):

staticvoidTrivial_dealloc(TrivialObject*self){/* Clear weakrefs first before calling any destructors */PyObject_ClearWeakRefs((PyObject*)self);/* ... remainder of destruction code omitted for brevity ... */Py_TYPE(self)->tp_free((PyObject*)self);}

3.7.More Suggestions¶

In order to learn how to implement any specific method for your new data type,get theCPython source code. Go to theObjects directory,then search the C source files fortp_ plus the function you want(for example,tp_richcompare). You will find examples of the functionyou want to implement.

When you need to verify that an object is a concrete instance of the type youare implementing, use thePyObject_TypeCheck() function. A sample ofits use might be something like the following:

if(!PyObject_TypeCheck(some_object,&MyType)){PyErr_SetString(PyExc_TypeError,"arg #1 not a mything");returnNULL;}