# Capsules

Consulte Fornecendo uma API C para um módulo de extensão para obter mais informações sobre o uso desses objetos.

Adicionado na versão 3.1.

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

type PyCapsule_Destructor
  Parte da ABI Estável.

  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`. Esta função sempre tem sucesso.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
  Retorna valor: Nova referência. Parte da ABI Estável.

  Cria um `PyCapsule` que encapsula o ponteiro. O argumento pointer pode não ser `NULL`.

  Em caso de falha, define uma exceção e retorna `NULL`.

  A string name pode ser `NULL` ou um ponteiro para uma string C válida. Se não for `NULL`, essa string deverá sobreviver à cápsula. (Embora seja permitido liberá-lo dentro do descructor.)

  Se o argumento destructor não for `NULL`, ele será chamado com a cápsula como argumento quando for destruído.

  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)
  Parte da ABI Estável.

  Recupera o pointer armazenado na cápsula. Em caso de falha, define uma exceção e retorna `NULL`.

  O parâmetro name deve ser comparado exatamente com o nome armazenado na cápsula. Se o nome armazenado na cápsula for `NULL`, o name passado também deve ser `NULL`. Python usa a função C `strcmp()` para comparar nomes de cápsulas.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
  Parte da ABI Estável.

  Retorna o destruidor atual armazenado na cápsula. Em caso de falha, define uma exceção e retorna `NULL`.

  É legal para uma cápsula ter um destruidor `NULL`. Isso torna um código de retorno `NULL` um tanto ambíguo; use `PyCapsule_IsValid()` ou `PyErr_Occurred()` para desambiguar.

void *PyCapsule_GetContext(PyObject *capsule)
  Parte da ABI Estável.

  Retorna o contexto atual armazenado na cápsula. Em caso de falha, define uma exceção e retorna `NULL`.

  É legal para uma cápsula ter um contexto `NULL`. Isso torna um código de retorno `NULL` um tanto ambíguo; use `PyCapsule_IsValid()` ou `PyErr_Occurred()` para desambiguar.

const char *PyCapsule_GetName(PyObject *capsule)
  Parte da ABI Estável.

  Retorna o nome atual armazenado na cápsula. Em caso de falha, define uma exceção e retorna `NULL`.

  É legal para uma cápsula ter um nome `NULL`. Isso torna um código de retorno `NULL` um tanto ambíguo; use `PyCapsule_IsValid()` ou `PyErr_Occurred()` para desambiguar.

void *PyCapsule_Import(const char *name, int no_block)
  Parte da ABI Estável.

  Importa um ponteiro para um objeto C de um atributo de cápsula em um módulo. O parâmetro name deve especificar o nome completo do atributo, como em `module.attribute`. O name armazenado na cápsula deve corresponder exatamente a essa string.

  Esta função divide name no caractere `.` e importa o primeiro elemento. Em seguida, processa os elementos seguintes usando pesquisas de atributos.

  Retorna o ponteiro interno pointer da cápsula com sucesso. Em caso de falha, define uma exceção e retorna `NULL`.

  Nota

  Se name apontar para um atributo de algum submódulo ou subpacote, esse submódulo ou subpacote deverá ser importado previamente usando outros meios (por exemplo, usando `PyImport_ImportModule()`) para que as pesquisas de atributos sejam bem-sucedidas.

  Alterado na versão 3.3: no_block não tem mais efeito.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
  Parte da ABI Estável.

  Determina se capsule é ou não uma cápsula válida. Uma cápsula válida é diferente de `NULL`, passa `PyCapsule_CheckExact()`, possui um ponteiro diferente de `NULL` armazenado e seu nome interno corresponde ao parâmetro name. (Consulte `PyCapsule_GetPointer()` para obter informações sobre como os nomes das cápsulas são comparados.)

  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)
  Parte da ABI Estável.

  Define o ponteiro de contexto dentro de capsule para context.

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

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
  Parte da ABI Estável.

  Define o destrutor dentro de capsule para destructor.

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

int PyCapsule_SetName(PyObject *capsule, const char *name)
  Parte da ABI Estável.

  Define o nome dentro de capsule como name. Se não for `NULL`, o nome deve sobreviver à cápsula. Se o name anterior armazenado na cápsula não era `NULL`, nenhuma tentativa será feita para liberá-lo.

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

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
  Parte da ABI Estável.

  Define o ponteiro nulo dentro de capsule para pointer. O ponteiro não pode ser `NULL`.

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