Struct pyo3_error::PyErrChain

pub struct PyErrChain { /* private fields */ }

PyErrChain wraps a PyErr together with its causality chain.

Unlike PyErr, PyErrChain’s implementation of std::error::Error provides access to the error cause through the std::error::Error::source method.

Note that since PyErrs can be readily cloned, the PyErrChain only captures the causality chain at the time of construction. Calling PyErr::set_cause on a clone of the wrapped error after construction will thus not update the chain as captured by this PyErrChain.

Implementations

impl PyErrChain

pub fn new<T: Into<Box<dyn Error + 'static>>>(py: Python<'_>, err: T) -> Self

Create a new PyErrChain from err.

The error’s causality chain, as expressed by std::error::Error::source, is translated into a PyErr::cause chain.

If any error in the chain is a PyErrChain or a PyErr, it is extracted directly. All other error types are translated into PyErrs using PyException::new_err with format!("{}", err).

If you want to customize the translation from std::error::Error into PyErr, please use Self::new_with_translator instead.

This constructor is equivalent to chaining Self::pyerr_from_err with Self::from_pyerr.

pub fn new_with_translator<E: Into<Box<dyn Error + 'static>>, T: AnyErrorToPyErr, M: MapErrorToPyErr>( py: Python<'_>, err: E, ) -> Self

Create a new PyErrChain from err using a custom translator from std::error::Error to PyErr.

The error’s causality chain, as expressed by std::error::Error::source, is translated into a PyErr::cause chain.

If any error in the chain is a PyErrChain or a PyErr, it is extracted directly. All other error types first attempt to be translated into PyErrs using the AnyErrorToPyErr and MapErrorToPyErr. As a fallback, all remaining errors are translated into PyErrs using PyException::new_err with format!("{}", err).

This constructor is equivalent to chaining Self::pyerr_from_err_with_translator with Self::from_pyerr.

pub fn pyerr_from_err<T: Into<Box<dyn Error + 'static>>>( py: Python<'_>, err: T, ) -> PyErr

Transform an err implementing std::error::Error into a PyErr that preserves the error’s causality chain.

The error’s causality chain, as expressed by std::error::Error::source, is translated into a PyErr::cause chain.

If any error in the chain is a PyErrChain or a PyErr, it is extracted directly. All other error types are translated into PyErrs using PyException::new_err with format!("{}", err).

If you want to customize the translation from std::error::Error into PyErr, please use Self::pyerr_from_err_with_translator instead.

pub fn pyerr_from_err_with_translator<E: Into<Box<dyn Error + 'static>>, T: AnyErrorToPyErr, M: MapErrorToPyErr>( py: Python<'_>, err: E, ) -> PyErr

Transform an err implementing std::error::Error into a PyErr that preserves the error’s causality chain using a custom translator.

The error’s causality chain, as expressed by std::error::Error::source, is translated into a PyErr::cause chain.

If any error in the chain is a PyErrChain or a PyErr, it is extracted directly. All other error types first attempt to be translated into PyErrs using the AnyErrorToPyErr and MapErrorToPyErr. As a fallback, all remaining errors are translated into PyErrs using PyException::new_err with format!("{}", err).

pub fn from_pyerr(py: Python<'_>, err: PyErr) -> Self

Wrap a PyErr and capture its causality chain, as expressed by PyErr::cause.

pub fn into_pyerr(self) -> PyErr

Extract the wrapped PyErr.

pub const fn as_pyerr(&self) -> &PyErr

Get a reference to the wrapped PyErr.

Note that while PyErr::set_cause can be called on the returned PyErr, the change in causality chain will not be reflected in this PyErrChain.

pub fn cause(&self) -> Option<&PyErr>

Get a reference to the cause of the wrapped PyErr.

Note that while PyErr::set_cause can be called on the returned PyErr, the change in causality chain will not be reflected in this PyErrChain.

pub fn clone_ref(&self, py: Python<'_>) -> Self

Clone the PyErrChain.

This requires the GIL, which is why PyErrChain does not implement Clone.

Note that all elements of the cloned PyErrChain will be shared using reference counting in Python with the existing PyErrChain self.

Trait Implementations

impl Debug for PyErrChain

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for PyErrChain

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for PyErrChain

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<PyErr> for PyErrChain

fn from(err: PyErr) -> Self

Converts to this type from the input type.

impl From<PyErrChain> for PyErr

fn from(err: PyErrChain) -> Self

Converts to this type from the input type.