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.
- int PyContext_ClearFreeList()
- Clear the context variable free list. Return the total number of freed items. This function always succeeds.
Context variable functions:
- 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 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
If the value was found, the function will create a new reference to it.
- 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.
- 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.