Context Variables Objects

Note

Changed in version 3.7.1:

In Python 3.7.1 the signatures of all context variablesC APIs werechanged to usePyObject pointers insteadofPyContext,PyContextVar, andPyContextToken, e.g.:

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

Seebpo-34762 for more details.

New in version 3.7.

This section details the public C API for thecontextvars module.

PyContext

The C structure used to represent acontextvars.Contextobject.

PyContextVar

The C structure used to represent acontextvars.ContextVarobject.

PyContextToken

The C structure used to represent acontextvars.Token object.

PyTypeObjectPyContext_Type

The type object representing thecontext type.

PyTypeObjectPyContextVar_Type

The type object representing thecontext variable type.

PyTypeObjectPyContextToken_Type

The type object representing thecontext variable token type.

Type-check macros:

intPyContext_CheckExact(PyObject *o)

Return true ifo is of typePyContext_Type.o must not beNULL. This function always succeeds.

intPyContextVar_CheckExact(PyObject *o)

Return true ifo is of typePyContextVar_Type.o must not beNULL. This function always succeeds.

intPyContextToken_CheckExact(PyObject *o)

Return true ifo is of typePyContextToken_Type.o must not beNULL. This function always succeeds.

Context object management functions:

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

Create a new empty context object. ReturnsNULL if an errorhas occurred.

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

Create a shallow copy of the passedctx context object.ReturnsNULL if an error has occurred.

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

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

intPyContext_Enter(PyObject *ctx)

Setctx as the current context for the current thread.Returns0 on success, and-1 on error.

intPyContext_Exit(PyObject *ctx)

Deactivate thectx context and restore the previous context as thecurrent context for the current thread. Returns0 on success,and-1 on error.

Context variable functions:

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

Create a newContextVar object. Thename parameter is usedfor introspection and debug purposes. Thedef parameter specifiesa default value for the context variable, orNULL for no default.If an error has occurred, this function returnsNULL.

intPyContextVar_Get(PyObject *var,PyObject *default_value,PyObject **value)

Get the value of a context variable. Returns-1 if an error hasoccurred during lookup, and0 if no error occurred, whether or nota value was found.

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

  • default_value, if notNULL;

  • the default value ofvar, if notNULL;

  • NULL

Except forNULL, the function returns a new reference.

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

Set the value ofvar tovalue in the current context. Returnsa new token object for this change, orNULL if an error has occurred.

intPyContextVar_Reset(PyObject *var,PyObject *token)

Reset the state of thevar context variable to that it was in beforePyContextVar_Set() that returned thetoken was called.This function returns0 on success and-1 on error.