3. Definición de tipos de extensión: temas variados
***************************************************

Esta sección tiene como objetivo dar un vistazo rápido a los diversos
métodos de tipo que puede implementar y lo que hacen.

Aquí está la definición de "PyTypeObject", con algunos campos que solo
se usan en las versiones de depuración omitidas:

   typedef struct _typeobject {
       PyObject_VAR_HEAD
       const char *tp_name; /* For printing, in format "<module>.<name>" */
       Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

       /* Methods to implement standard operations */

       destructor tp_dealloc;
       Py_ssize_t tp_vectorcall_offset;
       getattrfunc tp_getattr;
       setattrfunc tp_setattr;
       PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                       or tp_reserved (Python 3) */
       reprfunc tp_repr;

       /* Method suites for standard classes */

       PyNumberMethods *tp_as_number;
       PySequenceMethods *tp_as_sequence;
       PyMappingMethods *tp_as_mapping;

       /* More standard operations (here for binary compatibility) */

       hashfunc tp_hash;
       ternaryfunc tp_call;
       reprfunc tp_str;
       getattrofunc tp_getattro;
       setattrofunc tp_setattro;

       /* Functions to access object as input/output buffer */
       PyBufferProcs *tp_as_buffer;

       /* Flags to define presence of optional/expanded features */
       unsigned long tp_flags;

       const char *tp_doc; /* Documentation string */

       /* Assigned meaning in release 2.0 */
       /* call function for all accessible objects */
       traverseproc tp_traverse;

       /* delete references to contained objects */
       inquiry tp_clear;

       /* Assigned meaning in release 2.1 */
       /* rich comparisons */
       richcmpfunc tp_richcompare;

       /* weak reference enabler */
       Py_ssize_t tp_weaklistoffset;

       /* Iterators */
       getiterfunc tp_iter;
       iternextfunc tp_iternext;

       /* Attribute descriptor and subclassing stuff */
       struct PyMethodDef *tp_methods;
       struct PyMemberDef *tp_members;
       struct PyGetSetDef *tp_getset;
       // Strong reference on a heap type, borrowed reference on a static type
       struct _typeobject *tp_base;
       PyObject *tp_dict;
       descrgetfunc tp_descr_get;
       descrsetfunc tp_descr_set;
       Py_ssize_t tp_dictoffset;
       initproc tp_init;
       allocfunc tp_alloc;
       newfunc tp_new;
       freefunc tp_free; /* Low-level free-memory routine */
       inquiry tp_is_gc; /* For PyObject_IS_GC */
       PyObject *tp_bases;
       PyObject *tp_mro; /* method resolution order */
       PyObject *tp_cache;
       PyObject *tp_subclasses;
       PyObject *tp_weaklist;
       destructor tp_del;

       /* Type attribute cache version tag. Added in version 2.6 */
       unsigned int tp_version_tag;

       destructor tp_finalize;
       vectorcallfunc tp_vectorcall;

       /* bitset of which type-watchers care about this type */
       unsigned char tp_watched;
   } PyTypeObject;

Esos son *muchos* métodos. Sin embargo, no se preocupe demasiado: si
tiene un tipo que desea definir, es muy probable que solo implemente
un puñado de estos.

Como probablemente espera ahora, vamos a repasar esto y daremos más
información sobre los diversos controladores. No iremos en el orden en
que se definen en la estructura, porque hay mucho equipaje histórico
que afecta el orden de los campos. A menudo es más fácil encontrar un
ejemplo que incluya los campos que necesita y luego cambiar los
valores para adaptarlos a su nuevo tipo.

   const char *tp_name; /* For printing */

El nombre del tipo -- como se mencionó en el capítulo anterior,
aparecerá en varios lugares, casi por completo para fines de
diagnóstico. ¡Intente elegir algo que sea útil en tal situación!

   Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

Estos campos le dicen al tiempo de ejecución cuánta memoria asignar
cuando se crean nuevos objetos de este tipo. Python tiene algún
soporte incorporado para estructuras de longitud variable (piense:
cadenas, tuplas) que es donde entra el campo "tp_itemsize". Esto se
tratará más adelante.

   const char *tp_doc;

Aquí puede poner una cadena de caracteres (o su dirección) que desea
que se retorne cuando el script de Python haga referencia a
"obj.__doc__" para recuperar el docstring.

Ahora llegamos a los métodos de tipo básicos: los que implementarán la
mayoría de los tipos de extensión.


3.1. Finalización y desasignación
=================================

   destructor tp_dealloc;

Se llama a esta función cuando el recuento de referencia de la
instancia de su tipo se reduce a cero y el intérprete de Python quiere
reclamarlo. Si su tipo tiene memoria para liberar u otra limpieza para
realizar, puede ponerla aquí. El objeto en sí mismo necesita ser
liberado aquí también. Aquí hay un ejemplo de esta función:

   static void
   newdatatype_dealloc(newdatatypeobject *obj)
   {
       free(obj->obj_UnderlyingDatatypePtr);
       Py_TYPE(obj)->tp_free((PyObject *)obj);
   }

Si su tipo admite la recolección de basura, el destructor debe llamar
a "PyObject_GC_UnTrack()" antes de borrar cualquier campo miembro:

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

Un requisito importante de la función desasignador es que deja solo
las excepciones pendientes. Esto es importante ya que los
desasignadores se llaman con frecuencia cuando el intérprete
desenrolla la pila de Python; cuando la pila se desenrolla debido a
una excepción (en lugar de retornos normales), no se hace nada para
proteger a los desasignadores de memoria (*deallocator*) de ver que ya
se ha establecido una excepción. Cualquier acción que realice un
desasignador que pueda hacer que se ejecute código Python adicional
puede detectar que se ha establecido una excepción. Esto puede
conducir a errores engañosos del intérprete. La forma correcta de
protegerse contra esto es guardar una excepción pendiente antes de
realizar la acción insegura y restaurarla cuando haya terminado. Esto
se puede hacer usando las funciones "PyErr_Fetch()" y
"PyErr_Restore()":

   static void
   my_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);
           else
               Py_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);
   }

Nota:

  Existen limitaciones para lo que puede hacer de manera segura en una
  función de desasignación. Primero, si su tipo admite la recolección
  de basura (usando "tp_traverse" o "tp_clear"), algunos de los
  miembros del objeto pueden haber sido borrados o finalizados por el
  time "tp_dealloc" es llamado. Segundo, en "tp_dealloc", su objeto
  está en un estado inestable: su recuento de referencia es igual a
  cero. Cualquier llamada a un objeto o API no trivial (como en el
  ejemplo anterior) podría terminar llamando "tp_dealloc" nuevamente,
  causando una doble liberación y un bloqueo.Comenzando con Python
  3.4, se recomienda no poner ningún código de finalización complejo
  en "tp_dealloc", y en su lugar use el nuevo método de tipo
  "tp_finalize".

  Ver también: **PEP 442** explica el nuevo esquema de finalización.


3.2. Presentación de objetos
============================

En Python, hay dos formas de generar una representación textual de un
objeto: la función "repr()", y la función "str()". (La función
"print()" solo llama a "str()".) Estos controladores son opcionales.

   reprfunc tp_repr;
   reprfunc tp_str;

El manejador "tp_repr" debe retornar un objeto de cadena que contenga
una representación de la instancia para la que se llama. Aquí hay un
ejemplo simple:

   static PyObject *
   newdatatype_repr(newdatatypeobject *obj)
   {
       return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                   obj->obj_UnderlyingDatatypePtr->size);
   }

Si no se especifica un controlador "tp_repr", el intérprete
proporcionará una representación que utiliza el "tp_name" del tipo y
un valor de identificación exclusivo para el objeto.

El manejador "tp_str" es para "str()" lo que el manejador "tp_repr"
descrito arriba es para "repr()"; es decir, se llama cuando el código
Python llama "str()" en una instancia de su objeto. Su implementación
es muy similar a la función "tp_repr", pero la cadena resultante está
destinada al consumo humano. Si "tp_str" no se especifica, en su lugar
se utiliza el controlador "tp_repr".

Aquí hay un ejemplo simple:

   static PyObject *
   newdatatype_str(newdatatypeobject *obj)
   {
       return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                   obj->obj_UnderlyingDatatypePtr->size);
   }


3.3. Gestión de atributos
=========================

Para cada objeto que puede soportar atributos, el tipo correspondiente
debe proporcionar las funciones que controlan cómo se resuelven los
atributos. Es necesario que haya una función que pueda recuperar
atributos (si hay alguna definida), y otra para establecer atributos
(si se permite establecer atributos). La eliminación de un atributo es
un caso especial, para el cual el nuevo valor pasado al controlador es
"NULL".

Python admite dos pares de controladores de atributos; un tipo que
admite atributos solo necesita implementar las funciones para un par.
La diferencia es que un par toma el nombre del atributo como char*,
mientras que el otro acepta un PyObject*. Cada tipo puede usar
cualquier par que tenga más sentido para la conveniencia de la
implementación.

   getattrfunc  tp_getattr;        /* char * version */
   setattrfunc  tp_setattr;
   /* ... */
   getattrofunc tp_getattro;       /* PyObject * version */
   setattrofunc tp_setattro;

Si acceder a los atributos de un objeto siempre es una operación
simple (esto se explicará en breve), existen implementaciones
genéricas que se pueden usar para proporcionar la versión PyObject* de
las funciones de administración de atributos. La necesidad real de
controladores de atributos específicos de tipo desapareció casi por
completo a partir de Python 2.2, aunque hay muchos ejemplos que no se
han actualizado para usar algunos de los nuevos mecanismos genéricos
disponibles.


3.3.1. Gestión de atributos genéricos
-------------------------------------

La mayoría de los tipos de extensión solo usan atributos *simple*.
Entonces, ¿qué hace que los atributos sean simples? Solo hay un par de
condiciones que se deben cumplir:

1. El nombre de los atributos debe ser conocido cuando
   "PyType_Ready()" es llamado.

2. No se necesita un procesamiento especial para registrar que un
   atributo se buscó o se configuró, ni se deben tomar acciones
   basadas en el valor.

Tenga en cuenta que esta lista no impone restricciones a los valores
de los atributos, cuándo se calculan los valores o cómo se almacenan
los datos relevantes.

Cuando se llama a "PyType_Ready()", utiliza tres tablas a las que hace
referencia el objeto de tipo para crear *descriptor* que se colocan en
el diccionario del objeto de tipo. Cada descriptor controla el acceso
a un atributo del objeto de instancia. Cada una de las tablas es
opcional; si los tres son "NULL", las instancias del tipo solo tendrán
atributos que se heredan de su tipo base, y deberían dejar
"tp_getattro" y los campos "tp_setattro" "NULL" también, permitiendo
que el tipo base maneje los atributos.

Las tablas se declaran como tres campos del tipo objeto:

   struct PyMethodDef *tp_methods;
   struct PyMemberDef *tp_members;
   struct PyGetSetDef *tp_getset;

Si "tp_methods" no es "NULL", debe referirse a un arreglo de
estructuras "PyMethodDef". Cada entrada en la tabla es una instancia
de esta estructura:

   typedef struct PyMethodDef {
       const char  *ml_name;       /* method name */
       PyCFunction  ml_meth;       /* implementation function */
       int          ml_flags;      /* flags */
       const char  *ml_doc;        /* docstring */
   } PyMethodDef;

One entry should be defined for each method provided by the type; no
entries are needed for methods inherited from a base type.  One
additional entry is needed at the end; it is a sentinel that marks the
end of the array.  The "ml_name" field of the sentinel must be "NULL".

La segunda tabla se utiliza para definir atributos que se asignan
directamente a los datos almacenados en la instancia. Se admite una
variedad de tipos C primitivos, y el acceso puede ser de solo lectura
o lectura-escritura. Las estructuras en la tabla se definen como:

   typedef struct PyMemberDef {
       const char *name;
       int         type;
       int         offset;
       int         flags;
       const char *doc;
   } PyMemberDef;

For each entry in the table, a *descriptor* will be constructed and
added to the type which will be able to extract a value from the
instance structure.  The "type" field should contain a type code like
"Py_T_INT" or "Py_T_DOUBLE"; the value will be used to determine how
to convert Python values to and from C values.  The "flags" field is
used to store flags which control how the attribute can be accessed:
you can set it to "Py_READONLY" to prevent Python code from setting
it.

An interesting advantage of using the "tp_members" table to build
descriptors that are used at runtime is that any attribute defined
this way can have an associated doc string simply by providing the
text in the table.  An application can use the introspection API to
retrieve the descriptor from the class object, and get the doc string
using its "__doc__" attribute.

As with the "tp_methods" table, a sentinel entry with a "ml_name"
value of "NULL" is required.


3.3.2. Gestión de atributos específicos de tipo
-----------------------------------------------

Para simplificar, solo la versión char* será demostrada aquí; el tipo
del parámetro con nombre es la única diferencia entre char* y
PyObject* de la interfaz. Este ejemplo efectivamente hace lo mismo que
el ejemplo genérico anterior, pero no usa el soporte genérico agregado
en Python 2.2. Explica cómo se llaman las funciones del controlador,
de modo que si necesita ampliar su funcionalidad, comprenderá lo que
debe hacerse.

The "tp_getattr" handler is called when the object requires an
attribute look-up.  It is called in the same situations where the
"__getattr__()" method of a class would be called.

Aquí hay un ejemplo:

   static PyObject *
   newdatatype_getattr(newdatatypeobject *obj, char *name)
   {
       if (strcmp(name, "data") == 0)
       {
           return PyLong_FromLong(obj->data);
       }

       PyErr_Format(PyExc_AttributeError,
                    "'%.100s' object has no attribute '%.400s'",
                    Py_TYPE(obj)->tp_name, name);
       return NULL;
   }

The "tp_setattr" handler is called when the "__setattr__()" or
"__delattr__()" method of a class instance would be called.  When an
attribute should be deleted, the third parameter will be "NULL".  Here
is an example that simply raises an exception; if this were really all
you wanted, the "tp_setattr" handler should be set to "NULL".

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


3.4. Comparación de Objetos
===========================

   richcmpfunc tp_richcompare;

The "tp_richcompare" handler is called when comparisons are needed.
It is analogous to the rich comparison methods, like "__lt__()", and
also called by "PyObject_RichCompare()" and
"PyObject_RichCompareBool()".

Esta función se llama con dos objetos de Python y el operador como
argumentos, donde el operador es uno de "Py_EQ", "Py_NE", "Py_LE",
"Py_GE", "Py_LT" o "Py_GT". Debe comparar los dos objetos con respecto
al operador especificado y retornar "Py_True" o "Py_False" si la
comparación es exitosa, "Py_NotImplemented" para indicar que la
comparación no está implementada y se debe probar el método de
comparación del otro objeto, o "NULL" si se estableció una excepción.

Aquí hay una implementación de muestra, para un tipo de datos que se
considera igual si el tamaño de un puntero interno es igual:

   static PyObject *
   newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
   {
       PyObject *result;
       int c, 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) {
       case Py_LT: c = size1 <  size2; break;
       case Py_LE: c = size1 <= size2; break;
       case Py_EQ: c = size1 == size2; break;
       case Py_NE: c = size1 != size2; break;
       case Py_GT: c = size1 >  size2; break;
       case Py_GE: c = size1 >= size2; break;
       }
       result = c ? Py_True : Py_False;
       Py_INCREF(result);
       return result;
    }


3.5. Soporte de protocolo abstracto
===================================

Python admite una variedad de protocolos *abstractos*; las interfaces
específicas proporcionadas para usar estas interfaces están
documentadas en Capa de objetos abstractos.

Varias de estas interfaces abstractas se definieron temprano en el
desarrollo de la implementación de Python. En particular, los
protocolos de número, mapeo y secuencia han sido parte de Python desde
el principio. Se han agregado otros protocolos con el tiempo. Para los
protocolos que dependen de varias rutinas de controlador de la
implementación de tipo, los protocolos más antiguos se han definido
como bloques opcionales de controladores a los que hace referencia el
objeto de tipo. Para los protocolos más nuevos, hay espacios
adicionales en el objeto de tipo principal, con un bit de marca que se
establece para indicar que los espacios están presentes y el
intérprete debe verificarlos. (El bit de indicador no indica que los
valores de intervalo no son "NULL". El indicador puede establecerse
para indicar la presencia de un intervalo, pero un intervalo aún puede
estar vacío.):

   PyNumberMethods   *tp_as_number;
   PySequenceMethods *tp_as_sequence;
   PyMappingMethods  *tp_as_mapping;

Si desea que su objeto pueda actuar como un número, una secuencia o un
objeto de mapeo, entonces coloca la dirección de una estructura que
implementa el tipo C "PyNumberMethods", "PySequenceMethods", o
"PyMappingMethods", respectivamente. Depende de usted completar esta
estructura con los valores apropiados. Puede encontrar ejemplos del
uso de cada uno de estos en el directorio "Objects" de la distribución
fuente de Python.

   hashfunc tp_hash;

Esta función, si elige proporcionarla, debería retornar un número hash
para una instancia de su tipo de datos. Aquí hay un ejemplo simple:

   static Py_hash_t
   newdatatype_hash(newdatatypeobject *obj)
   {
       Py_hash_t result;
       result = obj->some_size + 32767 * obj->some_number;
       if (result == -1)
          result = -2;
       return result;
   }

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

   ternaryfunc tp_call;

Esta función se llama cuando una instancia de su tipo de datos se
"llama", por ejemplo, si "obj1" es una instancia de su tipo de datos y
el script de Python contiene "obj1('hello')", el controlador "tp_call"
se invoca.

Esta función toma tres argumentos:

1. *self* es la instancia del tipo de datos que es el sujeto de la
   llamada. Si la llamada es "obj1('hola')", entonces *self* es
   "obj1".

2. *args* es una tupla que contiene los argumentos de la llamada.
   Puede usar "PyArg_ParseTuple()" para extraer los argumentos.

3. *kwds* es un diccionario de argumentos de palabras clave que se
   pasaron. Si no es "NULL" y admite argumentos de palabras clave, use
   "PyArg_ParseTupleAndKeywords()" para extraer los argumentos. Si no
   desea admitir argumentos de palabras clave y esto no es "NULL",
   genere un "TypeError" con un mensaje que indique que los argumentos
   de palabras clave no son compatibles.

Aquí hay una implementación de juguete "tp_call":

   static PyObject *
   newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
   {
       PyObject *result;
       const char *arg1;
       const char *arg2;
       const char *arg3;

       if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
           return NULL;
       }
       result = PyUnicode_FromFormat(
           "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
           obj->obj_UnderlyingDatatypePtr->size,
           arg1, arg2, arg3);
       return result;
   }

   /* Iterators */
   getiterfunc tp_iter;
   iternextfunc tp_iternext;

These functions provide support for the iterator protocol.  Both
handlers take 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 an exception and return "NULL".  "tp_iter" corresponds
to the Python "__iter__()" method, while "tp_iternext" corresponds to
the Python "__next__()" method.

Cualquier objeto *iterable* debe implementar el manejador "tp_iter",
que debe retornar un objeto *iterator*. Aquí se aplican las mismas
pautas que para las clases de Python:

* Para colecciones (como listas y tuplas) que pueden admitir múltiples
  iteradores independientes, cada llamada debe crear y retornar un
  nuevo iterador a "tp_iter".

* Los objetos que solo se pueden iterar una vez (generalmente debido a
  los efectos secundarios de la iteración, como los objetos de
  archivo) pueden implementar "tp_iter" retornando una nueva
  referencia a ellos mismos y, por lo tanto, también deben implementar
  el manejador "tp_iternext".

Cualquier objeto *iterator* debe implementar tanto "tp_iter" como
"tp_iternext". El manejador de un iterador "tp_iter" debería retornar
una nueva referencia al iterador. Su controlador "tp_iternext" debería
retornar una nueva referencia al siguiente objeto en la iteración, si
hay uno. Si la iteración ha llegado al final, "tp_iternext" puede
retornar "NULL" sin establecer una excepción, o puede establecer
"StopIteration" *además* para retornar "NULL"; evitar la excepción
puede producir un rendimiento ligeramente mejor. Si se produce un
error real, "tp_iternext" siempre debe establecer una excepción y
retornar "NULL".


3.6. Soporte de referencia débil
================================

Uno de los objetivos de la implementación de referencia débil de
Python es permitir que cualquier tipo participe en el mecanismo de
referencia débil sin incurrir en la sobrecarga de objetos críticos
para el rendimiento (como los números).

Ver también: Documentación para el módulo "weakref".

For an object to be weakly referenceable, the extension type must set
the "Py_TPFLAGS_MANAGED_WEAKREF" bit of the "tp_flags" field. The
legacy "tp_weaklistoffset" field should be left as zero.

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

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

The only further addition is that "tp_dealloc" needs to clear any weak
references (by calling "PyObject_ClearWeakRefs()"):

   static void
   Trivial_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. Más Sugerencias
====================

Para aprender a implementar cualquier método específico para su nuevo
tipo de datos, obtenga el código fuente *CPython*. Vaya al directorio
"Objects", luego busque en los archivos fuente C "tp_" más la función
que desee (por ejemplo, "tp_richcompare"). Encontrará ejemplos de la
función que desea implementar.

Cuando necesite verificar que un objeto es una instancia concreta del
tipo que está implementando, use la función "PyObject_TypeCheck()".
Una muestra de su uso podría ser algo como lo siguiente:

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

Ver también:

  Descargue las versiones de origen de CPython.
     https://www.python.org/downloads/source/

  El proyecto CPython en GitHub, donde se desarrolla el código fuente
  de CPython.
     https://github.com/python/cpython
