Context Variables Objects¶

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

This section details the public C API for thecontextvars module.

typePyContext¶

The C structure used to represent acontextvars.Contextobject.

typePyContextVar¶

The C structure used to represent acontextvars.ContextVarobject.

typePyContextToken¶

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.

intPyContext_AddWatcher(PyContext_WatchCallbackcallback)¶

Registercallback as a context object watcher for the current interpreter.Return an ID which may be passed toPyContext_ClearWatcher().In case of error (e.g. no more watcher IDs available),return-1 and set an exception.

Added in version 3.14.

intPyContext_ClearWatcher(intwatcher_id)¶

Clear watcher identified bywatcher_id previously returned fromPyContext_AddWatcher() for the current interpreter.Return0 on success, or-1 and set an exception on error(e.g. if the givenwatcher_id was never registered.)

Added in version 3.14.

typePyContextEvent¶

Enumeration of possible context object watcher events:

• Py_CONTEXT_SWITCHED: Thecurrent context has switched to adifferent context. The object passed to the watch callback is thenow-currentcontextvars.Context object, or None if no context iscurrent.

Added in version 3.14.

typedefint(*PyContext_WatchCallback)(PyContextEventevent,PyObject*obj)¶

Context object watcher callback function. The object passed to the callbackis event-specific; seePyContextEvent for details.

If the callback returns with an exception set, it must return-1; thisexception will be printed as an unraisable exception usingPyErr_FormatUnraisable(). Otherwise it should return0.

There may already be a pending exception set on entry to the callback. Inthis case, the callback should return0 with the same exception stillset. This means the callback may not call any other API that can set anexception unless it saves and clears the exception state first, and restoresit before returning.

Added in version 3.14.

Context variable functions:

PyObject*PyContextVar_New(constchar*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.