Context Variables Objects — Python 3.9.2 documentation

# 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.

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.