Objetos de variáveis ​​de contexto

Adicionado na versão 3.7.

Alterado na versão 3.7.1:

Nota

No Python 3.7.1, as assinaturas de todas as APIs C de variáveis de contexto foram alteradas para usar ponteiros PyObject em vez de PyContext, PyContextVar e PyContextToken. Por exemplo:

// no 3.7.0:
PyContext *PyContext_New(void);

// no 3.7.1+:
PyObject *PyContext_New(void);

Veja bpo-34762 para mais detalhes.

Esta seção detalha a API C pública para o módulo contextvars.

type PyContext

A estrutura C usada para representar um objeto contextvars.Context.

type PyContextVar

A estrutura C usada para representar um objeto contextvars.ContextVar.

type PyContextToken

A estrutura C usada para representar um objeto contextvars.Token

PyTypeObject PyContext_Type

O objeto de tipo que representa o tipo de contexto.

PyTypeObject PyContextVar_Type

O objeto de tipo que representa o tipo de variável de contexto.

PyTypeObject PyContextToken_Type

O objeto de tipo que representa o tipo de token de variável de contexto.

Macros de verificação de tipo:

int PyContext_CheckExact(PyObject *o)

Retorna verdadeiro se o for do tipo PyContext_Type. o não deve ser NULL. Esta função sempre tem sucesso.

int PyContextVar_CheckExact(PyObject *o)

Retorna verdadeiro se o for do tipo PyContextVar_Type. o não deve ser NULL. Esta função sempre tem sucesso.

int PyContextToken_CheckExact(PyObject *o)

Retorna verdadeiro se o for do tipo PyContextToken_Type. o não deve ser NULL. Esta função sempre tem sucesso.

Funções de gerenciamento de objetos de contexto:

PyObject *PyContext_New(void)
Retorna valor: Nova referência.

Cria um novo objeto de contexto vazio. Retorna NULL se um erro ocorreu.

PyObject *PyContext_Copy(PyObject *ctx)
Retorna valor: Nova referência.

Cria uma cópia rasa do objeto de contexto ctx passado. Retorna NULL se um erro ocorreu.

PyObject *PyContext_CopyCurrent(void)
Retorna valor: Nova referência.

Cria uma cópia rasa do contexto da thread atual. Retorna NULL se um erro ocorreu.

int PyContext_Enter(PyObject *ctx)

Defina ctx como o contexto atual para o thread atual. Retorna 0 em caso de sucesso e -1 em caso de erro.

int PyContext_Exit(PyObject *ctx)

Desativa o contexto ctx e restaura o contexto anterior como o contexto atual para a thread atual. Retorna 0 em caso de sucesso e -1 em caso de erro.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

Register callback as a context object watcher for the current interpreter. Return an ID which may be passed to PyContext_ClearWatcher(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Adicionado na versão 3.14.

int PyContext_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id previously returned from PyContext_AddWatcher() for the current interpreter. Return 0 on success, or -1 and set an exception on error (e.g. if the given watcher_id was never registered.)

Adicionado na versão 3.14.

type PyContextEvent

Enumeration of possible context object watcher events:

  • Py_CONTEXT_SWITCHED: The current context has switched to a different context. The object passed to the watch callback is the now-current contextvars.Context object, or None if no context is current.

Adicionado na versão 3.14.

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

Context object watcher callback function. The object passed to the callback is event-specific; see PyContextEvent for details.

If the callback returns with an exception set, it must return -1; this exception will be printed as an unraisable exception using PyErr_FormatUnraisable(). Otherwise it should return 0.

There may already be a pending exception set on entry to the callback. In this case, the callback should return 0 with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

Adicionado na versão 3.14.

Funções de variável de contexto:

PyObject *PyContextVar_New(const char *name, PyObject *def)
Retorna valor: Nova referência.

Cria um novo objeto ContextVar. O parâmetro name é usado para fins de introspecção e depuração. O parâmetro def especifica um valor padrão para a variável de contexto, ou NULL para nenhum padrão. Se ocorrer um erro, esta função retorna NULL.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

Obtém o valor de uma variável de contexto. Retorna -1 se um erro ocorreu durante a pesquisa, e 0 se nenhum erro ocorreu, se um valor foi encontrado ou não.

Se a variável de contexto foi encontrada, value será um ponteiro para ela. Se a variável de contexto não foi encontrada, value apontará para:

  • default_value, se não for NULL;

  • o valor padrão de var, se não for NULL;

  • NULL

Exceto para NULL, a função retorna uma nova referência.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Retorna valor: Nova referência.

Define o valor de var como value no contexto atual. Retorna um novo objeto token para esta alteração, ou NULL se um erro ocorreu.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Redefine o estado da variável de contexto var para o estado que anterior a PyContextVar_Set() que retornou o token foi chamado. Esta função retorna 0 em caso de sucesso e -1 em caso de erro.