Objetos tipo
************

type PyTypeObject
    * Part of the Limited API (as an opaque struct).*

   La estructura C de los objetos utilizados para describir los tipos
   incorporados.

PyTypeObject PyType_Type
    * Part of the Stable ABI.*

   Este es el objeto tipo para objetos tipo; es el mismo objeto que
   "type" en la capa Python.

int PyType_Check(PyObject *o)

   Retorna un valor distinto de cero si el objeto *o* es un objeto
   tipo, incluidas las instancias de tipos derivados del objeto de
   tipo estándar. Retorna 0 en todos los demás casos. Esta función
   siempre finaliza con éxito.

int PyType_CheckExact(PyObject *o)

   Retorna un valor distinto de cero si el objeto *o* es un objeto
   tipo, pero no un subtipo del objeto tipo estándar. Retorna 0 en
   todos los demás casos. Esta función siempre finaliza con éxito.

unsigned int PyType_ClearCache()
    * Part of the Stable ABI.*

   Borra la caché de búsqueda interna. Retorna la etiqueta (*tag*) de
   la versión actual.

unsigned long PyType_GetFlags(PyTypeObject *type)
    * Part of the Stable ABI.*

   Return the "tp_flags" member of *type*. This function is primarily
   meant for use with "Py_LIMITED_API"; the individual flag bits are
   guaranteed to be stable across Python releases, but access to
   "tp_flags" itself is not part of the limited API.

   Added in version 3.2.

   Distinto en la versión 3.4: El tipo de retorno es ahora "unsigned
   long" en vez de "long".

PyObject *PyType_GetDict(PyTypeObject *type)

   Return the type object's internal namespace, which is otherwise
   only exposed via a read-only proxy ("cls.__dict__"). This is a
   replacement for accessing "tp_dict" directly. The returned
   dictionary must be treated as read-only.

   This function is meant for specific embedding and language-binding
   cases, where direct access to the dict is necessary and indirect
   access (e.g. via the proxy or "PyObject_GetAttr()") isn't adequate.

   Extension modules should continue to use "tp_dict", directly or
   indirectly, when setting up their own types.

   Added in version 3.12.

void PyType_Modified(PyTypeObject *type)
    * Part of the Stable ABI.*

   Invalida la memoria caché de búsqueda interna para el tipo y todos
   sus subtipos. Esta función debe llamarse después de cualquier
   modificación manual de los atributos o clases base del tipo.

int PyType_AddWatcher(PyType_WatchCallback callback)

   Register *callback* as a type watcher. Return a non-negative
   integer ID which must be passed to future calls to
   "PyType_Watch()". In case of error (e.g. no more watcher IDs
   available), return "-1" and set an exception.

   In free-threaded builds, "PyType_AddWatcher()" is not thread-safe,
   so it must be called at start up (before spawning the first
   thread).

   Added in version 3.12.

int PyType_ClearWatcher(int watcher_id)

   Clear watcher identified by *watcher_id* (previously returned from
   "PyType_AddWatcher()"). Return "0" on success, "-1" on error (e.g.
   if *watcher_id* was never registered.)

   An extension should never call "PyType_ClearWatcher" with a
   *watcher_id* that was not returned to it by a previous call to
   "PyType_AddWatcher()".

   Added in version 3.12.

int PyType_Watch(int watcher_id, PyObject *type)

   Mark *type* as watched. The callback granted *watcher_id* by
   "PyType_AddWatcher()" will be called whenever "PyType_Modified()"
   reports a change to *type*. (The callback may be called only once
   for a series of consecutive modifications to *type*, if
   "_PyType_Lookup()" is not called on *type* between the
   modifications; this is an implementation detail and subject to
   change.)

   An extension should never call "PyType_Watch" with a *watcher_id*
   that was not returned to it by a previous call to
   "PyType_AddWatcher()".

   Added in version 3.12.

int PyType_Unwatch(int watcher_id, PyObject *type)

   Mark *type* as not watched. This undoes a previous call to
   "PyType_Watch()". *type* must not be "NULL".

   An extension should never call this function with a *watcher_id*
   that was not returned to it by a previous call to
   "PyType_AddWatcher()".

   On success, this function returns "0". On failure, this function
   returns "-1" with an exception set.

   Added in version 3.12.

typedef int (*PyType_WatchCallback)(PyObject *type)

   Type of a type-watcher callback function.

   The callback must not modify *type* or cause "PyType_Modified()" to
   be called on *type* or any type in its MRO; violating this rule
   could cause infinite recursion.

   Added in version 3.12.

int PyType_HasFeature(PyTypeObject *o, int feature)

   Retorna un valor distinto de cero si el tipo objeto *o* establece
   la característica *feature*. Las características de tipo se indican
   mediante flags de un solo bit.

int PyType_FastSubclass(PyTypeObject *type, int flag)

   Return non-zero if the type object *type* sets the subclass flag
   *flag*. Subclass flags are denoted by "Py_TPFLAGS_*_SUBCLASS". This
   function is used by many "_Check" functions for common types.

   Ver también:

     "PyObject_TypeCheck()", which is used as a slower alternative in
     "_Check" functions for types that don't come with subclass flags.

int PyType_IS_GC(PyTypeObject *o)

   Return true if the type object includes support for the cycle
   detector; this tests the type flag "Py_TPFLAGS_HAVE_GC".

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
    * Part of the Stable ABI.*

   Retorna verdadero si *a* es un subtipo de *b*.

   This function only checks for actual subtypes, which means that
   "__subclasscheck__()" is not called on *b*.  Call
   "PyObject_IsSubclass()" to do the same check that "issubclass()"
   would do.

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
    *Return value: New reference.** Part of the Stable ABI.*

   Generic handler for the "tp_alloc" slot of a type object.  Uses
   Python's default memory allocation mechanism to allocate memory for
   a new instance, zeros the memory, then initializes the memory as if
   by calling "PyObject_Init()" or "PyObject_InitVar()".

   Do not call this directly to allocate memory for an object; call
   the type's "tp_alloc" slot instead.

   For types that support garbage collection (i.e., the
   "Py_TPFLAGS_HAVE_GC" flag is set), this function behaves like
   "PyObject_GC_New" or "PyObject_GC_NewVar" (except the memory is
   guaranteed to be zeroed before initialization), and should be
   paired with "PyObject_GC_Del()" in "tp_free". Otherwise, it behaves
   like "PyObject_New" or "PyObject_NewVar" (except the memory is
   guaranteed to be zeroed before initialization) and should be paired
   with "PyObject_Free()" in "tp_free".

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
    *Return value: New reference.** Part of the Stable ABI.*

   Generic handler for the "tp_new" slot of a type object.  Creates a
   new instance using the type's "tp_alloc" slot and returns the
   resulting object.

int PyType_Ready(PyTypeObject *type)
    * Part of the Stable ABI.*

   Finalizar un objeto tipo. Se debe llamar a todos los objetos tipo
   para finalizar su inicialización. Esta función es responsable de
   agregar ranuras heredadas de la clase base de un tipo. Retorna "0"
   en caso de éxito o retorna "-1" y establece una excepción en caso
   de error.

   Nota:

     If some of the base classes implements the GC protocol and the
     provided type does not include the "Py_TPFLAGS_HAVE_GC" in its
     flags, then the GC protocol will be automatically implemented
     from its parents. On the contrary, if the type being created does
     include "Py_TPFLAGS_HAVE_GC" in its flags then it **must**
     implement the GC protocol itself by at least implementing the
     "tp_traverse" handle.

PyObject *PyType_GetName(PyTypeObject *type)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.11.*

   Return the type's name. Equivalent to getting the type's "__name__"
   attribute.

   Added in version 3.11.

PyObject *PyType_GetQualName(PyTypeObject *type)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.11.*

   Return the type's qualified name. Equivalent to getting the type's
   "__qualname__" attribute.

   Added in version 3.11.

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)
    * Part of the Stable ABI since version 3.13.*

   Return the type's fully qualified name. Equivalent to
   "f"{type.__module__}.{type.__qualname__}"", or "type.__qualname__"
   if "type.__module__" is not a string or is equal to ""builtins"".

   Added in version 3.13.

PyObject *PyType_GetModuleName(PyTypeObject *type)
    * Part of the Stable ABI since version 3.13.*

   Return the type's module name. Equivalent to getting the
   "type.__module__" attribute.

   Added in version 3.13.

void *PyType_GetSlot(PyTypeObject *type, int slot)
    * Part of the Stable ABI since version 3.4.*

   Retorna el puntero de función almacenado en la ranura dada. Si el
   resultado es "NULL", esto indica que la ranura es "NULL" o que la
   función se llamó con parámetros no válidos. Las personas que llaman
   suelen convertir el puntero de resultado en el tipo de función
   apropiado.

   Consulte "PyType_Slot.slot" para conocer los posibles valores del
   argumento *slot*.

   Added in version 3.4.

   Distinto en la versión 3.10: "PyType_GetSlot()" ahora puede aceptar
   todos los tipos. Anteriormente, estaba limitado a heap types.

PyObject *PyType_GetModule(PyTypeObject *type)
    * Part of the Stable ABI since version 3.10.*

   Retorna el objeto módulo asociado con el tipo dado cuando se creó
   el tipo usando "PyType_FromModuleAndSpec()".

   Si no hay ningún módulo asociado con el tipo dado, establece
   "TypeError" y retorna "NULL".

   This function is usually used to get the module in which a method
   is defined. Note that in such a method,
   "PyType_GetModule(Py_TYPE(self))" may not return the intended
   result. "Py_TYPE(self)" may be a *subclass* of the intended class,
   and subclasses are not necessarily defined in the same module as
   their superclass. See "PyCMethod" to get the class that defines the
   method. See "PyType_GetModuleByToken()" for cases when "PyCMethod"
   cannot be used.

   Added in version 3.9.

void *PyType_GetModuleState(PyTypeObject *type)
    * Part of the Stable ABI since version 3.10.*

   Retorna el estado del objeto de módulo asociado con el tipo dado.
   Este es un atajo para llamar "PyModule_GetState()" en el resultado
   de "PyType_GetModule()".

   Si no hay ningún módulo asociado con el tipo dado, establece
   "TypeError" y retorna "NULL".

   Si el tipo *type* tiene un módulo asociado pero su estado es
   "NULL", retorna "NULL" sin establecer una excepción.

   Added in version 3.9.

PyObject *PyType_GetModuleByToken(PyTypeObject *type, const void *mod_token)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.15.*

   Find the first superclass whose module has the given module token,
   and return that module.

   Si no se encuentra ningún módulo, lanza "TypeError" y retorna
   "NULL".

   Esta función está pensada para ser utilizada junto con
   "PyModule_GetState()" para obtener el estado del módulo de los
   métodos de ranura (como "tp_init" o "nb_add") y en otros lugares
   donde la clase que define a un método no se puede pasar utilizando
   la convención de llamada "PyCMethod".

   Added in version 3.15.

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
    *Return value: Borrowed reference.** Part of the Stable ABI since
   version 3.13.*

   Find the first superclass whose module was created from the given
   "PyModuleDef" *def*, or whose module token is equal to *def*, and
   return that module.

   Note that modules created from a "PyModuleDef" always have their
   token set to the "PyModuleDef"'s address. In other words, this
   function is equivalent to "PyType_GetModuleByToken()", except that
   it:

   * returns a borrowed reference, and

   * has a non-"void*" argument type (which is a cosmetic difference
     in C).

   The returned reference is *borrowed* from *type*, and will be valid
   as long as you hold a reference to *type*. Do not release it with
   "Py_DECREF()" or similar.

   Added in version 3.11.

int PyType_GetBaseByToken(PyTypeObject *type, void *tp_token, PyTypeObject **result)
    * Part of the Stable ABI since version 3.14.*

   Find the first superclass in *type*'s *method resolution order*
   whose "Py_tp_token" token is equal to *tp_token*.

   * If found, set **result* to a new *strong reference* to it and
     return "1".

   * If not found, set **result* to "NULL" and return "0".

   * On error, set **result* to "NULL" and return "-1" with an
     exception set.

   The *result* argument may be "NULL", in which case **result* is not
   set. Use this if you need only the return value.

   The *tp_token* argument may not be "NULL".

   Added in version 3.14.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

   *This is Unstable API. It may change without warning in minor
   releases.*

   Attempt to assign a version tag to the given type.

   Returns 1 if the type already had a valid version tag or a new one
   was assigned, or 0 if a new tag could not be assigned.

   Added in version 3.12.

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

   Return true if instances of *type* support creating weak
   references, false otherwise. This function always succeeds. *type*
   must not be "NULL".

   Ver también:

     * Objetos de referencia débil

     * "weakref"


Crear tipos asignados en montículo (*heap*)
===========================================

Las siguientes funciones y estructuras se utilizan para crear heap
types.

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
    * Part of the Stable ABI since version 3.12.*

   Create and return a heap type from the *spec* (see
   "Py_TPFLAGS_HEAPTYPE").

   The metaclass *metaclass* is used to construct the resulting type
   object. When *metaclass* is "NULL", the metaclass is derived from
   *bases* (or *Py_tp_base[s]* slots if *bases* is "NULL", see below).

   Metaclasses that override "tp_new" are not supported, except if
   "tp_new" is "NULL".

   The *bases* argument can be used to specify base classes; it can
   either be only one class or a tuple of classes. If *bases* is
   "NULL", the "Py_tp_bases" slot is used instead. If that also is
   "NULL", the "Py_tp_base" slot is used instead. If that also is
   "NULL", the new type derives from "object".

   El argumento *module* se puede utilizar para registrar el módulo en
   el que se define la nueva clase. Debe ser un objeto de módulo o
   "NULL". Si no es "NULL", el módulo se asocia con el nuevo tipo y
   luego se puede recuperar con "PyType_GetModule()". El módulo
   asociado no es heredado por subclases; debe especificarse para cada
   clase individualmente.

   Esta función llama "PyType_Ready()" en el tipo nuevo.

   Note that this function does *not* fully match the behavior of
   calling "type()" or using the "class" statement. With user-provided
   base types or metaclasses, prefer calling "type" (or the metaclass)
   over "PyType_From*" functions. Specifically:

   * "__new__()" is not called on the new class (and it must be set to
     "type.__new__").

   * "__init__()" is not called on the new class.

   * "__init_subclass__()" is not called on any bases.

   * "__set_name__()" is not called on new descriptors.

   Added in version 3.12.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.10.*

   Equivalent to "PyType_FromMetaclass(NULL, module, spec, bases)".

   Added in version 3.9.

   Distinto en la versión 3.10: La función ahora acepta una sola clase
   como argumento *bases* y "NULL" como ranura "tp_doc".

   Distinto en la versión 3.12: The function now finds and uses a
   metaclass corresponding to the provided base classes.  Previously,
   only "type" instances were returned.The "tp_new" of the metaclass
   is *ignored*. which may result in incomplete initialization.
   Creating classes whose metaclass overrides "tp_new" is deprecated.

   Distinto en la versión 3.14: Creating classes whose metaclass
   overrides "tp_new" is no longer allowed.

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
    *Return value: New reference.** Part of the Stable ABI since
   version 3.3.*

   Equivalent to "PyType_FromMetaclass(NULL, NULL, spec, bases)".

   Added in version 3.3.

   Distinto en la versión 3.12: The function now finds and uses a
   metaclass corresponding to the provided base classes.  Previously,
   only "type" instances were returned.The "tp_new" of the metaclass
   is *ignored*. which may result in incomplete initialization.
   Creating classes whose metaclass overrides "tp_new" is deprecated.

   Distinto en la versión 3.14: Creating classes whose metaclass
   overrides "tp_new" is no longer allowed.

PyObject *PyType_FromSpec(PyType_Spec *spec)
    *Return value: New reference.** Part of the Stable ABI.*

   Equivalent to "PyType_FromMetaclass(NULL, NULL, spec, NULL)".

   Distinto en la versión 3.12: The function now finds and uses a
   metaclass corresponding to the base classes provided in
   *Py_tp_base[s]* slots. Previously, only "type" instances were
   returned.The "tp_new" of the metaclass is *ignored*. which may
   result in incomplete initialization. Creating classes whose
   metaclass overrides "tp_new" is deprecated.

   Distinto en la versión 3.14: Creating classes whose metaclass
   overrides "tp_new" is no longer allowed.

int PyType_Freeze(PyTypeObject *type)
    * Part of the Stable ABI since version 3.14.*

   Make a type immutable: set the "Py_TPFLAGS_IMMUTABLETYPE" flag.

   All base classes of *type* must be immutable.

   On success, return "0". On error, set an exception and return "-1".

   The type must not be used before it's made immutable. For example,
   type instances must not be created before the type is made
   immutable.

   Added in version 3.14.

type PyType_Spec
    * Part of the Stable ABI (including all members).*

   Estructura que define el comportamiento de un tipo.

   const char *name

      Nombre del tipo, utilizado para establecer
      "PyTypeObject.tp_name".

   int basicsize

      If positive, specifies the size of the instance in bytes. It is
      used to set "PyTypeObject.tp_basicsize".

      If zero, specifies that "tp_basicsize" should be inherited.

      If negative, the absolute value specifies how much space
      instances of the class need *in addition* to the superclass. Use
      "PyObject_GetTypeData()" to get a pointer to subclass-specific
      memory reserved this way. For negative "basicsize", Python will
      insert padding when needed to meet "tp_basicsize"'s alignment
      requirements.

      Distinto en la versión 3.12: Previously, this field could not be
      negative.

   int itemsize

      Size of one element of a variable-size type, in bytes. Used to
      set "PyTypeObject.tp_itemsize". See "tp_itemsize" documentation
      for caveats.

      If zero, "tp_itemsize" is inherited. Extending arbitrary
      variable-sized classes is dangerous, since some types use a
      fixed offset for variable-sized memory, which can then overlap
      fixed-sized memory used by a subclass. To help prevent mistakes,
      inheriting "itemsize" is only possible in the following
      situations:

      * The base is not variable-sized (its "tp_itemsize").

      * The requested "PyType_Spec.basicsize" is positive, suggesting
        that the memory layout of the base class is known.

      * The requested "PyType_Spec.basicsize" is zero, suggesting that
        the subclass does not access the instance's memory directly.

      * With the "Py_TPFLAGS_ITEMS_AT_END" flag.

   unsigned int flags

      Banderas (*flags*) del tipo, que se usan para establecer
      "PyTypeObject.tp_flags".

      Si el indicador "Py_TPFLAGS_HEAPTYPE" no está establecido,
      "PyType_FromSpecWithBases()" lo establece automáticamente.

   PyType_Slot *slots

      Arreglo de estructuras "PyType_Slot". Terminado por el valor de
      ranura especial "{0, NULL}".

      Each slot ID should be specified at most once.

type PyType_Slot
    * Part of the Stable ABI (including all members).*

   Estructura que define la funcionalidad opcional de un tipo, que
   contiene una ranura ID y un puntero de valor.

   int slot

      Una ranura ID.

      Las ranuras IDs se nombran como los nombres de campo de las
      estructuras "PyTypeObject", "PyNumberMethods",
      "PySequenceMethods", "PyMappingMethods" y "PyAsyncMethods" con
      un prefijo "Py_" agregado. Por ejemplo, use:

      * "Py_tp_dealloc" to set "PyTypeObject.tp_dealloc"

      * "Py_nb_add" to set "PyNumberMethods.nb_add"

      * "Py_sq_length" to set "PySequenceMethods.sq_length"

      An additional slot is supported that does not correspond to a
      "PyTypeObject" struct field:

      * "Py_tp_token"

      The following “offset” fields cannot be set using "PyType_Slot":

      * "tp_weaklistoffset" (use "Py_TPFLAGS_MANAGED_WEAKREF" instead
        if possible)

      * "tp_dictoffset" (use "Py_TPFLAGS_MANAGED_DICT" instead if
        possible)

      * "tp_vectorcall_offset" (use ""__vectorcalloffset__"" in
        PyMemberDef)

      If it is not possible to switch to a "MANAGED" flag (for
      example, for vectorcall or to support Python older than 3.12),
      specify the offset in "Py_tp_members". See PyMemberDef
      documentation for details.

      The following internal fields cannot be set at all when creating
      a heap type:

      * "tp_dict", "tp_mro", "tp_cache", "tp_subclasses", and
        "tp_weaklist".

      Setting "Py_tp_bases" or "Py_tp_base" may be problematic on some
      platforms. To avoid issues, use the *bases* argument of
      "PyType_FromSpecWithBases()" instead.

      Distinto en la versión 3.9: Las ranuras en "PyBufferProcs" se
      pueden configurar en la API ilimitada.

      Distinto en la versión 3.11: "bf_getbuffer" and
      "bf_releasebuffer" are now available under the limited API.

      Distinto en la versión 3.14: The field "tp_vectorcall" can now
      be set using "Py_tp_vectorcall".  See the field's documentation
      for details.

   void *pfunc

      El valor deseado de la ranura. En la mayoría de los casos, este
      es un puntero a una función.

      *pfunc* values may not be "NULL", except for the following
      slots:

      * "Py_tp_doc"

      * "Py_tp_token" (for clarity, prefer "Py_TP_USE_SPEC" rather
        than "NULL")

Py_tp_token
    * Part of the Stable ABI since version 3.14.*

   A "slot" that records a static memory layout ID for a class.

   If the "PyType_Spec" of the class is statically allocated, the
   token can be set to the spec using the special value
   "Py_TP_USE_SPEC":

      static PyType_Slot foo_slots[] = {
         {Py_tp_token, Py_TP_USE_SPEC},

   It can also be set to an arbitrary pointer, but you must ensure
   that:

   * The pointer outlives the class, so it's not reused for something
     else while the class exists.

   * It "belongs" to the extension module where the class lives, so it
     will not clash with other extensions.

   Use "PyType_GetBaseByToken()" to check if a class's superclass has
   a given token -- that is, check whether the memory layout is
   compatible.

   To get the token for a given class (without considering
   superclasses), use "PyType_GetSlot()" with "Py_tp_token".

   Added in version 3.14.

   Py_TP_USE_SPEC
       * Part of the Stable ABI since version 3.14.*

      Used as a value with "Py_tp_token" to set the token to the
      class's "PyType_Spec". Expands to "NULL".

      Added in version 3.14.
