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.