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

 <span id="id1"></span><h1>Capsules</h1> <p id="index-0">Refer to <a class="reference internal" href="../extending/extending#using-capsules"><span class="std std-ref">Providing a C API for an Extension Module</span></a> for more information on using these objects.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.1.</span></p> </div> <dl class="c type"> <dt class="sig sig-object c" id="c.PyCapsule">
<code>type PyCapsule</code> </dt> <dd>
<p>This subtype of <a class="reference internal" href="structures#c.PyObject" title="PyObject"><code>PyObject</code></a> represents an opaque value, useful for C extension modules who need to pass an opaque value (as a <span class="c-expr sig sig-inline c"><span class="kt">void</span><span class="p">*</span></span> pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.</p> </dd>
</dl> <dl class="c type"> <dt class="sig sig-object c" id="c.PyCapsule_Destructor">
<code>type PyCapsule_Destructor</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>The type of a destructor callback for a capsule. Defined as:</p> <pre data-language="c">typedef void (*PyCapsule_Destructor)(PyObject *);
</pre> <p>See <a class="reference internal" href="#c.PyCapsule_New" title="PyCapsule_New"><code>PyCapsule_New()</code></a> for the semantics of PyCapsule_Destructor callbacks.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_CheckExact">
<code>int PyCapsule_CheckExact(PyObject *p)</code> </dt> <dd>
<p>Return true if its argument is a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code>PyCapsule</code></a>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_New">
<code>PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code>PyCapsule</code></a> encapsulating the <em>pointer</em>. The <em>pointer</em> argument may not be <code>NULL</code>.</p> <p>On failure, set an exception and return <code>NULL</code>.</p> <p>The <em>name</em> string may either be <code>NULL</code> or a pointer to a valid C string. If non-<code>NULL</code>, this string must outlive the capsule. (Though it is permitted to free it inside the <em>destructor</em>.)</p> <p>If the <em>destructor</em> argument is not <code>NULL</code>, it will be called with the capsule as its argument when it is destroyed.</p> <p>If this capsule will be stored as an attribute of a module, the <em>name</em> should be specified as <code>modulename.attributename</code>. This will enable other modules to import the capsule using <a class="reference internal" href="#c.PyCapsule_Import" title="PyCapsule_Import"><code>PyCapsule_Import()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_GetPointer">
<code>void *PyCapsule_GetPointer(PyObject *capsule, const char *name)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Retrieve the <em>pointer</em> stored in the capsule. On failure, set an exception and return <code>NULL</code>.</p> <p>The <em>name</em> parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is <code>NULL</code>, the <em>name</em> passed in must also be <code>NULL</code>. Python uses the C function <code>strcmp()</code> to compare capsule names.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_GetDestructor">
<code>PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the current destructor stored in the capsule. On failure, set an exception and return <code>NULL</code>.</p> <p>It is legal for a capsule to have a <code>NULL</code> destructor. This makes a <code>NULL</code> return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code>PyCapsule_IsValid()</code></a> or <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_GetContext">
<code>void *PyCapsule_GetContext(PyObject *capsule)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the current context stored in the capsule. On failure, set an exception and return <code>NULL</code>.</p> <p>It is legal for a capsule to have a <code>NULL</code> context. This makes a <code>NULL</code> return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code>PyCapsule_IsValid()</code></a> or <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_GetName">
<code>const char *PyCapsule_GetName(PyObject *capsule)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the current name stored in the capsule. On failure, set an exception and return <code>NULL</code>.</p> <p>It is legal for a capsule to have a <code>NULL</code> name. This makes a <code>NULL</code> return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code>PyCapsule_IsValid()</code></a> or <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_Import">
<code>void *PyCapsule_Import(const char *name, int no_block)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Import a pointer to a C object from a capsule attribute in a module. The <em>name</em> parameter should specify the full name to the attribute, as in <code>module.attribute</code>. The <em>name</em> stored in the capsule must match this string exactly.</p> <p>Return the capsule’s internal <em>pointer</em> on success. On failure, set an exception and return <code>NULL</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>no_block</em> has no effect anymore.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_IsValid">
<code>int PyCapsule_IsValid(PyObject *capsule, const char *name)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Determines whether or not <em>capsule</em> is a valid capsule. A valid capsule is non-<code>NULL</code>, passes <a class="reference internal" href="#c.PyCapsule_CheckExact" title="PyCapsule_CheckExact"><code>PyCapsule_CheckExact()</code></a>, has a non-<code>NULL</code> pointer stored in it, and its internal name matches the <em>name</em> parameter. (See <a class="reference internal" href="#c.PyCapsule_GetPointer" title="PyCapsule_GetPointer"><code>PyCapsule_GetPointer()</code></a> for information on how capsule names are compared.)</p> <p>In other words, if <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code>PyCapsule_IsValid()</code></a> returns a true value, calls to any of the accessors (any function starting with <code>PyCapsule_Get</code>) are guaranteed to succeed.</p> <p>Return a nonzero value if the object is valid and matches the name passed in. Return <code>0</code> otherwise. This function will not fail.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_SetContext">
<code>int PyCapsule_SetContext(PyObject *capsule, void *context)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the context pointer inside <em>capsule</em> to <em>context</em>.</p> <p>Return <code>0</code> on success. Return nonzero and set an exception on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_SetDestructor">
<code>int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the destructor inside <em>capsule</em> to <em>destructor</em>.</p> <p>Return <code>0</code> on success. Return nonzero and set an exception on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_SetName">
<code>int PyCapsule_SetName(PyObject *capsule, const char *name)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the name inside <em>capsule</em> to <em>name</em>. If non-<code>NULL</code>, the name must outlive the capsule. If the previous <em>name</em> stored in the capsule was not <code>NULL</code>, no attempt is made to free it.</p> <p>Return <code>0</code> on success. Return nonzero and set an exception on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyCapsule_SetPointer">
<code>int PyCapsule_SetPointer(PyObject *capsule, void *pointer)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the void pointer inside <em>capsule</em> to <em>pointer</em>. The pointer may not be <code>NULL</code>.</p> <p>Return <code>0</code> on success. Return nonzero and set an exception on failure.</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/capsule.html" class="_attribution-link">https://docs.python.org/3.12/c-api/capsule.html</a>
  </p>
</div>