|
Let's expend the basic example to add some data and methods. Let's also make the type
usable as a base class. We'll create a new module, noddy2 that adds
these capabilities:
#include <Python.h>
#include "structmember.h"
typedef struct {
PyObject_HEAD
PyObject *first;
PyObject *last;
int number;
} Noddy;
static void
Noddy_dealloc(Noddy* self)
{
Py_XDECREF(self->first);
Py_XDECREF(self->last);
self->ob_type->tp_free((PyObject*)self);
}
static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
Noddy *self;
self = (Noddy *)type->tp_alloc(type, 0);
if (self != NULL) {
self->first = PyString_FromString("");
if (self->first == NULL)
{
Py_DECREF(self);
return NULL;
}
self->last = PyString_FromString("");
if (self->last == NULL)
{
Py_DECREF(self);
return NULL;
}
self->number = 0;
}
return (PyObject *)self;
}
static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
PyObject *first=NULL, *last=NULL;
static char *kwlist[] = {"first", "last", "number", NULL};
if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
&first, &last,
&self->number))
return -1;
if (first) {
Py_XDECREF(self->first);
Py_INCREF(first);
self->first = first;
}
if (last) {
Py_XDECREF(self->last);
Py_INCREF(last);
self->last = last;
}
return 0;
}
static PyMemberDef Noddy_members[] = {
{"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
"first name"},
{"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
"last name"},
{"number", T_INT, offsetof(Noddy, number), 0,
"noddy number"},
{NULL} /* Sentinel */
};
static PyObject *
Noddy_name(Noddy* self)
{
static PyObject *format = NULL;
PyObject *args, *result;
if (format == NULL) {
format = PyString_FromString("%s %s");
if (format == NULL)
return NULL;
}
if (self->first == NULL) {
PyErr_SetString(PyExc_AttributeError, "first");
return NULL;
}
if (self->last == NULL) {
PyErr_SetString(PyExc_AttributeError, "last");
return NULL;
}
args = Py_BuildValue("OO", self->first, self->last);
if (args == NULL)
return NULL;
result = PyString_Format(format, args);
Py_DECREF(args);
return result;
}
static PyMethodDef Noddy_methods[] = {
{"name", (PyCFunction)Noddy_name, METH_NOARGS,
"Return the name, combining the first and last name"
},
{NULL} /* Sentinel */
};
static PyTypeObject NoddyType = {
PyObject_HEAD_INIT(NULL)
0, /*ob_size*/
"noddy.Noddy", /*tp_name*/
sizeof(Noddy), /*tp_basicsize*/
0, /*tp_itemsize*/
(destructor)Noddy_dealloc, /*tp_dealloc*/
0, /*tp_print*/
0, /*tp_getattr*/
0, /*tp_setattr*/
0, /*tp_compare*/
0, /*tp_repr*/
0, /*tp_as_number*/
0, /*tp_as_sequence*/
0, /*tp_as_mapping*/
0, /*tp_hash */
0, /*tp_call*/
0, /*tp_str*/
0, /*tp_getattro*/
0, /*tp_setattro*/
0, /*tp_as_buffer*/
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
"Noddy objects", /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
Noddy_methods, /* tp_methods */
Noddy_members, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
(initproc)Noddy_init, /* tp_init */
0, /* tp_alloc */
Noddy_new, /* tp_new */
};
static PyMethodDef module_methods[] = {
{NULL} /* Sentinel */
};
#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy2(void)
{
PyObject* m;
if (PyType_Ready(&NoddyType) < 0)
return;
m = Py_InitModule3("noddy2", module_methods,
"Example module that creates an extension type.");
if (m == NULL)
return;
Py_INCREF(&NoddyType);
PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
}
This version of the module has a number of changes.
We've added an extra include:
#include "structmember.h"
This include provides declarations that we use to handle attributes, as described a bit
later.
The name of the Noddy object structure has been shortened to Noddy. The type object name has been shortened to NoddyType.
The Noddy type now has three data attributes, first, last,
and number. The first and last variables are Python strings
containing first and last names. The number attribute is an integer.
The object structure is updated accordingly:
typedef struct {
PyObject_HEAD
PyObject *first;
PyObject *last;
int number;
} Noddy;
Because we now have data to manage, we have to be more careful about object allocation and
deallocation. At a minimum, we need a deallocation method:
static void
Noddy_dealloc(Noddy* self)
{
Py_XDECREF(self->first);
Py_XDECREF(self->last);
self->ob_type->tp_free((PyObject*)self);
}
which is assigned to the tp_dealloc member:
(destructor)Noddy_dealloc, /*tp_dealloc*/
This method decrements the reference counts of the two Python attributes. We use Py_XDECREF() here because the first and last members could be NULL. It then calls the tp_free member of the object's type to free the object's memory. Note that
the object's type might not be NoddyType, because the object may be an
instance of a subclass.
We want to make sure that the first and last names are initialized to empty strings, so we
provide a new method:
static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
Noddy *self;
self = (Noddy *)type->tp_alloc(type, 0);
if (self != NULL) {
self->first = PyString_FromString("");
if (self->first == NULL)
{
Py_DECREF(self);
return NULL;
}
self->last = PyString_FromString("");
if (self->last == NULL)
{
Py_DECREF(self);
return NULL;
}
self->number = 0;
}
return (PyObject *)self;
}
and install it in the tp_new member:
The new member is responsible for creating (as opposed to initializing) objects of the
type. It is exposed in Python as the __new__() method. See the paper
titled ``Unifying types and classes in Python'' for a detailed discussion of the __new__() method. One reason to implement a new method is to assure the
initial values of instance variables. In this case, we use the new method to make sure that
the initial values of the members first and last
are not NULL. If we didn't care whether the initial values were NULL, we could have used PyType_GenericNew()
as our new method, as we did before. PyType_GenericNew()
initializes all of the instance variable members to NULLs.
The new method is a static method that is passed the type being instantiated and any
arguments passed when the type was called, and that returns the new object created. New
methods always accept positional and keyword arguments, but they often ignore the arguments,
leaving the argument handling to initializer methods. Note that if the type supports
subclassing, the type passed may not be the type being defined. The new method calls the
tp_alloc slot to allocate memory. We don't fill the tp_alloc slot
ourselves. Rather PyType_Ready() fills it for us by inheriting it
from our base class, which is object by default. Most types use the
default allocation.
We provide an initialization function:
static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
PyObject *first=NULL, *last=NULL;
static char *kwlist[] = {"first", "last", "number", NULL};
if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
&first, &last,
&self->number))
return -1;
if (first) {
Py_XDECREF(self->first);
Py_INCREF(first);
self->first = first;
}
if (last) {
Py_XDECREF(self->last);
Py_INCREF(last);
self->last = last;
}
return 0;
}
by filling the tp_init slot.
(initproc)Noddy_init, /* tp_init */
The tp_init slot is exposed in Python as the __init__()
method. It is used to initialize an object after it's created. Unlike the new method, we can't
guarantee that the initializer is called. The initializer isn't called when unpickling objects
and it can be overridden. Our initializer accepts arguments to provide initial values for our
instance. Initializers always accept positional and keyword arguments.
We want to want to expose our instance variables as attributes. There are a number of ways
to do that. The simplest way is to define member definitions:
static PyMemberDef Noddy_members[] = {
{"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
"first name"},
{"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
"last name"},
{"number", T_INT, offsetof(Noddy, number), 0,
"noddy number"},
{NULL} /* Sentinel */
};
and put the definitions in the tp_members slot:
Noddy_members, /* tp_members */
Each member definition has a member name, type, offset, access flags and documentation
string. See the ``Generic Attribute Management'' section below for details.
A disadvantage of this approach is that it doesn't provide a way to restrict the types of
objects that can be assigned to the Python attributes. We expect the first and last names to
be strings, but any Python objects can be assigned. Further, the attributes can be deleted,
setting the C pointers to NULL. Even though we can make sure the
members are initialized to non-NULL values, the members can be set
to NULL if the attributes are deleted.
We define a single method, name, that outputs the objects name as
the concatenation of the first and last names.
static PyObject *
Noddy_name(Noddy* self)
{
static PyObject *format = NULL;
PyObject *args, *result;
if (format == NULL) {
format = PyString_FromString("%s %s");
if (format == NULL)
return NULL;
}
if (self->first == NULL) {
PyErr_SetString(PyExc_AttributeError, "first");
return NULL;
}
if (self->last == NULL) {
PyErr_SetString(PyExc_AttributeError, "last");
return NULL;
}
args = Py_BuildValue("OO", self->first, self->last);
if (args == NULL)
return NULL;
result = PyString_Format(format, args);
Py_DECREF(args);
return result;
}
The method is implemented as a C function that takes a Noddy (or Noddy subclass) instance as the first argument. Methods always take an
instance as the first argument. Methods often take positional and keyword arguments as well,
but in this cased we don't take any and don't need to accept a positional argument tuple or
keyword argument dictionary. This method is equivalent to the Python method:
def name(self):
return "%s %s" % (self.first, self.last)
Note that we have to check for the possibility that our first and last members are NULL. This is because they can
be deleted, in which case they are set to NULL. It would be better
to prevent deletion of these attributes and to restrict the attribute values to be strings.
We'll see how to do that in the next section.
Now that we've defined the method, we need to create an array of method definitions:
static PyMethodDef Noddy_methods[] = {
{"name", (PyCFunction)Noddy_name, METH_NOARGS,
"Return the name, combining the first and last name"
},
{NULL} /* Sentinel */
};
and assign them to the tp_methods slot:
Noddy_methods, /* tp_methods */
Note that we used the METH_NOARGS flag to indicate that the
method is passed no arguments.
Finally, we'll make our type usable as a base class. We've written our methods carefully so
far so that they don't make any assumptions about the type of the object being created or
used, so all we need to do is to add the Py_TPFLAGS_BASETYPE to our
class flag definition:
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
We rename initnoddy() to initnoddy2()
and update the module name passed to Py_InitModule3().
Finally, we update our setup.py file to build the new module:
from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
ext_modules=[
Extension("noddy", ["noddy.c"]),
Extension("noddy2", ["noddy2.c"]),
])
|
