[Python-checkins] r54151 - in python/branches/release25-maint: Doc/ext/newtypes.tex Doc/ext/shoddy.c Misc/NEWS
georg.brandl
python-checkins at python.org
Tue Mar 6 11:03:03 CET 2007
Author: georg.brandl
Date: Tue Mar 6 11:02:59 2007
New Revision: 54151
Added:
python/branches/release25-maint/Doc/ext/shoddy.c
Modified:
python/branches/release25-maint/Doc/ext/newtypes.tex
python/branches/release25-maint/Misc/NEWS
Log:
Patch #1671450: add a section about subclassing builtin types to the
"extending and embedding" tutorial.
(backport from rev. 54150)
Modified: python/branches/release25-maint/Doc/ext/newtypes.tex
==============================================================================
--- python/branches/release25-maint/Doc/ext/newtypes.tex (original)
+++ python/branches/release25-maint/Doc/ext/newtypes.tex Tue Mar 6 11:02:59 2007
@@ -489,7 +489,6 @@
garbage collection, there are calls that can be made to ``untrack''
the object from garbage collection, however, these calls are
advanced and not covered here.}
-\item
\end{itemize}
@@ -930,6 +929,102 @@
collection. Most extensions will use the versions automatically
provided.
+\subsection{Subclassing other types}
+
+It is possible to create new extension types that are derived from existing
+types. It is easiest to inherit from the built in types, since an extension
+can easily use the \class{PyTypeObject} it needs. It can be difficult to
+share these \class{PyTypeObject} structures between extension modules.
+
+In this example we will create a \class{Shoddy} type that inherits from
+the builtin \class{list} type. The new type will be completely compatible
+with regular lists, but will have an additional \method{increment()} method
+that increases an internal counter.
+
+\begin{verbatim}
+>>> import shoddy
+>>> s = shoddy.Shoddy(range(3))
+>>> s.extend(s)
+>>> print len(s)
+6
+>>> print s.increment()
+1
+>>> print s.increment()
+2
+\end{verbatim}
+
+\verbatiminput{shoddy.c}
+
+As you can see, the source code closely resembles the \class{Noddy} examples in previous
+sections. We will break down the main differences between them.
+
+\begin{verbatim}
+typedef struct {
+ PyListObject list;
+ int state;
+} Shoddy;
+\end{verbatim}
+
+The primary difference for derived type objects is that the base type's
+object structure must be the first value. The base type will already
+include the \cfunction{PyObject_HEAD} at the beginning of its structure.
+
+When a Python object is a \class{Shoddy} instance, its \var{PyObject*} pointer
+can be safely cast to both \var{PyListObject*} and \var{Shoddy*}.
+
+\begin{verbatim}
+static int
+Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
+{
+ if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
+ return -1;
+ self->state = 0;
+ return 0;
+}
+\end{verbatim}
+
+In the \member{__init__} method for our type, we can see how to call through
+to the \member{__init__} method of the base type.
+
+This pattern is important when writing a type with custom \member{new} and
+\member{dealloc} methods. The \member{new} method should not actually create the
+memory for the object with \member{tp_alloc}, that will be handled by
+the base class when calling its \member{tp_new}.
+
+When filling out the \cfunction{PyTypeObject} for the \class{Shoddy} type,
+you see a slot for \cfunction{tp_base}. Due to cross platform compiler
+issues, you can't fill that field directly with the \cfunction{PyList_Type};
+it can be done later in the module's \cfunction{init} function.
+
+\begin{verbatim}
+PyMODINIT_FUNC
+initshoddy(void)
+{
+ PyObject *m;
+
+ ShoddyType.tp_base = &PyList_Type;
+ if (PyType_Ready(&ShoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("shoddy", NULL, "Shoddy module");
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&ShoddyType);
+ PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
+}
+\end{verbatim}
+
+Before calling \cfunction{PyType_Ready}, the type structure must have the
+\member{tp_base} slot filled in. When we are deriving a new type, it is
+not necessary to fill out the \member{tp_alloc} slot with
+\cfunction{PyType_GenericNew} -- the allocate function from the base type
+will be inherited.
+
+After that, calling \cfunction{PyType_Ready} and adding the type object
+to the module is the same as with the basic \class{Noddy} examples.
+
+
\section{Type Methods
\label{dnt-type-methods}}
Added: python/branches/release25-maint/Doc/ext/shoddy.c
==============================================================================
--- (empty file)
+++ python/branches/release25-maint/Doc/ext/shoddy.c Tue Mar 6 11:02:59 2007
@@ -0,0 +1,91 @@
+#include <Python.h>
+
+typedef struct {
+ PyListObject list;
+ int state;
+} Shoddy;
+
+
+static PyObject *
+Shoddy_increment(Shoddy *self, PyObject *unused)
+{
+ self->state++;
+ return PyInt_FromLong(self->state);
+}
+
+
+static PyMethodDef Shoddy_methods[] = {
+ {"increment", (PyCFunction)Shoddy_increment, METH_NOARGS,
+ PyDoc_STR("increment state counter")},
+ {NULL, NULL},
+};
+
+static int
+Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
+{
+ if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
+ return -1;
+ self->state = 0;
+ return 0;
+}
+
+
+static PyTypeObject ShoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /* ob_size */
+ "shoddy.Shoddy", /* tp_name */
+ sizeof(Shoddy), /* tp_basicsize */
+ 0, /* tp_itemsize */
+ 0, /* 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 */
+ 0, /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ Shoddy_methods, /* tp_methods */
+ 0, /* tp_members */
+ 0, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ (initproc)Shoddy_init, /* tp_init */
+ 0, /* tp_alloc */
+ 0, /* tp_new */
+};
+
+PyMODINIT_FUNC
+initshoddy(void)
+{
+ PyObject *m;
+
+ ShoddyType.tp_base = &PyList_Type;
+ if (PyType_Ready(&ShoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("shoddy", NULL, "Shoddy module");
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&ShoddyType);
+ PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
+}
Modified: python/branches/release25-maint/Misc/NEWS
==============================================================================
--- python/branches/release25-maint/Misc/NEWS (original)
+++ python/branches/release25-maint/Misc/NEWS Tue Mar 6 11:02:59 2007
@@ -457,6 +457,9 @@
Documentation
-------------
+- Patch #1671450: add a section about subclassing builtin types to the
+ "extending and embedding" tutorial.
+
- Bug #1629125: fix wrong data type (int -> Py_ssize_t) in PyDict_Next
docs.
More information about the Python-checkins
mailing list