2. Definición de tipos de extensión: Tutorial
*********************************************

Python le permite al escritor de un módulo de extensión C definir
nuevos tipos que pueden ser manipulados desde el código Python, al
igual que los tipos incorporados "str" y "list". El código para todos
los tipos de extensión sigue un patrón, pero hay algunos detalles que
debe comprender antes de comenzar. Este documento es una introducción
suave al tema.


2.1. Lo Básico
==============

The *CPython* runtime sees all Python objects as variables of type
"PyObject*", which serves as a "base type" for all Python objects. The
"PyObject" structure itself only contains the object's *reference
count* and a pointer to the object's "type object". This is where the
action is; the type object determines which (C) functions get called
by the interpreter when, for instance, an attribute gets looked up on
an object, a method called, or it is multiplied by another object.
These C functions are called "type methods".

Por lo tanto, si desea definir un nuevo tipo de extensión, debe crear
un nuevo objeto de tipo.

Este tipo de cosas solo se pueden explicar con un ejemplo, por lo que
aquí hay un módulo mínimo, pero completo, que define un nuevo tipo
llamado "Custom" dentro de un módulo de extensión C "custom":

Nota:

  Lo que estamos mostrando aquí es la forma tradicional de definir
  tipos de extensión *estáticos*. Debe ser adecuado para la mayoría de
  los usos. La API de C también permite definir tipos de extensiones
  asignadas en el montón utilizando la función "PyType_FromSpec()",
  que no se trata en este tutorial.

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

   typedef struct {
       PyObject_HEAD
       /* Type-specific fields go here. */
   } CustomObject;

   static PyTypeObject CustomType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "custom.Custom",
       .tp_doc = PyDoc_STR("Custom objects"),
       .tp_basicsize = sizeof(CustomObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT,
       .tp_new = PyType_GenericNew,
   };

   static PyModuleDef custommodule = {
       PyModuleDef_HEAD_INIT,
       .m_name = "custom",
       .m_doc = "Example module that creates an extension type.",
       .m_size = -1,
   };

   PyMODINIT_FUNC
   PyInit_custom(void)
   {
       PyObject *m;
       if (PyType_Ready(&CustomType) < 0)
           return NULL;

       m = PyModule_Create(&custommodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&CustomType);
       if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
           Py_DECREF(&CustomType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Ahora, eso es bastante para asimilar a la vez, pero espero que los
fragmentos le resulten familiares del capítulo anterior. Este archivo
define tres cosas:

1. Lo que contiene un **objeto** "Custom": esta es la estructura
   "CustomObject", que se asigna una vez para cada instancia de
   "Custom".

2. Cómo se comporta "Custom" **type**: esta es la estructura
   "CustomType", que define un conjunto de indicadores y punteros de
   función que el intérprete inspecciona cuando se solicitan
   operaciones específicas.

3. Cómo inicializar el módulo "custom": esta es la función
   "PyInit_custom" y la estructura asociada "custommodule".

La primera parte es:

   typedef struct {
       PyObject_HEAD
   } CustomObject;

This is what a Custom object will contain.  "PyObject_HEAD" is
mandatory at the start of each object struct and defines a field
called "ob_base" of type "PyObject", containing a pointer to a type
object and a reference count (these can be accessed using the macros
"Py_TYPE" and "Py_REFCNT" respectively).  The reason for the macro is
to abstract away the layout and to enable additional fields in debug
builds.

Nota:

  No hay punto y coma (;) arriba después de la macro "PyObject_HEAD".
  Tenga cuidado de agregar uno por accidente: algunos compiladores se
  quejarán.

Por supuesto, los objetos generalmente almacenan datos adicionales
además del estándar "PyObject_HEAD" repetitivo; por ejemplo, aquí está
la definición de puntos flotantes del estándar de Python:

   typedef struct {
       PyObject_HEAD
       double ob_fval;
   } PyFloatObject;

La segunda parte es la definición del tipo de objeto.

   static PyTypeObject CustomType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "custom.Custom",
       .tp_doc = PyDoc_STR("Custom objects"),
       .tp_basicsize = sizeof(CustomObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT,
       .tp_new = PyType_GenericNew,
   };

Nota:

  Recomendamos utilizar los inicializadores designados al estilo C99
  como se indica arriba, para evitar enumerar todos los campos
  "PyTypeObject" que no le interesan y también para evitar preocuparse
  por el orden de declaración de los campos.

La definición real de "PyTypeObject" en "object.h" tiene muchos más
campos que la definición anterior. El compilador de C rellenará los
campos restantes con ceros, y es una práctica común no especificarlos
explícitamente a menos que los necesite.

Lo vamos a separar, un campo a la vez:

   PyVarObject_HEAD_INIT(NULL, 0)

Esta línea es obligatoria para inicializar el campo "ob_base"
mencionado anteriormente.

   .tp_name = "custom.Custom",

El nombre de nuestro tipo. Esto aparecerá en la representación textual
predeterminada de nuestros objetos y en algunos mensajes de error, por
ejemplo:

   >>> "" + custom.Custom()
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: can only concatenate str (not "custom.Custom") to str

Tenga en cuenta que el nombre es un nombre punteado que incluye tanto
el nombre del módulo como el nombre del tipo dentro del módulo. El
módulo en este caso es "custom" y el tipo es "Custom", por lo que
establecemos el nombre del tipo en "custom.Custom". Usar la ruta de
importación punteada real es importante para que su tipo sea
compatible con los módulos "pydoc" y "pickle".

   .tp_basicsize = sizeof(CustomObject),
   .tp_itemsize = 0,

Esto es para que Python sepa cuánta memoria asignar al crear
instancias nuevas "Custom". "tp_itemsize" solo se usa para objetos de
tamaño variable y, de lo contrario, debería ser cero.

Nota:

  Si desea que su tipo pueda tener subclases desde Python, y su tipo
  tiene el mismo "tp_basicsize" como su tipo base, puede tener
  problemas con la herencia múltiple. Una subclase de Python de su
  tipo tendrá que enumerar su tipo primero en su "__bases__", o de lo
  contrario no podrá llamar al método de su tipo "__new__()" sin
  obtener un error. Puede evitar este problema asegurándose de que su
  tipo tenga un valor mayor para "tp_basicsize" que su tipo base. La
  mayoría de las veces, esto será cierto de todos modos, porque su
  tipo base será "object", o de lo contrario agregará miembros de
  datos a su tipo base y, por lo tanto, aumentará su tamaño.

Configuramos las banderas de clase a "Py_TPFLAGS_DEFAULT".

   .tp_flags = Py_TPFLAGS_DEFAULT,

Todos los tipos deben incluir esta constante en sus banderas. Habilita
todos los miembros definidos hasta al menos Python 3.3. Si necesita
más miembros, necesitará O (*OR*) las banderas correspondientes.

Proporcionamos una cadena de documentos para el tipo en "tp_doc".

   .tp_doc = PyDoc_STR("Custom objects"),

Para habilitar la creación de objetos, debemos proporcionar un
controlador "tp_new". Este es el equivalente del método Python
"__new__()", pero debe especificarse explícitamente. En este caso,
podemos usar la implementación predeterminada proporcionada por la
función API "PyType_GenericNew()".

   .tp_new = PyType_GenericNew,

Todo lo demás en el archivo debe ser familiar, excepto algún código en
"PyInit_custom()":

   if (PyType_Ready(&CustomType) < 0)
       return;

Esto inicializa el tipo "Custom", completando un número de miembros
con los valores predeterminados apropiados, que incluyen "ob_type" que
inicialmente configuramos en "NULL".

   Py_INCREF(&CustomType);
   if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
       Py_DECREF(&CustomType);
       Py_DECREF(m);
       return NULL;
   }

Esto agrega el tipo al diccionario del módulo. Esto nos permite crear
instancias "Custom" llamando la clase "Custom":

   >>> import custom
   >>> mycustom = custom.Custom()

¡Eso es! Todo lo que queda es construirlo; ponga el código anterior en
un archivo llamado "custom.c" y:

   from distutils.core import setup, Extension
   setup(name="custom", version="1.0",
         ext_modules=[Extension("custom", ["custom.c"])])

en un archivo llamado "setup.py"; luego escribiendo

   $ python setup.py build

en un shell debería producir un archivo "custom.so" en un
subdirectorio; muévete a ese directorio y abre Python --- deberías
poder "import custom" y jugar con objetos personalizados.

Eso no fue tan difícil, ¿verdad?

Por supuesto, el tipo personalizado actual es bastante poco
interesante. No tiene datos y no hace nada. Ni siquiera se puede
subclasificar.

Nota:

  Si bien esta documentación muestra el módulo estándar "distutils"
  para construir extensiones C, se recomienda en casos de uso del
  mundo real utilizar la biblioteca "setuptools" más nueva y mejor
  mantenida. La documentación sobre cómo hacer esto está fuera del
  alcance de este documento y se puede encontrar en la Guía de usuario
  del Empaquetamiento de Python.


2.2. Agregar datos y métodos al ejemplo básico
==============================================

Extendamos el ejemplo básico para agregar algunos datos y métodos.
También hagamos que el tipo sea utilizable como una clase base.
Crearemos un nuevo módulo, "custom2" que agrega estas capacidades:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>
   #include "structmember.h"

   typedef struct {
       PyObject_HEAD
       PyObject *first; /* first name */
       PyObject *last;  /* last name */
       int number;
   } CustomObject;

   static void
   Custom_dealloc(CustomObject *self)
   {
       Py_XDECREF(self->first);
       Py_XDECREF(self->last);
       Py_TYPE(self)->tp_free((PyObject *) self);
   }

   static PyObject *
   Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
   {
       CustomObject *self;
       self = (CustomObject *) type->tp_alloc(type, 0);
       if (self != NULL) {
           self->first = PyUnicode_FromString("");
           if (self->first == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->last = PyUnicode_FromString("");
           if (self->last == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->number = 0;
       }
       return (PyObject *) self;
   }

   static int
   Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
   {
       static char *kwlist[] = {"first", "last", "number", NULL};
       PyObject *first = NULL, *last = NULL, *tmp;

       if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                        &first, &last,
                                        &self->number))
           return -1;

       if (first) {
           tmp = self->first;
           Py_INCREF(first);
           self->first = first;
           Py_XDECREF(tmp);
       }
       if (last) {
           tmp = self->last;
           Py_INCREF(last);
           self->last = last;
           Py_XDECREF(tmp);
       }
       return 0;
   }

   static PyMemberDef Custom_members[] = {
       {"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
        "first name"},
       {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
        "last name"},
       {"number", T_INT, offsetof(CustomObject, number), 0,
        "custom number"},
       {NULL}  /* Sentinel */
   };

   static PyObject *
   Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
   {
       if (self->first == NULL) {
           PyErr_SetString(PyExc_AttributeError, "first");
           return NULL;
       }
       if (self->last == NULL) {
           PyErr_SetString(PyExc_AttributeError, "last");
           return NULL;
       }
       return PyUnicode_FromFormat("%S %S", self->first, self->last);
   }

   static PyMethodDef Custom_methods[] = {
       {"name", (PyCFunction) Custom_name, METH_NOARGS,
        "Return the name, combining the first and last name"
       },
       {NULL}  /* Sentinel */
   };

   static PyTypeObject CustomType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "custom2.Custom",
       .tp_doc = PyDoc_STR("Custom objects"),
       .tp_basicsize = sizeof(CustomObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
       .tp_new = Custom_new,
       .tp_init = (initproc) Custom_init,
       .tp_dealloc = (destructor) Custom_dealloc,
       .tp_members = Custom_members,
       .tp_methods = Custom_methods,
   };

   static PyModuleDef custommodule = {
       PyModuleDef_HEAD_INIT,
       .m_name = "custom2",
       .m_doc = "Example module that creates an extension type.",
       .m_size = -1,
   };

   PyMODINIT_FUNC
   PyInit_custom2(void)
   {
       PyObject *m;
       if (PyType_Ready(&CustomType) < 0)
           return NULL;

       m = PyModule_Create(&custommodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&CustomType);
       if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
           Py_DECREF(&CustomType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Esta versión del módulo tiene una serie de cambios.

Hemos agregado una inclusión adicional:

   #include <structmember.h>

Esto incluye declaraciones que usamos para manejar atributos, como se
describe un poco más adelante.

El tipo "Custom" ahora tiene tres atributos de datos en su estructura
C, *first*, *last* y *number*. Las variables *first* y *last* son
cadenas de caracteres de Python que contienen nombres y apellidos. El
atributo *number* es un entero C.

La estructura del objeto se actualiza en consecuencia:

   typedef struct {
       PyObject_HEAD
       PyObject *first; /* first name */
       PyObject *last;  /* last name */
       int number;
   } CustomObject;

Debido a que ahora tenemos datos para administrar, debemos ser más
cuidadosos con la asignación de objetos y la desasignación. Como
mínimo, necesitamos un método de desasignación:

   static void
   Custom_dealloc(CustomObject *self)
   {
       Py_XDECREF(self->first);
       Py_XDECREF(self->last);
       Py_TYPE(self)->tp_free((PyObject *) self);
   }

que se asigna al miembro "tp_dealloc":

   .tp_dealloc = (destructor) Custom_dealloc,

Este método primero borra los recuentos de referencia de los dos
atributos de Python. "Py_XDECREF()" maneja correctamente el caso donde
su argumento es "NULL" (lo que podría ocurrir aquí si "tp_new" fallara
a mitad de camino). Luego llama al miembro "tp_free" del tipo de
objeto (calculado por "Py_TYPE(self)") para liberar la memoria del
objeto. Tenga en cuenta que el tipo de objeto podría no ser
"CustomType", porque el objeto puede ser una instancia de una
subclase.

Nota:

  La conversión explícita a "destructor" anterior es necesaria porque
  definimos "Custom_dealloc" para tomar un argumento "CustomObject *",
  pero el puntero de función "tp_dealloc" espera recibir un argumento
  "PyObject *". De lo contrario, el compilador emitirá una
  advertencia. Este es un polimorfismo orientado a objetos, en C!

Queremos asegurarnos de que el nombre y el apellido se inicialicen en
cadenas de caracteres vacías, por lo que proporcionamos una
implementación "tp_new":

   static PyObject *
   Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
   {
       CustomObject *self;
       self = (CustomObject *) type->tp_alloc(type, 0);
       if (self != NULL) {
           self->first = PyUnicode_FromString("");
           if (self->first == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->last = PyUnicode_FromString("");
           if (self->last == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->number = 0;
       }
       return (PyObject *) self;
   }

e instalarlo en el miembro "tp_new":

   .tp_new = Custom_new,

El controlador "tp_new" es responsable de crear (en lugar de
inicializar) objetos del tipo. Está expuesto en Python como el método
"__new__()". No es necesario definir un miembro "tp_new", y de hecho
muchos tipos de extensiones simplemente reutilizarán
"PyType_GenericNew()" como se hizo en la primera versión del tipo
"Personalizado" anterior. En este caso, usamos el controlador "tp_new"
para inicializar los atributos "first" y "last" a valores
predeterminados que no sean "NULL".

"tp_new" se pasa el tipo que se instancia (no necesariamente
"CustomType", si se instancia una subclase) y cualquier argumento
pasado cuando se llamó al tipo, y se espera que retorna la instancia
creada. Los manejadores "tp_new" siempre aceptan argumentos
posicionales y de palabras clave, pero a menudo ignoran los
argumentos, dejando el manejo de argumentos al inicializador (también
conocido como, "tp_init" en C o "__init__" en Python).

Nota:

  "tp_new" no debería llamar explícitamente a "tp_init", ya que el
  intérprete lo hará por sí mismo.

La implementación "tp_new" llama al "tp_alloc" para asignar memoria:

   self = (CustomObject *) type->tp_alloc(type, 0);

Como la asignación de memoria puede fallar, debemos verificar el
resultado "tp_alloc" contra "NULL" antes de continuar.

Nota:

  No llenamos la ranura "tp_alloc" nosotros mismos. Más bien
  "PyType_Ready()" lo llena para nosotros al heredarlo de nuestra
  clase base, que es "object" por defecto. La mayoría de los tipos
  utilizan la estrategia de asignación predeterminada.

Nota:

  Si está creando una cooperativa "tp_new" (una que llama a un tipo
  base "tp_new" o "__new__()"), *no* debe intentar determinar a qué
  método llamar utilizando el orden de resolución del método en tiempo
  de ejecución. Siempre determine estáticamente a qué tipo va a
  llamar, y llame a su "tp_new" directamente, o mediante
  "type->tp_base->tp_new". Si no hace esto, las subclases de Python de
  su tipo que también heredan de otras clases definidas por Python
  pueden no funcionar correctamente. (Específicamente, es posible que
  no pueda crear instancias de tales subclases sin obtener un
  "TypeError").

También definimos una función de inicialización que acepta argumentos
para proporcionar valores iniciales para nuestra instancia:

   static int
   Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
   {
       static char *kwlist[] = {"first", "last", "number", NULL};
       PyObject *first = NULL, *last = NULL, *tmp;

       if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                        &first, &last,
                                        &self->number))
           return -1;

       if (first) {
           tmp = self->first;
           Py_INCREF(first);
           self->first = first;
           Py_XDECREF(tmp);
       }
       if (last) {
           tmp = self->last;
           Py_INCREF(last);
           self->last = last;
           Py_XDECREF(tmp);
       }
       return 0;
   }

rellenando la ranura "tp_init".

   .tp_init = (initproc) Custom_init,

La ranura "tp_init" está expuesta en Python como el método
"__init__()". Se utiliza para inicializar un objeto una vez creado.
Los inicializadores siempre aceptan argumentos posicionales y de
palabras clave, y deben retornar "0" en caso de éxito o "-1" en caso
de error.

A diferencia del controlador "tp_new", no hay garantía de que se llame
a "tp_init" (por ejemplo, el módulo "pickle" por defecto no llama a
"__init__()" en instancias no controladas ) También se puede llamar
varias veces. Cualquiera puede llamar al método "__init__()" en
nuestros objetos. Por esta razón, debemos tener mucho cuidado al
asignar los nuevos valores de atributo. Podríamos sentirnos tentados,
por ejemplo, a asignar el "primer" miembro de esta manera:

   if (first) {
       Py_XDECREF(self->first);
       Py_INCREF(first);
       self->first = first;
   }

Pero esto sería arriesgado. Nuestro tipo no restringe el tipo del
"primer" miembro, por lo que podría ser cualquier tipo de objeto.
Podría tener un destructor que haga que se ejecute código que intente
acceder al "primer" miembro; o ese destructor podría liberar el
*Global Interpreter Lock* y permite que se ejecute código arbitrario
en otros hilos que acceden y modifican nuestro objeto.

Para ser paranoicos y protegernos de esta posibilidad, casi siempre
reasignamos miembros antes de disminuir sus recuentos de referencias.
¿Cuándo no tenemos que hacer esto?

* cuando sabemos absolutamente que el recuento de referencia es mayor
  que 1;

* cuando sabemos que la desasignación del objeto [1] no liberará el
  *GIL* ni causará ninguna llamada al código de nuestro tipo;

* al disminuir un recuento de referencias en un manejador "tp_dealloc"
  en un tipo que no admite la recolección de basura cíclica [2].

Queremos exponer nuestras variables de instancia como atributos. Hay
varias formas de hacerlo. La forma más simple es definir definiciones
de miembros:

   static PyMemberDef Custom_members[] = {
       {"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
        "first name"},
       {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
        "last name"},
       {"number", T_INT, offsetof(CustomObject, number), 0,
        "custom number"},
       {NULL}  /* Sentinel */
   };

y poner las definiciones en la ranura "tp_members":

   .tp_members = Custom_members,

Cada definición de miembro tiene un nombre de miembro, tipo,
desplazamiento, banderas de acceso y cadena de caracteres de
documentación. Consulte la sección Gestión de atributos genéricos a
continuación para obtener más detalles.

Una desventaja de este enfoque es que no proporciona una forma de
restringir los tipos de objetos que se pueden asignar a los atributos
de Python. Esperamos que el nombre y el apellido sean cadenas, pero se
pueden asignar objetos de Python. Además, los atributos se pueden
eliminar, configurando los punteros C en "NULL". Si bien podemos
asegurarnos de que los miembros se inicialicen en valores que no sean
"NULL", los miembros se pueden establecer en "NULL" si se eliminan los
atributos.

Definimos un método único, "Custom.name()", que genera el nombre de
los objetos como la concatenación de los nombres y apellidos.

   static PyObject *
   Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
   {
       if (self->first == NULL) {
           PyErr_SetString(PyExc_AttributeError, "first");
           return NULL;
       }
       if (self->last == NULL) {
           PyErr_SetString(PyExc_AttributeError, "last");
           return NULL;
       }
       return PyUnicode_FromFormat("%S %S", self->first, self->last);
   }

El método se implementa como una función C que toma una instancia de
"Custom" (o subclase "Custom") como primer argumento. Los métodos
siempre toman una instancia como primer argumento. Los métodos a
menudo también toman argumentos posicionales y de palabras clave, pero
en este caso no tomamos ninguno y no necesitamos aceptar una tupla de
argumentos posicionales o un diccionario de argumentos de palabras
clave. Este método es equivalente al método Python:

   def name(self):
       return "%s %s" % (self.first, self.last)

Tenga en cuenta que tenemos que verificar la posibilidad de que
nuestros miembros "first" y "last" sean "NULL". Esto se debe a que se
pueden eliminar, en cuyo caso se establecen en "NULL". Sería mejor
evitar la eliminación de estos atributos y restringir los valores de
los atributos para que sean cadenas de caracteres. Veremos cómo
hacerlo en la siguiente sección.

Ahora que hemos definido el método, necesitamos crear un arreglo de
definiciones de métodos:

   static PyMethodDef Custom_methods[] = {
       {"name", (PyCFunction) Custom_name, METH_NOARGS,
        "Return the name, combining the first and last name"
       },
       {NULL}  /* Sentinel */
   };

(tenga en cuenta que usamos el indicador "METH_NOARGS" para indicar
que el método no espera argumentos distintos de *self*)

y asignarlo a la ranura "tp_methods":

   .tp_methods = Custom_methods,

Finalmente, haremos que nuestro tipo sea utilizable como una clase
base para la subclase. Hemos escrito nuestros métodos cuidadosamente
hasta ahora para que no hagan suposiciones sobre el tipo de objeto que
se está creando o utilizando, por lo que todo lo que tenemos que hacer
es agregar "Py_TPFLAGS_BASETYPE" a nuestra definición de bandera de
clase:

   .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

Cambiamos el nombre de "PyInit_custom()" a "PyInit_custom2()",
actualizamos el nombre del módulo en la estructura "PyModuleDef" y
actualizamos el nombre completo de la clase en la estructura
"PyTypeObject".

Finalmente, actualizamos nuestro archivo "setup.py" para construir el
nuevo módulo:

   from distutils.core import setup, Extension
   setup(name="custom", version="1.0",
         ext_modules=[
            Extension("custom", ["custom.c"]),
            Extension("custom2", ["custom2.c"]),
            ])


2.3. Proporcionar un control más preciso sobre los atributos de datos
=====================================================================

En esta sección, proporcionaremos un control más preciso sobre cómo se
establecen los atributos "first" y "last" en el ejemplo "Custom". En
la versión anterior de nuestro módulo, las variables de instancia
"first" y "last" podrían establecerse en valores que no sean de cadena
o incluso eliminarse. Queremos asegurarnos de que estos atributos
siempre contengan cadenas.

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>
   #include "structmember.h"

   typedef struct {
       PyObject_HEAD
       PyObject *first; /* first name */
       PyObject *last;  /* last name */
       int number;
   } CustomObject;

   static void
   Custom_dealloc(CustomObject *self)
   {
       Py_XDECREF(self->first);
       Py_XDECREF(self->last);
       Py_TYPE(self)->tp_free((PyObject *) self);
   }

   static PyObject *
   Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
   {
       CustomObject *self;
       self = (CustomObject *) type->tp_alloc(type, 0);
       if (self != NULL) {
           self->first = PyUnicode_FromString("");
           if (self->first == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->last = PyUnicode_FromString("");
           if (self->last == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->number = 0;
       }
       return (PyObject *) self;
   }

   static int
   Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
   {
       static char *kwlist[] = {"first", "last", "number", NULL};
       PyObject *first = NULL, *last = NULL, *tmp;

       if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                        &first, &last,
                                        &self->number))
           return -1;

       if (first) {
           tmp = self->first;
           Py_INCREF(first);
           self->first = first;
           Py_DECREF(tmp);
       }
       if (last) {
           tmp = self->last;
           Py_INCREF(last);
           self->last = last;
           Py_DECREF(tmp);
       }
       return 0;
   }

   static PyMemberDef Custom_members[] = {
       {"number", T_INT, offsetof(CustomObject, number), 0,
        "custom number"},
       {NULL}  /* Sentinel */
   };

   static PyObject *
   Custom_getfirst(CustomObject *self, void *closure)
   {
       Py_INCREF(self->first);
       return self->first;
   }

   static int
   Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
   {
       PyObject *tmp;
       if (value == NULL) {
           PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
           return -1;
       }
       if (!PyUnicode_Check(value)) {
           PyErr_SetString(PyExc_TypeError,
                           "The first attribute value must be a string");
           return -1;
       }
       tmp = self->first;
       Py_INCREF(value);
       self->first = value;
       Py_DECREF(tmp);
       return 0;
   }

   static PyObject *
   Custom_getlast(CustomObject *self, void *closure)
   {
       Py_INCREF(self->last);
       return self->last;
   }

   static int
   Custom_setlast(CustomObject *self, PyObject *value, void *closure)
   {
       PyObject *tmp;
       if (value == NULL) {
           PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
           return -1;
       }
       if (!PyUnicode_Check(value)) {
           PyErr_SetString(PyExc_TypeError,
                           "The last attribute value must be a string");
           return -1;
       }
       tmp = self->last;
       Py_INCREF(value);
       self->last = value;
       Py_DECREF(tmp);
       return 0;
   }

   static PyGetSetDef Custom_getsetters[] = {
       {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
        "first name", NULL},
       {"last", (getter) Custom_getlast, (setter) Custom_setlast,
        "last name", NULL},
       {NULL}  /* Sentinel */
   };

   static PyObject *
   Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
   {
       return PyUnicode_FromFormat("%S %S", self->first, self->last);
   }

   static PyMethodDef Custom_methods[] = {
       {"name", (PyCFunction) Custom_name, METH_NOARGS,
        "Return the name, combining the first and last name"
       },
       {NULL}  /* Sentinel */
   };

   static PyTypeObject CustomType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "custom3.Custom",
       .tp_doc = PyDoc_STR("Custom objects"),
       .tp_basicsize = sizeof(CustomObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
       .tp_new = Custom_new,
       .tp_init = (initproc) Custom_init,
       .tp_dealloc = (destructor) Custom_dealloc,
       .tp_members = Custom_members,
       .tp_methods = Custom_methods,
       .tp_getset = Custom_getsetters,
   };

   static PyModuleDef custommodule = {
       PyModuleDef_HEAD_INIT,
       .m_name = "custom3",
       .m_doc = "Example module that creates an extension type.",
       .m_size = -1,
   };

   PyMODINIT_FUNC
   PyInit_custom3(void)
   {
       PyObject *m;
       if (PyType_Ready(&CustomType) < 0)
           return NULL;

       m = PyModule_Create(&custommodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&CustomType);
       if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
           Py_DECREF(&CustomType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Para proporcionar un mayor control sobre los atributos "first" y
"last", usaremos funciones personalizadas *getter* y *setter*. Estas
son las funciones para obtener y configurar el atributo "first":

   static PyObject *
   Custom_getfirst(CustomObject *self, void *closure)
   {
       Py_INCREF(self->first);
       return self->first;
   }

   static int
   Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
   {
       PyObject *tmp;
       if (value == NULL) {
           PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
           return -1;
       }
       if (!PyUnicode_Check(value)) {
           PyErr_SetString(PyExc_TypeError,
                           "The first attribute value must be a string");
           return -1;
       }
       tmp = self->first;
       Py_INCREF(value);
       self->first = value;
       Py_DECREF(tmp);
       return 0;
   }

La función *getter* se pasa al objeto "Custom" y un "cierre"
(*closure*), que es un puntero nulo. En este caso, se ignora el
cierre. (El cierre admite un uso avanzado en el que los datos de
definición se pasan al captador y al definidor. Esto podría, por
ejemplo, usarse para permitir un solo conjunto de funciones de
captador y definidor que deciden que el atributo se obtenga o
establezca en función de los datos en el cierre.)

La función *setter* pasa el objeto "Custom", el nuevo valor y el
cierre. El nuevo valor puede ser "NULL", en cuyo caso se está
eliminando el atributo. En nuestro *setter*, generamos un error si el
atributo se elimina o si su nuevo valor no es una cadena.

Creamos un arreglo de estructuras "PyGetSetDef":

   static PyGetSetDef Custom_getsetters[] = {
       {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
        "first name", NULL},
       {"last", (getter) Custom_getlast, (setter) Custom_setlast,
        "last name", NULL},
       {NULL}  /* Sentinel */
   };

y lo registra en la ranura "tp_getset":

   .tp_getset = Custom_getsetters,

El último elemento en la estructura "PyGetSetDef" es el "cierre"
(*closure*) mencionado anteriormente. En este caso, no estamos usando
un cierre, por lo que simplemente pasamos "NULL".

También eliminamos las definiciones de miembro para estos atributos:

   static PyMemberDef Custom_members[] = {
       {"number", T_INT, offsetof(CustomObject, number), 0,
        "custom number"},
       {NULL}  /* Sentinel */
   };

También necesitamos actualizar el manejador "tp_init" para permitir
que solo se pasen las cadenas [3]:

   static int
   Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
   {
       static char *kwlist[] = {"first", "last", "number", NULL};
       PyObject *first = NULL, *last = NULL, *tmp;

       if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                        &first, &last,
                                        &self->number))
           return -1;

       if (first) {
           tmp = self->first;
           Py_INCREF(first);
           self->first = first;
           Py_DECREF(tmp);
       }
       if (last) {
           tmp = self->last;
           Py_INCREF(last);
           self->last = last;
           Py_DECREF(tmp);
       }
       return 0;
   }

Con estos cambios, podemos asegurar que los miembros "primero" y
"último" nunca sean "NULL", por lo que podemos eliminar las
comprobaciones de los valores "NULL" en casi todos los casos. Esto
significa que la mayoría de las llamadas "Py_XDECREF()" se pueden
convertir en llamadas "Py_DECREF()". El único lugar donde no podemos
cambiar estas llamadas es en la implementación "tp_dealloc", donde
existe la posibilidad de que la inicialización de estos miembros falle
en "tp_new".

También cambiamos el nombre de la función de inicialización del módulo
y el nombre del módulo en la función de inicialización, como lo
hicimos antes, y agregamos una definición adicional al archivo
"setup.py".


2.4. Apoyo a la recolección de basura cíclica
=============================================

Python tiene un *recolector de basura cíclico (GC)* que puede
identificar objetos innecesarios incluso cuando sus recuentos de
referencia no son cero. Esto puede suceder cuando los objetos están
involucrados en ciclos. Por ejemplo, considere:

   >>> l = []
   >>> l.append(l)
   >>> del l

En este ejemplo, creamos una lista que se contiene a sí misma. Cuando
lo eliminamos, todavía tiene una referencia de sí mismo. Su recuento
de referencia no cae a cero. Afortunadamente, el recolector cíclico de
basura de Python finalmente descubrirá que la lista es basura y la
liberará.

En la segunda versión del ejemplo "Custom", permitimos que cualquier
tipo de objeto se almacene en "first" o "last" atributos [4]. Además,
en la segunda y tercera versión, permitimos subclases "Custom", y las
subclases pueden agregar atributos arbitrarios. Por cualquiera de esos
dos motivos, los objetos "Custom" pueden participar en ciclos:

   >>> import custom3
   >>> class Derived(custom3.Custom): pass
   ...
   >>> n = Derived()
   >>> n.some_attribute = n

Para permitir que una instancia de "Custom" que participa en un ciclo
de referencia sea detectada y recolectada correctamente por el GC
cíclico, nuestro tipo "Custom" necesita llenar dos espacios
adicionales y habilitar un indicador que permita estos espacios:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>
   #include "structmember.h"

   typedef struct {
       PyObject_HEAD
       PyObject *first; /* first name */
       PyObject *last;  /* last name */
       int number;
   } CustomObject;

   static int
   Custom_traverse(CustomObject *self, visitproc visit, void *arg)
   {
       Py_VISIT(self->first);
       Py_VISIT(self->last);
       return 0;
   }

   static int
   Custom_clear(CustomObject *self)
   {
       Py_CLEAR(self->first);
       Py_CLEAR(self->last);
       return 0;
   }

   static void
   Custom_dealloc(CustomObject *self)
   {
       PyObject_GC_UnTrack(self);
       Custom_clear(self);
       Py_TYPE(self)->tp_free((PyObject *) self);
   }

   static PyObject *
   Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
   {
       CustomObject *self;
       self = (CustomObject *) type->tp_alloc(type, 0);
       if (self != NULL) {
           self->first = PyUnicode_FromString("");
           if (self->first == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->last = PyUnicode_FromString("");
           if (self->last == NULL) {
               Py_DECREF(self);
               return NULL;
           }
           self->number = 0;
       }
       return (PyObject *) self;
   }

   static int
   Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
   {
       static char *kwlist[] = {"first", "last", "number", NULL};
       PyObject *first = NULL, *last = NULL, *tmp;

       if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                        &first, &last,
                                        &self->number))
           return -1;

       if (first) {
           tmp = self->first;
           Py_INCREF(first);
           self->first = first;
           Py_DECREF(tmp);
       }
       if (last) {
           tmp = self->last;
           Py_INCREF(last);
           self->last = last;
           Py_DECREF(tmp);
       }
       return 0;
   }

   static PyMemberDef Custom_members[] = {
       {"number", T_INT, offsetof(CustomObject, number), 0,
        "custom number"},
       {NULL}  /* Sentinel */
   };

   static PyObject *
   Custom_getfirst(CustomObject *self, void *closure)
   {
       Py_INCREF(self->first);
       return self->first;
   }

   static int
   Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
   {
       if (value == NULL) {
           PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
           return -1;
       }
       if (!PyUnicode_Check(value)) {
           PyErr_SetString(PyExc_TypeError,
                           "The first attribute value must be a string");
           return -1;
       }
       Py_INCREF(value);
       Py_CLEAR(self->first);
       self->first = value;
       return 0;
   }

   static PyObject *
   Custom_getlast(CustomObject *self, void *closure)
   {
       Py_INCREF(self->last);
       return self->last;
   }

   static int
   Custom_setlast(CustomObject *self, PyObject *value, void *closure)
   {
       if (value == NULL) {
           PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
           return -1;
       }
       if (!PyUnicode_Check(value)) {
           PyErr_SetString(PyExc_TypeError,
                           "The last attribute value must be a string");
           return -1;
       }
       Py_INCREF(value);
       Py_CLEAR(self->last);
       self->last = value;
       return 0;
   }

   static PyGetSetDef Custom_getsetters[] = {
       {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
        "first name", NULL},
       {"last", (getter) Custom_getlast, (setter) Custom_setlast,
        "last name", NULL},
       {NULL}  /* Sentinel */
   };

   static PyObject *
   Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
   {
       return PyUnicode_FromFormat("%S %S", self->first, self->last);
   }

   static PyMethodDef Custom_methods[] = {
       {"name", (PyCFunction) Custom_name, METH_NOARGS,
        "Return the name, combining the first and last name"
       },
       {NULL}  /* Sentinel */
   };

   static PyTypeObject CustomType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "custom4.Custom",
       .tp_doc = PyDoc_STR("Custom objects"),
       .tp_basicsize = sizeof(CustomObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
       .tp_new = Custom_new,
       .tp_init = (initproc) Custom_init,
       .tp_dealloc = (destructor) Custom_dealloc,
       .tp_traverse = (traverseproc) Custom_traverse,
       .tp_clear = (inquiry) Custom_clear,
       .tp_members = Custom_members,
       .tp_methods = Custom_methods,
       .tp_getset = Custom_getsetters,
   };

   static PyModuleDef custommodule = {
       PyModuleDef_HEAD_INIT,
       .m_name = "custom4",
       .m_doc = "Example module that creates an extension type.",
       .m_size = -1,
   };

   PyMODINIT_FUNC
   PyInit_custom4(void)
   {
       PyObject *m;
       if (PyType_Ready(&CustomType) < 0)
           return NULL;

       m = PyModule_Create(&custommodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&CustomType);
       if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
           Py_DECREF(&CustomType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Primero, el método transversal permite que el GC cíclico conozca los
subobjetos que podrían participar en los ciclos:

   static int
   Custom_traverse(CustomObject *self, visitproc visit, void *arg)
   {
       int vret;
       if (self->first) {
           vret = visit(self->first, arg);
           if (vret != 0)
               return vret;
       }
       if (self->last) {
           vret = visit(self->last, arg);
           if (vret != 0)
               return vret;
       }
       return 0;
   }

Para cada subobjeto que puede participar en ciclos, necesitamos llamar
a la función "visit()", que se pasa al método transversal. La función
"visit()" toma como argumentos el subobjeto y el argumento extra *arg*
pasados al método transversal. Retorna un valor entero que debe
retornarse si no es cero.

Python proporciona una macro "Py_VISIT()" que automatiza las funciones
de visita de llamada. Con "Py_VISIT()", podemos minimizar la cantidad
de repeticiones en "Custom_traverse":

   static int
   Custom_traverse(CustomObject *self, visitproc visit, void *arg)
   {
       Py_VISIT(self->first);
       Py_VISIT(self->last);
       return 0;
   }

Nota:

  La implementación "tp_traverse" debe nombrar sus argumentos
  exactamente *visit* y *arg* para usar "Py_VISIT()".

En segundo lugar, debemos proporcionar un método para borrar cualquier
subobjeto que pueda participar en los ciclos:

   static int
   Custom_clear(CustomObject *self)
   {
       Py_CLEAR(self->first);
       Py_CLEAR(self->last);
       return 0;
   }

Observe el uso de la macro "Py_CLEAR()". Es la forma recomendada y
segura de borrar los atributos de datos de tipos arbitrarios al tiempo
que disminuye sus recuentos de referencia. Si tuviera que llamar a
"Py_XDECREF()" en lugar del atributo antes de establecerlo en "NULL",
existe la posibilidad de que el destructor del atributo vuelva a
llamar al código que lee el atributo nuevamente (*especialmente* si
hay un ciclo de referencia).

Nota:

  Puede emular "Py_CLEAR()" escribiendo:

     PyObject *tmp;
     tmp = self->first;
     self->first = NULL;
     Py_XDECREF(tmp);

  Sin embargo, es mucho más fácil y menos propenso a errores usar
  siempre "Py_CLEAR()" al eliminar un atributo. ¡No intentes micro-
  optimizar a expensas de la robustez!

El desasignador "Custom_dealloc" puede llamar a un código arbitrario
al borrar los atributos. Significa que el GC circular se puede activar
dentro de la función. Dado que el GC asume que el recuento de
referencias no es cero, debemos destrabar el objeto del GC llamando a
"PyObject_GC_UnTrack()" antes de borrar los miembros. Aquí está
nuestro reubicador reimplementado usando "PyObject_GC_UnTrack()" y
"Custom_clear":

   static void
   Custom_dealloc(CustomObject *self)
   {
       PyObject_GC_UnTrack(self);
       Custom_clear(self);
       Py_TYPE(self)->tp_free((PyObject *) self);
   }

Finalmente, agregamos el indicador "Py_TPFLAGS_HAVE_GC" a los
indicadores de clase:

   .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

Eso es prácticamente todo. Si hubiéramos escrito controladores
personalizados "tp_alloc" o "tp_free", tendríamos que modificarlos
para la recolección de basura cíclica. La mayoría de las extensiones
usarán las versiones proporcionadas automáticamente.


2.5. Subclases de otros tipos
=============================

Es posible crear nuevos tipos de extensión que se derivan de los tipos
existentes. Es más fácil heredar de los tipos incorporados, ya que una
extensión puede usar fácilmente "PyTypeObject" que necesita. Puede ser
difícil compartir estas estructuras "PyTypeObject" entre módulos de
extensión.

En este ejemplo crearemos un tipo "SubList" que hereda del tipo
incorporado "list". El nuevo tipo será completamente compatible con
las listas regulares, pero tendrá un método adicional "increment()"
que aumenta un contador interno:

   >>> import sublist
   >>> s = sublist.SubList(range(3))
   >>> s.extend(s)
   >>> print(len(s))
   6
   >>> print(s.increment())
   1
   >>> print(s.increment())
   2

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

   typedef struct {
       PyListObject list;
       int state;
   } SubListObject;

   static PyObject *
   SubList_increment(SubListObject *self, PyObject *unused)
   {
       self->state++;
       return PyLong_FromLong(self->state);
   }

   static PyMethodDef SubList_methods[] = {
       {"increment", (PyCFunction) SubList_increment, METH_NOARGS,
        PyDoc_STR("increment state counter")},
       {NULL},
   };

   static int
   SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
   {
       if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
           return -1;
       self->state = 0;
       return 0;
   }

   static PyTypeObject SubListType = {
       PyVarObject_HEAD_INIT(NULL, 0)
       .tp_name = "sublist.SubList",
       .tp_doc = PyDoc_STR("SubList objects"),
       .tp_basicsize = sizeof(SubListObject),
       .tp_itemsize = 0,
       .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
       .tp_init = (initproc) SubList_init,
       .tp_methods = SubList_methods,
   };

   static PyModuleDef sublistmodule = {
       PyModuleDef_HEAD_INIT,
       .m_name = "sublist",
       .m_doc = "Example module that creates an extension type.",
       .m_size = -1,
   };

   PyMODINIT_FUNC
   PyInit_sublist(void)
   {
       PyObject *m;
       SubListType.tp_base = &PyList_Type;
       if (PyType_Ready(&SubListType) < 0)
           return NULL;

       m = PyModule_Create(&sublistmodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&SubListType);
       if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
           Py_DECREF(&SubListType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Como puede ver, el código fuente se parece mucho a los ejemplos
"Custom" en secciones anteriores. Desglosaremos las principales
diferencias entre ellos.

   typedef struct {
       PyListObject list;
       int state;
   } SubListObject;

La diferencia principal para los objetos de tipo derivado es que la
estructura de objeto del tipo base debe ser el primer valor. El tipo
base ya incluirá "PyObject_HEAD()" al comienzo de su estructura.

Cuando un objeto Python es una instancia de "SubList", su puntero
"PyObject *" se puede convertir de forma segura tanto en "PyListObject
*" como en "SubListObject *":

   static int
   SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
   {
       if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
           return -1;
       self->state = 0;
       return 0;
   }

Vemos arriba cómo llamar al método "__init__" del tipo base.

Este patrón es importante cuando se escribe un tipo con miembros
personalizados "tp_new" y "tp_dealloc". El manejador "tp_new" no
debería crear realmente la memoria para el objeto con su "tp_alloc",
pero deja que la clase base lo maneje llamando a su propio "tp_new".

La estructura "PyTypeObject" admite a "tp_base" especificando la clase
base concreta del tipo. Debido a problemas de compilación
multiplataforma, no puede llenar ese campo directamente con una
referencia a "PyList_Type"; debe hacerse más tarde en la función de
inicialización del módulo:

   PyMODINIT_FUNC
   PyInit_sublist(void)
   {
       PyObject* m;
       SubListType.tp_base = &PyList_Type;
       if (PyType_Ready(&SubListType) < 0)
           return NULL;

       m = PyModule_Create(&sublistmodule);
       if (m == NULL)
           return NULL;

       Py_INCREF(&SubListType);
       if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
           Py_DECREF(&SubListType);
           Py_DECREF(m);
           return NULL;
       }

       return m;
   }

Antes de llamar a "PyType_Ready()", la estructura de tipo debe tener
el espacio "tp_base" rellenado. Cuando derivamos un tipo existente, no
es necesario completar el "tp_alloc" ranura con "PyType_GenericNew()"
-- la función de asignación del tipo base será heredada.

Después de eso, llamar a "PyType_Ready()" y agregar el objeto tipo al
módulo es lo mismo que con los ejemplos básicos "Custom".

-[ Notas al pie ]-

[1] Esto es cierto cuando sabemos que el objeto es un tipo básico,
    como una cadena o un flotador.

[2] Nos basamos en esto en el manejador "tp_dealloc" en este ejemplo,
    porque nuestro tipo no admite la recolección de basura.

[3] Ahora sabemos que el primer y el último miembro son cadenas de
    caracteres, por lo que quizás podríamos ser menos cuidadosos al
    disminuir sus recuentos de referencia, sin embargo, aceptamos
    instancias de subclases de cadenas. A pesar de que la
    desasignación de cadenas normales no volverá a llamar a nuestros
    objetos, no podemos garantizar que la desasignación de una
    instancia de una subclase de cadena de caracteres no vuelva a
    llamar a nuestros objetos.

[4] Además, incluso con nuestros atributos restringidos a instancias
    de cadenas, el usuario podría pasar subclases arbitrarias "str" y,
    por lo tanto, seguir creando ciclos de referencia.
