Implement eyre feature

.github/workflows/ci.yml

@@ -64,8 +64,8 @@ jobs:
             # TODO suppress linking using config file rather than extension-module feature
             PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module"
             PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module abi3"
-            PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods"
-            PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module abi3 macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods"
+            PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods eyre"
+            PYO3_BUILD_CONFIG=$(pwd)/config.txt cargo check --all-targets --features "extension-module abi3 macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods eyre"
           done
 
   build:
@@ -163,7 +163,7 @@ jobs:
         id: settings
         shell: bash
         run: |
-          echo "::set-output name=all_additive_features::macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods"
+          echo "::set-output name=all_additive_features::macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods eyre"
 
       - if: matrix.msrv == 'MSRV'
         name: Prepare minimal package versions (MSRV only)

.github/workflows/guide.yml

@@ -44,7 +44,7 @@ jobs:
         # This adds the docs to gh-pages-build/doc
       - name: Build the doc
         run: |
-          cargo +nightly rustdoc --lib --no-default-features --features="macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods" -- --cfg docsrs
+          cargo +nightly rustdoc --lib --no-default-features --features="macros num-bigint num-complex hashbrown indexmap serde multiple-pymethods eyre" -- --cfg docsrs
           cp -r target/doc gh-pages-build/doc
           echo "<meta http-equiv=refresh content=0;url=pyo3/index.html>" > gh-pages-build/doc/index.html
 

Cargo.toml

@@ -17,6 +17,7 @@ links = "python"
 [dependencies]
 cfg-if = { version = "1.0" }
 # must stay at 0.3.x for Rust 1.41 compatibility
+eyre = {version = ">= 0.4" , optional = true}
 indoc = { version = "0.3.6", optional = true }
 inventory = { version = "0.1.4", optional = true }
 libc = "0.2.62"

Makefile

@@ -11,8 +11,8 @@ fmt:
 	black . --check
 
 clippy:
-	cargo clippy --features="num-bigint num-complex hashbrown serde" --tests -- -Dwarnings
-	cargo clippy --features="abi3 num-bigint num-complex hashbrown serde" --tests -- -Dwarnings
+	cargo clippy --features="num-bigint num-complex hashbrown serde indexmap eyre " --tests -- -Dwarnings
+	cargo clippy --features="abi3 num-bigint num-complex hashbrown serde indexmap eyre" --tests -- -Dwarnings
 	for example in examples/*/; do cargo clippy --manifest-path $$example/Cargo.toml -- -Dwarnings || exit 1; done
 
 lint: fmt clippy

src/conversions/eyre.rs

@@ -0,0 +1,158 @@
+#![cfg(feature = "eyre")]
+#![cfg_attr(docsrs, doc(cfg(feature = "eyre")))]
+//! A conversion from [eyre]’s [`Report`] type to [`PyErr`].
+//!
+//! Use of an error handling library like [eyre] is common in application code and when you just
+//! want error handling to be easy. If you are writing a library or you need more control over your
+//! errors you might want to design your own error type instead.
+//!
+//! This implementation always creates a Python [`RuntimeError`]. You might find that you need to
+//! map the error from your Rust code into another Python exception. See [`PyErr::new`] for more
+//! information about that.
+//!
+//! For information about error handling in general, see the [Error handling] chapter of the Rust
+//! book.
+//!
+//! # Setup
+//!
+//! To use this feature, add this to your **`Cargo.toml`**:
+//!
+//! ```toml
+//! [dependencies]
+//! ## change * to the version you want to use, ideally the latest.
+//! eyre = "*"
+// workaround for `extended_key_value_attributes`: https://github.com/rust-lang/rust/issues/82768#issuecomment-803935643
+#![cfg_attr(docsrs, cfg_attr(docsrs, doc = concat!("pyo3 = { version = \"", env!("CARGO_PKG_VERSION"),  "\", features = [\"eyre\"] }")))]
+#![cfg_attr(not(docsrs), doc = "pyo3 = { version = \"*\", features = [\"eyre\"] }")]
+//! ```
+//!
+//! Note that you must use compatible versions of eyre and PyO3.
+//! The required eyre version may vary based on the version of PyO3.
+//!
+//! # Example: Propagating a `PyErr` into [`eyre::Report`]
+//!
+//! ```rust
+//! use pyo3::prelude::*;
+//! use pyo3::wrap_pyfunction;
+//! use std::path::PathBuf;
+//!
+//! // An example function that returns `eyre::Result<...>`.
+//! fn rust_open(filename: PathBuf) -> eyre::Result<Vec<u8>> {
+//!     let data = std::fs::read(filename)?;
+//!     Ok(data)
+//! }
+//!
+//! // A wrapper around a Rust function.
+//! #[pyfunction]
+//! fn py_open(filename: PathBuf) -> PyResult<Vec<u8>> {
+//!     // The `?` ("try") operator performs the conversion
+//!     // into a `PyErr` - if it is an error.
+//!     let data = rust_open(filename)?;
+//!     Ok(data)
+//! }
+//!
+//! fn main() {
+//!     let error = Python::with_gil(|py| -> PyResult<Vec<u8>> {
+//!         let fun = wrap_pyfunction!(py_open, py)?;
+//!         let text = fun.call1(("foo.txt",))?.extract::<Vec<u8>>()?;
+//!         Ok(text)
+//!     }).unwrap_err();
+//!
+//!     println!("{}", error);
+//! }
+//! ```
+//!
+//! # Example: Using `eyre` in general
+//!
+//! Note that you don't need this feature to convert a [`PyErr`] into an [`eyre::Report`], because
+//! it can already convert anything that implements [`Error`](std::error::Error):
+//!
+//! ```rust
+//! use pyo3::prelude::*;
+//! use pyo3::types::PyBytes;
+//!
+//! // An example function that must handle multiple error types.
+//! //
+//! // To do this you usually need to design your own error type or use
+//! // `Box<dyn Error>`. `eyre` is a convenient alternative for this.
+//! pub fn decompress(bytes: &[u8]) -> eyre::Result<String> {
+//!     // An arbitrary example of a Python api you
+//!     // could call inside an application...
+//!     // This might return a `PyErr`.
+//!     let res = Python::with_gil(|py| {
+//!         let zlib = PyModule::import(py, "zlib")?;
+//!         let decompress = zlib.getattr("decompress")?;
+//!         let bytes = PyBytes::new(py, bytes);
+//!         let value = decompress.call1((bytes,))?;
+//!         value.extract::<Vec<u8>>()
+//!     })?;
+//!
+//!     // This might be a `FromUtf8Error`.
+//!     let text = String::from_utf8(res)?;
+//!
+//!     Ok(text)
+//! }
+//!
+//! fn main() -> eyre::Result<()> {
+//!     let bytes: &[u8] = b"x\x9c\x8b\xcc/U(\xce\xc8/\xcdIQ((\xcaOJL\xca\xa9T\
+//!                         (-NU(\xc9HU\xc8\xc9LJ\xcbI,IUH.\x02\x91\x99y\xc5%\
+//!                         \xa9\x89)z\x00\xf2\x15\x12\xfe";
+//!     let text = decompress(bytes)?;
+//!
+//!     println!("The text is \"{}\"", text);
+//! # assert_eq!(text, "You should probably use the libflate crate instead.");
+//!     Ok(())
+//! }
+//! ```
+//!
+//! [eyre]: https://docs.rs/eyre/ "A library for easy idiomatic error handling and reporting in Rust applications."
+//! [`RuntimeError`]: https://docs.python.org/3/library/exceptions.html#RuntimeError "Built-in Exceptions — Python documentation"
+//! [Error handling]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html "Recoverable Errors with Result - The Rust Programming Language"
+
+use crate::exceptions::PyRuntimeError;
+use crate::PyErr;
+use eyre::Report;
+
+/// Converts [`eyre::Report`] to a [`PyErr`] containing a [`PyRuntimeError`].
+///
+/// If you want to raise a different Python exception you will have to do so manually. See
+/// [`PyErr::new`] for more information about that.
+impl From<eyre::Report> for PyErr {
+    fn from(error: Report) -> Self {
+        PyRuntimeError::new_err(format!("{:?}", error))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pyo3::prelude::*;
+    use pyo3::types::IntoPyDict;
+
+    use eyre::{bail, Result, WrapErr};
+
+    fn f() -> Result<()> {
+        use std::io;
+        bail!(io::Error::new(io::ErrorKind::PermissionDenied, "oh no!"));
+    }
+
+    fn g() -> Result<()> {
+        f().wrap_err("f failed")
+    }
+
+    fn h() -> Result<()> {
+        g().wrap_err("g failed")
+    }
+
+    #[test]
+    fn test_pyo3_exception_contents() {
+        let err = h().unwrap_err();
+        let expected_contents = format!("{:?}", err);
+        let pyerr = PyErr::from(err);
+
+        Python::with_gil(|py| {
+            let locals = [("err", pyerr)].into_py_dict(py);
+            let pyerr = py.run("raise err", None, Some(locals)).unwrap_err();
+            assert_eq!(pyerr.pvalue(py).to_string(), expected_contents);
+        })
+    }
+}

src/conversions/mod.rs

@@ -1,6 +1,7 @@
 //! This module contains conversions between various Rust object and their representation in Python.
 
 mod array;
+pub mod eyre;
 pub mod hashbrown;
 pub mod indexmap;
 pub mod num_bigint;

src/lib.rs

@@ -76,7 +76,7 @@
 //! crate, which is not supported on all platforms.
 //!
 //! The following features enable interactions with other crates in the Rust ecosystem:
-//
+//! - [`eyre`]: Enables a conversion from [eyre]’s [`Report`] type to [`PyErr`].
 //! - [`hashbrown`]: Enables conversions between Python objects and [hashbrown]'s [`HashMap`] and
 //! [`HashSet`] types.
 //! - [`indexmap`]: Enables conversions between Python dictionary and [indexmap]'s [`IndexMap`].
@@ -254,6 +254,9 @@
 //! [`Complex`]: https://docs.rs/num-complex/latest/num_complex/struct.Complex.html
 //! [`Deserialize`]: https://docs.rs/serde/latest/serde/trait.Deserialize.html
 //! [`Serialize`]: https://docs.rs/serde/latest/serde/trait.Serialize.html
+//! [eyre]: https://docs.rs/eyre/ "A library for easy idiomatic error handling and reporting in Rust applications."
+//! [`Report`]: https://docs.rs/eyre/latest/eyre/struct.Report.html
+//! [`eyre`]: ./eyre/index.html
 //! [`hashbrown`]: ./hashbrown/index.html
 //! [`indexmap`]: <./indexmap/index.html>
 //! [`maturin`]: https://github.com/PyO3/maturin "Build and publish crates with pyo3, rust-cpython and cffi bindings as well as rust binaries as python packages"