python-docs-fa/library/contextvars.html at gh-pages · python/python-docs-fa

734 lines (641 loc) · 50.9 KB
<!DOCTYPE html>
<html lang="fa" data-content_root="../">
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="contextvars --- Context Variables" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/contextvars.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="This module provides APIs to manage, store, and access context-local state. The ContextVar class is used to declare and work with Context Variables. The copy_context() function and the Context clas..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="This module provides APIs to manage, store, and access context-local state. The ContextVar class is used to declare and work with Context Variables. The copy_context() function and the Context clas..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
    <title>contextvars --- Context Variables &#8212; مستندات Python3.14.6</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
    <script src="../_static/documentation_options.js?v=e254dbbb"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/translations.js?v=5df48d09"></script>
    <script src="../_static/sidebar.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="جستجو در مستندات Python3.14.6"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="درباره این مستندات" href="../about.html" />
    <link rel="index" title="فهرست" href="../genindex.html" />
    <link rel="search" title="جستجو" href="../search.html" />
    <link rel="copyright" title="حق چاپ" 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">
    <style>
      @media only screen {
        table.full-width-table {
            width: 100%;
    </style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">
            <script type="text/javascript" src="../_static/copybutton.js"></script>
            <script type="text/javascript" src="../_static/menu.js"></script>
            <script type="text/javascript" src="../_static/search-focus.js"></script>
            <script type="text/javascript" src="../_static/themetoggle.js"></script> 
            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>
            <meta name="readthedocs-addons-api-version" content="1">
<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">
            <span></span>
        </label>
        <span class="nav-items-wrapper">
            <a href="https://www.python.org/" class="nav-logo">
                <img src="../_static/py.svg" alt="Python logo">
            </a>
            <span class="version_switcher_placeholder"></span>
            <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="جستجو سریع" aria-label="جستجو سریع" type="search" name="q">
                <input type="submit" value="برو">
            </form>
        </span>
    <div class="menu-wrapper">
        <nav class="menu" role="navigation" aria-label="main navigation">
            <div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
    <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>
    <h3><a href="../contents.html">فهرست عناوین</a></h3>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></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>
    <h4>موضوع قبلی</h4>
    <p class="topless"><a href="queue.html"
                          title="فصل قبلی"><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code> --- A synchronized queue class</a></p>
    <h4>موضوع  بعدی</h4>
    <p class="topless"><a href="_thread.html"
                          title="فصل بعدی"><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code> --- Low-level threading API</a></p>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "library/contextvars.rst");
            element.href = url.toString();
        });
  </script>
  <div role="note" aria-label="source link">
    <h3>این صفحه</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">گزارش یک اشکال</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">بهبود این صفحه</a></li>
        <a href="https://github.com/python/cpython/blob/main/Doc/library/contextvars.rst?plain=1"
            rel="nofollow">نمایش منبع
        </a>
      </li>
        <a href="https://github.com/python/python-docs-fa/blob/3.14/library/contextvars.po?plain=1"
           rel="nofollow">نمایش منبع ترجمه</a>
      </li>
        </nav>
    <div class="related" role="navigation" aria-label="Related">
      <h3>ناوبری</h3>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="فهرست کلی"
             accesskey="I">فهرست</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"
             >ماژول ها</a> |</li>
        <li class="right" >
          <a href="_thread.html" title="_thread --- Low-level threading API"
             accesskey="N">بعدی</a> |</li>
        <li class="right" >
          <a href="queue.html" title="queue --- A synchronized queue class"
             accesskey="P">قبلی</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.14.6 Documentation</a> &#187;
          <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"><span class="pre">contextvars</span></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="جستجو سریع" aria-label="جستجو سریع" type="search" name="q" id="search-box">
          <input type="submit" value="برو">
        </form>
                </li>
            <li class="right">
<label class="theme-selector-label">
    <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="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
  <section id="module-contextvars">
<span id="contextvars-context-variables"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></code> --- Context Variables<a class="headerlink" href="#module-contextvars" title="Link to this heading">¶</a></h1>
<hr class="docutils" />
<p>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"><span class="pre">ContextVar</span></code></a> class is used to declare
and work with <em>Context Variables</em>.  The <a class="reference internal" href="#contextvars.copy_context" title="contextvars.copy_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy_context()</span></code></a>
function and the <a class="reference internal" href="#contextvars.Context" title="contextvars.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> class should be used to
manage the current context in asynchronous frameworks.</p>
<p>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"><span class="pre">threading.local()</span></code></a> to prevent their state from
bleeding to other code unexpectedly, when used in concurrent code.</p>
<p>See also <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0567/"><strong>PEP 567</strong></a> for additional details.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.</span></p>
<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">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">contextvars.</span></span><span class="sig-name descname"><span class="pre">ContextVar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.ContextVar" title="Link to this definition">¶</a></dt>
<dd><p>This class is used to declare a new Context Variable, e.g.:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">var</span><span class="p">:</span> <span class="n">ContextVar</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">'var'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
</pre></div>
<p>The required <em>name</em> parameter is used for introspection and debug
purposes.</p>
<p>The optional keyword-only <em>default</em> 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"><span class="pre">ContextVar.get()</span></code></a> when no value for the variable is found
in the current context.</p>
<p><strong>Important:</strong> 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"><span class="pre">Context</span></code></a> objects hold strong
references to context variables which prevents context variables
from being properly garbage collected.</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code>s are <a class="reference internal" href="typing.html#generics"><span class="std std-ref">generic</span></a> over the type of
their contained value.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.ContextVar.name">
<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#contextvars.ContextVar.name" title="Link to this definition">¶</a></dt>
<dd><p>The name of the variable.  This is a read-only property.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.1.</span></p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">default</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.ContextVar.get" title="Link to this definition">¶</a></dt>
<dd><p>Return a value for the context variable for the current context.</p>
<p>If there is no value for the variable in the current context,
the method will:</p>
<ul class="simple">
<li><p>return the value of the <em>default</em> argument of the method,
if provided; or</p></li>
<li><p>return the default value for the context variable,
if it was created with one; or</p></li>
<li><p>raise a <a class="reference internal" href="exceptions.html#LookupError" title="LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>.</p></li>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.set">
<span class="sig-name descname"><span class="pre">set</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.ContextVar.set" title="Link to this definition">¶</a></dt>
<dd><p>Call to set a new value for the context variable in the current
context.</p>
<p>The required <em>value</em> argument is the new value for the context
variable.</p>
<p>Returns a <a class="reference internal" href="#contextvars.Token" title="contextvars.Token"><code class="xref py py-class docutils literal notranslate"><span class="pre">Token</span></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"><span class="pre">ContextVar.reset()</span></code></a> method.</p>
<p>For convenience, the token object can be used as a context manager
to avoid calling <a class="reference internal" href="#contextvars.ContextVar.reset" title="contextvars.ContextVar.reset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ContextVar.reset()</span></code></a> manually:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">'var'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'default value'</span><span class="p">)</span>
<span class="k">with</span> <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'new value'</span><span class="p">):</span>
    <span class="k">assert</span> <span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'new value'</span>
<span class="k">assert</span> <span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'default value'</span>
</pre></div>
<p>It is a shorthand for:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">'var'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'default value'</span><span class="p">)</span>
<span class="n">token</span> <span class="o">=</span> <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'new value'</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
    <span class="k">assert</span> <span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'new value'</span>
<span class="k">finally</span><span class="p">:</span>
    <span class="n">var</span><span class="o">.</span><span class="n">reset</span><span class="p">(</span><span class="n">token</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'default value'</span>
</pre></div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14: </span>Added support for using tokens as context managers.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.ContextVar.reset">
<span class="sig-name descname"><span class="pre">reset</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">token</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.ContextVar.reset" title="Link to this definition">¶</a></dt>
<dd><p>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"><span class="pre">ContextVar.set()</span></code></a> that created the <em>token</em> was used.</p>
<p>For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="o">=</span> <span class="n">ContextVar</span><span class="p">(</span><span class="s1">'var'</span><span class="p">)</span>
<span class="n">token</span> <span class="o">=</span> <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'new value'</span><span class="p">)</span>
<span class="c1"># code that uses 'var'; var.get() returns 'new value'.</span>
<span class="n">var</span><span class="o">.</span><span class="n">reset</span><span class="p">(</span><span class="n">token</span><span class="p">)</span>
<span class="c1"># After the reset call the var has no value again, so</span>
<span class="c1"># var.get() would raise a LookupError.</span>
</pre></div>
<p>The same <em>token</em> cannot be used twice.</p>
<dl class="py class">
<dt class="sig sig-object py" id="contextvars.Token">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">contextvars.</span></span><span class="sig-name descname"><span class="pre">Token</span></span><a class="headerlink" href="#contextvars.Token" title="Link to this definition">¶</a></dt>
<dd><p><em>Token</em> 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"><span class="pre">ContextVar.set()</span></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"><span class="pre">ContextVar.reset()</span></code></a> method to revert
the value of the variable to what it was before the corresponding
<em>set</em>. A single token cannot reset a context variable more than once.</p>
<p>Tokens support the <a class="reference internal" href="../reference/datamodel.html#context-managers"><span class="std std-ref">context manager protocol</span></a>
to automatically reset context variables. See <a class="reference internal" href="#contextvars.ContextVar.set" title="contextvars.ContextVar.set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ContextVar.set()</span></code></a>.</p>
<p>Tokens are <a class="reference internal" href="typing.html#generics"><span class="std std-ref">generic</span></a> over the same type as the
<a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code></a> which created them.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14: </span>Added support for usage as a context manager.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.var">
<span class="sig-name descname"><span class="pre">var</span></span><a class="headerlink" href="#contextvars.Token.var" title="Link to this definition">¶</a></dt>
<dd><p>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"><span class="pre">ContextVar</span></code></a> object
that created the token.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.old_value">
<span class="sig-name descname"><span class="pre">old_value</span></span><a class="headerlink" href="#contextvars.Token.old_value" title="Link to this definition">¶</a></dt>
<dd><p>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"><span class="pre">ContextVar.set()</span></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"><span class="pre">Token.MISSING</span></code></a> if the variable was not set
before the call.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="contextvars.Token.MISSING">
<span class="sig-name descname"><span class="pre">MISSING</span></span><a class="headerlink" href="#contextvars.Token.MISSING" title="Link to this definition">¶</a></dt>
<dd><p>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"><span class="pre">Token.old_value</span></code></a>.</p>
<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">
<span class="sig-prename descclassname"><span class="pre">contextvars.</span></span><span class="sig-name descname"><span class="pre">copy_context</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.copy_context" title="Link to this definition">¶</a></dt>
<dd><p>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"><span class="pre">Context</span></code></a> object.</p>
<p>The following snippet gets a copy of the current context and prints
all variables and their values that are set in it:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ctx</span><span class="p">:</span> <span class="n">Context</span> <span class="o">=</span> <span class="n">copy_context</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">ctx</span><span class="o">.</span><span class="n">items</span><span class="p">()))</span>
</pre></div>
<p>The function has an <em>O</em>(1) complexity, i.e. works equally fast for
contexts with a few context variables and for contexts that have
a lot of them.</p>
<dl class="py class">
<dt class="sig sig-object py" id="contextvars.Context">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">contextvars.</span></span><span class="sig-name descname"><span class="pre">Context</span></span><a class="headerlink" href="#contextvars.Context" title="Link to this definition">¶</a></dt>
<dd><p>A mapping of <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVars</span></code></a> to their values.</p>
<p><code class="docutils literal notranslate"><span class="pre">Context()</span></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"><span class="pre">copy_context()</span></code></a> function.</p>
<p>Each thread has its own effective stack of <code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code> objects.  The
<a class="reference internal" href="../glossary.html#term-current-context"><span class="xref std std-term">current context</span></a> is the <code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code> object at the top of the
current thread's stack.  All <code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code> objects in the stacks are
considered to be <em>entered</em>.</p>
<p><em>Entering</em> a context, which can be done by calling its <a class="reference internal" href="#contextvars.Context.run" title="contextvars.Context.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>
method, makes the context the current context by pushing it onto the top of
the current thread's context stack.</p>
<p><em>Exiting</em> from the current context, which can be done by returning from the
callback passed to the <a class="reference internal" href="#contextvars.Context.run" title="contextvars.Context.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method, restores the current
context to what it was before the context was entered by popping the context
off the top of the context stack.</p>
<p>Since each thread has its own context stack, <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code></a> objects
behave 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"><span class="pre">threading.local()</span></code></a> when values are
assigned in different threads.</p>
<p>Attempting to enter an already entered context, including contexts entered in
other threads, raises a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>.</p>
<p>After exiting a context, it can later be re-entered (from any thread).</p>
<p>Any changes to <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></code></a> values via the <a class="reference internal" href="#contextvars.ContextVar.set" title="contextvars.ContextVar.set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ContextVar.set()</span></code></a>
method are recorded in the current context.  The <a class="reference internal" href="#contextvars.ContextVar.get" title="contextvars.ContextVar.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ContextVar.get()</span></code></a>
method returns the value associated with the current context.  Exiting a
context effectively reverts any changes made to context variables while the
context was entered (if needed, the values can be restored by re-entering the
context).</p>
<p>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"><span class="pre">collections.abc.Mapping</span></code></a> interface.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.run">
<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callable</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.run" title="Link to this definition">¶</a></dt>
<dd><p>Enters the Context, executes <code class="docutils literal notranslate"><span class="pre">callable(*args,</span> <span class="pre">**kwargs)</span></code>, then exits the
Context.  Returns <em>callable</em>'s return value, or propagates an exception if
one occurred.</p>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">contextvars</span>
<span class="n">var</span> <span class="o">=</span> <span class="n">contextvars</span><span class="o">.</span><span class="n">ContextVar</span><span class="p">(</span><span class="s1">'var'</span><span class="p">)</span>
<span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'spam'</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>  <span class="c1"># 'spam'</span>
<span class="n">ctx</span> <span class="o">=</span> <span class="n">contextvars</span><span class="o">.</span><span class="n">copy_context</span><span class="p">()</span>
<span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
    <span class="c1"># 'var' was set to 'spam' before</span>
    <span class="c1"># calling 'copy_context()' and 'ctx.run(main)', so:</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>  <span class="c1"># 'spam'</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">ctx</span><span class="p">[</span><span class="n">var</span><span class="p">])</span>  <span class="c1"># 'spam'</span>
    <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'ham'</span><span class="p">)</span>
    <span class="c1"># Now, after setting 'var' to 'ham':</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>  <span class="c1"># 'ham'</span>
    <span class="nb">print</span><span class="p">(</span><span class="n">ctx</span><span class="p">[</span><span class="n">var</span><span class="p">])</span>  <span class="c1"># 'ham'</span>
<span class="c1"># Any changes that the 'main' function makes to 'var'</span>
<span class="c1"># will be contained in 'ctx'.</span>
<span class="n">ctx</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">)</span>
<span class="c1"># The 'main()' function was run in the 'ctx' context,</span>
<span class="c1"># so changes to 'var' are contained in it:</span>
<span class="nb">print</span><span class="p">(</span><span class="n">ctx</span><span class="p">[</span><span class="n">var</span><span class="p">])</span>  <span class="c1"># 'ham'</span>
<span class="c1"># However, outside of 'ctx', 'var' is still set to 'spam':</span>
<span class="nb">print</span><span class="p">(</span><span class="n">var</span><span class="o">.</span><span class="n">get</span><span class="p">())</span>  <span class="c1"># 'spam'</span>
</pre></div>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.copy">
<span class="sig-name descname"><span class="pre">copy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.copy" title="Link to this definition">¶</a></dt>
<dd><p>Return a shallow copy of the context object.</p>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">var</span> <span class="pre">in</span> <span class="pre">context</span></span></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the <em>context</em> has a value for <em>var</em> set;
return <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">context[var]</span></span></dt>
<dd><p>Return the value of the <em>var</em> <a class="reference internal" href="#contextvars.ContextVar" title="contextvars.ContextVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">ContextVar</span></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"><span class="pre">KeyError</span></code></a> is raised.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">var</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">default</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.get" title="Link to this definition">¶</a></dt>
<dd><p>Return the value for <em>var</em> if <em>var</em> has the value in the context
object.  Return <em>default</em> otherwise.  If <em>default</em> is not given,
return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">iter(context)</span></span></dt>
<dd><p>Return an iterator over the variables stored in the context
object.</p>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">len(proxy)</span></span></dt>
<dd><p>Return the number of variables set in the context object.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.keys">
<span class="sig-name descname"><span class="pre">keys</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.keys" title="Link to this definition">¶</a></dt>
<dd><p>Return a list of all variables in the context object.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.values">
<span class="sig-name descname"><span class="pre">values</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.values" title="Link to this definition">¶</a></dt>
<dd><p>Return a list of all variables' values in the context object.</p>
<dl class="py method">
<dt class="sig sig-object py" id="contextvars.Context.items">
<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#contextvars.Context.items" title="Link to this definition">¶</a></dt>
<dd><p>Return a list of 2-tuples containing all variables and their
values in the context object.</p>
<section id="asyncio-support">
<h2>asyncio support<a class="headerlink" href="#asyncio-support" title="Link to this heading">¶</a></h2>
<p>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"><span class="pre">asyncio</span></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:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">contextvars</span>
<span class="n">client_addr_var</span> <span class="o">=</span> <span class="n">contextvars</span><span class="o">.</span><span class="n">ContextVar</span><span class="p">(</span><span class="s1">'client_addr'</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">render_goodbye</span><span class="p">():</span>
    <span class="c1"># The address of the currently handled client can be accessed</span>
    <span class="c1"># without passing it explicitly to this function.</span>
    <span class="n">client_addr</span> <span class="o">=</span> <span class="n">client_addr_var</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
    <span class="k">return</span> <span class="sa">f</span><span class="s1">'Good bye, client @ </span><span class="si">{</span><span class="n">client_addr</span><span class="si">}</span><span class="se">\r\n</span><span class="s1">'</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_request</span><span class="p">(</span><span class="n">reader</span><span class="p">,</span> <span class="n">writer</span><span class="p">):</span>
    <span class="n">addr</span> <span class="o">=</span> <span class="n">writer</span><span class="o">.</span><span class="n">transport</span><span class="o">.</span><span class="n">get_extra_info</span><span class="p">(</span><span class="s1">'socket'</span><span class="p">)</span><span class="o">.</span><span class="n">getpeername</span><span class="p">()</span>
    <span class="n">client_addr_var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">addr</span><span class="p">)</span>
    <span class="c1"># In any code that we call is now possible to get</span>
    <span class="c1"># client's address by calling 'client_addr_var.get()'.</span>
    <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
        <span class="n">line</span> <span class="o">=</span> <span class="k">await</span> <span class="n">reader</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
        <span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span>
            <span class="k">break</span>
    <span class="n">writer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s1">'HTTP/1.1 200 OK</span><span class="se">\r\n</span><span class="s1">'</span><span class="p">)</span>  <span class="c1"># status line</span>
    <span class="n">writer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s1">'</span><span class="se">\r\n</span><span class="s1">'</span><span class="p">)</span>  <span class="c1"># headers</span>
    <span class="n">writer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">render_goodbye</span><span class="p">())</span>  <span class="c1"># body</span>
    <span class="n">writer</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">():</span>
    <span class="n">srv</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">start_server</span><span class="p">(</span>
        <span class="n">handle_request</span><span class="p">,</span> <span class="s1">'127.0.0.1'</span><span class="p">,</span> <span class="mi">8081</span><span class="p">)</span>
    <span class="k">async</span> <span class="k">with</span> <span class="n">srv</span><span class="p">:</span>
        <span class="k">await</span> <span class="n">srv</span><span class="o">.</span><span class="n">serve_forever</span><span class="p">()</span>
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
<span class="c1"># To test it you can use telnet or curl:</span>
<span class="c1">#     telnet 127.0.0.1 8081</span>
<span class="c1">#     curl 127.0.0.1:8081</span>
</pre></div>
            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
    <h3><a href="../contents.html">فهرست عناوین</a></h3>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></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>
    <h4>موضوع قبلی</h4>
    <p class="topless"><a href="queue.html"
                          title="فصل قبلی"><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code> --- A synchronized queue class</a></p>
    <h4>موضوع  بعدی</h4>
    <p class="topless"><a href="_thread.html"
                          title="فصل بعدی"><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code> --- Low-level threading API</a></p>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "library/contextvars.rst");
            element.href = url.toString();
        });
  </script>
  <div role="note" aria-label="source link">
    <h3>این صفحه</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">گزارش یک اشکال</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">بهبود این صفحه</a></li>
        <a href="https://github.com/python/cpython/blob/main/Doc/library/contextvars.rst?plain=1"
            rel="nofollow">نمایش منبع
        </a>
      </li>
        <a href="https://github.com/python/python-docs-fa/blob/3.14/library/contextvars.po?plain=1"
           rel="nofollow">نمایش منبع ترجمه</a>
      </li>
        </div>
<div id="sidebarbutton" title="تا کردن نوار کناره">
<span>«</span>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related" role="navigation" aria-label="Related">
      <h3>ناوبری</h3>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="فهرست کلی"
             >فهرست</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"
             >ماژول ها</a> |</li>
        <li class="right" >
          <a href="_thread.html" title="_thread --- Low-level threading API"
             >بعدی</a> |</li>
        <li class="right" >
          <a href="queue.html" title="queue --- A synchronized queue class"
             >قبلی</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.14.6 Documentation</a> &#187;
          <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"><span class="pre">contextvars</span></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="جستجو سریع" aria-label="جستجو سریع" type="search" name="q" id="search-box">
          <input type="submit" value="برو">
        </form>
                </li>
            <li class="right">
<label class="theme-selector-label">
    <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">حق چاپ</a> 2001 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.<br>
    The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
      آخرین بروز رسانی در اوت 18, 2026 (04:23 UTC) .
      <a href="/bugs.html">Found a bug</a>?
    ایجاد شده با<a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

contextvars.html

Latest commit

History

contextvars.html

File metadata and controls
