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.Contextobject.
-
PyContextVar¶ The C structure used to represent a
contextvars.ContextVarobject.
-
PyContextToken¶ The C structure used to represent a
contextvars.Tokenobject.
-
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 beNULL. This function always succeeds.
-
int
PyContextVar_CheckExact(PyObject *o)¶ Return true if o is of type
PyContextVar_Type. o must not beNULL. This function always succeeds.
-
int
PyContextToken_CheckExact(PyObject *o)¶ Return true if o is of type
PyContextToken_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. Returns
NULLif an error has occurred.
-
PyObject *
PyContext_Copy(PyObject *ctx)¶ - Return value: New reference.
Create a shallow copy of the passed ctx context object. Returns
NULLif an error has occurred.
-
PyObject *
PyContext_CopyCurrent(void)¶ - Return value: New reference.
Create a shallow copy of the current thread context. Returns
NULLif an error has occurred.
-
int
PyContext_Enter(PyObject *ctx)¶ Set ctx as the current context for the current thread. Returns
0on success, and-1on error.
-
int
PyContext_Exit(PyObject *ctx)¶ Deactivate the ctx context and restore the previous context as the current context for the current thread. Returns
0on success, and-1on error.
Context variable functions:
-
PyObject *
PyContextVar_New(const char *name, PyObject *def)¶ - Return value: New reference.
Create a new
ContextVarobject. The name parameter is used for introspection and debug purposes. The def parameter specifies a default value for the context variable, orNULLfor 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
-1if an error has occurred during lookup, and0if 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.
-
PyObject *
PyContextVar_Set(PyObject *var, PyObject *value)¶ - Return value: New reference.
Set the value of var to value in the current context. Returns a new token object for this change, or
NULLif 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 returns0on success and-1on error.