Objetos de variables de contexto

Added in version 3.7.

Distinto en la versión 3.7.1:

Nota

En Python 3.7.1, las firmas de todas las variables de contexto C APIs fueron cambiadas para usar punteros PyObject en lugar de PyContext, PyContextVar, y PyContextToken, por ejemplo:

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

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

Ver bpo-34762 para más detalles.

Esta sección detalla la API pública de C para el módulo contextvars.

type PyContext

La estructura C utilizada para representar un objeto contextvars.Context.

type PyContextVar

La estructura C utilizada para representar un objeto contextvars.ContextVar.

type PyContextToken

La estructura C solía representar un objeto contextvars.Token.

PyTypeObject PyContext_Type

El objeto de tipo que representa el tipo context.

PyTypeObject PyContextVar_Type

El objeto tipo que representa el tipo variable de contexto.

PyTypeObject PyContextToken_Type

El tipo objeto que representa el tipo token de variable de contexto.

Macros de verificación de tipo:

int PyContext_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContext_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

int PyContextVar_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContextVar_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

int PyContextToken_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContextToken_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

Funciones de gestión de objetos de contexto:

PyObject *PyContext_New(void)
Return value: New reference.

Crea un nuevo objeto de contexto vacío. Retorna NULL si se ha producido un error.

PyObject *PyContext_Copy(PyObject *ctx)
Return value: New reference.

Crea una copia superficial del objeto de contexto ctx pasado. Retorna NULL si se ha producido un error.

PyObject *PyContext_CopyCurrent(void)
Return value: New reference.

Crea una copia superficial del contexto actual del hilo. Retorna NULL si se ha producido un error.

int PyContext_Enter(PyObject *ctx)

Establece ctx como el contexto actual para el hilo actual. Retorna 0 en caso de éxito y -1 en caso de error.

int PyContext_Exit(PyObject *ctx)

Desactiva el contexto ctx y restaura el contexto anterior como el contexto actual para el hilo actual. Retorna 0 en caso de éxito y -1 en caso de error.

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.

Added in version 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.)

Added in version 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.

Added in version 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.

Added in version 3.14.

Funciones variables de contexto:

PyObject *PyContextVar_New(const char *name, PyObject *def)
Return value: New reference.

Crea un nuevo objeto ContextVar. El parámetro name se usa para propósitos de introspección y depuración. El parámetro def especifica el valor predeterminado para la variable de contexto, o NULL para no especificar un valor predeterminado. Si se ha producido un error, esta función retorna NULL.

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

Obtiene el valor de una variable de contexto. Retorna -1 si se produjo un error durante la búsqueda y 0 si no se produjo ningún error, se haya encontrado o no un valor.

Si se encontró la variable de contexto, value será un puntero a ella. Si la variable de contexto not se encontró, value apuntará a:

  • default_value, si no es NULL;

  • el valor predeterminado de var, si no es NULL;

  • NULL

A excepción de NULL, la función retorna una nueva referencia.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Return value: New reference.

Establece el valor de var en value en el contexto actual. Retorna un nuevo objeto token para este cambio, o NULL si se ha producido un error.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Restablece el estado de la variable de contexto var a la que estaba antes PyContextVar_Set() que retornó el token fue llamado. Esta función retorna 0 en caso de éxito y -1 en caso de error.