# Capsules

Consulte Providing a C API for an Extension Module para obter mais informações sobre o uso desses objetos.

Novo na versão 3.1.

`PyCapsule`

  Este subtipo de `PyObject` representa um valor opaco, útil para módulos de extensão C que precisam passar um valor opaco (como ponteiro `void*`) através do código Python para outro código C . É frequentemente usado para disponibilizar um ponteiro de função C definido em um módulo para outros módulos, para que o mecanismo de importação regular possa ser usado para acessar APIs C definidas em módulos carregados dinamicamente.

`PyCapsule_Destructor`

  O tipo de um retorno de chamada destruidor para uma cápsula. Definido como:

      typedef void (*PyCapsule_Destructor)(PyObject *);

  Veja `PyCapsule_New()` para a semântica dos retornos de chamada PyCapsule_Destructor.

int `PyCapsule_CheckExact`(PyObject *p)

  Retorna true se seu argumento é um `PyCapsule`.

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

  Create a `PyCapsule` encapsulating the pointer. The pointer argument may not be NULL.

  Em caso de falha, defina uma exceção e retorne NULL.

  The name string may either be NULL or a pointer to a valid C string. If non-NULL, this string must outlive the capsule. (Though it is permitted to free it inside the destructor.)

  If the destructor argument is not NULL, it will be called with the capsule as its argument when it is destroyed.

  Se esta cápsula for armazenada como um atributo de um módulo, o name deve ser especificado como `modulename.attributename`. Isso permitirá que outros módulos importem a cápsula usando `PyCapsule_Import()`.

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

  Retrieve the pointer stored in the capsule. On failure, set an exception and return 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)

  Return the current destructor stored in the capsule. On failure, set an exception and return NULL.

  It is legal for a capsule to have a NULL destructor. This makes a NULL return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

void* `PyCapsule_GetContext`(PyObject *capsule)

  Return the current context stored in the capsule. On failure, set an exception and return NULL.

  It is legal for a capsule to have a NULL context. This makes a NULL return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

const char* `PyCapsule_GetName`(PyObject *capsule)

  Return the current name stored in the capsule. On failure, set an exception and return NULL.

  It is legal for a capsule to have a NULL name. This makes a NULL return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

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

  Importa um ponteiro para um objeto C de um atributo capsule em um módulo. O parâmetro name deve especificar o nome completo do atributo, como em `module.attribute`. O nome armazenado na cápsula deve corresponder exatamente a essa sequência. Se no_block for verdadeiro, importa o módulo sem bloquear (usando `PyImport_ImportModuleNoBlock()`). Se no_block for falso, importa o módulo convencionalmente (usando `PyImport_ImportModule()`).

  Return the capsule’s internal pointer on success. On failure, set an exception and return NULL.

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

  Determines whether or not capsule is a valid capsule. A valid capsule is non-NULL, passes `PyCapsule_CheckExact()`, has a non-NULL pointer stored in it, and its internal name matches the name parameter. (See `PyCapsule_GetPointer()` for information on how capsule names are compared.)

  Em outras palavras, se `PyCapsule_IsValid()` retornar um valor verdadeiro, as chamadas para qualquer um dos acessadores (qualquer função que comece com `PyCapsule_Get()`) terão êxito garantido.

  Retorna um valor diferente de zero se o objeto for válido e corresponder ao nome passado. Retorna `0` caso contrário. Esta função não falhará.

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

  Define o ponteiro de contexto dentro de capsule para context.

  Retorna `0` em caso de sucesso. Retorne diferente de zero e defina uma exceção em caso de falha.

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

  Define o destrutor dentro de capsule para destructor.

  Retorna `0` em caso de sucesso. Retorne diferente de zero e defina uma exceção em caso de falha.

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

  Set the name inside capsule to name. If non-NULL, the name must outlive the capsule. If the previous name stored in the capsule was not NULL, no attempt is made to free it.

  Retorna `0` em caso de sucesso. Retorne diferente de zero e defina uma exceção em caso de falha.

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

  Set the void pointer inside capsule to pointer. The pointer may not be NULL.

  Retorna `0` em caso de sucesso. Retorne diferente de zero e defina uma exceção em caso de falha.