Debian Codegraph @

Doc/library/contextvars.rst

raw
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