Auto Generated Documentation
This commit is contained in:
github-actions[bot]
@@ -0,0 +1,287 @@
|
||||
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Marker type that indicates that the GIL is currently held."><meta name="keywords" content="rust, rustlang, rust-lang, Python"><title>pyo3::prelude::Python - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../../ayu.css" disabled ><script id="default-settings"></script><script src="../../storage.js"></script><script src="../../crates.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="icon" type="image/svg+xml" href="../../favicon.svg">
|
||||
<link rel="alternate icon" type="image/png" href="../../favicon-16x16.png">
|
||||
<link rel="alternate icon" type="image/png" href="../../favicon-32x32.png"><style type="text/css">#crate-search{background-image:url("../../down-arrow.svg");}</style></head><body class="rustdoc struct"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu" role="button">☰</div><a href='../../pyo3/index.html'><div class='logo-container rust-logo'><img src='../../rust-logo.png' alt='logo'></div></a><p class="location">Struct Python</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#implementations">Methods</a><div class="sidebar-links"><a href="#method.None">None</a><a href="#method.NotImplemented">NotImplemented</a><a href="#method.acquire_gil">acquire_gil</a><a href="#method.allow_threads">allow_threads</a><a href="#method.assume_gil_acquired">assume_gil_acquired</a><a href="#method.cast_as">cast_as</a><a href="#method.check_signals">check_signals</a><a href="#method.checked_cast_as">checked_cast_as</a><a href="#method.eval">eval</a><a href="#method.from_borrowed_ptr">from_borrowed_ptr</a><a href="#method.from_borrowed_ptr_or_err">from_borrowed_ptr_or_err</a><a href="#method.from_borrowed_ptr_or_opt">from_borrowed_ptr_or_opt</a><a href="#method.from_owned_ptr">from_owned_ptr</a><a href="#method.from_owned_ptr_or_err">from_owned_ptr_or_err</a><a href="#method.from_owned_ptr_or_opt">from_owned_ptr_or_opt</a><a href="#method.get_type">get_type</a><a href="#method.import">import</a><a href="#method.is_instance">is_instance</a><a href="#method.is_subclass">is_subclass</a><a href="#method.new_pool">new_pool</a><a href="#method.release">release</a><a href="#method.run">run</a><a href="#method.version">version</a><a href="#method.version_info">version_info</a><a href="#method.with_gil">with_gil</a><a href="#method.xdecref">xdecref</a></div><a class="sidebar-title" href="#trait-implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Clone">Clone</a><a href="#impl-Copy">Copy</a></div><a class="sidebar-title" href="#synthetic-implementations">Auto Trait Implementations</a><div class="sidebar-links"><a href="#impl-RefUnwindSafe">!RefUnwindSafe</a><a href="#impl-Send">!Send</a><a href="#impl-Sync">!Sync</a><a href="#impl-Unpin">Unpin</a><a href="#impl-UnwindSafe">!UnwindSafe</a></div><a class="sidebar-title" href="#blanket-implementations">Blanket Implementations</a><div class="sidebar-links"><a href="#impl-Any">Any</a><a href="#impl-Borrow%3CT%3E">Borrow<T></a><a href="#impl-BorrowMut%3CT%3E">BorrowMut<T></a><a href="#impl-From%3CT%3E">From<T></a><a href="#impl-Into%3CU%3E">Into<U></a><a href="#impl-ToOwned">ToOwned</a><a href="#impl-TryFrom%3CU%3E">TryFrom<U></a><a href="#impl-TryInto%3CU%3E">TryInto<U></a></div></div><p class="location"><a href="../index.html">pyo3</a>::<wbr><a href="index.html">prelude</a></p><div id="sidebar-vars" data-name="Python" data-ty="struct" data-relpath=""></div><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu"><img src="../../brush.svg" width="18" height="18" alt="Pick another theme!"></button><div id="theme-choices" role="menu"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><button type="button" class="help-button">?</button>
|
||||
<a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" height="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><span class="in-band">Struct <a href="../index.html">pyo3</a>::<wbr><a href="index.html">prelude</a>::<wbr><a class="struct" href="">Python</a></span><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span><a class="srclink" href="../../src/pyo3/python.rs.html#129" title="goto source code">[src]</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><pre class="rust struct">pub struct Python<'p>(_);</pre></div><div class="docblock"><p>Marker type that indicates that the GIL is currently held.</p>
|
||||
<p>The <code>Python</code> struct is a zero-sized marker struct that is required for most Python operations.
|
||||
This is used to indicate that the operation accesses/modifies the Python interpreter state,
|
||||
and thus can only be called if the Python interpreter is initialized and the
|
||||
Python global interpreter lock (GIL) is acquired. The lifetime <code>'p</code> represents the lifetime of
|
||||
holding the lock.</p>
|
||||
<p>Note that the GIL can be temporarily released by the Python interpreter during a function call
|
||||
(e.g. importing a module), even when you’re holding a GILGuard. In general, you don’t need to
|
||||
worry about this because the GIL is reacquired before returning to the Rust code:</p>
|
||||
<pre><code class="language-text">`Python` exists |=====================================|
|
||||
GIL actually held |==========| |================|
|
||||
Rust code running |=======| |==| |======|
|
||||
</code></pre>
|
||||
<p>This behaviour can cause deadlocks when trying to lock a Rust mutex while
|
||||
holding the GIL:</p>
|
||||
<ul>
|
||||
<li>Thread 1 acquires the GIL</li>
|
||||
<li>Thread 1 locks a mutex</li>
|
||||
<li>Thread 1 makes a call into the Python interpreter which releases the GIL</li>
|
||||
<li>Thread 2 acquires the GIL</li>
|
||||
<li>Thread 2 tries to locks the mutex, blocks</li>
|
||||
<li>Thread 1’s Python interpreter call blocks trying to reacquire the GIL held by thread 2</li>
|
||||
</ul>
|
||||
<p>To avoid deadlocking, you should release the GIL before trying to lock a mutex, e.g. with
|
||||
<a href="../../pyo3/prelude/struct.Python.html#method.allow_threads" title="Python::allow_threads">Python::allow_threads</a>.</p>
|
||||
</div><h2 id="implementations" class="small-section-header">Implementations<a href="#implementations" class="anchor"></a></h2><h3 id="impl" class="impl"><code class="in-band">impl <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'_></code><a href="#impl" class="anchor"></a><a class="srclink" href="../../src/pyo3/python.rs.html#131-159" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.with_gil" class="method"><code>pub fn <a href="#method.with_gil" class="fnname">with_gil</a><F, R>(f: F) -> R <span class="where fmt-newline">where<br> F: for<'p> <a class="trait" href="https://doc.rust-lang.org/nightly/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>(<a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p>) -> R, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#153-158" title="goto source code">[src]</a></h4><div class="docblock"><p>Acquires the global interpreter lock, which allows access to the Python runtime. The
|
||||
provided closure F will be executed with the acquired <code>Python</code> marker token.</p>
|
||||
<p>If the <code>auto-initialize</code> feature is enabled and the Python runtime is not already
|
||||
initialized, this function will initialize it. See
|
||||
<a href="fn.prepare_freethreaded_python.html">prepare_freethreaded_python()</a> for details.</p>
|
||||
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
|
||||
<ul>
|
||||
<li>If the <code>auto-initialize</code> feature is not enabled and the Python interpreter is not
|
||||
initialized.</li>
|
||||
</ul>
|
||||
<h1 id="example" class="section-header"><a href="#example">Example</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pyo3</span>::<span class="ident">prelude</span>::<span class="kw-2">*</span>;
|
||||
<span class="ident">Python</span>::<span class="ident">with_gil</span>(<span class="op">|</span><span class="ident">py</span><span class="op">|</span> <span class="op">-</span><span class="op">></span> <span class="ident">PyResult</span><span class="op"><</span>()<span class="op">></span> {
|
||||
<span class="kw">let</span> <span class="ident">x</span>: <span class="ident">i32</span> <span class="op">=</span> <span class="ident">py</span>.<span class="ident">eval</span>(<span class="string">"5"</span>, <span class="prelude-val">None</span>, <span class="prelude-val">None</span>)<span class="question-mark">?</span>.<span class="ident">extract</span>()<span class="question-mark">?</span>;
|
||||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">x</span>, <span class="number">5</span>);
|
||||
<span class="prelude-val">Ok</span>(())
|
||||
});</pre></div>
|
||||
</div></div><h3 id="impl-1" class="impl"><code class="in-band">impl<'p> <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-1" class="anchor"></a><a class="srclink" href="../../src/pyo3/python.rs.html#161-689" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.acquire_gil" class="method"><code>pub fn <a href="#method.acquire_gil" class="fnname">acquire_gil</a>() -> <a class="struct" href="../../pyo3/prelude/struct.GILGuard.html" title="struct pyo3::prelude::GILGuard">GILGuard</a></code><a class="srclink" href="../../src/pyo3/python.rs.html#184-186" title="goto source code">[src]</a></h4><div class="docblock"><p>Acquires the global interpreter lock, which allows access to the Python runtime.</p>
|
||||
<p>If the <code>auto-initialize</code> feature is enabled and the Python runtime is not already
|
||||
initialized, this function will initialize it. See
|
||||
<a href="fn.prepare_freethreaded_python.html">prepare_freethreaded_python()</a> for details.</p>
|
||||
<p>Most users should not need to use this API directly, and should prefer one of two options:</p>
|
||||
<ol>
|
||||
<li>When implementing <code>#[pymethods]</code> or <code>#[pyfunction]</code> add a function argument
|
||||
<code>py: Python</code> to receive access to the GIL context in which the function is running.</li>
|
||||
<li>Use <a href="#method.with_gil"><code>Python::with_gil</code></a> to run a closure with the GIL, acquiring
|
||||
only if needed.</li>
|
||||
</ol>
|
||||
<p><strong>Note:</strong> This return type from this function, <code>GILGuard</code>, is implemented as a RAII guard
|
||||
around the C-API Python_EnsureGIL. This means that multiple <code>acquire_gil()</code> calls are
|
||||
allowed, and will not deadlock. However, <code>GILGuard</code>s must be dropped in the reverse order
|
||||
to acquisition. If PyO3 detects this order is not maintained, it may be forced to begin
|
||||
an irrecoverable panic.</p>
|
||||
<h1 id="panics-1" class="section-header"><a href="#panics-1">Panics</a></h1>
|
||||
<ul>
|
||||
<li>If the <code>auto-initialize</code> feature is not enabled and the Python interpreter is not
|
||||
initialized.</li>
|
||||
</ul>
|
||||
</div><h4 id="method.allow_threads" class="method"><code>pub fn <a href="#method.allow_threads" class="fnname">allow_threads</a><T, F>(self, f: F) -> T <span class="where fmt-newline">where<br> F: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> + <a class="trait" href="https://doc.rust-lang.org/nightly/core/ops/function/trait.FnOnce.html" title="trait core::ops::function::FnOnce">FnOnce</a>() -> T,<br> T: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#248-273" title="goto source code">[src]</a></h4><div class="docblock"><p>Temporarily releases the <code>GIL</code>, thus allowing other Python threads to run.</p>
|
||||
<h1 id="example-1" class="section-header"><a href="#example-1">Example</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pyo3</span>::<span class="ident">exceptions</span>::<span class="ident">PyRuntimeError</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">sync</span>::<span class="ident">Arc</span>;
|
||||
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
|
||||
<span class="attribute">#[<span class="ident">pyfunction</span>]</span>
|
||||
<span class="kw">fn</span> <span class="ident">parallel_count</span>(<span class="ident">py</span>: <span class="ident">Python</span><span class="op"><</span><span class="lifetime">'_</span><span class="op">></span>, <span class="ident">strings</span>: <span class="ident">Vec</span><span class="op"><</span><span class="ident">String</span><span class="op">></span>, <span class="ident">query</span>: <span class="ident">String</span>) <span class="op">-</span><span class="op">></span> <span class="ident">PyResult</span><span class="op"><</span><span class="ident">usize</span><span class="op">></span> {
|
||||
<span class="kw">let</span> <span class="ident">query</span> <span class="op">=</span> <span class="ident">query</span>.<span class="ident">chars</span>().<span class="ident">next</span>().<span class="ident">unwrap</span>();
|
||||
<span class="ident">py</span>.<span class="ident">allow_threads</span>(<span class="kw">move</span> <span class="op">|</span><span class="op">|</span> {
|
||||
<span class="kw">let</span> <span class="ident">threads</span>: <span class="ident">Vec</span><span class="op"><</span><span class="kw">_</span><span class="op">></span> <span class="op">=</span> <span class="ident">strings</span>
|
||||
.<span class="ident">into_iter</span>()
|
||||
.<span class="ident">map</span>(<span class="op">|</span><span class="ident">s</span><span class="op">|</span> <span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="kw">move</span> <span class="op">|</span><span class="op">|</span> <span class="ident">s</span>.<span class="ident">chars</span>().<span class="ident">filter</span>(<span class="op">|</span><span class="kw-2">&</span><span class="ident">c</span><span class="op">|</span> <span class="ident">c</span> <span class="op">=</span><span class="op">=</span> <span class="ident">query</span>).<span class="ident">count</span>()))
|
||||
.<span class="ident">collect</span>();
|
||||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">sum</span> <span class="op">=</span> <span class="number">0</span>;
|
||||
<span class="kw">for</span> <span class="ident">t</span> <span class="kw">in</span> <span class="ident">threads</span> {
|
||||
<span class="ident">sum</span> <span class="op">+</span><span class="op">=</span> <span class="ident">t</span>.<span class="ident">join</span>().<span class="ident">map_err</span>(<span class="op">|</span><span class="kw">_</span><span class="op">|</span> <span class="ident">PyRuntimeError</span>::<span class="ident">new_err</span>(()))<span class="question-mark">?</span>;
|
||||
}
|
||||
<span class="prelude-val">Ok</span>(<span class="ident">sum</span>)
|
||||
})
|
||||
}
|
||||
<span class="kw">let</span> <span class="ident">gil</span> <span class="op">=</span> <span class="ident">Python</span>::<span class="ident">acquire_gil</span>();
|
||||
<span class="kw">let</span> <span class="ident">py</span> <span class="op">=</span> <span class="ident">gil</span>.<span class="ident">python</span>();
|
||||
<span class="kw">let</span> <span class="ident">m</span> <span class="op">=</span> <span class="ident">PyModule</span>::<span class="ident">new</span>(<span class="ident">py</span>, <span class="string">"pcount"</span>).<span class="ident">unwrap</span>();
|
||||
<span class="ident">m</span>.<span class="ident">add_function</span>(<span class="macro">wrap_pyfunction</span><span class="macro">!</span>(<span class="ident">parallel_count</span>, <span class="ident">m</span>).<span class="ident">unwrap</span>()).<span class="ident">unwrap</span>();
|
||||
<span class="kw">let</span> <span class="ident">locals</span> <span class="op">=</span> [(<span class="string">"pcount"</span>, <span class="ident">m</span>)].<span class="ident">into_py_dict</span>(<span class="ident">py</span>);
|
||||
<span class="ident">py</span>.<span class="ident">run</span>(<span class="string">r#"
|
||||
s = ["Flow", "my", "tears", "the", "Policeman", "Said"]
|
||||
assert pcount.parallel_count(s, "a") == 3
|
||||
"#</span>, <span class="prelude-val">None</span>, <span class="prelude-val">Some</span>(<span class="ident">locals</span>));</pre></div>
|
||||
<p><strong>Note:</strong>
|
||||
PyO3 types that represent objects with a lifetime tied to holding the GIL
|
||||
cannot be used in the closure. This includes <code>&PyAny</code> and all the
|
||||
concrete-typed siblings, like <code>&PyString</code>.</p>
|
||||
<p>This is achieved via the <code>Send</code> bound on the closure and the return type. This is slightly
|
||||
more restrictive than necessary, but it’s the most fitting solution available in stable
|
||||
Rust. In the future this bound may be relaxed by a new “auto-trait”, if auto-traits
|
||||
become a stable feature of the Rust language.</p>
|
||||
<p>You can convert such references to e.g. <code>PyObject</code> or <code>Py<PyString></code>,
|
||||
which makes them independent of the GIL lifetime. However, you cannot
|
||||
do much with those without a <code>Python<'p></code> token, for which you’d need to
|
||||
reacquire the GIL.</p>
|
||||
<h1 id="example-2" class="section-header"><a href="#example-2">Example</a></h1>
|
||||
<div class='information'><div class='tooltip compile_fail'>ⓘ</div></div><div class="example-wrap"><pre class="rust rust-example-rendered compile_fail">
|
||||
<span class="kw">fn</span> <span class="ident">parallel_print</span>(<span class="ident">py</span>: <span class="ident">Python</span><span class="op"><</span><span class="lifetime">'_</span><span class="op">></span>) {
|
||||
<span class="kw">let</span> <span class="ident">s</span> <span class="op">=</span> <span class="ident">PyString</span>::<span class="ident">new</span>(<span class="ident">py</span>, <span class="string">"This object should not be shared >_<"</span>);
|
||||
<span class="ident">py</span>.<span class="ident">allow_threads</span>(<span class="kw">move</span> <span class="op">|</span><span class="op">|</span> {
|
||||
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{:?}"</span>, <span class="ident">s</span>); <span class="comment">// This causes a compile error.</span>
|
||||
});
|
||||
}</pre></div>
|
||||
</div><h4 id="method.eval" class="method"><code>pub fn <a href="#method.eval" class="fnname">eval</a>(<br> self, <br> code: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <br> globals: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&<a class="struct" href="../../pyo3/types/struct.PyDict.html" title="struct pyo3::types::PyDict">PyDict</a>>, <br> locals: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&<a class="struct" href="../../pyo3/types/struct.PyDict.html" title="struct pyo3::types::PyDict">PyDict</a>><br>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><&'p <a class="struct" href="../../pyo3/prelude/struct.PyAny.html" title="struct pyo3::prelude::PyAny">PyAny</a>></code><a class="srclink" href="../../src/pyo3/python.rs.html#289-296" title="goto source code">[src]</a></h4><div class="docblock"><p>Evaluates a Python expression in the given context and returns the result.</p>
|
||||
<p>If <code>globals</code> is <code>None</code>, it defaults to Python module <code>__main__</code>.
|
||||
If <code>locals</code> is <code>None</code>, it defaults to the value of <code>globals</code>.</p>
|
||||
<h1 id="example-3" class="section-header"><a href="#example-3">Example:</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">let</span> <span class="ident">result</span> <span class="op">=</span> <span class="ident">py</span>.<span class="ident">eval</span>(<span class="string">"[i * 10 for i in range(5)]"</span>, <span class="prelude-val">None</span>, <span class="prelude-val">None</span>).<span class="ident">unwrap</span>();
|
||||
<span class="kw">let</span> <span class="ident">res</span>: <span class="ident">Vec</span><span class="op"><</span><span class="ident">i64</span><span class="op">></span> <span class="op">=</span> <span class="ident">result</span>.<span class="ident">extract</span>().<span class="ident">unwrap</span>();
|
||||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">res</span>, <span class="macro">vec</span><span class="macro">!</span>[<span class="number">0</span>, <span class="number">10</span>, <span class="number">20</span>, <span class="number">30</span>, <span class="number">40</span>])</pre></div>
|
||||
</div><h4 id="method.run" class="method"><code>pub fn <a href="#method.run" class="fnname">run</a>(<br> self, <br> code: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>, <br> globals: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&<a class="struct" href="../../pyo3/types/struct.PyDict.html" title="struct pyo3::types::PyDict">PyDict</a>>, <br> locals: <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><&<a class="struct" href="../../pyo3/types/struct.PyDict.html" title="struct pyo3::types::PyDict">PyDict</a>><br>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>></code><a class="srclink" href="../../src/pyo3/python.rs.html#322-332" title="goto source code">[src]</a></h4><div class="docblock"><p>Executes one or more Python statements in the given context.</p>
|
||||
<p>If <code>globals</code> is <code>None</code>, it defaults to Python module <code>__main__</code>.
|
||||
If <code>locals</code> is <code>None</code>, it defaults to the value of <code>globals</code>.</p>
|
||||
<h1 id="example-4" class="section-header"><a href="#example-4">Example:</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">use</span> <span class="ident">pyo3</span>::{<span class="ident">types</span>::{<span class="ident">PyBytes</span>, <span class="ident">PyDict</span>}, <span class="ident">prelude</span>::<span class="kw-2">*</span>};
|
||||
<span class="kw">let</span> <span class="ident">gil</span> <span class="op">=</span> <span class="ident">pyo3</span>::<span class="ident">Python</span>::<span class="ident">acquire_gil</span>();
|
||||
<span class="kw">let</span> <span class="ident">py</span> <span class="op">=</span> <span class="ident">gil</span>.<span class="ident">python</span>();
|
||||
<span class="kw">let</span> <span class="ident">locals</span> <span class="op">=</span> <span class="ident">PyDict</span>::<span class="ident">new</span>(<span class="ident">py</span>);
|
||||
<span class="ident">py</span>.<span class="ident">run</span>(
|
||||
<span class="string">r#"
|
||||
import base64
|
||||
s = 'Hello Rust!'
|
||||
ret = base64.b64encode(s.encode('utf-8'))
|
||||
"#</span>,
|
||||
<span class="prelude-val">None</span>,
|
||||
<span class="prelude-val">Some</span>(<span class="ident">locals</span>),
|
||||
).<span class="ident">unwrap</span>();
|
||||
<span class="kw">let</span> <span class="ident">ret</span> <span class="op">=</span> <span class="ident">locals</span>.<span class="ident">get_item</span>(<span class="string">"ret"</span>).<span class="ident">unwrap</span>();
|
||||
<span class="kw">let</span> <span class="ident">b64</span>: <span class="kw-2">&</span><span class="ident">PyBytes</span> <span class="op">=</span> <span class="ident">ret</span>.<span class="ident">downcast</span>().<span class="ident">unwrap</span>();
|
||||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">b64</span>.<span class="ident">as_bytes</span>(), <span class="string">b"SGVsbG8gUnVzdCE="</span>);</pre></div>
|
||||
</div><h4 id="method.get_type" class="method"><code>pub fn <a href="#method.get_type" class="fnname">get_type</a><T>(self) -> &'p <a class="struct" href="../../pyo3/types/struct.PyType.html" title="struct pyo3::types::PyType">PyType</a> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/type_object/trait.PyTypeObject.html" title="trait pyo3::type_object::PyTypeObject">PyTypeObject</a>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#371-376" title="goto source code">[src]</a></h4><div class="docblock"><p>Gets the Python type object for type <code>T</code>.</p>
|
||||
</div><h4 id="method.import" class="method"><code>pub fn <a href="#method.import" class="fnname">import</a>(self, name: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><&'p <a class="struct" href="../../pyo3/prelude/struct.PyModule.html" title="struct pyo3::prelude::PyModule">PyModule</a>></code><a class="srclink" href="../../src/pyo3/python.rs.html#379-381" title="goto source code">[src]</a></h4><div class="docblock"><p>Imports the Python module with the specified name.</p>
|
||||
</div><h4 id="method.None" class="method"><code>pub fn <a href="#method.None" class="fnname">None</a>(self) -> <a class="type" href="../../pyo3/prelude/type.PyObject.html" title="type pyo3::prelude::PyObject">PyObject</a></code><a class="srclink" href="../../src/pyo3/python.rs.html#386-388" title="goto source code">[src]</a></h4><div class="docblock"><p>Gets the Python builtin value <code>None</code>.</p>
|
||||
</div><h4 id="method.NotImplemented" class="method"><code>pub fn <a href="#method.NotImplemented" class="fnname">NotImplemented</a>(self) -> <a class="type" href="../../pyo3/prelude/type.PyObject.html" title="type pyo3::prelude::PyObject">PyObject</a></code><a class="srclink" href="../../src/pyo3/python.rs.html#393-395" title="goto source code">[src]</a></h4><div class="docblock"><p>Gets the Python builtin value <code>NotImplemented</code>.</p>
|
||||
</div><h4 id="method.version" class="method"><code>pub fn <a href="#method.version" class="fnname">version</a>(self) -> &'p <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a></code><a class="srclink" href="../../src/pyo3/python.rs.html#410-416" title="goto source code">[src]</a></h4><div class="docblock"><p>Gets the running Python interpreter version as a string.</p>
|
||||
<p>This is a wrapper around the ffi call Py_GetVersion.</p>
|
||||
<h1 id="example-5" class="section-header"><a href="#example-5">Example</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="ident">Python</span>::<span class="ident">with_gil</span>(<span class="op">|</span><span class="ident">py</span><span class="op">|</span> {
|
||||
<span class="comment">// The full string could be, for example:</span>
|
||||
<span class="comment">// "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"</span>
|
||||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">py</span>.<span class="ident">version</span>().<span class="ident">starts_with</span>(<span class="string">"3."</span>));
|
||||
});</pre></div>
|
||||
</div><h4 id="method.version_info" class="method"><code>pub fn <a href="#method.version_info" class="fnname">version_info</a>(self) -> <a class="struct" href="../../pyo3/struct.PythonVersionInfo.html" title="struct pyo3::PythonVersionInfo">PythonVersionInfo</a><'p></code><a class="srclink" href="../../src/pyo3/python.rs.html#430-438" title="goto source code">[src]</a></h4><div class="docblock"><p>Gets the running Python interpreter version as a struct similar to
|
||||
<code>sys.version_info</code>.</p>
|
||||
<h1 id="example-6" class="section-header"><a href="#example-6">Example</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="ident">Python</span>::<span class="ident">with_gil</span>(<span class="op">|</span><span class="ident">py</span><span class="op">|</span> {
|
||||
<span class="comment">// PyO3 supports Python 3.6 and up.</span>
|
||||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">py</span>.<span class="ident">version_info</span>() <span class="op">></span><span class="op">=</span> (<span class="number">3</span>, <span class="number">6</span>));
|
||||
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">py</span>.<span class="ident">version_info</span>() <span class="op">></span><span class="op">=</span> (<span class="number">3</span>, <span class="number">6</span>, <span class="number">0</span>));
|
||||
});</pre></div>
|
||||
</div><h4 id="method.checked_cast_as" class="method"><code>pub fn <a href="#method.checked_cast_as" class="fnname">checked_cast_as</a><T>(<br> self, <br> obj: <a class="type" href="../../pyo3/prelude/type.PyObject.html" title="type pyo3::prelude::PyObject">PyObject</a><br>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T, <a class="struct" href="../../pyo3/struct.PyDowncastError.html" title="struct pyo3::PyDowncastError">PyDowncastError</a><'p>> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.PyTryFrom.html" title="trait pyo3::conversion::PyTryFrom">PyTryFrom</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#441-447" title="goto source code">[src]</a></h4><div class="docblock"><p>Registers the object in the release pool, and tries to downcast to specific type.</p>
|
||||
</div><h4 id="method.cast_as" class="method"><code>pub unsafe fn <a href="#method.cast_as" class="fnname">cast_as</a><T>(self, obj: <a class="type" href="../../pyo3/prelude/type.PyObject.html" title="type pyo3::prelude::PyObject">PyObject</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/trait.PyNativeType.html" title="trait pyo3::PyNativeType">PyNativeType</a> + <a class="trait" href="../../pyo3/type_object/trait.PyTypeInfo.html" title="trait pyo3::type_object::PyTypeInfo">PyTypeInfo</a>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#455-461" title="goto source code">[src]</a></h4><div class="docblock"><p>Registers the object in the release pool, and does an unchecked downcast
|
||||
to the specific type.</p>
|
||||
<h1 id="safety" class="section-header"><a href="#safety">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_owned_ptr" class="method"><code>pub unsafe fn <a href="#method.from_owned_ptr" class="fnname">from_owned_ptr</a><T>(self, ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#470-475" title="goto source code">[src]</a></h4><div class="docblock"><p>Registers the object pointer in the release pool,
|
||||
and does an unchecked downcast to the specific type.</p>
|
||||
<h1 id="safety-1" class="section-header"><a href="#safety-1">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_owned_ptr_or_err" class="method"><code>pub unsafe fn <a href="#method.from_owned_ptr_or_err" class="fnname">from_owned_ptr_or_err</a><T>(<br> self, <br> ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a><br>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#486-491" title="goto source code">[src]</a></h4><div class="docblock"><p>Registers the owned object pointer in the release pool.</p>
|
||||
<p>Returns <code>Err(PyErr)</code> if the pointer is NULL.
|
||||
Does an unchecked downcast to the specific type.</p>
|
||||
<h1 id="safety-2" class="section-header"><a href="#safety-2">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_owned_ptr_or_opt" class="method"><code>pub unsafe fn <a href="#method.from_owned_ptr_or_opt" class="fnname">from_owned_ptr_or_opt</a><T>(<br> self, <br> ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a><br>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#502-507" title="goto source code">[src]</a></h4><div class="docblock"><p>Registers the owned object pointer in release pool.</p>
|
||||
<p>Returns <code>None</code> if the pointer is NULL.
|
||||
Does an unchecked downcast to the specific type.</p>
|
||||
<h1 id="safety-3" class="section-header"><a href="#safety-3">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_borrowed_ptr" class="method"><code>pub unsafe fn <a href="#method.from_borrowed_ptr" class="fnname">from_borrowed_ptr</a><T>(self, ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#517-522" title="goto source code">[src]</a></h4><div class="docblock"><p>Does an unchecked downcast to the specific type.</p>
|
||||
<p>Panics if the pointer is NULL.</p>
|
||||
<h1 id="safety-4" class="section-header"><a href="#safety-4">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_borrowed_ptr_or_err" class="method"><code>pub unsafe fn <a href="#method.from_borrowed_ptr_or_err" class="fnname">from_borrowed_ptr_or_err</a><T>(<br> self, <br> ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a><br>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#532-537" title="goto source code">[src]</a></h4><div class="docblock"><p>Does an unchecked downcast to the specific type.</p>
|
||||
<p>Returns <code>Err(PyErr)</code> if the pointer is NULL.</p>
|
||||
<h1 id="safety-5" class="section-header"><a href="#safety-5">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.from_borrowed_ptr_or_opt" class="method"><code>pub unsafe fn <a href="#method.from_borrowed_ptr_or_opt" class="fnname">from_borrowed_ptr_or_opt</a><T>(<br> self, <br> ptr: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.pointer.html">*mut </a><a class="struct" href="../../pyo3/ffi/struct.PyObject.html" title="struct pyo3::ffi::PyObject">PyObject</a><br>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&'p </a>T> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.FromPyPointer.html" title="trait pyo3::conversion::FromPyPointer">FromPyPointer</a><'p>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#547-552" title="goto source code">[src]</a></h4><div class="docblock"><p>Does an unchecked downcast to the specific type.</p>
|
||||
<p>Returns <code>None</code> if the pointer is NULL.</p>
|
||||
<h1 id="safety-6" class="section-header"><a href="#safety-6">Safety</a></h1>
|
||||
<p>Callers must ensure that ensure that the cast is valid.</p>
|
||||
</div><h4 id="method.is_instance" class="method"><code>pub fn <a href="#method.is_instance" class="fnname">is_instance</a><T: <a class="trait" href="../../pyo3/type_object/trait.PyTypeObject.html" title="trait pyo3::type_object::PyTypeObject">PyTypeObject</a>, V: <a class="trait" href="../../pyo3/conversion/trait.AsPyPointer.html" title="trait pyo3::conversion::AsPyPointer">AsPyPointer</a>>(<br> self, <br> obj: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>V<br>) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>></code><a class="srclink" href="../../src/pyo3/python.rs.html#558-560" title="goto source code">[src]</a></h4><div class="item-info"><div class="stab deprecated"><span class="emoji">👎</span> Deprecated since 0.13.0: <p>Please use obj.is_instance::<T>() instead</p>
|
||||
</div></div><div class="docblock"><p>Checks whether <code>obj</code> is an instance of type <code>T</code>.</p>
|
||||
<p>This is equivalent to the Python <code>isinstance</code> function.</p>
|
||||
</div><h4 id="method.is_subclass" class="method"><code>pub fn <a href="#method.is_subclass" class="fnname">is_subclass</a><T, U>(self) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a>> <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/type_object/trait.PyTypeObject.html" title="trait pyo3::type_object::PyTypeObject">PyTypeObject</a>,<br> U: <a class="trait" href="../../pyo3/type_object/trait.PyTypeObject.html" title="trait pyo3::type_object::PyTypeObject">PyTypeObject</a>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#569-575" title="goto source code">[src]</a></h4><div class="item-info"><div class="stab deprecated"><span class="emoji">👎</span> Deprecated since 0.13.0: <p>Please use T::type_object(py).is_subclass::<U>() instead</p>
|
||||
</div></div><div class="docblock"><p>Checks whether type <code>T</code> is subclass of type <code>U</code>.</p>
|
||||
<p>This is equivalent to the Python <code>issubclass</code> function.</p>
|
||||
</div><h4 id="method.release" class="method"><code>pub fn <a href="#method.release" class="fnname">release</a><T>(self, ob: T) <span class="where fmt-newline">where<br> T: <a class="trait" href="../../pyo3/conversion/trait.IntoPyPointer.html" title="trait pyo3::conversion::IntoPyPointer">IntoPyPointer</a>, </span></code><a class="srclink" href="../../src/pyo3/python.rs.html#580-590" title="goto source code">[src]</a></h4><div class="item-info"><div class="stab deprecated"><span class="emoji">👎</span> Deprecated since 0.13.0: <p>Please just drop ob instead</p>
|
||||
</div></div><div class="docblock"><p>Releases a PyObject reference.</p>
|
||||
</div><h4 id="method.xdecref" class="method"><code>pub fn <a href="#method.xdecref" class="fnname">xdecref</a><T: <a class="trait" href="../../pyo3/conversion/trait.IntoPyPointer.html" title="trait pyo3::conversion::IntoPyPointer">IntoPyPointer</a>>(self, ptr: T)</code><a class="srclink" href="../../src/pyo3/python.rs.html#595-597" title="goto source code">[src]</a></h4><div class="item-info"><div class="stab deprecated"><span class="emoji">👎</span> Deprecated since 0.13.0: <p>Please just drop obj instead</p>
|
||||
</div></div><div class="docblock"><p>Releases a <code>ffi::PyObject</code> pointer.</p>
|
||||
</div><h4 id="method.check_signals" class="method"><code>pub fn <a href="#method.check_signals" class="fnname">check_signals</a>(self) -> <a class="type" href="../../pyo3/prelude/type.PyResult.html" title="type pyo3::prelude::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>></code><a class="srclink" href="../../src/pyo3/python.rs.html#610-617" title="goto source code">[src]</a></h4><div class="docblock"><p>Lets the Python interpreter check for pending signals and invoke the
|
||||
corresponding signal handlers. This can run arbitrary Python code.</p>
|
||||
<p>If an exception is raised by the signal handler, or the default signal
|
||||
handler raises an exception (such as <code>KeyboardInterrupt</code> for <code>SIGINT</code>),
|
||||
an <code>Err</code> is returned.</p>
|
||||
<p>This is a wrapper of the C function <code>PyErr_CheckSignals()</code>. It is good
|
||||
practice to call this regularly in a long-running calculation since
|
||||
SIGINT and other signals handled by Python code are left pending for its
|
||||
entire duration.</p>
|
||||
</div><h4 id="method.assume_gil_acquired" class="method"><code>pub unsafe fn <a href="#method.assume_gil_acquired" class="fnname">assume_gil_acquired</a>() -> <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a class="srclink" href="../../src/pyo3/python.rs.html#630-632" title="goto source code">[src]</a></h4><div class="docblock"><p>Retrieves a Python instance under the assumption that the GIL is already
|
||||
acquired at this point, and stays acquired for the lifetime <code>'p</code>.</p>
|
||||
<p>Because the output lifetime <code>'p</code> is not connected to any input parameter,
|
||||
care must be taken that the compiler infers an appropriate lifetime for <code>'p</code>
|
||||
when calling this function.</p>
|
||||
<h1 id="safety-7" class="section-header"><a href="#safety-7">Safety</a></h1>
|
||||
<p>The lifetime <code>'p</code> must be shorter than the period you <em>assume</em> that you have GIL.
|
||||
I.e., <code>Python<'static></code> is always <em>really</em> unsafe.</p>
|
||||
</div><h4 id="method.new_pool" class="method"><code>pub unsafe fn <a href="#method.new_pool" class="fnname">new_pool</a>(self) -> <a class="struct" href="../../pyo3/struct.GILPool.html" title="struct pyo3::GILPool">GILPool</a></code><a class="srclink" href="../../src/pyo3/python.rs.html#686-688" title="goto source code">[src]</a></h4><div class="docblock"><p>Create a new pool for managing PyO3’s owned references.</p>
|
||||
<p>When this <code>GILPool</code> is dropped, all PyO3 owned references created after this <code>GILPool</code> will
|
||||
all have their Python reference counts decremented, potentially allowing Python to drop
|
||||
the corresponding Python objects.</p>
|
||||
<p>Typical usage of PyO3 will not need this API, as <code>Python::acquire_gil</code> automatically
|
||||
creates a <code>GILPool</code> where appropriate.</p>
|
||||
<p>Advanced uses of PyO3 which perform long-running tasks which never free the GIL may need
|
||||
to use this API to clear memory, as PyO3 usually does not clear memory until the GIL is
|
||||
released.</p>
|
||||
<h1 id="example-7" class="section-header"><a href="#example-7">Example</a></h1>
|
||||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||||
<span class="kw">let</span> <span class="ident">gil</span> <span class="op">=</span> <span class="ident">Python</span>::<span class="ident">acquire_gil</span>();
|
||||
<span class="kw">let</span> <span class="ident">py</span> <span class="op">=</span> <span class="ident">gil</span>.<span class="ident">python</span>();
|
||||
|
||||
<span class="comment">// Some long-running process like a webserver, which never releases the GIL.</span>
|
||||
<span class="kw">loop</span> {
|
||||
<span class="comment">// Create a new pool, so that PyO3 can clear memory at the end of the loop.</span>
|
||||
<span class="kw">let</span> <span class="ident">pool</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="ident">py</span>.<span class="ident">new_pool</span>() };
|
||||
|
||||
<span class="comment">// It is recommended to *always* immediately set py to the pool's Python, to help</span>
|
||||
<span class="comment">// avoid creating references with invalid lifetimes.</span>
|
||||
<span class="kw">let</span> <span class="ident">py</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="ident">pool</span>.<span class="ident">python</span>() };
|
||||
|
||||
<span class="comment">// do stuff...</span>
|
||||
}</pre></div>
|
||||
<h1 id="safety-8" class="section-header"><a href="#safety-8">Safety</a></h1>
|
||||
<p>Extreme care must be taken when using this API, as misuse can lead to accessing invalid
|
||||
memory. In addition, the caller is responsible for guaranteeing that the GIL remains held
|
||||
for the entire lifetime of the returned <code>GILPool</code>.</p>
|
||||
<p>Two best practices are required when using this API:</p>
|
||||
<ul>
|
||||
<li>From the moment <code>new_pool()</code> is called, only the <code>Python</code> token from the returned
|
||||
<code>GILPool</code> (accessible using <code>.python()</code>) should be used in PyO3 APIs. All other older
|
||||
<code>Python</code> tokens with longer lifetimes are unsafe to use until the <code>GILPool</code> is dropped,
|
||||
because they can be used to create PyO3 owned references which have lifetimes which
|
||||
outlive the <code>GILPool</code>.</li>
|
||||
<li>Similarly, methods on existing owned references will implicitly refer back to the
|
||||
<code>Python</code> token which that reference was originally created with. If the returned values
|
||||
from these methods are owned references they will inherit the same lifetime. As a result,
|
||||
Rust’s lifetime rules may allow them to outlive the <code>GILPool</code>, even though this is not
|
||||
safe for reasons discussed above. Care must be taken to never access these return values
|
||||
after the <code>GILPool</code> is dropped, unless they are converted to <code>Py<T></code> <em>before</em> the pool
|
||||
is dropped.</li>
|
||||
</ul>
|
||||
</div></div><h2 id="trait-implementations" class="small-section-header">Trait Implementations<a href="#trait-implementations" class="anchor"></a></h2><div id="trait-implementations-list"><h3 id="impl-Clone" class="impl"><code class="in-band">impl<'p> <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-Clone" class="anchor"></a><a class="srclink" href="../../src/pyo3/python.rs.html#128" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.clone" class="method hidden"><code>fn <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone" class="fnname">clone</a>(&self) -> <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a class="srclink" href="../../src/pyo3/python.rs.html#128" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Returns a copy of the value. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone">Read more</a></p>
|
||||
</div><h4 id="method.clone_from" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from" class="fnname">clone_from</a>(&mut self, source: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>Self)</code><span class="since" title="Stable since Rust version 1.0.0">1.0.0</span><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/clone.rs.html#130" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs copy-assignment from <code>source</code>. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from">Read more</a></p>
|
||||
</div></div><h3 id="impl-Copy" class="impl"><code class="in-band">impl<'p> <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Copy.html" title="trait core::marker::Copy">Copy</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-Copy" class="anchor"></a><a class="srclink" href="../../src/pyo3/python.rs.html#128" title="goto source code">[src]</a></h3><div class="impl-items"></div></div><h2 id="synthetic-implementations" class="small-section-header">Auto Trait Implementations<a href="#synthetic-implementations" class="anchor"></a></h2><div id="synthetic-implementations-list"><h3 id="impl-RefUnwindSafe" class="impl"><code class="in-band">impl<'p> !<a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.RefUnwindSafe.html" title="trait std::panic::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-RefUnwindSafe" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Send" class="impl"><code class="in-band">impl<'p> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-Send" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Sync" class="impl"><code class="in-band">impl<'p> !<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-Sync" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-Unpin" class="impl"><code class="in-band">impl<'p> <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-Unpin" class="anchor"></a></h3><div class="impl-items"></div><h3 id="impl-UnwindSafe" class="impl"><code class="in-band">impl<'p> !<a class="trait" href="https://doc.rust-lang.org/nightly/std/panic/trait.UnwindSafe.html" title="trait std::panic::UnwindSafe">UnwindSafe</a> for <a class="struct" href="../../pyo3/prelude/struct.Python.html" title="struct pyo3::prelude::Python">Python</a><'p></code><a href="#impl-UnwindSafe" class="anchor"></a></h3><div class="impl-items"></div></div><h2 id="blanket-implementations" class="small-section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor"></a></h2><div id="blanket-implementations-list"><h3 id="impl-Any" class="impl"><code class="in-band">impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html" title="trait core::any::Any">Any</a> for T <span class="where fmt-newline">where<br> T: 'static + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href="#impl-Any" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#131-135" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.type_id" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id" class="fnname">type_id</a>(&self) -> <a class="struct" href="https://doc.rust-lang.org/nightly/core/any/struct.TypeId.html" title="struct core::any::TypeId">TypeId</a></code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/any.rs.html#132" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Gets the <code>TypeId</code> of <code>self</code>. <a href="https://doc.rust-lang.org/nightly/core/any/trait.Any.html#tymethod.type_id">Read more</a></p>
|
||||
</div></div><h3 id="impl-Borrow%3CT%3E" class="impl"><code class="in-band">impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a><T> for T <span class="where fmt-newline">where<br> T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href="#impl-Borrow%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#208-213" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.borrow" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow" class="fnname">borrow</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&</a>T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#210" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></p>
|
||||
</div></div><h3 id="impl-BorrowMut%3CT%3E" class="impl"><code class="in-band">impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a><T> for T <span class="where fmt-newline">where<br> T: ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>, </span></code><a href="#impl-BorrowMut%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#216-220" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.borrow_mut" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut" class="fnname">borrow_mut</a>(&mut self) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut </a>T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/borrow.rs.html#217" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Mutably borrows from an owned value. <a href="https://doc.rust-lang.org/nightly/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut">Read more</a></p>
|
||||
</div></div><h3 id="impl-From%3CT%3E" class="impl"><code class="in-band">impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a><T> for T</code><a href="#impl-From%3CT%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#544-548" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.from" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html#tymethod.from" class="fnname">from</a>(t: T) -> T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#545" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||||
</div></div><h3 id="impl-Into%3CU%3E" class="impl"><code class="in-band">impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.From.html" title="trait core::convert::From">From</a><T>, </span></code><a href="#impl-Into%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#533-540" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="method.into" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html#tymethod.into" class="fnname">into</a>(self) -> U</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#537" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||||
</div></div><h3 id="impl-ToOwned" class="impl"><code class="in-band">impl<T> <a class="trait" href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html" title="trait alloc::borrow::ToOwned">ToOwned</a> for T <span class="where fmt-newline">where<br> T: <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a>, </span></code><a href="#impl-ToOwned" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#81-93" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="associatedtype.Owned" class="type"><code>type <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#associatedtype.Owned" class="type">Owned</a> = T</code></h4><div class='docblock'><p>The resulting type after obtaining ownership.</p>
|
||||
</div><h4 id="method.to_owned" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#tymethod.to_owned" class="fnname">to_owned</a>(&self) -> T</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#86" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Creates owned data from borrowed data, usually by cloning. <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#tymethod.to_owned">Read more</a></p>
|
||||
</div><h4 id="method.clone_into" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#method.clone_into" class="fnname">clone_into</a>(&self, target: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut </a>T)</code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/alloc/borrow.rs.html#90" title="goto source code">[src]</a></h4><div class="item-info hidden"><div class="stab unstable"><details><summary><span class="emoji">🔬</span> This is a nightly-only experimental API. (<code>toowned_clone_into</code>)</summary><p>recently added</p>
|
||||
</details></div></div><div class='docblock hidden'><p>Uses borrowed data to replace owned data, usually by cloning. <a href="https://doc.rust-lang.org/nightly/alloc/borrow/trait.ToOwned.html#method.clone_into">Read more</a></p>
|
||||
</div></div><h3 id="impl-TryFrom%3CU%3E" class="impl"><code class="in-band">impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a><T>, </span></code><a href="#impl-TryFrom%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#581-590" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="associatedtype.Error" class="type"><code>type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" class="type">Error</a> = <a class="enum" href="https://doc.rust-lang.org/nightly/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
|
||||
</div><h4 id="method.try_from" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#tymethod.try_from" class="fnname">try_from</a>(value: U) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><T, <T as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><U>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#587" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||||
</div></div><h3 id="impl-TryInto%3CU%3E" class="impl"><code class="in-band">impl<T, U> <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a><U> for T <span class="where fmt-newline">where<br> U: <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>, </span></code><a href="#impl-TryInto%3CU%3E" class="anchor"></a><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#567-576" title="goto source code">[src]</a></h3><div class="impl-items"><h4 id="associatedtype.Error-1" class="type"><code>type <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#associatedtype.Error" class="type">Error</a> = <U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></code></h4><div class='docblock'><p>The type returned in the event of a conversion error.</p>
|
||||
</div><h4 id="method.try_into" class="method hidden"><code>pub fn <a href="https://doc.rust-lang.org/nightly/core/convert/trait.TryInto.html#tymethod.try_into" class="fnname">try_into</a>(self) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><U, <U as <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a><T>>::<a class="type" href="https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>></code><a class="srclink" href="https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#573" title="goto source code">[src]</a></h4><div class='docblock hidden'><p>Performs the conversion.</p>
|
||||
</div></div></div></section><section id="search" class="content hidden"></section><section class="footer"></section><div id="rustdoc-vars" data-root-path="../../" data-current-crate="pyo3" data-search-js="../../search-index.js"></div>
|
||||
<script src="../../main.js"></script></body></html>
|
||||
Reference in New Issue
Block a user