contextvars

Contextvars is a module in the Python standard library that provides context-local storage for asynchronous and concurrent code. It was introduced in Python 3.7 (PEP 567) to address the challenges of implicit context sharing across asynchronous tasks, ensuring that data associated with one task does not inadvertently leak into another.

The core concept is the ContextVar class. A ContextVar represents a value that is local to the current context. Each running task or thread has its own view of the context, so setting a value in one task does not affect other tasks running concurrently. Accessing a variable with get(default=…) returns the current value for the active context, or the provided default if no value has been set. Setting a value with set(value) returns a Token, which can be used to revert the variable to its previous value via reset(token) or by using the token in a future context switch.

Contexts can be copied and propagated. copy_context() returns a Context object representing the current context, and Context.run(callable, …) executes a function within that specific context. When a new asyncio.Task is created, the current context is captured and becomes the initial context for that task, meaning changes within one task do not automatically affect others unless explicitly propagated.

Common use cases include tracking request-scoped data in asynchronous web applications, such as correlation IDs for logging or tracing, and maintaining per-task state without resorting to global variables. Contextvars is not a replacement for proper synchronization in multi-threaded code, but it provides a robust mechanism for local context in asynchronous environments.