contextvars.ContextVar

The ContextVar class has the following constructor signature: ContextVar(name, *, default=_NO_DEFAULT). The name parameter is used for introspection and debug purposes, and is exposed as a read-only ContextVar.name attribute. The default parameter is optional. Example:

# Declare a context variable 'var' with the default value 42.
var = ContextVar('var', default=42)

(The _NO_DEFAULT is an internal sentinel object used to detect if the default value was provided.)

ContextVar.get(default=_NO_DEFAULT) returns a value for the context variable for the current Context:

# Get the value of `var`.
var.get()

If there is no value for the variable in the current context, ContextVar.get() will:

• return the value of the default argument of the get() method, if provided; or
• return the default value for the context variable, if provided; or
• raise a LookupError.

ContextVar.set(value) -> Token is used to set a new value for the context variable in the current Context:

# Set the variable 'var' to 1 in the current context.
var.set(1)

ContextVar.reset(token) is used to reset the variable in the current context to the value it had before the set() operation that created the token (or to remove the variable if it was not set):

# Assume: var.get(None) is None

# Set 'var' to 1:
token = var.set(1)
try:
    # var.get() == 1
finally:
    var.reset(token)

# After reset: var.get(None) is None,
# i.e. 'var' was removed from the current context.

The ContextVar.reset() method raises:

• a ValueError if it is called with a token object created by another variable;
• a ValueError if the current Context object does not match the one where the token object was created;
• a RuntimeError if the token object has already been used once to reset the variable.

contextvars.Token

contextvars.Token is an opaque object that should be used to restore the ContextVar to its previous value, or to remove it from the context if the variable was not set before. It can be created only by calling ContextVar.set().

For debug and introspection purposes it has:

• a read-only attribute Token.var pointing to the variable that created the token;
• a read-only attribute Token.old_value set to the value the variable had before the set() call, or to Token.MISSING if the variable wasn’t set before.

contextvars.Context

Context object is a mapping of context variables to values.

Context() creates an empty context. To get a copy of the current Context for the current OS thread, use the contextvars.copy_context() method:

ctx = contextvars.copy_context()

To run Python code in some Context, use Context.run() method:

ctx.run(function)

Any changes to any context variables that function causes will be contained in the ctx context:

var = ContextVar('var')
var.set('spam')

def main():
    # 'var' was set to 'spam' before
    # calling 'copy_context()' and 'ctx.run(main)', so:
    # var.get() == ctx[var] == 'spam'

    var.set('ham')

    # Now, after setting 'var' to 'ham':
    # var.get() == ctx[var] == 'ham'

ctx = copy_context()

# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)

# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
# ctx[var] == 'ham'

# However, outside of 'ctx', 'var' is still set to 'spam':
# var.get() == 'spam'

Context.run() raises a RuntimeError when called on the same context object from more than one OS thread, or when called recursively.

Context.copy() returns a shallow copy of the context object.

Context objects implement the collections.abc.Mapping ABC. This can be used to introspect contexts:

ctx = contextvars.copy_context()

# Print all context variables and their values in 'ctx':
print(ctx.items())

# Print the value of 'some_variable' in context 'ctx':
print(ctx[some_variable])

Note that all Mapping methods, including Context.__getitem__ and Context.get, ignore default values for context variables (i.e. ContextVar.default). This means that for a variable var that was created with a default value and was not set in the context:

• context[var] raises a KeyError,
• var in context returns False,
• the variable isn’t included in context.items(), etc.

asyncio

asyncio uses Loop.call_soon(), Loop.call_later(), and Loop.call_at() to schedule the asynchronous execution of a function. asyncio.Task uses call_soon() to run the wrapped coroutine.

We modify Loop.call_{at,later,soon} and Future.add_done_callback() to accept the new optional context keyword-only argument, which defaults to the current context:

def call_soon(self, callback, *args, context=None):
    if context is None:
        context = contextvars.copy_context()

    # ... some time later
    context.run(callback, *args)

Tasks in asyncio need to maintain their own context that they inherit from the point they were created at. asyncio.Task is modified as follows:

class Task:
    def __init__(self, coro):
        ...
        # Get the current context snapshot.
        self._context = contextvars.copy_context()
        self._loop.call_soon(self._step, context=self._context)

    def _step(self, exc=None):
        ...
        # Every advance of the wrapped coroutine is done in
        # the task's context.
        self._loop.call_soon(self._step, context=self._context)
        ...

Python API

1. A new contextvars module with ContextVar, Context, and Token classes, and a copy_context() function.
2. asyncio.Loop.call_at(), asyncio.Loop.call_later(), asyncio.Loop.call_soon(), and asyncio.Future.add_done_callback() run callback functions in the context they were called in. A new context keyword-only parameter can be used to specify a custom context.
3. asyncio.Task is modified internally to maintain its own context.

C API

1. PyObject * PyContextVar_New(char *name, PyObject *default): create a ContextVar object. The default argument can be NULL, which means that the variable has no default value.
2. int PyContextVar_Get(PyObject *, PyObject *default_value, PyObject **value): return -1 if an error occurs during the lookup, 0 otherwise. If a value for the context variable is found, it will be set to the value pointer. Otherwise, value will be set to default_value when it is not NULL. If default_value is NULL, value will be set to the default value of the variable, which can be NULL too. value is always a new reference.
3. PyObject * PyContextVar_Set(PyObject *, PyObject *): set the value of the variable in the current context.
4. PyContextVar_Reset(PyObject *, PyObject *): reset the value of the context variable.
5. PyObject * PyContext_New(): create a new empty context.
6. PyObject * PyContext_Copy(PyObject *): return a shallow copy of the passed context object.
7. PyObject * PyContext_CopyCurrent(): get a copy of the current context.
8. int PyContext_Enter(PyObject *) and int PyContext_Exit(PyObject *) allow to set and restore the context for the current OS thread. It is required to always restore the previous context:

   PyObject *old_ctx = PyContext_Copy();
   if (old_ctx == NULL) goto error;
   
   if (PyContext_Enter(new_ctx)) goto error;
   
   // run some code
   
   if (PyContext_Exit(old_ctx)) goto error;
   

Replicating threading.local() interface

Please refer to PEP 550 where this topic is covered in detail: 2.

Replacing Token with ContextVar.unset()

The Token API allows to get around having a ContextVar.unset() method, which is incompatible with chained contexts design of PEP 550. Future compatibility with PEP 550 is desired in case there is demand to support context variables in generators and asynchronous generators.

The Token API also offers better usability: the user does not have to special-case absence of a value. Compare:

token = cv.set(new_value)
try:
    # cv.get() is new_value
finally:
    cv.reset(token)

with:

_deleted = object()
old = cv.get(default=_deleted)
try:
    cv.set(blah)
    # code
finally:
    if old is _deleted:
        cv.unset()
    else:
        cv.set(old)

Having Token.reset() instead of ContextVar.reset()

Nathaniel Smith suggested to implement the ContextVar.reset() method directly on the Token class, so instead of:

token = var.set(value)
# ...
var.reset(token)

we would write:

token = var.set(value)
# ...
token.reset()

Having Token.reset() would make it impossible for a user to attempt to reset a variable with a token object created by another variable.

This proposal was rejected for the reason of ContextVar.reset() being clearer to the human reader of the code which variable is being reset.

Making Context objects picklable

Proposed by Antoine Pitrou, this could enable transparent cross-process use of Context objects, so the Offloading execution to other threads example would work with a ProcessPoolExecutor too.

Enabling this is problematic because of the following reasons:

1. ContextVar objects do not have __module__ and __qualname__ attributes, making straightforward pickling of Context objects impossible. This is solvable by modifying the API to either auto detect the module where a context variable is defined, or by adding a new keyword-only “module” parameter to ContextVar constructor.
2. Not all context variables refer to picklable objects. Making a ContextVar picklable must be an opt-in.

Given the time frame of the Python 3.7 release schedule it was decided to defer this proposal to Python 3.8.

Making Context a MutableMapping

Making the Context class implement the abc.MutableMapping interface would mean that it is possible to set and unset variables using Context[var] = value and del Context[var] operations.

This proposal was deferred to Python 3.8+ because of the following:

1. If in Python 3.8 it is decided that generators should support context variables (see PEP 550 and PEP 568), then Context would be transformed into a chain-map of context variables mappings (as every generator would have its own mapping). That would make mutation operations like Context.__delitem__ confusing, as they would operate only on the topmost mapping of the chain.
2. Having a single way of mutating the context (ContextVar.set() and ContextVar.reset() methods) makes the API more straightforward.

   For example, it would be non-obvious why the below code fragment does not work as expected:

   var = ContextVar('var')
   
   ctx = copy_context()
   ctx[var] = 'value'
   print(ctx[var])  # Prints 'value'
   
   print(var.get())  # Raises a LookupError
   

   While the following code would work:

   ctx = copy_context()
   
   def func():
       ctx[var] = 'value'
   
       # Contrary to the previous example, this would work
       # because 'func()' is running within 'ctx'.
       print(ctx[var])
       print(var.get())
   
   ctx.run(func)
   

3. If Context was mutable it would mean that context variables could be mutated separately (or concurrently) from the code that runs within the context. That would be similar to obtaining a reference to a running Python frame object and modifying its f_locals from another OS thread. Having one single way to assign values to context variables makes contexts conceptually simpler and more predictable, while keeping the door open for future performance optimizations.

Having initial values for ContextVars

Nathaniel Smith proposed to have a required initial_value keyword-only argument for the ContextVar constructor.

The main argument against this proposal is that for some types there is simply no sensible “initial value” except None. E.g. consider a web framework that stores the current HTTP request object in a context variable. With the current semantics it is possible to create a context variable without a default value:

# Framework:
current_request: ContextVar[Request] = \
    ContextVar('current_request')


# Later, while handling an HTTP request:
request: Request = current_request.get()

# Work with the 'request' object:
return request.method

Note that in the above example there is no need to check if request is None. It is simply expected that the framework always sets the current_request variable, or it is a bug (in which case current_request.get() would raise a LookupError).

If, however, we had a required initial value, we would have to guard against None values explicitly:

# Framework:
current_request: ContextVar[Optional[Request]] = \
    ContextVar('current_request', initial_value=None)


# Later, while handling an HTTP request:
request: Optional[Request] = current_request.get()

# Check if the current request object was set:
if request is None:
    raise RuntimeError

# Work with the 'request' object:
return request.method

Moreover, we can loosely compare context variables to regular Python variables and to threading.local() objects. Both of them raise errors on failed lookups (NameError and AttributeError respectively).

Converting code that uses threading.local()

A typical code fragment that uses threading.local() usually looks like the following:

class PrecisionStorage(threading.local):
    # Subclass threading.local to specify a default value.
    value = 0.0

precision = PrecisionStorage()

# To set a new precision:
precision.value = 0.5

# To read the current precision:
print(precision.value)

Such code can be converted to use the contextvars module:

precision = contextvars.ContextVar('precision', default=0.0)

# To set a new precision:
precision.set(0.5)

# To read the current precision:
print(precision.get())

Offloading execution to other threads

It is possible to run code in a separate OS thread using a copy of the current thread context:

executor = ThreadPoolExecutor()
current_context = contextvars.copy_context()

executor.submit(current_context.run, some_function)