pyo3/src/lib.rs

367 lines
11 KiB
Rust
Raw Normal View History

#![cfg_attr(feature = "nightly", feature(specialization))]
2020-02-08 19:24:40 +00:00
#![allow(clippy::missing_safety_doc)] // FIXME (#698)
2016-03-06 12:33:57 +00:00
2015-06-27 20:45:35 +00:00
//! Rust bindings to the Python interpreter.
2015-04-18 20:20:19 +00:00
//!
2019-02-01 13:01:18 +00:00
//! Look at [the guide](https://pyo3.rs/) for a detailed introduction.
//!
2015-04-18 22:39:04 +00:00
//! # Ownership and Lifetimes
2019-02-01 13:01:18 +00:00
//!
//! Because all Python objects potentially have multiple owners, the concept of
//! Rust mutability does not apply to Python objects. As a result, PyO3 allows
//! mutating Python objects even if they are not stored in a mutable Rust
//! variable.
//!
//! In Python, all objects are implicitly reference counted. The Python
//! interpreter uses a global interpreter lock (GIL) to ensure thread-safety.
//! Thus, we use `struct Python<'py>` as a token to indicate that
//! a function can assume that the GIL is held. In Rust, we use different types
//! to represent a reference to a Python object, depending on whether we know
//! the GIL is held, and depending on whether we know the underlying type. See
2020-03-17 09:54:51 +00:00
//! [the guide](https://pyo3.rs/master/types.html) for an explanation of
//! the different Python object types.
//!
//! A `Python` instance is either obtained explicitly by acquiring the GIL,
//! or implicitly by PyO3 when it generates the wrapper code for Rust functions
//! and structs wrapped as Python functions and objects.
2015-04-18 22:39:04 +00:00
//!
//! # Error Handling
//!
//! The vast majority of operations in this library will return `PyResult<...>`.
//! This is an alias for the type `Result<..., PyErr>`.
2015-04-18 22:39:04 +00:00
//!
2017-06-11 15:46:23 +00:00
//! A `PyErr` represents a Python exception. Errors within the `PyO3` library are
2015-06-27 20:45:35 +00:00
//! also exposed as Python exceptions.
2015-04-18 22:39:04 +00:00
//!
2015-04-18 20:20:19 +00:00
//! # Example
//!
//! ## Using Rust from Python
//!
//! PyO3 can be used to generate a native Python module.
2015-04-18 20:20:19 +00:00
//!
2019-02-01 13:01:18 +00:00
//! **`Cargo.toml`**
//!
2019-02-01 13:01:18 +00:00
//! ```toml
//! [package]
//! name = "string-sum"
//! version = "0.1.0"
//! edition = "2018"
//!
2019-02-01 13:01:18 +00:00
//! [lib]
//! name = "string_sum"
//! crate-type = ["cdylib"]
//!
2019-02-01 13:01:18 +00:00
//! [dependencies.pyo3]
2020-09-10 21:54:38 +00:00
//! version = "0.12.0"
2019-02-01 13:01:18 +00:00
//! features = ["extension-module"]
2015-04-18 20:20:19 +00:00
//! ```
2017-06-11 23:35:24 +00:00
//!
2019-02-01 13:01:18 +00:00
//! **`src/lib.rs`**
//!
//! ```rust
2018-07-03 18:42:02 +00:00
//! use pyo3::prelude::*;
2019-02-01 13:01:18 +00:00
//! use pyo3::wrap_pyfunction;
2017-06-11 23:35:24 +00:00
//!
2019-02-01 13:01:18 +00:00
//! #[pyfunction]
//! /// Formats the sum of two numbers as string.
2019-02-01 13:01:18 +00:00
//! fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
//! Ok((a + b).to_string())
//! }
//!
2019-02-01 13:01:18 +00:00
//! #[pymodule]
//! /// A Python module implemented in Rust.
2019-02-01 13:01:18 +00:00
//! fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {
//! m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
//!
2017-06-11 23:35:24 +00:00
//! Ok(())
//! }
//! ```
//!
//! On Windows and linux, you can build normally with `cargo build
//! --release`. On macOS, you need to set additional linker arguments. One
//! option is to compile with `cargo rustc --release -- -C link-arg=-undefined
//! -C link-arg=dynamic_lookup`, the other is to create a `.cargo/config` with
//! the following content:
2017-06-11 23:35:24 +00:00
//!
//! ```toml
//! [target.x86_64-apple-darwin]
//! rustflags = [
//! "-C", "link-arg=-undefined",
//! "-C", "link-arg=dynamic_lookup",
//! ]
2017-06-11 23:35:24 +00:00
//! ```
//!
//! While developing, you symlink (or copy) and rename the shared library from
//! the target folder: On macOS, rename `libstring_sum.dylib` to
//! `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd` and on
//! Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the
//! same folder and you'll be able to `import string_sum`.
2017-06-11 23:35:24 +00:00
//!
//! To build, test and publish your crate as a Python module, you can use
//! [maturin](https://github.com/PyO3/maturin) or
//! [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an
//! example for setuptools-rust in [examples/word-count](examples/word-count),
//! while maturin should work on your crate without any configuration.
2019-02-01 13:01:18 +00:00
//!
//! ## Using Python from Rust
2019-02-01 13:01:18 +00:00
//!
//! Add `pyo3` to your `Cargo.toml`:
2019-02-01 13:01:18 +00:00
//!
//! ```toml
//! [dependencies]
2020-09-10 21:54:38 +00:00
//! pyo3 = "0.12.0"
2019-02-01 13:01:18 +00:00
//! ```
//!
//! Example program displaying the value of `sys.version`:
//!
//! ```rust
//! use pyo3::prelude::*;
//! use pyo3::types::IntoPyDict;
2019-02-01 13:01:18 +00:00
//!
//! fn main() -> PyResult<()> {
//! let gil = Python::acquire_gil();
//! let py = gil.python();
//! let sys = py.import("sys")?;
//! let version: String = sys.get("version")?.extract()?;
//!
//! let locals = [("os", py.import("os")?)].into_py_dict(py);
2019-02-01 13:01:18 +00:00
//! let code = "os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'";
//! let user: String = py.eval(code, None, Some(&locals))?.extract()?;
//!
//! println!("Hello {}, I'm Python {}", user, version);
//! Ok(())
//! }
//! ```
2018-10-31 10:43:21 +00:00
pub use crate::class::*;
pub use crate::conversion::{
2020-07-21 23:02:11 +00:00
AsPyPointer, FromPyObject, FromPyPointer, IntoPy, IntoPyPointer, PyTryFrom, PyTryInto,
ToBorrowedObject, ToPyObject,
};
2020-08-25 19:33:36 +00:00
pub use crate::err::{PyDowncastError, PyErr, PyErrArguments, PyResult};
pub use crate::gil::{GILGuard, GILPool};
2020-08-09 21:47:54 +00:00
pub use crate::instance::{Py, PyNativeType, PyObject};
pub use crate::pycell::{PyCell, PyRef, PyRefMut};
2020-02-03 13:25:16 +00:00
pub use crate::pyclass::PyClass;
pub use crate::pyclass_init::PyClassInitializer;
2019-02-23 17:01:22 +00:00
pub use crate::python::{prepare_freethreaded_python, Python};
pub use crate::type_object::{type_flags, PyTypeInfo};
2020-03-18 04:31:22 +00:00
// Since PyAny is as important as PyObject, we expose it to the top level.
pub use crate::types::PyAny;
2015-03-08 14:29:44 +00:00
#[cfg(feature = "macros")]
2019-02-01 13:01:18 +00:00
#[doc(hidden)]
pub use {
ctor, // Re-exported for pyproto
indoc, // Re-exported for py_run
inventory, // Re-exported for pymethods
paste, // Re-exported for wrap_function
unindent, // Re-exported for py_run
};
// Re-exported for the `__wrap` functions
#[doc(hidden)]
pub use libc;
2019-02-01 13:01:18 +00:00
// The CPython stable ABI does not include PyBuffer.
#[cfg(not(Py_LIMITED_API))]
2018-09-21 21:32:48 +00:00
pub mod buffer;
#[doc(hidden)]
pub mod callback;
2019-03-18 10:01:55 +00:00
pub mod class;
pub mod conversion;
#1064: Comparisons with __eq__ should not raise TypeError (#1072) * Add (failing) tests for issue #1064 * Return NotImplemented when richcmp doesn't match the expected type. * Fix tests that expect TypeError when richcmp returns NotImplemented. - The python code 'class Other: pass; c2 {} Other()' was raising a NameError: c2 not found - eq and ne never raise a TypeError, so I split the those cases. * Return NotImplemented for number-like binary operations. * Add dummy impl PyNumberProtocol for the test struct. * Rework tests of NotImplemented. * Make py_ternary_num_func return NotImplemented when type mismatches. * Return NotImplement for type mismatches in binary inplace operators. * Reduce boilerplate with `extract_or_return_not_implemented!` * Extract common definition 'Other' into a function. * Test explicitly for NotImplemented in the __ipow__ test. * Add entry in CHANGELOG for PR #1072. * Add the section 'Emulating numeric types' to the guide. * Ensure we're returning NotImplemented in tests. * Simplify the tests: only test we return NotImplemented. Our previous test were rather indirect: were relying that Python behaves correctly when we return NotImplemented. Now we only test that calling a pyclass dunder method returns NotImplemented when the argument doesn't match the type signature. This is the expected behavior. * Remove reverse operators in tests of NotImplemented The won't be used because of #844. * Apply suggestions from code review Co-authored-by: Yuji Kanagawa <yuji.kngw.80s.revive@gmail.com> * Add a note about #844 below the list of reflected operations. Co-authored-by: Yuji Kanagawa <yuji.kngw.80s.revive@gmail.com>
2020-08-05 13:53:16 +00:00
#[macro_use]
2018-09-21 21:32:48 +00:00
#[doc(hidden)]
pub mod derive_utils;
mod err;
2019-02-23 17:01:22 +00:00
pub mod exceptions;
/// Raw ffi declarations for the c interface of python
#[allow(clippy::unknown_clippy_lints)]
#[allow(clippy::missing_safety_doc)]
pub mod ffi;
2018-09-21 21:32:48 +00:00
pub mod freelist;
2019-02-23 17:01:22 +00:00
mod gil;
2018-09-21 21:32:48 +00:00
mod instance;
2019-12-08 08:18:25 +00:00
#[macro_use]
mod internal_tricks;
pub mod marshal;
2020-06-14 15:29:40 +00:00
pub mod once_cell;
pub mod panic;
2018-09-21 21:32:48 +00:00
pub mod prelude;
pub mod pycell;
pub mod pyclass;
2020-01-05 07:01:05 +00:00
pub mod pyclass_init;
2019-12-08 08:18:25 +00:00
pub mod pyclass_slots;
2019-02-23 17:01:22 +00:00
mod python;
pub mod type_object;
2018-09-21 21:32:48 +00:00
pub mod types;
2020-03-17 14:16:15 +00:00
/// The proc macros, which are also part of the prelude.
#[cfg(feature = "macros")]
2018-09-21 21:32:48 +00:00
pub mod proc_macro {
2019-03-22 13:07:33 +00:00
pub use pyo3cls::pymodule;
2018-09-21 21:32:48 +00:00
/// The proc macro attributes
pub use pyo3cls::{pyclass, pyfunction, pymethods, pyproto};
}
2020-03-17 14:16:15 +00:00
/// Returns a function that takes a [Python] instance and returns a Python function.
2018-05-02 17:26:54 +00:00
///
2018-11-12 21:25:45 +00:00
/// Use this together with `#[pyfunction]` and [types::PyModule::add_wrapped].
#[macro_export]
2019-02-01 13:01:18 +00:00
macro_rules! wrap_pyfunction {
2019-08-04 14:50:10 +00:00
($function_name: ident) => {{
&pyo3::paste::expr! { [<__pyo3_get_function_ $function_name>] }
}};
($function_name: ident, $arg: expr) => {
pyo3::wrap_pyfunction!($function_name)(pyo3::derive_utils::PyFunctionArguments::from($arg))
};
2018-07-18 21:14:10 +00:00
}
2018-11-12 21:25:45 +00:00
2020-09-08 12:23:24 +00:00
/// Returns the function that is called in the C-FFI.
///
/// Use this together with `#[pyfunction]` and [types::PyCFunction].
#[macro_export]
macro_rules! raw_pycfunction {
($function_name: ident) => {{
pyo3::paste::expr! { [<__pyo3_raw_ $function_name>] }
}};
}
2020-03-17 14:16:15 +00:00
/// Returns a function that takes a [Python] instance and returns a Python module.
2018-11-12 21:25:45 +00:00
///
/// Use this together with `#[pymodule]` and [types::PyModule::add_wrapped].
#[macro_export]
2019-02-01 13:01:18 +00:00
macro_rules! wrap_pymodule {
2018-11-12 21:25:45 +00:00
($module_name:ident) => {{
2019-08-04 14:50:10 +00:00
pyo3::paste::expr! {
&|py| unsafe { pyo3::PyObject::from_owned_ptr(py, [<PyInit_ $module_name>]()) }
2018-11-12 21:25:45 +00:00
}
}};
}
2019-04-28 08:36:32 +00:00
2019-06-14 09:58:00 +00:00
/// A convenient macro to execute a Python code snippet, with some local variables set.
2019-06-13 09:09:17 +00:00
///
/// # Example
/// ```
/// use pyo3::{prelude::*, py_run, types::PyList};
/// let gil = Python::acquire_gil();
/// let py = gil.python();
/// let list = PyList::new(py, &[1, 2, 3]);
/// py_run!(py, list, "assert list == [1, 2, 3]");
/// ```
///
/// You can use this macro to test pyfunctions or pyclasses quickly.
///
/// # Example
/// ```
2020-02-03 13:25:16 +00:00
/// use pyo3::{prelude::*, py_run, PyCell};
2019-06-13 09:09:17 +00:00
/// #[pyclass]
2019-06-14 09:58:00 +00:00
/// #[derive(Debug)]
2019-06-13 09:09:17 +00:00
/// struct Time {
/// hour: u32,
/// minute: u32,
/// second: u32,
/// }
/// #[pymethods]
/// impl Time {
/// fn repl_japanese(&self) -> String {
/// format!("{}時{}分{}秒", self.hour, self.minute, self.second)
/// }
/// #[getter]
2019-06-14 09:58:00 +00:00
/// fn hour(&self) -> u32 {
/// self.hour
/// }
/// fn as_tuple(&self) -> (u32, u32, u32) {
/// (self.hour, self.minute, self.second)
2019-06-13 09:09:17 +00:00
/// }
/// }
/// let gil = Python::acquire_gil();
/// let py = gil.python();
2020-02-15 15:24:38 +00:00
/// let time = PyCell::new(py, Time {hour: 8, minute: 43, second: 16}).unwrap();
2019-06-14 09:58:00 +00:00
/// let time_as_tuple = (8, 43, 16);
/// py_run!(py, time time_as_tuple, r#"
2019-06-13 09:09:17 +00:00
/// assert time.hour == 8
/// assert time.repl_japanese() == "8時43分16秒"
2019-06-14 09:58:00 +00:00
/// assert time.as_tuple() == time_as_tuple
2019-06-13 09:09:17 +00:00
/// "#);
/// ```
2019-06-14 09:58:00 +00:00
///
/// **Note**
/// Since this macro is intended to use for testing, it **causes panic** when
/// [Python::run] returns `Err` internally.
/// If you need to handle failures, please use [Python::run] directly.
///
2019-06-13 09:09:17 +00:00
#[macro_export]
#[cfg(feature = "macros")]
2019-06-13 09:09:17 +00:00
macro_rules! py_run {
2019-06-14 09:58:00 +00:00
($py:expr, $($val:ident)+, $code:literal) => {{
2019-06-13 09:09:17 +00:00
pyo3::py_run_impl!($py, $($val)+, pyo3::indoc::indoc!($code))
}};
2019-06-14 09:58:00 +00:00
($py:expr, $($val:ident)+, $code:expr) => {{
pyo3::py_run_impl!($py, $($val)+, &pyo3::unindent::unindent($code))
2019-06-13 09:09:17 +00:00
}};
}
#[macro_export]
#[doc(hidden)]
#[cfg(feature = "macros")]
2019-06-13 09:09:17 +00:00
macro_rules! py_run_impl {
2019-06-14 09:58:00 +00:00
($py:expr, $($val:ident)+, $code:expr) => {{
2019-06-13 09:09:17 +00:00
use pyo3::types::IntoPyDict;
2019-06-14 09:58:00 +00:00
use pyo3::ToPyObject;
let d = [$((stringify!($val), $val.to_object($py)),)+].into_py_dict($py);
2019-06-13 09:09:17 +00:00
$py.run($code, None, Some(d))
.map_err(|e| {
e.print($py);
// So when this c api function the last line called printed the error to stderr,
// the output is only written into a buffer which is never flushed because we
// panic before flushing. This is where this hack comes into place
$py.run("import sys; sys.stderr.flush()", None, None)
.unwrap();
})
.expect($code)
}};
}
2019-04-28 08:36:32 +00:00
/// Test readme and user guide
#[doc(hidden)]
pub mod doc_test {
macro_rules! doc_comment {
($x:expr, $($tt:tt)*) => {
#[doc = $x]
$($tt)*
};
}
macro_rules! doctest {
($x:expr, $y:ident) => {
doc_comment!(include_str!($x), mod $y {});
};
}
doctest!("../README.md", readme_md);
doctest!("../guide/src/advanced.md", guide_advanced_md);
doctest!(
"../guide/src/building_and_distribution.md",
guide_building_and_distribution_md
);
doctest!("../guide/src/class.md", guide_class_md);
doctest!("../guide/src/conversions.md", guide_conversions_md);
doctest!("../guide/src/debugging.md", guide_debugging_md);
doctest!("../guide/src/exception.md", guide_exception_md);
doctest!("../guide/src/function.md", guide_function_md);
doctest!("../guide/src/migration.md", guide_migration_md);
2019-04-28 08:36:32 +00:00
doctest!("../guide/src/module.md", guide_module_md);
doctest!(
"../guide/src/python_from_rust.md",
guide_python_from_rust_md
);
2019-04-28 08:36:32 +00:00
doctest!("../guide/src/parallelism.md", guide_parallelism_md);
doctest!("../guide/src/pypy.md", guide_pypy_md);
doctest!("../guide/src/rust_cpython.md", guide_rust_cpython_md);
doctest!("../guide/src/types.md", guide_types_md);
doctest!("../guide/src/trait_bounds.md", guide_trait_bounds_md);
2019-04-28 08:36:32 +00:00
}