# Cápsulas

Consulta Proporcionar una API C para un módulo de extensión para obtener más información sobre el uso de estos objetos.

Nuevo en la versión 3.1.

`PyCapsule`

  Este subtipo de `PyObject` representa un valor opaco, útil para los módulos de extensión C que necesitan pasar un valor opaco (como un puntero `void*`) a través del código Python a otro código C . A menudo se usa para hacer que un puntero de función C definido en un módulo esté disponible para otros módulos, por lo que el mecanismo de importación regular se puede usar para acceder a las API C definidas en módulos cargados dinámicamente.

`PyCapsule_Destructor`

  El tipo de devolución de llamada de un destructor para una cápsula. Definido como:

      typedef void (*PyCapsule_Destructor)(PyObject *);

  Consulte `PyCapsule_New()` para conocer la semántica de las devoluciones de llamada de PyCapsule_Destructor.

int `PyCapsule_CheckExact`(PyObject *p)

  Retorna verdadero si su argumento es a `PyCapsule`. Esta función siempre finaliza con éxito.

PyObject* `PyCapsule_New`(void *pointer, const char *name, PyCapsule_Destructor destructor)
  Return value: New reference.

  Crea un `PyCapsule` encapsulando el pointer. El argumento pointer puede no ser `NULL`.

  En caso de falla, establece una excepción y retorna `NULL`.

  La cadena de caracteres name puede ser `NULL` o un puntero a una cadena C válida. Si no es `NULL`, esta cadena de caracteres debe sobrevivir a la cápsula. (Aunque está permitido liberarlo dentro del destructor).

  Si el argumento destructor no es `NULL`, se llamará con la cápsula como argumento cuando se destruya.

  Si esta cápsula se almacenará como un atributo de un módulo, el nombre name debe especificarse como `modulename.attributename`. Esto permitirá que otros módulos importen la cápsula usando `PyCapsule_Import()`.

void* `PyCapsule_GetPointer`(PyObject *capsule, const char *name)

  Recupera el pointer almacenado en la cápsula. En caso de falla, establece una excepción y retorna `NULL`.

  El parámetro name debe compararse exactamente con el nombre almacenado en la cápsula. Si el nombre almacenado en la cápsula es `NULL`, el name pasado también debe ser `NULL`. Python usa la función C `strcmp()` para comparar nombres de cápsulas.

PyCapsule_Destructor `PyCapsule_GetDestructor`(PyObject *capsule)

  Retorna el destructor actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna `NULL`.

  Es legal que una cápsula tenga un destructor `NULL`. Esto hace que un código de retorno `NULL` sea algo ambiguo; use `PyCapsule_IsValid()` o `PyErr_Occurred()` para desambiguar.

void* `PyCapsule_GetContext`(PyObject *capsule)

  Retorna el contexto actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna `NULL`.

  Es legal que una cápsula tenga un contexto `NULL`. Esto hace que un código de retorno `NULL` sea algo ambiguo; use `PyCapsule_IsValid()` o `PyErr_Occurred()` para desambiguar.

const char* `PyCapsule_GetName`(PyObject *capsule)

  Retorna el nombre actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna `NULL`.

  Es legal que una cápsula tenga un nombre `NULL`. Esto hace que un código de retorno `NULL` sea algo ambiguo; use `PyCapsule_IsValid()` o `PyErr_Occurred()` para desambiguar.

void* `PyCapsule_Import`(const char *name, int no_block)

  Importa un puntero a un objeto C desde un atributo cápsula en un módulo. El parámetro name debe especificar el nombre completo del atributo, como en `module.attribute`. El nombre name almacenado en la cápsula debe coincidir exactamente con esta cadena de caracteres. Si no_block es verdadero, importa el módulo sin bloquear (usando `PyImport_ImportModuleNoBlock()`). Si no_block es falso, importa el módulo convencionalmente (usando `PyImport_ImportModule()`).

  Retorna el puntero pointer interno de la cápsula en caso de éxito. En caso de falla, establece una excepción y retorna `NULL`.

int `PyCapsule_IsValid`(PyObject *capsule, const char *name)

  Determina si capsule es o no una cápsula válida. Una cápsula válida no es `NULL`, pasa `PyCapsule_CheckExact()`, tiene un puntero no `NULL` almacenado y su nombre interno coincide con el parámetro name. (Consulte `PyCapsule_GetPointer()` para obtener información sobre cómo se comparan los nombres de las cápsulas).

  En otras palabras, si `PyCapsule_IsValid()` retorna un valor verdadero, las llamadas a cualquiera de las funciones de acceso (cualquier función que comience con `PyCapsule_Get()`) tienen éxito.

  Retorna un valor distinto de cero si el objeto es válido y coincide con el nombre pasado. Retorna `0` de lo contrario. Esta función no fallará.

int `PyCapsule_SetContext`(PyObject *capsule, void *context)

  Establece el puntero de contexto dentro de capsule a context.

  Retorna `0` en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int `PyCapsule_SetDestructor`(PyObject *capsule, PyCapsule_Destructor destructor)

  Establece el destructor dentro de capsule en destructor.

  Retorna `0` en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int `PyCapsule_SetName`(PyObject *capsule, const char *name)

  Establece el nombre dentro de capsule a name. Si no es `NULL`, el nombre debe sobrevivir a la cápsula. Si el name anterior almacenado en la cápsula no era `NULL`, no se intenta liberarlo.

  Retorna `0` en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int `PyCapsule_SetPointer`(PyObject *capsule, void *pointer)

  Establece el puntero vacío dentro de capsule a pointer. El puntero puede no ser `NULL`.

  Retorna `0` en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.