| 1 |
:mod:`!contextvars` --- Context Variables |
| 2 |
========================================= |
| 3 |
|
| 4 |
.. module:: contextvars |
| 5 |
:synopsis: Context Variables |
| 6 |
|
| 7 |
.. sectionauthor:: Yury Selivanov <[email protected]> |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
This module provides APIs to manage, store, and access context-local |
| 12 |
state. The :class:`~contextvars.ContextVar` class is used to declare |
| 13 |
and work with *Context Variables*. The :func:`~contextvars.copy_context` |
| 14 |
function and the :class:`~contextvars.Context` class should be used to |
| 15 |
manage the current context in asynchronous frameworks. |
| 16 |
|
| 17 |
Context managers that have state should use Context Variables |
| 18 |
instead of :func:`threading.local` to prevent their state from |
| 19 |
bleeding to other code unexpectedly, when used in concurrent code. |
| 20 |
|
| 21 |
See also :pep:`567` for additional details. |
| 22 |
|
| 23 |
.. versionadded:: 3.7 |
| 24 |
|
| 25 |
|
| 26 |
Context Variables |
| 27 |
----------------- |
| 28 |
|
| 29 |
.. class:: ContextVar(name, [*, default]) |
| 30 |
|
| 31 |
This class is used to declare a new Context Variable, e.g.:: |
| 32 |
|
| 33 |
var: ContextVar[int] = ContextVar('var', default=42) |
| 34 |
|
| 35 |
The required *name* parameter is used for introspection and debug |
| 36 |
purposes. |
| 37 |
|
| 38 |
The optional keyword-only *default* parameter is returned by |
| 39 |
:meth:`ContextVar.get` when no value for the variable is found |
| 40 |
in the current context. |
| 41 |
|
| 42 |
**Important:** Context Variables should be created at the top module |
| 43 |
level and never in closures. :class:`Context` objects hold strong |
| 44 |
references to context variables which prevents context variables |
| 45 |
from being properly garbage collected. |
| 46 |
|
| 47 |
:class:`!ContextVar`\s are :ref:`generic <generics>` over the type of |
| 48 |
their contained value. |
| 49 |
|
| 50 |
.. attribute:: ContextVar.name |
| 51 |
|
| 52 |
The name of the variable. This is a read-only property. |
| 53 |
|
| 54 |
.. versionadded:: 3.7.1 |
| 55 |
|
| 56 |
.. method:: get([default]) |
| 57 |
|
| 58 |
Return a value for the context variable for the current context. |
| 59 |
|
| 60 |
If there is no value for the variable in the current context, |
| 61 |
the method will: |
| 62 |
|
| 63 |
* return the value of the *default* argument of the method, |
| 64 |
if provided; or |
| 65 |
|
| 66 |
* return the default value for the context variable, |
| 67 |
if it was created with one; or |
| 68 |
|
| 69 |
* raise a :exc:`LookupError`. |
| 70 |
|
| 71 |
.. method:: set(value) |
| 72 |
|
| 73 |
Call to set a new value for the context variable in the current |
| 74 |
context. |
| 75 |
|
| 76 |
The required *value* argument is the new value for the context |
| 77 |
variable. |
| 78 |
|
| 79 |
Returns a :class:`~contextvars.Token` object that can be used |
| 80 |
to restore the variable to its previous value via the |
| 81 |
:meth:`ContextVar.reset` method. |
| 82 |
|
| 83 |
For convenience, the token object can be used as a context manager |
| 84 |
to avoid calling :meth:`ContextVar.reset` manually:: |
| 85 |
|
| 86 |
var = ContextVar('var', default='default value') |
| 87 |
|
| 88 |
with var.set('new value'): |
| 89 |
assert var.get() == 'new value' |
| 90 |
|
| 91 |
assert var.get() == 'default value' |
| 92 |
|
| 93 |
It is a shorthand for:: |
| 94 |
|
| 95 |
var = ContextVar('var', default='default value') |
| 96 |
|
| 97 |
token = var.set('new value') |
| 98 |
try: |
| 99 |
assert var.get() == 'new value' |
| 100 |
finally: |
| 101 |
var.reset(token) |
| 102 |
|
| 103 |
assert var.get() == 'default value' |
| 104 |
|
| 105 |
.. versionadded:: 3.14 |
| 106 |
|
| 107 |
Added support for using tokens as context managers. |
| 108 |
|
| 109 |
.. method:: reset(token) |
| 110 |
|
| 111 |
Reset the context variable to the value it had before the |
| 112 |
:meth:`ContextVar.set` that created the *token* was used. |
| 113 |
|
| 114 |
For example:: |
| 115 |
|
| 116 |
var = ContextVar('var') |
| 117 |
|
| 118 |
token = var.set('new value') |
| 119 |
# code that uses 'var'; var.get() returns 'new value'. |
| 120 |
var.reset(token) |
| 121 |
|
| 122 |
# After the reset call the var has no value again, so |
| 123 |
# var.get() would raise a LookupError. |
| 124 |
|
| 125 |
The same *token* cannot be used twice. |
| 126 |
|
| 127 |
|
| 128 |
.. class:: Token |
| 129 |
|
| 130 |
*Token* objects are returned by the :meth:`ContextVar.set` method. |
| 131 |
They can be passed to the :meth:`ContextVar.reset` method to revert |
| 132 |
the value of the variable to what it was before the corresponding |
| 133 |
*set*. A single token cannot reset a context variable more than once. |
| 134 |
|
| 135 |
Tokens support the :ref:`context manager protocol <context-managers>` |
| 136 |
to automatically reset context variables. See :meth:`ContextVar.set`. |
| 137 |
|
| 138 |
Tokens are :ref:`generic <generics>` over the same type as the |
| 139 |
:class:`ContextVar` which created them. |
| 140 |
|
| 141 |
.. versionadded:: 3.14 |
| 142 |
|
| 143 |
Added support for usage as a context manager. |
| 144 |
|
| 145 |
.. attribute:: Token.var |
| 146 |
|
| 147 |
A read-only property. Points to the :class:`ContextVar` object |
| 148 |
that created the token. |
| 149 |
|
| 150 |
.. attribute:: Token.old_value |
| 151 |
|
| 152 |
A read-only property. Set to the value the variable had before |
| 153 |
the :meth:`ContextVar.set` method call that created the token. |
| 154 |
It points to :attr:`Token.MISSING` if the variable was not set |
| 155 |
before the call. |
| 156 |
|
| 157 |
.. attribute:: Token.MISSING |
| 158 |
|
| 159 |
A marker object used by :attr:`Token.old_value`. |
| 160 |
|
| 161 |
|
| 162 |
Manual Context Management |
| 163 |
------------------------- |
| 164 |
|
| 165 |
.. function:: copy_context() |
| 166 |
|
| 167 |
Returns a copy of the current :class:`~contextvars.Context` object. |
| 168 |
|
| 169 |
The following snippet gets a copy of the current context and prints |
| 170 |
all variables and their values that are set in it:: |
| 171 |
|
| 172 |
ctx: Context = copy_context() |
| 173 |
print(list(ctx.items())) |
| 174 |
|
| 175 |
The function has an *O*\ (1) complexity, i.e. works equally fast for |
| 176 |
contexts with a few context variables and for contexts that have |
| 177 |
a lot of them. |
| 178 |
|
| 179 |
|
| 180 |
.. class:: Context() |
| 181 |
|
| 182 |
A mapping of :class:`ContextVars <ContextVar>` to their values. |
| 183 |
|
| 184 |
``Context()`` creates an empty context with no values in it. |
| 185 |
To get a copy of the current context use the |
| 186 |
:func:`~contextvars.copy_context` function. |
| 187 |
|
| 188 |
Each thread has its own effective stack of :class:`!Context` objects. The |
| 189 |
:term:`current context` is the :class:`!Context` object at the top of the |
| 190 |
current thread's stack. All :class:`!Context` objects in the stacks are |
| 191 |
considered to be *entered*. |
| 192 |
|
| 193 |
*Entering* a context, which can be done by calling its :meth:`~Context.run` |
| 194 |
method, makes the context the current context by pushing it onto the top of |
| 195 |
the current thread's context stack. |
| 196 |
|
| 197 |
*Exiting* from the current context, which can be done by returning from the |
| 198 |
callback passed to the :meth:`~Context.run` method, restores the current |
| 199 |
context to what it was before the context was entered by popping the context |
| 200 |
off the top of the context stack. |
| 201 |
|
| 202 |
Since each thread has its own context stack, :class:`ContextVar` objects |
| 203 |
behave in a similar fashion to :func:`threading.local` when values are |
| 204 |
assigned in different threads. |
| 205 |
|
| 206 |
Attempting to enter an already entered context, including contexts entered in |
| 207 |
other threads, raises a :exc:`RuntimeError`. |
| 208 |
|
| 209 |
After exiting a context, it can later be re-entered (from any thread). |
| 210 |
|
| 211 |
Any changes to :class:`ContextVar` values via the :meth:`ContextVar.set` |
| 212 |
method are recorded in the current context. The :meth:`ContextVar.get` |
| 213 |
method returns the value associated with the current context. Exiting a |
| 214 |
context effectively reverts any changes made to context variables while the |
| 215 |
context was entered (if needed, the values can be restored by re-entering the |
| 216 |
context). |
| 217 |
|
| 218 |
Context implements the :class:`collections.abc.Mapping` interface. |
| 219 |
|
| 220 |
.. method:: run(callable, *args, **kwargs) |
| 221 |
|
| 222 |
Enters the Context, executes ``callable(*args, **kwargs)``, then exits the |
| 223 |
Context. Returns *callable*'s return value, or propagates an exception if |
| 224 |
one occurred. |
| 225 |
|
| 226 |
Example: |
| 227 |
|
| 228 |
.. testcode:: |
| 229 |
|
| 230 |
import contextvars |
| 231 |
|
| 232 |
var = contextvars.ContextVar('var') |
| 233 |
var.set('spam') |
| 234 |
print(var.get()) # 'spam' |
| 235 |
|
| 236 |
ctx = contextvars.copy_context() |
| 237 |
|
| 238 |
def main(): |
| 239 |
# 'var' was set to 'spam' before |
| 240 |
# calling 'copy_context()' and 'ctx.run(main)', so: |
| 241 |
print(var.get()) # 'spam' |
| 242 |
print(ctx[var]) # 'spam' |
| 243 |
|
| 244 |
var.set('ham') |
| 245 |
|
| 246 |
# Now, after setting 'var' to 'ham': |
| 247 |
print(var.get()) # 'ham' |
| 248 |
print(ctx[var]) # 'ham' |
| 249 |
|
| 250 |
# Any changes that the 'main' function makes to 'var' |
| 251 |
# will be contained in 'ctx'. |
| 252 |
ctx.run(main) |
| 253 |
|
| 254 |
# The 'main()' function was run in the 'ctx' context, |
| 255 |
# so changes to 'var' are contained in it: |
| 256 |
print(ctx[var]) # 'ham' |
| 257 |
|
| 258 |
# However, outside of 'ctx', 'var' is still set to 'spam': |
| 259 |
print(var.get()) # 'spam' |
| 260 |
|
| 261 |
.. testoutput:: |
| 262 |
:hide: |
| 263 |
|
| 264 |
spam |
| 265 |
spam |
| 266 |
spam |
| 267 |
ham |
| 268 |
ham |
| 269 |
ham |
| 270 |
spam |
| 271 |
|
| 272 |
.. method:: copy() |
| 273 |
|
| 274 |
Return a shallow copy of the context object. |
| 275 |
|
| 276 |
.. describe:: var in context |
| 277 |
|
| 278 |
Return ``True`` if the *context* has a value for *var* set; |
| 279 |
return ``False`` otherwise. |
| 280 |
|
| 281 |
.. describe:: context[var] |
| 282 |
|
| 283 |
Return the value of the *var* :class:`ContextVar` variable. |
| 284 |
If the variable is not set in the context object, a |
| 285 |
:exc:`KeyError` is raised. |
| 286 |
|
| 287 |
.. method:: get(var, [default]) |
| 288 |
|
| 289 |
Return the value for *var* if *var* has the value in the context |
| 290 |
object. Return *default* otherwise. If *default* is not given, |
| 291 |
return ``None``. |
| 292 |
|
| 293 |
.. describe:: iter(context) |
| 294 |
|
| 295 |
Return an iterator over the variables stored in the context |
| 296 |
object. |
| 297 |
|
| 298 |
.. describe:: len(proxy) |
| 299 |
|
| 300 |
Return the number of variables set in the context object. |
| 301 |
|
| 302 |
.. method:: keys() |
| 303 |
|
| 304 |
Return a list of all variables in the context object. |
| 305 |
|
| 306 |
.. method:: values() |
| 307 |
|
| 308 |
Return a list of all variables' values in the context object. |
| 309 |
|
| 310 |
|
| 311 |
.. method:: items() |
| 312 |
|
| 313 |
Return a list of 2-tuples containing all variables and their |
| 314 |
values in the context object. |
| 315 |
|
| 316 |
|
| 317 |
asyncio support |
| 318 |
--------------- |
| 319 |
|
| 320 |
Context variables are natively supported in :mod:`asyncio` and are |
| 321 |
ready to be used without any extra configuration. For example, here |
| 322 |
is a simple echo server, that uses a context variable to make the |
| 323 |
address of a remote client available in the Task that handles that |
| 324 |
client:: |
| 325 |
|
| 326 |
import asyncio |
| 327 |
import contextvars |
| 328 |
|
| 329 |
client_addr_var = contextvars.ContextVar('client_addr') |
| 330 |
|
| 331 |
def render_goodbye(): |
| 332 |
# The address of the currently handled client can be accessed |
| 333 |
# without passing it explicitly to this function. |
| 334 |
|
| 335 |
client_addr = client_addr_var.get() |
| 336 |
return f'Good bye, client @ {client_addr}\r\n'.encode() |
| 337 |
|
| 338 |
async def handle_request(reader, writer): |
| 339 |
addr = writer.transport.get_extra_info('socket').getpeername() |
| 340 |
client_addr_var.set(addr) |
| 341 |
|
| 342 |
# In any code that we call is now possible to get |
| 343 |
# client's address by calling 'client_addr_var.get()'. |
| 344 |
|
| 345 |
while True: |
| 346 |
line = await reader.readline() |
| 347 |
print(line) |
| 348 |
if not line.strip(): |
| 349 |
break |
| 350 |
|
| 351 |
writer.write(b'HTTP/1.1 200 OK\r\n') # status line |
| 352 |
writer.write(b'\r\n') # headers |
| 353 |
writer.write(render_goodbye()) # body |
| 354 |
writer.close() |
| 355 |
|
| 356 |
async def main(): |
| 357 |
srv = await asyncio.start_server( |
| 358 |
handle_request, '127.0.0.1', 8081) |
| 359 |
|
| 360 |
async with srv: |
| 361 |
await srv.serve_forever() |
| 362 |
|
| 363 |
asyncio.run(main()) |
| 364 |
|
| 365 |
# To test it you can use telnet or curl: |
| 366 |
# telnet 127.0.0.1 8081 |
| 367 |
# curl 127.0.0.1:8081 |