CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 568 – Generator-sensitivity for Context Variables | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0568/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 568 – Generator-sensitivity for Context Variables | peps.python.org'> <meta property="og:description" content="Context variables provide a generic mechanism for tracking dynamic, context-local state, similar to thread-local storage but generalized to cope work with other kinds of thread-like contexts, such as asyncio Tasks. PEP 550 proposed a mechanism for conte..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0568/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Context variables provide a generic mechanism for tracking dynamic, context-local state, similar to thread-local storage but generalized to cope work with other kinds of thread-like contexts, such as asyncio Tasks. PEP 550 proposed a mechanism for conte..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 568</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 568 – Generator-sensitivity for Context Variables</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Nathaniel J. Smith <njs at pobox.com></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Inactive draft that may be taken up again at a later time">Deferred</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">04-Jan-2018</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.8</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even"></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#high-level-summary">High-level summary</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#review-of-pep-567">Review of PEP 567</a></li> <li><a class="reference internal" href="#changes-from-pep-567-to-this-pep">Changes from PEP 567 to this PEP</a></li> </ul> </li> <li><a class="reference internal" href="#comparison-to-pep-550">Comparison to PEP 550</a></li> <li><a class="reference internal" href="#implementation-notes">Implementation notes</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> Context variables provide a generic mechanism for tracking dynamic, context-local state, similar to thread-local storage but generalized to cope work with other kinds of thread-like contexts, such as asyncio Tasks. <a class="pep reference internal" href="../pep-0550/" title="PEP 550 – Execution Context">PEP 550</a> proposed a mechanism for context-local state that was also sensitive to generator context, but this was pretty complicated, so the BDFL requested it be simplified. The result was <a class="pep reference internal" href="../pep-0567/" title="PEP 567 – Context Variables">PEP 567</a>, which is targeted for inclusion in 3.7. This PEP then extends <a class="pep reference internal" href="../pep-0567/" title="PEP 567 – Context Variables">PEP 567</a>’s machinery to add generator context sensitivity. This PEP is starting out in the “deferred” status, because there isn’t enough time to give it proper consideration before the 3.7 feature freeze. The only goal right now is to understand what would be required to add generator context sensitivity in 3.8, so that we can avoid shipping something in 3.7 that would rule it out by accident. (Ruling it out on purpose can wait until 3.8 ;-).) </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> [Currently the point of this PEP is just to understand how this would work, with discussion of whether it’s a good idea deferred until after the 3.7 feature freeze. So rationale is TBD.] </section> <section id="high-level-summary"> <h2><a class="toc-backref" href="#high-level-summary" role="doc-backlink">High-level summary</a></h2> Instead of holding a single <code class="docutils literal notranslate">Context</code>, the threadstate now holds a <code class="docutils literal notranslate">ChainMap</code> of <code class="docutils literal notranslate">Context</code>s. <code class="docutils literal notranslate">ContextVar.get</code> and <code class="docutils literal notranslate">ContextVar.set</code> are backed by the <code class="docutils literal notranslate">ChainMap</code>. Generators and async generators each have an associated <code class="docutils literal notranslate">Context</code> that they push onto the <code class="docutils literal notranslate">ChainMap</code> while they’re running to isolate their context-local changes from their callers, though this can be overridden in cases like <code class="docutils literal notranslate">@contextlib.contextmanager</code> where “leaking” context changes from the generator into its caller is desirable. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="review-of-pep-567"> <h3><a class="toc-backref" href="#review-of-pep-567" role="doc-backlink">Review of PEP 567</a></h3> Let’s start by reviewing how <a class="pep reference internal" href="../pep-0567/" title="PEP 567 – Context Variables">PEP 567</a> works, and then in the next section we’ll describe the differences. In <a class="pep reference internal" href="../pep-0567/" title="PEP 567 – Context Variables">PEP 567</a>, a <code class="docutils literal notranslate">Context</code> is a <code class="docutils literal notranslate">Mapping</code> from <code class="docutils literal notranslate">ContextVar</code> objects to arbitrary values. In our pseudo-code here we’ll pretend that it uses a <code class="docutils literal notranslate">dict</code> for backing storage. (The real implementation uses a HAMT, which is semantically equivalent to a <code class="docutils literal notranslate">dict</code> but with different performance trade-offs.): <div class="highlight-default notranslate"><div class="highlight"><pre>class Context(collections.abc.Mapping): def __init__(self): self._data = {} self._in_use = False def __getitem__(self, key): return self._data[key] def __iter__(self): return iter(self._data) def __len__(self): return len(self._data) </pre></div> </div> At any given moment, the threadstate holds a current <code class="docutils literal notranslate">Context</code> (initialized to an empty <code class="docutils literal notranslate">Context</code> when the threadstate is created); we can use <code class="docutils literal notranslate">Context.run</code> to temporarily switch the current <code class="docutils literal notranslate">Context</code>: <div class="highlight-default notranslate"><div class="highlight"><pre># Context.run def run(self, fn, *args, **kwargs): if self._in_use: raise RuntimeError("Context already in use") tstate = get_thread_state() old_context = tstate.current_context tstate.current_context = self self._in_use = True try: return fn(*args, **kwargs) finally: state.current_context = old_context self._in_use = False </pre></div> </div> We can fetch a shallow copy of the current <code class="docutils literal notranslate">Context</code> by calling <code class="docutils literal notranslate">copy_context</code>; this is commonly used when spawning a new task, so that the child task can inherit context from its parent: <div class="highlight-default notranslate"><div class="highlight"><pre>def copy_context(): tstate = get_thread_state() new_context = Context() new_context._data = dict(tstate.current_context) return new_context </pre></div> </div> In practice, what end users generally work with is <code class="docutils literal notranslate">ContextVar</code> objects, which also provide the only way to mutate a <code class="docutils literal notranslate">Context</code>. They work with a utility class <code class="docutils literal notranslate">Token</code>, which can be used to restore a <code class="docutils literal notranslate">ContextVar</code> to its previous value: <div class="highlight-default notranslate"><div class="highlight"><pre>class Token: MISSING = sentinel_value() # Note: constructor is private def __init__(self, context, var, old_value): self._context = context self.var = var self.old_value = old_value # XX: PEP 567 currently makes this a method on ContextVar, but # I'm going to propose it switch to this API because it's simpler. def reset(self): # XX: should we allow token reuse? # XX: should we allow tokens to be used if the saved # context is no longer active? if self.old_value is self.MISSING: del self._context._data[self.context_var] else: self._context._data[self.context_var] = self.old_value # XX: the handling of defaults here uses the simplified proposal from # https://mail.python.org/pipermail/python-dev/2018-January/151596.html # This can be updated to whatever we settle on, it was just less # typing this way :-) class ContextVar: def __init__(self, name, *, default=None): self.name = name self.default = default def get(self): context = get_thread_state().current_context return context.get(self, self.default) def set(self, new_value): context = get_thread_state().current_context token = Token(context, self, context.get(self, Token.MISSING)) context._data[self] = new_value return token </pre></div> </div> </section> <section id="changes-from-pep-567-to-this-pep"> <h3><a class="toc-backref" href="#changes-from-pep-567-to-this-pep" role="doc-backlink">Changes from PEP 567 to this PEP</a></h3> In general, <code class="docutils literal notranslate">Context</code> remains the same. However, now instead of holding a single <code class="docutils literal notranslate">Context</code> object, the threadstate stores a stack of them. This stack acts just like a <code class="docutils literal notranslate">collections.ChainMap</code>, so we’ll use that in our pseudocode. <code class="docutils literal notranslate">Context.run</code> then becomes: <div class="highlight-default notranslate"><div class="highlight"><pre># Context.run def run(self, fn, *args, **kwargs): if self._in_use: raise RuntimeError("Context already in use") tstate = get_thread_state() old_context_stack = tstate.current_context_stack tstate.current_context_stack = ChainMap([self]) # changed self._in_use = True try: return fn(*args, **kwargs) finally: state.current_context_stack = old_context_stack self._in_use = False </pre></div> </div> Aside from some updated variables names (e.g., <code class="docutils literal notranslate">tstate.current_context</code> → <code class="docutils literal notranslate">tstate.current_context_stack</code>), the only change here is on the marked line, which now wraps the context in a <code class="docutils literal notranslate">ChainMap</code> before stashing it in the threadstate. We also add a <code class="docutils literal notranslate">Context.push</code> method, which is almost exactly like <code class="docutils literal notranslate">Context.run</code>, except that it temporarily pushes the <code class="docutils literal notranslate">Context</code> onto the existing stack, instead of temporarily replacing the whole stack: <div class="highlight-default notranslate"><div class="highlight"><pre># Context.push def push(self, fn, *args, **kwargs): if self._in_use: raise RuntimeError("Context already in use") tstate = get_thread_state() tstate.current_context_stack.maps.insert(0, self) # different from run self._in_use = True try: return fn(*args, **kwargs) finally: tstate.current_context_stack.maps.pop(0) # different from run self._in_use = False </pre></div> </div> In most cases, we don’t expect <code class="docutils literal notranslate">push</code> to be used directly; instead, it will be used implicitly by generators. Specifically, every generator object and async generator object gains a new attribute <code class="docutils literal notranslate">.context</code>. When an (async) generator object is created, this attribute is initialized to an empty <code class="docutils literal notranslate">Context</code> (<code class="docutils literal notranslate">self.context = Context()</code>). This is a mutable attribute; it can be changed by user code. But trying to set it to anything that isn’t a <code class="docutils literal notranslate">Context</code> object or <code class="docutils literal notranslate">None</code> will raise an error. Whenever we enter an generator via <code class="docutils literal notranslate">__next__</code>, <code class="docutils literal notranslate">send</code>, <code class="docutils literal notranslate">throw</code>, or <code class="docutils literal notranslate">close</code>, or enter an async generator by calling one of those methods on its <code class="docutils literal notranslate">__anext__</code>, <code class="docutils literal notranslate">asend</code>, <code class="docutils literal notranslate">athrow</code>, or <code class="docutils literal notranslate">aclose</code> coroutines, then its <code class="docutils literal notranslate">.context</code> attribute is checked, and if non-<code class="docutils literal notranslate">None</code>, is automatically pushed: <div class="highlight-default notranslate"><div class="highlight"><pre># GeneratorType.__next__ def __next__(self): if self.context is not None: return self.context.push(self.__real_next__) else: return self.__real_next__() </pre></div> </div> While we don’t expect people to use <code class="docutils literal notranslate">Context.push</code> often, making it a public API preserves the principle that a generator can always be rewritten as an explicit iterator class with equivalent semantics. Also, we modify <code class="docutils literal notranslate">contextlib.(async)contextmanager</code> to always set its (async) generator objects’ <code class="docutils literal notranslate">.context</code> attribute to <code class="docutils literal notranslate">None</code>: <div class="highlight-default notranslate"><div class="highlight"><pre># contextlib._GeneratorContextManagerBase.__init__ def __init__(self, func, args, kwds): self.gen = func(*args, **kwds) self.gen.context = None # added ... </pre></div> </div> This makes sure that code like this continues to work as expected: <div class="highlight-default notranslate"><div class="highlight"><pre>@contextmanager def decimal_precision(prec): with decimal.localcontext() as ctx: ctx.prec = prec yield with decimal_precision(2): ... </pre></div> </div> The general idea here is that by default, every generator object gets its own local context, but if users want to explicitly get some other behavior then they can do that. Otherwise, things mostly work as before, except that we go through and swap everything to use the threadstate <code class="docutils literal notranslate">ChainMap</code> instead of the threadstate <code class="docutils literal notranslate">Context</code>. In full detail: The <code class="docutils literal notranslate">copy_context</code> function now returns a flattened copy of the “effective” context. (As an optimization, the implementation might choose to do this flattening lazily, but if so this will be made invisible to the user.) Compared to our previous implementation above, the only change here is that <code class="docutils literal notranslate">tstate.current_context</code> has been replaced with <code class="docutils literal notranslate">tstate.current_context_stack</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>def copy_context() -> Context: tstate = get_thread_state() new_context = Context() new_context._data = dict(tstate.current_context_stack) return new_context </pre></div> </div> <code class="docutils literal notranslate">Token</code> is unchanged, and the changes to <code class="docutils literal notranslate">ContextVar.get</code> are trivial: <div class="highlight-default notranslate"><div class="highlight"><pre># ContextVar.get def get(self): context_stack = get_thread_state().current_context_stack return context_stack.get(self, self.default) </pre></div> </div> <code class="docutils literal notranslate">ContextVar.set</code> is a little more interesting: instead of going through the <code class="docutils literal notranslate">ChainMap</code> machinery like everything else, it always mutates the top <code class="docutils literal notranslate">Context</code> in the stack, and – crucially! – sets up the returned <code class="docutils literal notranslate">Token</code> to restore its state later. This allows us to avoid accidentally “promoting” values between different levels in the stack, as would happen if we did <code class="docutils literal notranslate">old = var.get(); ...; var.set(old)</code>: <div class="highlight-default notranslate"><div class="highlight"><pre># ContextVar.set def set(self, new_value): top_context = get_thread_state().current_context_stack.maps[0] token = Token(top_context, self, top_context.get(self, Token.MISSING)) top_context._data[self] = new_value return token </pre></div> </div> And finally, to allow for introspection of the full context stack, we provide a new function <code class="docutils literal notranslate">contextvars.get_context_stack</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>def get_context_stack() -> List[Context]: return list(get_thread_state().current_context_stack.maps) </pre></div> </div> That’s all. </section> </section> <section id="comparison-to-pep-550"> <h2><a class="toc-backref" href="#comparison-to-pep-550" role="doc-backlink">Comparison to PEP 550</a></h2> The main difference from <a class="pep reference internal" href="../pep-0550/" title="PEP 550 – Execution Context">PEP 550</a> is that it reified what we’re calling “contexts” and “context stacks” as two different concrete types (<code class="docutils literal notranslate">LocalContext</code> and <code class="docutils literal notranslate">ExecutionContext</code> respectively). This led to lots of confusion about what the differences were, and which object should be used in which places. This proposal simplifies things by only reifying the <code class="docutils literal notranslate">Context</code>, which is “just a dict”, and makes the “context stack” an unnamed feature of the interpreter’s runtime state – though it is still possible to introspect it using <code class="docutils literal notranslate">get_context_stack</code>, for debugging and other purposes. </section> <section id="implementation-notes"> <h2><a class="toc-backref" href="#implementation-notes" role="doc-backlink">Implementation notes</a></h2> <code class="docutils literal notranslate">Context</code> will continue to use a HAMT-based mapping structure under the hood instead of <code class="docutils literal notranslate">dict</code>, since we expect that calls to <code class="docutils literal notranslate">copy_context</code> are much more common than <code class="docutils literal notranslate">ContextVar.set</code>. In almost all cases, <code class="docutils literal notranslate">copy_context</code> will find that there’s only one <code class="docutils literal notranslate">Context</code> in the stack (because it’s rare for generators to spawn new tasks), and can simply re-use it directly; in other cases HAMTs are cheap to merge and this can be done lazily. Rather than using an actual <code class="docutils literal notranslate">ChainMap</code> object, we’ll represent the context stack using some appropriate structure – the most appropriate options are probably either a bare <code class="docutils literal notranslate">list</code> with the “top” of the stack being the end of the list so we can use <code class="docutils literal notranslate">push</code>/<code class="docutils literal notranslate">pop</code>, or else an intrusive linked list (<code class="docutils literal notranslate">PyThreadState</code> → <code class="docutils literal notranslate">Context</code> → <code class="docutils literal notranslate">Context</code> → …), with the “top” of the stack at the beginning of the list to allow efficient push/pop. A critical optimization in <a class="pep reference internal" href="../pep-0567/" title="PEP 567 – Context Variables">PEP 567</a> is the caching of values inside <code class="docutils literal notranslate">ContextVar</code>. Switching from a single context to a context stack makes this a little bit more complicated, but not too much. Currently, we invalidate the cache whenever the threadstate’s current <code class="docutils literal notranslate">Context</code> changes (on thread switch, and when entering/exiting <code class="docutils literal notranslate">Context.run</code>). The simplest approach here would be to invalidate the cache whenever stack changes (on thread switch, when entering/exiting <code class="docutils literal notranslate">Context.run</code>, and when entering/leaving <code class="docutils literal notranslate">Context.push</code>). The main effect of this is that iterating a generator will invalidate the cache. It seems unlikely that this will cause serious problems, but if it does, then I think it can be avoided with a cleverer cache key that recognizes that pushing and then popping a <code class="docutils literal notranslate">Context</code> returns the threadstate to its previous state. (Idea: store the cache key for a particular stack configuration in the topmost <code class="docutils literal notranslate">Context</code>.) It seems unavoidable in this design that uncached <code class="docutils literal notranslate">get</code> will be O(n), where n is the size of the context stack. However, n will generally be very small – it’s roughly the number of nested generators, so usually n=1, and it will be extremely rare to see n greater than, say, 5. At worst, n is bounded by the recursion limit. In addition, we can expect that in most cases of deep generator recursion, most of the <code class="docutils literal notranslate">Context</code>s in the stack will be empty, and thus can be skipped extremely quickly during lookup. And for repeated lookups the caching mechanism will kick in. So it’s probably possible to construct some extreme case where this causes performance problems, but ordinary code should be essentially unaffected. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0568.rst">https://github.com/python/peps/blob/main/peps/pep-0568.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0568.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#high-level-summary">High-level summary</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#review-of-pep-567">Review of PEP 567</a></li> <li><a class="reference internal" href="#changes-from-pep-567-to-this-pep">Changes from PEP 567 to this PEP</a></li> </ul> </li> <li><a class="reference internal" href="#comparison-to-pep-550">Comparison to PEP 550</a></li> <li><a class="reference internal" href="#implementation-notes">Implementation notes</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0568.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>