# 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.

  Controlador genérico para la ranura `tp_alloc` de un objeto tipo. Usa el mecanismo de asignación de memoria predeterminado de Python para asignar una nueva instancia e inicializar todo su contenido a `NULL`.

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

  Controlador genérico para la ranura `tp_new` de un objeto tipo. Crea una nueva instancia utilizando la ranura del tipo `tp_alloc`.

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_GetModuleByDef()` 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_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
  Return value: Borrowed reference. Part of the Stable ABI since version 3.13.

  Encuentra la primer superclase cuyo módulo fue creado a partir del `PyModuleDef` def dado, y retorna ese módulo.

  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`.

  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 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`. (For backwards compatibility, other `PyType_From*` functions allow such metaclasses. They ignore `tp_new`, which may result in incomplete initialization. This is deprecated and in Python 3.14+ such metaclasses will not be supported.)

  El argumento bases se puede utilizar para especificar clases base; puede ser solo una clase o una tupla de clases. Si bases es `NULL`, en su lugar se utiliza la ranura Py_tp_bases. Si esa también es `NULL`, se usa la ranura Py_tp_base en su lugar. Si también es `NULL`, el nuevo tipo se deriva de `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 and in Python 3.14+ it will be 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 and in Python 3.14+ it will be 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 and in Python 3.14+ it will be no longer allowed.

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` para establecer `PyTypeObject.tp_dealloc`

    - `Py_nb_add` para establecer `PyNumberMethods.nb_add`

    - `Py_sq_length` para establecer `PySequenceMethods.sq_length`

    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 fields cannot be set at all when creating a heap type:

    - `tp_vectorcall` (use `tp_new` and/or `tp_init`)

    - Internal fields: `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.

  void *pfunc

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

    Las ranuras que no sean `Py_tp_doc` pueden no ser `NULL`.