path: root/devdocs/python~3.12/c-api%2Fcontextvars.html

 <span id="contextvarsobjects"></span><h1>Context Variables Objects</h1> <div class="versionchanged" id="contextvarsobjects-pointertype-change"> <p><span class="versionmodified changed">Changed in version 3.7.1: </span></p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>In Python 3.7.1 the signatures of all context variables C APIs were <strong>changed</strong> to use <a class="reference internal" href="structures#c.PyObject" title="PyObject"><code>PyObject</code></a> pointers instead of <a class="reference internal" href="#c.PyContext" title="PyContext"><code>PyContext</code></a>, <a class="reference internal" href="#c.PyContextVar" title="PyContextVar"><code>PyContextVar</code></a>, and <a class="reference internal" href="#c.PyContextToken" title="PyContextToken"><code>PyContextToken</code></a>, e.g.:</p> <pre data-language="c">// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);
</pre> <p>See <a class="reference external" href="https://bugs.python.org/issue?@action=redirect&amp;bpo=34762">bpo-34762</a> for more details.</p> </div> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> <p>This section details the public C API for the <a class="reference internal" href="../library/contextvars#module-contextvars" title="contextvars: Context Variables"><code>contextvars</code></a> module.</p> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContext">
<code>type PyContext</code> </dt> <dd>
<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.Context" title="contextvars.Context"><code>contextvars.Context</code></a> object.</p> </dd>
</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContextVar">
<code>type PyContextVar</code> </dt> <dd>
<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.ContextVar" title="contextvars.ContextVar"><code>contextvars.ContextVar</code></a> object.</p> </dd>
</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyContextToken">
<code>type PyContextToken</code> </dt> <dd>
<p>The C structure used to represent a <a class="reference internal" href="../library/contextvars#contextvars.Token" title="contextvars.Token"><code>contextvars.Token</code></a> object.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContext_Type">
<code>PyTypeObject PyContext_Type</code> </dt> <dd>
<p>The type object representing the <em>context</em> type.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContextVar_Type">
<code>PyTypeObject PyContextVar_Type</code> </dt> <dd>
<p>The type object representing the <em>context variable</em> type.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyContextToken_Type">
<code>PyTypeObject PyContextToken_Type</code> </dt> <dd>
<p>The type object representing the <em>context variable token</em> type.</p> </dd>
</dl> <p>Type-check macros:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_CheckExact">
<code>int PyContext_CheckExact(PyObject *o)</code> </dt> <dd>
<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContext_Type" title="PyContext_Type"><code>PyContext_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_CheckExact">
<code>int PyContextVar_CheckExact(PyObject *o)</code> </dt> <dd>
<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContextVar_Type" title="PyContextVar_Type"><code>PyContextVar_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextToken_CheckExact">
<code>int PyContextToken_CheckExact(PyObject *o)</code> </dt> <dd>
<p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyContextToken_Type" title="PyContextToken_Type"><code>PyContextToken_Type</code></a>. <em>o</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd>
</dl> <p>Context object management functions:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_New">
<code>PyObject *PyContext_New(void)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Create a new empty context object. Returns <code>NULL</code> if an error has occurred.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Copy">
<code>PyObject *PyContext_Copy(PyObject *ctx)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Create a shallow copy of the passed <em>ctx</em> context object. Returns <code>NULL</code> if an error has occurred.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_CopyCurrent">
<code>PyObject *PyContext_CopyCurrent(void)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Create a shallow copy of the current thread context. Returns <code>NULL</code> if an error has occurred.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Enter">
<code>int PyContext_Enter(PyObject *ctx)</code> </dt> <dd>
<p>Set <em>ctx</em> as the current context for the current thread. Returns <code>0</code> on success, and <code>-1</code> on error.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContext_Exit">
<code>int PyContext_Exit(PyObject *ctx)</code> </dt> <dd>
<p>Deactivate the <em>ctx</em> context and restore the previous context as the current context for the current thread. Returns <code>0</code> on success, and <code>-1</code> on error.</p> </dd>
</dl> <p>Context variable functions:</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_New">
<code>PyObject *PyContextVar_New(const char *name, PyObject *def)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Create a new <code>ContextVar</code> object. The <em>name</em> parameter is used for introspection and debug purposes. The <em>def</em> parameter specifies a default value for the context variable, or <code>NULL</code> for no default. If an error has occurred, this function returns <code>NULL</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Get">
<code>int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)</code> </dt> <dd>
<p>Get the value of a context variable. Returns <code>-1</code> if an error has occurred during lookup, and <code>0</code> if no error occurred, whether or not a value was found.</p> <p>If the context variable was found, <em>value</em> will be a pointer to it. If the context variable was <em>not</em> found, <em>value</em> will point to:</p> <ul class="simple"> <li>
<em>default_value</em>, if not <code>NULL</code>;</li> <li>the default value of <em>var</em>, if not <code>NULL</code>;</li> <li><code>NULL</code></li> </ul> <p>Except for <code>NULL</code>, the function returns a new reference.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Set">
<code>PyObject *PyContextVar_Set(PyObject *var, PyObject *value)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Set the value of <em>var</em> to <em>value</em> in the current context. Returns a new token object for this change, or <code>NULL</code> if an error has occurred.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyContextVar_Reset">
<code>int PyContextVar_Reset(PyObject *var, PyObject *token)</code> </dt> <dd>
<p>Reset the state of the <em>var</em> context variable to that it was in before <a class="reference internal" href="#c.PyContextVar_Set" title="PyContextVar_Set"><code>PyContextVar_Set()</code></a> that returned the <em>token</em> was called. This function returns <code>0</code> on success and <code>-1</code> on error.</p> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/contextvars.html" class="_attribution-link">https://docs.python.org/3.12/c-api/contextvars.html</a>
  </p>
</div>