1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml">
7
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
<title>Capsules — Python 2.7.12 documentation</title>
11
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
12
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
14
<script type="text/javascript">
15
var DOCUMENTATION_OPTIONS = {
18
COLLAPSE_INDEX: false,
23
<script type="text/javascript" src="../_static/jquery.js"></script>
24
<script type="text/javascript" src="../_static/underscore.js"></script>
25
<script type="text/javascript" src="../_static/doctools.js"></script>
26
<script type="text/javascript" src="../_static/sidebar.js"></script>
27
<link rel="search" type="application/opensearchdescription+xml"
28
title="Search within Python 2.7.12 documentation"
29
href="../_static/opensearch.xml"/>
30
<link rel="author" title="About these documents" href="../about.html" />
31
<link rel="copyright" title="Copyright" href="../copyright.html" />
32
<link rel="top" title="Python 2.7.12 documentation" href="../contents.html" />
33
<link rel="up" title="Concrete Objects Layer" href="concrete.html" />
34
<link rel="next" title="CObjects" href="cobject.html" />
35
<link rel="prev" title="Weak Reference Objects" href="weakref.html" />
36
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
37
<script type="text/javascript" src="../_static/copybutton.js"></script>
38
<script type="text/javascript" src="../_static/version_switch.js"></script>
43
<body role="document">
44
<div class="related" role="navigation" aria-label="related navigation">
47
<li class="right" style="margin-right: 10px">
48
<a href="../genindex.html" title="General Index"
49
accesskey="I">index</a></li>
51
<a href="../py-modindex.html" title="Python Module Index"
54
<a href="cobject.html" title="CObjects"
55
accesskey="N">next</a> |</li>
57
<a href="weakref.html" title="Weak Reference Objects"
58
accesskey="P">previous</a> |</li>
59
<li><img src="../_static/py.png" alt=""
60
style="vertical-align: middle; margin-top: -1px"/></li>
61
<li><a href="https://www.python.org/">Python</a> »</li>
63
<span class="version_switcher_placeholder">2.7.12</span>
64
<a href="../index.html">Documentation</a> »
67
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
68
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
72
<div class="document">
73
<div class="documentwrapper">
74
<div class="bodywrapper">
75
<div class="body" role="main">
77
<div class="section" id="capsules">
78
<span id="id1"></span><h1>Capsules<a class="headerlink" href="#capsules" title="Permalink to this headline">¶</a></h1>
79
<p id="index-0">Refer to <a class="reference internal" href="../extending/extending.html#using-capsules"><span>Providing a C API for an Extension Module</span></a> for more information on using these objects.</p>
82
<code class="descname">PyCapsule</code><a class="headerlink" href="#c.PyCapsule" title="Permalink to this definition">¶</a></dt>
83
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal"><span class="pre">PyObject</span></code></a> represents an opaque value, useful for C
84
extension modules who need to pass an opaque value (as a <code class="xref c c-type docutils literal"><span class="pre">void*</span></code>
85
pointer) through Python code to other C code. It is often used to make a C
86
function pointer defined in one module available to other modules, so the
87
regular import mechanism can be used to access C APIs defined in dynamically
92
<dt id="c.PyCapsule_Destructor">
93
<code class="descname">PyCapsule_Destructor</code><a class="headerlink" href="#c.PyCapsule_Destructor" title="Permalink to this definition">¶</a></dt>
94
<dd><p>The type of a destructor callback for a capsule. Defined as:</p>
95
<div class="highlight-c"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="n">PyCapsule_Destructor</span><span class="p">)(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">);</span>
98
<p>See <a class="reference internal" href="#c.PyCapsule_New" title="PyCapsule_New"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_New()</span></code></a> for the semantics of PyCapsule_Destructor
102
<dl class="function">
103
<dt id="c.PyCapsule_CheckExact">
104
int <code class="descname">PyCapsule_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_CheckExact" title="Permalink to this definition">¶</a></dt>
105
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code class="xref c c-type docutils literal"><span class="pre">PyCapsule</span></code></a>.</p>
108
<dl class="function">
109
<dt id="c.PyCapsule_New">
110
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCapsule_New</code><span class="sig-paren">(</span>void<em> *pointer</em>, const char<em> *name</em>, <a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a><em> destructor</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_New" title="Permalink to this definition">¶</a></dt>
111
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code class="xref c c-type docutils literal"><span class="pre">PyCapsule</span></code></a> encapsulating the <em>pointer</em>. The <em>pointer</em>
112
argument may not be <em>NULL</em>.</p>
113
<p>On failure, set an exception and return <em>NULL</em>.</p>
114
<p>The <em>name</em> string may either be <em>NULL</em> or a pointer to a valid C string. If
115
non-<em>NULL</em>, this string must outlive the capsule. (Though it is permitted to
116
free it inside the <em>destructor</em>.)</p>
117
<p>If the <em>destructor</em> argument is not <em>NULL</em>, it will be called with the
118
capsule as its argument when it is destroyed.</p>
119
<p>If this capsule will be stored as an attribute of a module, the <em>name</em> should
120
be specified as <code class="docutils literal"><span class="pre">modulename.attributename</span></code>. This will enable other modules
121
to import the capsule using <a class="reference internal" href="#c.PyCapsule_Import" title="PyCapsule_Import"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_Import()</span></code></a>.</p>
124
<dl class="function">
125
<dt id="c.PyCapsule_GetPointer">
126
void* <code class="descname">PyCapsule_GetPointer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetPointer" title="Permalink to this definition">¶</a></dt>
127
<dd><p>Retrieve the <em>pointer</em> stored in the capsule. On failure, set an exception
128
and return <em>NULL</em>.</p>
129
<p>The <em>name</em> parameter must compare exactly to the name stored in the capsule.
130
If the name stored in the capsule is <em>NULL</em>, the <em>name</em> passed in must also
131
be <em>NULL</em>. Python uses the C function <code class="xref c c-func docutils literal"><span class="pre">strcmp()</span></code> to compare capsule
135
<dl class="function">
136
<dt id="c.PyCapsule_GetDestructor">
137
<a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a> <code class="descname">PyCapsule_GetDestructor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetDestructor" title="Permalink to this definition">¶</a></dt>
138
<dd><p>Return the current destructor stored in the capsule. On failure, set an
139
exception and return <em>NULL</em>.</p>
140
<p>It is legal for a capsule to have a <em>NULL</em> destructor. This makes a <em>NULL</em>
141
return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_IsValid()</span></code></a> or
142
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
145
<dl class="function">
146
<dt id="c.PyCapsule_GetContext">
147
void* <code class="descname">PyCapsule_GetContext</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetContext" title="Permalink to this definition">¶</a></dt>
148
<dd><p>Return the current context stored in the capsule. On failure, set an
149
exception and return <em>NULL</em>.</p>
150
<p>It is legal for a capsule to have a <em>NULL</em> context. This makes a <em>NULL</em>
151
return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_IsValid()</span></code></a> or
152
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
155
<dl class="function">
156
<dt id="c.PyCapsule_GetName">
157
const char* <code class="descname">PyCapsule_GetName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetName" title="Permalink to this definition">¶</a></dt>
158
<dd><p>Return the current name stored in the capsule. On failure, set an exception
159
and return <em>NULL</em>.</p>
160
<p>It is legal for a capsule to have a <em>NULL</em> name. This makes a <em>NULL</em> return
161
code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_IsValid()</span></code></a> or
162
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
165
<dl class="function">
166
<dt id="c.PyCapsule_Import">
167
void* <code class="descname">PyCapsule_Import</code><span class="sig-paren">(</span>const char<em> *name</em>, int<em> no_block</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_Import" title="Permalink to this definition">¶</a></dt>
168
<dd><p>Import a pointer to a C object from a capsule attribute in a module. The
169
<em>name</em> parameter should specify the full name to the attribute, as in
170
<code class="docutils literal"><span class="pre">module.attribute</span></code>. The <em>name</em> stored in the capsule must match this
171
string exactly. If <em>no_block</em> is true, import the module without blocking
172
(using <a class="reference internal" href="import.html#c.PyImport_ImportModuleNoBlock" title="PyImport_ImportModuleNoBlock"><code class="xref c c-func docutils literal"><span class="pre">PyImport_ImportModuleNoBlock()</span></code></a>). If <em>no_block</em> is false,
173
import the module conventionally (using <a class="reference internal" href="import.html#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal"><span class="pre">PyImport_ImportModule()</span></code></a>).</p>
174
<p>Return the capsule’s internal <em>pointer</em> on success. On failure, set an
175
exception and return <em>NULL</em>. However, if <a class="reference internal" href="#c.PyCapsule_Import" title="PyCapsule_Import"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_Import()</span></code></a> failed to
176
import the module, and <em>no_block</em> was true, no exception is set.</p>
179
<dl class="function">
180
<dt id="c.PyCapsule_IsValid">
181
int <code class="descname">PyCapsule_IsValid</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_IsValid" title="Permalink to this definition">¶</a></dt>
182
<dd><p>Determines whether or not <em>capsule</em> is a valid capsule. A valid capsule is
183
non-<em>NULL</em>, passes <a class="reference internal" href="#c.PyCapsule_CheckExact" title="PyCapsule_CheckExact"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_CheckExact()</span></code></a>, has a non-<em>NULL</em> pointer
184
stored in it, and its internal name matches the <em>name</em> parameter. (See
185
<a class="reference internal" href="#c.PyCapsule_GetPointer" title="PyCapsule_GetPointer"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_GetPointer()</span></code></a> for information on how capsule names are
187
<p>In other words, if <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal"><span class="pre">PyCapsule_IsValid()</span></code></a> returns a true value, calls to
188
any of the accessors (any function starting with <code class="xref c c-func docutils literal"><span class="pre">PyCapsule_Get()</span></code>) are
189
guaranteed to succeed.</p>
190
<p>Return a nonzero value if the object is valid and matches the name passed in.
191
Return <code class="docutils literal"><span class="pre">0</span></code> otherwise. This function will not fail.</p>
194
<dl class="function">
195
<dt id="c.PyCapsule_SetContext">
196
int <code class="descname">PyCapsule_SetContext</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, void<em> *context</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetContext" title="Permalink to this definition">¶</a></dt>
197
<dd><p>Set the context pointer inside <em>capsule</em> to <em>context</em>.</p>
198
<p>Return <code class="docutils literal"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
201
<dl class="function">
202
<dt id="c.PyCapsule_SetDestructor">
203
int <code class="descname">PyCapsule_SetDestructor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, <a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a><em> destructor</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetDestructor" title="Permalink to this definition">¶</a></dt>
204
<dd><p>Set the destructor inside <em>capsule</em> to <em>destructor</em>.</p>
205
<p>Return <code class="docutils literal"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
208
<dl class="function">
209
<dt id="c.PyCapsule_SetName">
210
int <code class="descname">PyCapsule_SetName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetName" title="Permalink to this definition">¶</a></dt>
211
<dd><p>Set the name inside <em>capsule</em> to <em>name</em>. If non-<em>NULL</em>, the name must
212
outlive the capsule. If the previous <em>name</em> stored in the capsule was not
213
<em>NULL</em>, no attempt is made to free it.</p>
214
<p>Return <code class="docutils literal"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
217
<dl class="function">
218
<dt id="c.PyCapsule_SetPointer">
219
int <code class="descname">PyCapsule_SetPointer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, void<em> *pointer</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetPointer" title="Permalink to this definition">¶</a></dt>
220
<dd><p>Set the void pointer inside <em>capsule</em> to <em>pointer</em>. The pointer may not be
222
<p>Return <code class="docutils literal"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
231
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
232
<div class="sphinxsidebarwrapper">
233
<h4>Previous topic</h4>
234
<p class="topless"><a href="weakref.html"
235
title="previous chapter">Weak Reference Objects</a></p>
237
<p class="topless"><a href="cobject.html"
238
title="next chapter">CObjects</a></p>
240
<ul class="this-page-menu">
241
<li><a href="../bugs.html">Report a Bug</a></li>
242
<li><a href="../_sources/c-api/capsule.txt"
243
rel="nofollow">Show Source</a></li>
246
<div id="searchbox" style="display: none" role="search">
247
<h3>Quick search</h3>
248
<form class="search" action="../search.html" method="get">
249
<input type="text" name="q" />
250
<input type="submit" value="Go" />
251
<input type="hidden" name="check_keywords" value="yes" />
252
<input type="hidden" name="area" value="default" />
254
<p class="searchtip" style="font-size: 90%">
255
Enter search terms or a module, class or function name.
258
<script type="text/javascript">$('#searchbox').show(0);</script>
261
<div class="clearer"></div>
263
<div class="related" role="navigation" aria-label="related navigation">
266
<li class="right" style="margin-right: 10px">
267
<a href="../genindex.html" title="General Index"
270
<a href="../py-modindex.html" title="Python Module Index"
273
<a href="cobject.html" title="CObjects"
276
<a href="weakref.html" title="Weak Reference Objects"
278
<li><img src="../_static/py.png" alt=""
279
style="vertical-align: middle; margin-top: -1px"/></li>
280
<li><a href="https://www.python.org/">Python</a> »</li>
282
<span class="version_switcher_placeholder">2.7.12</span>
283
<a href="../index.html">Documentation</a> »
286
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
287
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
291
© <a href="../copyright.html">Copyright</a> 1990-2016, Python Software Foundation.
293
The Python Software Foundation is a non-profit corporation.
294
<a href="https://www.python.org/psf/donations/">Please donate.</a>
296
Last updated on Oct 27, 2016.
297
<a href="../bugs.html">Found a bug</a>?
299
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.
b'\\ No newline at end of file'
added
removed
python-2.7.12-docs-html/c-api/capsule.html
