Patch #1671450: add a section about subclassing builtin types to the

"extending and embedding" tutorial.
 (backport from rev. 54150)

Doc/ext/newtypes.tex

@@ -489,7 +489,6 @@ this?
   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 @@ That's pretty much it.  If we had written custom \member{tp_alloc} or
 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}}
 

Doc/ext/shoddy.c

@@ -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);
+}

Misc/NEWS

@@ -457,6 +457,9 @@ Tests
 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.