Context Variables Objects

Note

Changed in version 3.7.1:

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.

New in version 3.7.

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

PyContext

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

PyContextVar

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

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_ClearFreeList()

Clear the context variable free list. Return the total number of freed items. This function always succeeds.

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 may optionally specify the default value for the context variable. 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

If the value was found, the function will create a new reference to it.

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

Set the value of var to value in the current context. Returns a pointer to a PyObject object, 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.