Context Variables Objects — Python documentation
Context Variables Objects
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 :issue:`34762` for more details.
New in version 3.7.
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)
- Create a new empty context object. Returns
NULL
if an error has occurred.
- Create a shallow copy of the passed ctx context object. Returns
NULL
if an error has occurred.
- PyObject *PyContext_CopyCurrent(void)
- 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:
- 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, orNULL
for no default. If an error has occurred, this function returnsNULL
.
- 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, and0
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.
- 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.
- 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.