Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關注 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
分支: master
分支列表 標籤
${ item.name }
建立分支 ${ searchTerm }
從 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/contextvars.html

636 line
41KB
原始文件 永久連結 Blame 歷史記錄 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="contextvars — Context Variables" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/contextvars.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <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..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <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..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>contextvars — Context Variables &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="_thread — Low-level threading API" href="_thread.html" />

  39.     <link rel="prev" title="queue — A synchronized queue class" href="queue.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/contextvars.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <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>

  99. <li><a class="reference internal" href="#context-variables">Context Variables</a></li>

  100. <li><a class="reference internal" href="#manual-context-management">Manual Context Management</a></li>

  101. <li><a class="reference internal" href="#asyncio-support">asyncio support</a></li>

  102. </ul>

  103. </li>

  104. </ul>

  105. 

  106.   </div>

  107.   <div>

  108.     <h4>Previous topic</h4>

  109.     <p class="topless"><a href="queue.html"

  110.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code> — A synchronized queue class</a></p>

  111.   </div>

  112.   <div>

  113.     <h4>Next topic</h4>

  114.     <p class="topless"><a href="_thread.html"

  115.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code> — Low-level threading API</a></p>

  116.   </div>

  117.   <div role="note" aria-label="source link">

  118.     <h3>This Page</h3>

  119.     <ul class="this-page-menu">

  120.       <li><a href="../bugs.html">Report a Bug</a></li>

  121.       <li>

  122.         <a href="https://github.com/python/cpython/blob/main/Doc/library/contextvars.rst"

  123.             rel="nofollow">Show Source

  124.         </a>

  125.       </li>

  126.     </ul>

  127.   </div>

  128.         </nav>

  129.     </div>

  130. </div>

  131. 

  132.   

  133.     <div class="related" role="navigation" aria-label="related navigation">

  134.       <h3>Navigation</h3>

  135.       <ul>

  136.         <li class="right" style="margin-right: 10px">

  137.           <a href="../genindex.html" title="General Index"

  138.              accesskey="I">index</a></li>

  139.         <li class="right" >

  140.           <a href="../py-modindex.html" title="Python Module Index"

  141.              >modules</a> |</li>

  142.         <li class="right" >

  143.           <a href="_thread.html" title="_thread — Low-level threading API"

  144.              accesskey="N">next</a> |</li>

  145.         <li class="right" >

  146.           <a href="queue.html" title="queue — A synchronized queue class"

  147.              accesskey="P">previous</a> |</li>

  148. 

  149.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  150.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  151.           <li class="switchers">

  152.             <div class="language_switcher_placeholder"></div>

  153.             <div class="version_switcher_placeholder"></div>

  154.           </li>

  155.           <li>

  156.               

  157.           </li>

  158.     <li id="cpython-language-and-version">

  159.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  160.     </li>

  161. 

  162.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  163.           <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> &#187;</li>

  164.         <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>

  165.                 <li class="right">

  166.                     

  167. 

  168.     <div class="inline-search" role="search">

  169.         <form class="inline-search" action="../search.html" method="get">

  170.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  171.           <input type="submit" value="Go" />

  172.         </form>

  173.     </div>

  174.                      |

  175.                 </li>

  176.             <li class="right">

  177. <label class="theme-selector-label">

  178.     Theme

  179.     <select class="theme-selector" oninput="activateTheme(this.value)">

  180.         <option value="auto" selected>Auto</option>

  181.         <option value="light">Light</option>

  182.         <option value="dark">Dark</option>

  183.     </select>

  184. </label> |</li>

  185.             

  186.       </ul>

  187.     </div>    

  188. 

  189.     <div class="document">

  190.       <div class="documentwrapper">

  191.         <div class="bodywrapper">

  192.           <div class="body" role="main">

  193.             

  194.   <section id="module-contextvars">

  195. <span id="contextvars-context-variables"></span><h1><a class="reference internal" href="#module-contextvars" title="contextvars: Context Variables"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></code></a> — Context Variables<a class="headerlink" href="#module-contextvars" title="Link to this heading">¶</a></h1>

  196. <hr class="docutils" />

  197. <p>This module provides APIs to manage, store, and access context-local

  198. 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

  199. 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>

  200. 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

  201. manage the current context in asynchronous frameworks.</p>

  202. <p>Context managers that have state should use Context Variables

  203. 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

  204. bleeding to other code unexpectedly, when used in concurrent code.</p>

  205. <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>

  206. <div class="versionadded">

  207. <p><span class="versionmodified added">New in version 3.7.</span></p>

  208. </div>

  209. <section id="context-variables">

  210. <h2>Context Variables<a class="headerlink" href="#context-variables" title="Link to this heading">¶</a></h2>

  211. <dl class="py class">

  212. <dt class="sig sig-object py" id="contextvars.ContextVar">

  213. <em class="property"><span class="pre">class</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>

  214. <dd><p>This class is used to declare a new Context Variable, e.g.:</p>

  215. <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">&#39;var&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>

  216. </pre></div>

  217. </div>

  218. <p>The required <em>name</em> parameter is used for introspection and debug

  219. purposes.</p>

  220. <p>The optional keyword-only <em>default</em> parameter is returned by

  221. <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

  222. in the current context.</p>

  223. <p><strong>Important:</strong> Context Variables should be created at the top module

  224. 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

  225. references to context variables which prevents context variables

  226. from being properly garbage collected.</p>

  227. <dl class="py attribute">

  228. <dt class="sig sig-object py" id="contextvars.ContextVar.name">

  229. <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>

  230. <dd><p>The name of the variable.  This is a read-only property.</p>

  231. <div class="versionadded">

  232. <p><span class="versionmodified added">New in version 3.7.1.</span></p>

  233. </div>

  234. </dd></dl>

  235. 

  236. <dl class="py method">

  237. <dt class="sig sig-object py" id="contextvars.ContextVar.get">

  238. <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>

  239. <dd><p>Return a value for the context variable for the current context.</p>

  240. <p>If there is no value for the variable in the current context,

  241. the method will:</p>

  242. <ul class="simple">

  243. <li><p>return the value of the <em>default</em> argument of the method,

  244. if provided; or</p></li>

  245. <li><p>return the default value for the context variable,

  246. if it was created with one; or</p></li>

  247. <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>

  248. </ul>

  249. </dd></dl>

  250. 

  251. <dl class="py method">

  252. <dt class="sig sig-object py" id="contextvars.ContextVar.set">

  253. <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>

  254. <dd><p>Call to set a new value for the context variable in the current

  255. context.</p>

  256. <p>The required <em>value</em> argument is the new value for the context

  257. variable.</p>

  258. <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

  259. to restore the variable to its previous value via the

  260. <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>

  261. </dd></dl>

  262. 

  263. <dl class="py method">

  264. <dt class="sig sig-object py" id="contextvars.ContextVar.reset">

  265. <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>

  266. <dd><p>Reset the context variable to the value it had before the

  267. <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>

  268. <p>For example:</p>

  269. <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">&#39;var&#39;</span><span class="p">)</span>

  270. 

  271. <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">&#39;new value&#39;</span><span class="p">)</span>

  272. <span class="c1"># code that uses &#39;var&#39;; var.get() returns &#39;new value&#39;.</span>

  273. <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>

  274. 

  275. <span class="c1"># After the reset call the var has no value again, so</span>

  276. <span class="c1"># var.get() would raise a LookupError.</span>

  277. </pre></div>

  278. </div>

  279. </dd></dl>

  280. 

  281. </dd></dl>

  282. 

  283. <dl class="py class">

  284. <dt class="sig sig-object py" id="contextvars.Token">

  285. <em class="property"><span class="pre">class</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>

  286. <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.

  287. 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

  288. the value of the variable to what it was before the corresponding

  289. <em>set</em>.</p>

  290. <dl class="py attribute">

  291. <dt class="sig sig-object py" id="contextvars.Token.var">

  292. <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>

  293. <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

  294. that created the token.</p>

  295. </dd></dl>

  296. 

  297. <dl class="py attribute">

  298. <dt class="sig sig-object py" id="contextvars.Token.old_value">

  299. <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>

  300. <dd><p>A read-only property.  Set to the value the variable had before

  301. 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.

  302. 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

  303. before the call.</p>

  304. </dd></dl>

  305. 

  306. <dl class="py attribute">

  307. <dt class="sig sig-object py" id="contextvars.Token.MISSING">

  308. <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>

  309. <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>

  310. </dd></dl>

  311. 

  312. </dd></dl>

  313. 

  314. </section>

  315. <section id="manual-context-management">

  316. <h2>Manual Context Management<a class="headerlink" href="#manual-context-management" title="Link to this heading">¶</a></h2>

  317. <dl class="py function">

  318. <dt class="sig sig-object py" id="contextvars.copy_context">

  319. <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>

  320. <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>

  321. <p>The following snippet gets a copy of the current context and prints

  322. all variables and their values that are set in it:</p>

  323. <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>

  324. <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>

  325. </pre></div>

  326. </div>

  327. <p>The function has an <em>O</em>(1) complexity, i.e. works equally fast for

  328. contexts with a few context variables and for contexts that have

  329. a lot of them.</p>

  330. </dd></dl>

  331. 

  332. <dl class="py class">

  333. <dt class="sig sig-object py" id="contextvars.Context">

  334. <em class="property"><span class="pre">class</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>

  335. <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>

  336. <p><code class="docutils literal notranslate"><span class="pre">Context()</span></code> creates an empty context with no values in it.

  337. To get a copy of the current context use the

  338. <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>

  339. <p>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"><span class="pre">Context</span></code></a>

  340. object. This means that a <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 behaves in a similar

  341. 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

  342. threads.</p>

  343. <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>

  344. <dl class="py method">

  345. <dt class="sig sig-object py" id="contextvars.Context.run">

  346. <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>

  347. <dd><p>Execute <code class="docutils literal notranslate"><span class="pre">callable(*args,</span> <span class="pre">**kwargs)</span></code> code in the context object

  348. the <em>run</em> method is called on.  Return the result of the execution

  349. or propagate an exception if one occurred.</p>

  350. <p>Any changes to any context variables that <em>callable</em> makes will

  351. be contained in the context object:</p>

  352. <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">&#39;var&#39;</span><span class="p">)</span>

  353. <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">&#39;spam&#39;</span><span class="p">)</span>

  354. 

  355. <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  356.     <span class="c1"># &#39;var&#39; was set to &#39;spam&#39; before</span>

  357.     <span class="c1"># calling &#39;copy_context()&#39; and &#39;ctx.run(main)&#39;, so:</span>

  358.     <span class="c1"># var.get() == ctx[var] == &#39;spam&#39;</span>

  359. 

  360.     <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">&#39;ham&#39;</span><span class="p">)</span>

  361. 

  362.     <span class="c1"># Now, after setting &#39;var&#39; to &#39;ham&#39;:</span>

  363.     <span class="c1"># var.get() == ctx[var] == &#39;ham&#39;</span>

  364. 

  365. <span class="n">ctx</span> <span class="o">=</span> <span class="n">copy_context</span><span class="p">()</span>

  366. 

  367. <span class="c1"># Any changes that the &#39;main&#39; function makes to &#39;var&#39;</span>

  368. <span class="c1"># will be contained in &#39;ctx&#39;.</span>

  369. <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>

  370. 

  371. <span class="c1"># The &#39;main()&#39; function was run in the &#39;ctx&#39; context,</span>

  372. <span class="c1"># so changes to &#39;var&#39; are contained in it:</span>

  373. <span class="c1"># ctx[var] == &#39;ham&#39;</span>

  374. 

  375. <span class="c1"># However, outside of &#39;ctx&#39;, &#39;var&#39; is still set to &#39;spam&#39;:</span>

  376. <span class="c1"># var.get() == &#39;spam&#39;</span>

  377. </pre></div>

  378. </div>

  379. <p>The method 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> when called on the same

  380. context object from more than one OS thread, or when called

  381. recursively.</p>

  382. </dd></dl>

  383. 

  384. <dl class="py method">

  385. <dt class="sig sig-object py" id="contextvars.Context.copy">

  386. <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>

  387. <dd><p>Return a shallow copy of the context object.</p>

  388. </dd></dl>

  389. 

  390. <dl class="describe">

  391. <dt class="sig sig-object">

  392. <span class="sig-name descname"><span class="pre">var</span> <span class="pre">in</span> <span class="pre">context</span></span></dt>

  393. <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;

  394. return <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>

  395. </dd></dl>

  396. 

  397. <dl class="describe">

  398. <dt class="sig sig-object">

  399. <span class="sig-name descname"><span class="pre">context[var]</span></span></dt>

  400. <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.

  401. If the variable is not set in the context object, a

  402. <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>

  403. </dd></dl>

  404. 

  405. <dl class="py method">

  406. <dt class="sig sig-object py" id="contextvars.Context.get">

  407. <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>

  408. <dd><p>Return the value for <em>var</em> if <em>var</em> has the value in the context

  409. object.  Return <em>default</em> otherwise.  If <em>default</em> is not given,

  410. return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  411. </dd></dl>

  412. 

  413. <dl class="describe">

  414. <dt class="sig sig-object">

  415. <span class="sig-name descname"><span class="pre">iter(context)</span></span></dt>

  416. <dd><p>Return an iterator over the variables stored in the context

  417. object.</p>

  418. </dd></dl>

  419. 

  420. <dl class="describe">

  421. <dt class="sig sig-object">

  422. <span class="sig-name descname"><span class="pre">len(proxy)</span></span></dt>

  423. <dd><p>Return the number of variables set in the context object.</p>

  424. </dd></dl>

  425. 

  426. <dl class="py method">

  427. <dt class="sig sig-object py" id="contextvars.Context.keys">

  428. <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>

  429. <dd><p>Return a list of all variables in the context object.</p>

  430. </dd></dl>

  431. 

  432. <dl class="py method">

  433. <dt class="sig sig-object py" id="contextvars.Context.values">

  434. <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>

  435. <dd><p>Return a list of all variables’ values in the context object.</p>

  436. </dd></dl>

  437. 

  438. <dl class="py method">

  439. <dt class="sig sig-object py" id="contextvars.Context.items">

  440. <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>

  441. <dd><p>Return a list of 2-tuples containing all variables and their

  442. values in the context object.</p>

  443. </dd></dl>

  444. 

  445. </dd></dl>

  446. 

  447. </section>

  448. <section id="asyncio-support">

  449. <h2>asyncio support<a class="headerlink" href="#asyncio-support" title="Link to this heading">¶</a></h2>

  450. <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

  451. ready to be used without any extra configuration.  For example, here

  452. is a simple echo server, that uses a context variable to make the

  453. address of a remote client available in the Task that handles that

  454. client:</p>

  455. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">asyncio</span>

  456. <span class="kn">import</span> <span class="nn">contextvars</span>

  457. 

  458. <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">&#39;client_addr&#39;</span><span class="p">)</span>

  459. 

  460. <span class="k">def</span> <span class="nf">render_goodbye</span><span class="p">():</span>

  461.     <span class="c1"># The address of the currently handled client can be accessed</span>

  462.     <span class="c1"># without passing it explicitly to this function.</span>

  463. 

  464.     <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>

  465.     <span class="k">return</span> <span class="sa">f</span><span class="s1">&#39;Good bye, client @ </span><span class="si">{</span><span class="n">client_addr</span><span class="si">}</span><span class="se">\n</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>

  466. 

  467. <span class="k">async</span> <span class="k">def</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>

  468.     <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">&#39;socket&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">getpeername</span><span class="p">()</span>

  469.     <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>

  470. 

  471.     <span class="c1"># In any code that we call is now possible to get</span>

  472.     <span class="c1"># client&#39;s address by calling &#39;client_addr_var.get()&#39;.</span>

  473. 

  474.     <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>

  475.         <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>

  476.         <span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>

  477.         <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>

  478.             <span class="k">break</span>

  479.         <span class="n">writer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>

  480. 

  481.     <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>

  482.     <span class="n">writer</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  483. 

  484. <span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  485.     <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>

  486.         <span class="n">handle_request</span><span class="p">,</span> <span class="s1">&#39;127.0.0.1&#39;</span><span class="p">,</span> <span class="mi">8081</span><span class="p">)</span>

  487. 

  488.     <span class="k">async</span> <span class="k">with</span> <span class="n">srv</span><span class="p">:</span>

  489.         <span class="k">await</span> <span class="n">srv</span><span class="o">.</span><span class="n">serve_forever</span><span class="p">()</span>

  490. 

  491. <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>

  492. 

  493. <span class="c1"># To test it you can use telnet:</span>

  494. <span class="c1">#     telnet 127.0.0.1 8081</span>

  495. </pre></div>

  496. </div>

  497. </section>

  498. </section>

  499. 

  500. 

  501.             <div class="clearer"></div>

  502.           </div>

  503.         </div>

  504.       </div>

  505.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  506.         <div class="sphinxsidebarwrapper">

  507.   <div>

  508.     <h3><a href="../contents.html">Table of Contents</a></h3>

  509.     <ul>

  510. <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>

  511. <li><a class="reference internal" href="#context-variables">Context Variables</a></li>

  512. <li><a class="reference internal" href="#manual-context-management">Manual Context Management</a></li>

  513. <li><a class="reference internal" href="#asyncio-support">asyncio support</a></li>

  514. </ul>

  515. </li>

  516. </ul>

  517. 

  518.   </div>

  519.   <div>

  520.     <h4>Previous topic</h4>

  521.     <p class="topless"><a href="queue.html"

  522.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">queue</span></code> — A synchronized queue class</a></p>

  523.   </div>

  524.   <div>

  525.     <h4>Next topic</h4>

  526.     <p class="topless"><a href="_thread.html"

  527.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code> — Low-level threading API</a></p>

  528.   </div>

  529.   <div role="note" aria-label="source link">

  530.     <h3>This Page</h3>

  531.     <ul class="this-page-menu">

  532.       <li><a href="../bugs.html">Report a Bug</a></li>

  533.       <li>

  534.         <a href="https://github.com/python/cpython/blob/main/Doc/library/contextvars.rst"

  535.             rel="nofollow">Show Source

  536.         </a>

  537.       </li>

  538.     </ul>

  539.   </div>

  540.         </div>

  541. <div id="sidebarbutton" title="Collapse sidebar">

  542. <span>«</span>

  543. </div>

  544. 

  545.       </div>

  546.       <div class="clearer"></div>

  547.     </div>  

  548.     <div class="related" role="navigation" aria-label="related navigation">

  549.       <h3>Navigation</h3>

  550.       <ul>

  551.         <li class="right" style="margin-right: 10px">

  552.           <a href="../genindex.html" title="General Index"

  553.              >index</a></li>

  554.         <li class="right" >

  555.           <a href="../py-modindex.html" title="Python Module Index"

  556.              >modules</a> |</li>

  557.         <li class="right" >

  558.           <a href="_thread.html" title="_thread — Low-level threading API"

  559.              >next</a> |</li>

  560.         <li class="right" >

  561.           <a href="queue.html" title="queue — A synchronized queue class"

  562.              >previous</a> |</li>

  563. 

  564.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  565.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  566.           <li class="switchers">

  567.             <div class="language_switcher_placeholder"></div>

  568.             <div class="version_switcher_placeholder"></div>

  569.           </li>

  570.           <li>

  571.               

  572.           </li>

  573.     <li id="cpython-language-and-version">

  574.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  575.     </li>

  576. 

  577.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  578.           <li class="nav-item nav-item-2"><a href="concurrency.html" >Concurrent Execution</a> &#187;</li>

  579.         <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>

  580.                 <li class="right">

  581.                     

  582. 

  583.     <div class="inline-search" role="search">

  584.         <form class="inline-search" action="../search.html" method="get">

  585.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  586.           <input type="submit" value="Go" />

  587.         </form>

  588.     </div>

  589.                      |

  590.                 </li>

  591.             <li class="right">

  592. <label class="theme-selector-label">

  593.     Theme

  594.     <select class="theme-selector" oninput="activateTheme(this.value)">

  595.         <option value="auto" selected>Auto</option>

  596.         <option value="light">Light</option>

  597.         <option value="dark">Dark</option>

  598.     </select>

  599. </label> |</li>

  600.             

  601.       </ul>

  602.     </div>  

  603.     <div class="footer">

  604.     &copy; 

  605.       <a href="../copyright.html">

  606.     

  607.     Copyright

  608.     

  609.       </a>

  610.      2001-2024, Python Software Foundation.

  611.     <br />

  612.     This page is licensed under the Python Software Foundation License Version 2.

  613.     <br />

  614.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  615.     <br />

  616.     

  617.       See <a href="/license.html">History and License</a> for more information.<br />

  618.     

  619.     

  620.     <br />

  621. 

  622.     The Python Software Foundation is a non-profit corporation.

  623. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  624. <br />

  625.     <br />

  626.       Last updated on Apr 09, 2024 (13:47 UTC).

  627.     

  628.       <a href="/bugs.html">Found a bug</a>?

  629.     

  630.     <br />

  631. 

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

  633.     </div>

  634. 

  635.   </body>

  636. </html>
上海开阖软件有限公司 沪ICP备12045867号-1