Mr.Combet Webshell 🔥

Edit File Name : contextvars.html

<!DOCTYPE html>

<title>contextvars — Context Variables &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />
 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />
 
 <script src="../_static/documentation_options.js?v=2c828074"></script>
 <script src="../_static/doctools.js?v=888ff710"></script>
 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
 
 <script src="../_static/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 3.12.3 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="_thread — Low-level threading API" href="_thread.html" />
 <link rel="prev" title="queue — A synchronized queue class" href="queue.html" />
 <link rel="canonical" href="https://docs.python.org/3/library/contextvars.html" />

</head>
<body>
<div class="mobile-nav">
 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
 <nav class="nav-content" role="navigation">
 <label for="menuToggler" class="toggler__label">
 
 </label>
 
 <a href="https://www.python.org/" class="nav-logo">
 <img src="../_static/py.svg" alt="Python logo"/>
 </a>
 
 <form role="search" class="search" action="../search.html" method="get">
 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
 </svg>
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
 <input type="submit" value="Go"/>
 </form>
 
 </nav>
 <div class="menu-wrapper">
 <nav class="menu" role="navigation" aria-label="main navigation">
 <div class="language_switcher_placeholder"></div>
 
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label>
 <div>
 <h3><a href="../contents.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">contextvars</code> — Context Variables</a><ul>
<li><a class="reference internal" href="#context-variables">Context Variables</a></li>
<li><a class="reference internal" href="#manual-context-management">Manual Context Management</a></li>
<li><a class="reference internal" href="#asyncio-support">asyncio support</a></li>
</ul>
</li>
</ul>

</div>
 <div>
 <h4>Previous topic</h4>
 <a href="queue.html"
 title="previous chapter"><code class="xref py py-mod docutils literal notranslate">queue</code> — A synchronized queue class</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="_thread.html"
 title="next chapter"><code class="xref py py-mod docutils literal notranslate">_thread</code> — Low-level threading API</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/main/Doc/library/contextvars.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </nav>
 </div>
</div>

<div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="_thread.html" title="_thread — Low-level threading API"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="queue.html" title="queue — A synchronized queue class"
 accesskey="P">previous</a> |</li>

<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li class="switchers">
 <div class="language_switcher_placeholder"></div>
 <div class="version_switcher_placeholder"></div>
 </li>
 <li>
 
 </li>
 <li id="cpython-language-and-version">
 <a href="../index.html">3.12.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">contextvars</code> — Context Variables</a></li>
 <li class="right">

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="module-contextvars">
<h1><a class="reference internal" href="#module-contextvars" title="contextvars: Context Variables"><code class="xref py py-mod docutils literal notranslate">contextvars</code></a> — Context Variables<a class="headerlink" href="#module-contextvars" title="Link to this heading">¶</a></h1>
<hr class="docutils" />
This module provides APIs to manage, store, and access context-local
state. The <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate">ContextVar</code></a> class is used to declare
and work with Context Variables. The <a class="reference internal" href="#contextvars.copy_context" title="contextvars.copy_context"><code class="xref py py-func docutils literal notranslate">copy_context()</code></a>
function and the <a class="reference internal" href="#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate">Context</code></a> class should be used to
manage the current context in asynchronous frameworks.
Context managers that have state should use Context Variables
instead of <a class="reference internal" href="threading.html#threading.local" title="threading.local"><code class="xref py py-func docutils literal notranslate">threading.local()</code></a> to prevent their state from
bleeding to other code unexpectedly, when used in concurrent code.
See also <a class="pep reference external" href="https://peps.python.org/pep-0567/">PEP 567</a> for additional details.
<div class="versionadded">
New in version 3.7.
</div>
<section id="context-variables">
<h2>Context Variables<a class="headerlink" href="#context-variables" title="Link to this heading">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="contextvars.ContextVar">
class contextvars.ContextVar(name[, *, default])<a class="headerlink" href="#contextvars.ContextVar" title="Link to this definition">¶</a></dt>
<dd>This class is used to declare a new Context Variable, e.g.:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>var: ContextVar[int] = ContextVar(&#39;var&#39;, default=42)
</pre></div>
</div>
The required name parameter is used for introspection and debug
purposes.
The optional keyword-only default parameter is returned by
<a class="reference internal" href="#contextvars.ContextVar.get" title="contextvars.ContextVar.get"><code class="xref py py-meth docutils literal notranslate">ContextVar.get()</code></a> when no value for the variable is found
in the current context.
Important: Context Variables should be created at the top module
level and never in closures. <a class="reference internal" href="#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate">Context</code></a> objects hold strong
references to context variables which prevents context variables
from being properly garbage collected.
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.ContextVar.name">
name<a class="headerlink" href="#contextvars.ContextVar.name" title="Link to this definition">¶</a></dt>
<dd>The name of the variable. This is a read-only property.
<div class="versionadded">
New in version 3.7.1.
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.get">
get([default])<a class="headerlink" href="#contextvars.ContextVar.get" title="Link to this definition">¶</a></dt>
<dd>Return a value for the context variable for the current context.
If there is no value for the variable in the current context,
the method will:
<ul class="simple">
<li>return the value of the default argument of the method,
if provided; or</li>
<li>return the default value for the context variable,
if it was created with one; or</li>
<li>raise a <a class="reference internal" href="exceptions.html#LookupError" title="LookupError"><code class="xref py py-exc docutils literal notranslate">LookupError</code></a>.</li>
</ul>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.set">
set(value)<a class="headerlink" href="#contextvars.ContextVar.set" title="Link to this definition">¶</a></dt>
<dd>Call to set a new value for the context variable in the current
context.
The required value argument is the new value for the context
variable.
Returns a <a class="reference internal" href="#contextvars.Token" title="contextvars.Token"><code class="xref py py-class docutils literal notranslate">Token</code></a> object that can be used
to restore the variable to its previous value via the
<a class="reference internal" href="#contextvars.ContextVar.reset" title="contextvars.ContextVar.reset"><code class="xref py py-meth docutils literal notranslate">ContextVar.reset()</code></a> method.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.reset">
reset(token)<a class="headerlink" href="#contextvars.ContextVar.reset" title="Link to this definition">¶</a></dt>
<dd>Reset the context variable to the value it had before the
<a class="reference internal" href="#contextvars.ContextVar.set" title="contextvars.ContextVar.set"><code class="xref py py-meth docutils literal notranslate">ContextVar.set()</code></a> that created the token was used.
For example:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>var = ContextVar(&#39;var&#39;)

token = var.set(&#39;new value&#39;)
# code that uses &#39;var&#39;; var.get() returns &#39;new value&#39;.
var.reset(token)

# After the reset call the var has no value again, so
# var.get() would raise a LookupError.
</pre></div>
</div>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="contextvars.Token">
class contextvars.Token<a class="headerlink" href="#contextvars.Token" title="Link to this definition">¶</a></dt>
<dd>Token objects are returned by the <a class="reference internal" href="#contextvars.ContextVar.set" title="contextvars.ContextVar.set"><code class="xref py py-meth docutils literal notranslate">ContextVar.set()</code></a> method.
They can be passed to the <a class="reference internal" href="#contextvars.ContextVar.reset" title="contextvars.ContextVar.reset"><code class="xref py py-meth docutils literal notranslate">ContextVar.reset()</code></a> method to revert
the value of the variable to what it was before the corresponding
set.
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.var">
var<a class="headerlink" href="#contextvars.Token.var" title="Link to this definition">¶</a></dt>
<dd>A read-only property. Points to the <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate">ContextVar</code></a> object
that created the token.
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.old_value">
old_value<a class="headerlink" href="#contextvars.Token.old_value" title="Link to this definition">¶</a></dt>
<dd>A read-only property. Set to the value the variable had before
the <a class="reference internal" href="#contextvars.ContextVar.set" title="contextvars.ContextVar.set"><code class="xref py py-meth docutils literal notranslate">ContextVar.set()</code></a> method call that created the token.
It points to <a class="reference internal" href="#contextvars.Token.MISSING" title="contextvars.Token.MISSING"><code class="xref py py-attr docutils literal notranslate">Token.MISSING</code></a> if the variable was not set
before the call.
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.MISSING">
MISSING<a class="headerlink" href="#contextvars.Token.MISSING" title="Link to this definition">¶</a></dt>
<dd>A marker object used by <a class="reference internal" href="#contextvars.Token.old_value" title="contextvars.Token.old_value"><code class="xref py py-attr docutils literal notranslate">Token.old_value</code></a>.
</dd></dl>

</dd></dl>

</section>
<section id="manual-context-management">
<h2>Manual Context Management<a class="headerlink" href="#manual-context-management" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="contextvars.copy_context">
contextvars.copy_context()<a class="headerlink" href="#contextvars.copy_context" title="Link to this definition">¶</a></dt>
<dd>Returns a copy of the current <a class="reference internal" href="#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate">Context</code></a> object.
The following snippet gets a copy of the current context and prints
all variables and their values that are set in it:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>ctx: Context = copy_context()
print(list(ctx.items()))
</pre></div>
</div>
The function has an O(1) complexity, i.e. works equally fast for
contexts with a few context variables and for contexts that have
a lot of them.
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="contextvars.Context">
class contextvars.Context<a class="headerlink" href="#contextvars.Context" title="Link to this definition">¶</a></dt>
<dd>A mapping of <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate">ContextVars</code></a> to their values.
<code class="docutils literal notranslate">Context()</code> creates an empty context with no values in it.
To get a copy of the current context use the
<a class="reference internal" href="#contextvars.copy_context" title="contextvars.copy_context"><code class="xref py py-func docutils literal notranslate">copy_context()</code></a> function.
Every thread will have a different top-level <a class="reference internal" href="#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate">Context</code></a>
object. This means that a <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate">ContextVar</code></a> object behaves in a similar
fashion to <a class="reference internal" href="threading.html#threading.local" title="threading.local"><code class="xref py py-func docutils literal notranslate">threading.local()</code></a> when values are assigned in different
threads.
Context implements the <a class="reference internal" href="collections.abc.html#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate">collections.abc.Mapping</code></a> interface.
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.run">
run(callable, *args, **kwargs)<a class="headerlink" href="#contextvars.Context.run" title="Link to this definition">¶</a></dt>
<dd>Execute <code class="docutils literal notranslate">callable(*args, **kwargs)</code> code in the context object
the run method is called on. Return the result of the execution
or propagate an exception if one occurred.
Any changes to any context variables that callable makes will
be contained in the context object:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>var = ContextVar(&#39;var&#39;)
var.set(&#39;spam&#39;)

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

var.set(&#39;ham&#39;)

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

ctx = copy_context()

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

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

# However, outside of &#39;ctx&#39;, &#39;var&#39; is still set to &#39;spam&#39;:
# var.get() == &#39;spam&#39;
</pre></div>
</div>
The method raises a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate">RuntimeError</code></a> when called on the same
context object from more than one OS thread, or when called
recursively.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.copy">
copy()<a class="headerlink" href="#contextvars.Context.copy" title="Link to this definition">¶</a></dt>
<dd>Return a shallow copy of the context object.
</dd></dl>

<dl class="describe">
<dt class="sig sig-object">
var in context</dt>
<dd>Return <code class="docutils literal notranslate">True</code> if the context has a value for var set;
return <code class="docutils literal notranslate">False</code> otherwise.
</dd></dl>

<dl class="describe">
<dt class="sig sig-object">
context[var]</dt>
<dd>Return the value of the var <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate">ContextVar</code></a> variable.
If the variable is not set in the context object, a
<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate">KeyError</code></a> is raised.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.get">
get(var[, default])<a class="headerlink" href="#contextvars.Context.get" title="Link to this definition">¶</a></dt>
<dd>Return the value for var if var has the value in the context
object. Return default otherwise. If default is not given,
return <code class="docutils literal notranslate">None</code>.
</dd></dl>

<dl class="describe">
<dt class="sig sig-object">
iter(context)</dt>
<dd>Return an iterator over the variables stored in the context
object.
</dd></dl>

<dl class="describe">
<dt class="sig sig-object">
len(proxy)</dt>
<dd>Return the number of variables set in the context object.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.keys">
keys()<a class="headerlink" href="#contextvars.Context.keys" title="Link to this definition">¶</a></dt>
<dd>Return a list of all variables in the context object.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.values">
values()<a class="headerlink" href="#contextvars.Context.values" title="Link to this definition">¶</a></dt>
<dd>Return a list of all variables’ values in the context object.
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.items">
items()<a class="headerlink" href="#contextvars.Context.items" title="Link to this definition">¶</a></dt>
<dd>Return a list of 2-tuples containing all variables and their
values in the context object.
</dd></dl>

</dd></dl>

</section>
<section id="asyncio-support">
<h2>asyncio support<a class="headerlink" href="#asyncio-support" title="Link to this heading">¶</a></h2>
Context variables are natively supported in <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate">asyncio</code></a> and are
ready to be used without any extra configuration. For example, here
is a simple echo server, that uses a context variable to make the
address of a remote client available in the Task that handles that
client:
<div class="highlight-python3 notranslate"><div class="highlight"><pre>import asyncio
import contextvars

client_addr_var = contextvars.ContextVar(&#39;client_addr&#39;)

def render_goodbye():
 # The address of the currently handled client can be accessed
 # without passing it explicitly to this function.

client_addr = client_addr_var.get()
 return f&#39;Good bye, client @ {client_addr}\n&#39;.encode()

async def handle_request(reader, writer):
 addr = writer.transport.get_extra_info(&#39;socket&#39;).getpeername()
 client_addr_var.set(addr)

# In any code that we call is now possible to get
 # client&#39;s address by calling &#39;client_addr_var.get()&#39;.

while True:
 line = await reader.readline()
 print(line)
 if not line.strip():
 break
 writer.write(line)

writer.write(render_goodbye())
 writer.close()

async def main():
 srv = await asyncio.start_server(
 handle_request, &#39;127.0.0.1&#39;, 8081)

async with srv:
 await srv.serve_forever()

asyncio.run(main())

# To test it you can use telnet:
# telnet 127.0.0.1 8081
</pre></div>
</div>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h3><a href="../contents.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate">contextvars</code> — Context Variables</a><ul>
<li><a class="reference internal" href="#context-variables">Context Variables</a></li>
<li><a class="reference internal" href="#manual-context-management">Manual Context Management</a></li>
<li><a class="reference internal" href="#asyncio-support">asyncio support</a></li>
</ul>
</li>
</ul>

</div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="_thread.html" title="_thread — Low-level threading API"
 >next</a> |</li>
 <li class="right" >
 <a href="queue.html" title="queue — A synchronized queue class"
 >previous</a> |</li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="concurrency.html" >Concurrent Execution</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate">contextvars</code> — Context Variables</a></li>
 <li class="right">

<div class="inline-search" role="search">
 <form class="inline-search" action="../search.html" method="get">
 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
 <input type="submit" value="Go" />
 </form>
 </div>
 |
 </li>
 <li class="right">
<label class="theme-selector-label">
 Theme
 <select class="theme-selector" oninput="activateTheme(this.value)">
 <option value="auto" selected>Auto</option>
 <option value="light">Light</option>
 <option value="dark">Dark</option>
 </select>
</label> |</li>
 
 </ul>
 </div> 
 <div class="footer">
 &copy; 
 <a href="../copyright.html">
 
 Copyright
 
 </a>
 2001-2024, Python Software Foundation.
 
 This page is licensed under the Python Software Foundation License Version 2.
 
 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
 
 
 See <a href="/license.html">History and License</a> for more information.

The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
 
 
 Last updated on Apr 09, 2024 (13:47 UTC).
 
 <a href="/bugs.html">Found a bug</a>?

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
 </div>

</body>
</html>