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.

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

type PyCapsule_Destructor
    * Part of the Stable ABI.*

   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.** Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

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

   The *name* parameter must compare exactly to the name stored in the
   capsule. If the name stored in the capsule is "NULL", the *name*
   passed in must also be "NULL".  Python uses the C function
   "strcmp()" to compare capsule names.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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.

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

   Distinto en la versión 3.3: *no_block* ya no tiene efecto.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
    * Part of the Stable ABI.*

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

   In other words, if "PyCapsule_IsValid()" returns a true value,
   calls to any of the accessors (any function starting with
   "PyCapsule_Get") are guaranteed to succeed.

   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)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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)
    * Part of the Stable ABI.*

   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.
