Context Variables Objects

Added in version 3.7.

Changed in version 3.7.1:

Note

In Python 3.7.1 the signatures of all context variables C APIs were changed to use PyObject pointers instead of PyContext, PyContextVar, and PyContextToken, e.g.:

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

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

See bpo-34762 for more details.

This section details the public C API for the contextvars module.

type PyContext

The C structure used to represent a contextvars.Context object.

type PyContextVar

The C structure used to represent a contextvars.ContextVar object.

type PyContextToken

The C structure used to represent a contextvars.Token object.

PyTypeObject PyContext_Type

The type object representing the context type.

PyTypeObject PyContextVar_Type

The type object representing the context variable type.

PyTypeObject PyContextToken_Type

The type object representing the context variable token type.

Type-check macros:

int PyContext_CheckExact(PyObject *o)

Return true if o is of type PyContext_Type. o must not be NULL. This function always succeeds.

int PyContextVar_CheckExact(PyObject *o)

Return true if o is of type PyContextVar_Type. o must not be NULL. This function always succeeds.

int PyContextToken_CheckExact(PyObject *o)

Return true if o is of type PyContextToken_Type. o must not be NULL. This function always succeeds.

Context object management functions:

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

Create a new empty context object. Returns NULL if an error has occurred.

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

Create a shallow copy of the passed ctx context object. Returns NULL if an error has occurred.

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

Create a shallow copy of the current thread context. Returns NULL if an error has occurred.

int PyContext_Enter(PyObject *ctx)

Set ctx as the current context for the current thread. Returns 0 on success, and -1 on error.

int PyContext_Exit(PyObject *ctx)

Deactivate the ctx context and restore the previous context as the current context for the current thread. Returns 0 on success, and -1 on error.

int PyContext_AddWatcher(PyObject *callback)

Registers the callable object callback as a context object watcher for the current interpreter. When a context event occurs, callback is called with two arguments:

  1. An event type ID from PyContextEvent.

  2. An object containing event-specific supplemental data; see PyContextEvent for details.

Any exception raised by callback will be printed as an unraisable exception as if by a call to PyErr_FormatUnraisable(), then discarded.

On success, this function returns a non-negative ID which may be passed to PyContext_ClearWatcher() to unregister the callback and remove the reference this function adds to callback. Sets an exception and returns -1 on error (e.g., no more watcher IDs available).

Example using a C function as the callback:

static PyObject *
my_callback(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{
    if (PyVectorcall_NARGS(nargs) != 2) {
        PyErr_Format(PyExc_TypeError, "want 2 args, got %zd", nargs);
        return NULL;
    }
    int event = PyLong_AsInt(args[0]);
    if (event == -1 && PyErr_Occurred()) {
        return NULL;
    }
    if (event != Py_CONTEXT_SWITCHED) {
        Py_RETURN_NONE;
    }
    PyObject *ctx = args[1];

    // Do something interesting with self and ctx here.

    Py_RETURN_NONE;
}

PyMethodDef my_callback_md = {
    .ml_name = "my_callback",
    .ml_meth = (PyCFunction)(void *)&my_callback,
    .ml_flags = METH_FASTCALL,
    .ml_doc = NULL,
};

int
register_my_callback(PyObject *callback_state)
{
    PyObject *cb = PyCFunction_New(&my_callback_md, callback_state);
    if (cb == NULL) {
        return -1;
    }
    int id = PyContext_AddWatcher(cb);
    Py_CLEAR(cb);
    return id;
}

Added in version 3.14.

int PyContext_ClearWatcher(int watcher_id)

Clears the watcher identified by watcher_id previously returned from PyContext_AddWatcher() for the current interpreter, and removes the reference created for the registered callback object. Returns 0 on success, or sets an exception and returns -1 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.

Context variable functions:

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

Create a new ContextVar object. The name parameter is used for introspection and debug purposes. The def parameter specifies a default value for the context variable, or NULL for no default. If an error has occurred, this function returns NULL.

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

Get the value of a context variable. Returns -1 if an error has occurred during lookup, and 0 if no error occurred, whether or not a value was found.

If the context variable was found, value will be a pointer to it. If the context variable was not found, value will point to:

  • default_value, if not NULL;

  • the default value of var, if not NULL;

  • NULL

Except for NULL, the function returns a new reference.

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

Set the value of var to value in the current context. Returns a new token object for this change, or NULL if an error has occurred.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Reset the state of the var context variable to that it was in before PyContextVar_Set() that returned the token was called. This function returns 0 on success and -1 on error.