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 ponteirovoid*
) 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.
-
PyObject*
PyCapsule_New
(void *pointer, const char *name, PyCapsule_Destructor destructor)¶ - Return value: New reference.
Cria um
PyCapsule
que encapsula o ponteiro. O argumento pointer pode não serNULL
.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 forNULL
, 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 usandoPyCapsule_Import()
.
-
void*
PyCapsule_GetPointer
(PyObject *capsule, const char *name)¶ 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 serNULL
. Python usa a função Cstrcmp()
para comparar nomes de cápsulas.
-
PyCapsule_Destructor
PyCapsule_GetDestructor
(PyObject *capsule)¶ 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 retornoNULL
um tanto ambíguo; usePyCapsule_IsValid()
ouPyErr_Occurred()
para desambiguar.
-
void*
PyCapsule_GetContext
(PyObject *capsule)¶ 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 retornoNULL
um tanto ambíguo; usePyCapsule_IsValid()
ouPyErr_Occurred()
para desambiguar.
-
const char*
PyCapsule_GetName
(PyObject *capsule)¶ 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 retornoNULL
um tanto ambíguo; usePyCapsule_IsValid()
ouPyErr_Occurred()
para desambiguar.
-
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 (usandoPyImport_ImportModuleNoBlock()
). Se no_block for falso, importa o módulo convencionalmente (usandoPyImport_ImportModule()
).Retorna o ponteiro interno pointer da cápsula com sucesso. Em caso de falha, define uma exceção e retorna
NULL
.
-
int
PyCapsule_IsValid
(PyObject *capsule, const char *name)¶ Determina se capsule é ou não uma cápsula válida. Uma cápsula válida é diferente de
NULL
, passaPyCapsule_CheckExact()
, possui um ponteiro diferente deNULL
armazenado e seu nome interno corresponde ao parâmetro name. (ConsultePyCapsule_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 comPyCapsule_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. Retorna diferente de zero e define 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. Retorna diferente de zero e define uma exceção em caso de falha.
-
int
PyCapsule_SetName
(PyObject *capsule, const char *name)¶ 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 eraNULL
, 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.