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.