Struct pyo3::PyErr

pub struct PyErr { /* private fields */ }

Represents a Python exception.

Python exceptions can be raised in a “lazy” fashion, where the full Python object for the exception is not created until needed. The process of creating the full object is known as “normalization”. An exception which has not yet been created is known as “unnormalized”.

This struct builds upon that design, supporting all lazily-created Python exceptions and also supporting exceptions lazily-created from Rust.

Implementations

impl PyErr

pub fn new<T, A>(args: A) -> PyErrwhere T: PyTypeInfo, A: PyErrArguments + Send + Sync + 'static,

Creates a new PyErr of type T.

args can be:

• a tuple: the exception instance will be created using the equivalent to the Python expression T(*tuple)
• any other value: the exception instance will be created using the equivalent to the Python expression T(value)

This error will be stored in an unnormalized state. This avoids the need for the Python GIL to be held, but requires args to be Send and Sync. If args is not Send or Sync, consider using PyErr::from_value instead.

If an error occurs during normalization (for example if T is not a Python type which extends from BaseException), then a different error may be produced during normalization.

Examples

use pyo3::prelude::*;
use pyo3::exceptions::PyTypeError;

#[pyfunction]
fn always_throws() -> PyResult<()> {
    Err(PyErr::new::<PyTypeError, _>("Error message"))
}

In most cases, you can use a concrete exception’s constructor instead:

use pyo3::prelude::*;
use pyo3::exceptions::PyTypeError;

#[pyfunction]
fn always_throws() -> PyResult<()> {
    Err(PyTypeError::new_err("Error message"))
}

pub fn from_type<A>(ty: &PyType, args: A) -> PyErrwhere A: PyErrArguments + Send + Sync + 'static,

Constructs a new PyErr from the given Python type and arguments.

ty is the exception type; usually one of the standard exceptions like exceptions::PyRuntimeError.

args is either a tuple or a single value, with the same meaning as in PyErr::new.

If an error occurs during normalization (for example if T is not a Python type which extends from BaseException), then a different error may be produced during normalization.

This error will be stored in an unnormalized state.

pub fn from_value(obj: &PyAny) -> PyErr

Creates a new PyErr.

If obj is a Python exception object, the PyErr will contain that object. The error will be in a normalized state.

If obj is a Python exception type object, this is equivalent to PyErr::from_type(obj, ()).

Otherwise, a TypeError is created.

Examples

use pyo3::prelude::*;
use pyo3::exceptions::PyTypeError;
use pyo3::types::{PyType, PyString};

Python::with_gil(|py| {
    // Case #1: Exception object
    let err = PyErr::from_value(PyTypeError::new_err("some type error").value(py));
    assert_eq!(err.to_string(), "TypeError: some type error");

    // Case #2: Exception type
    let err = PyErr::from_value(PyType::new::<PyTypeError>(py));
    assert_eq!(err.to_string(), "TypeError: ");

    // Case #3: Invalid exception value
    let err = PyErr::from_value(PyString::new(py, "foo").into());
    assert_eq!(
        err.to_string(),
        "TypeError: exceptions must derive from BaseException"
    );
});

pub fn get_type<'py>(&'py self, py: Python<'py>) -> &'py PyType

Returns the type of this exception.

The object will be normalized first if needed.

Examples

use pyo3::{exceptions::PyTypeError, types::PyType, PyErr, Python};

Python::with_gil(|py| {
    let err: PyErr = PyTypeError::new_err(("some type error",));
    assert!(err.get_type(py).is(PyType::new::<PyTypeError>(py)));
});

pub fn value<'py>(&'py self, py: Python<'py>) -> &'py PyBaseException

Returns the value of this exception.

The object will be normalized first if needed.

Examples

use pyo3::{exceptions::PyTypeError, PyErr, Python};

Python::with_gil(|py| {
    let err: PyErr = PyTypeError::new_err(("some type error",));
    assert!(err.is_instance_of::<PyTypeError>(py));
    assert_eq!(err.value(py).to_string(), "some type error");
});

pub fn into_value(self, py: Python<'_>) -> Py<PyBaseException>

Consumes self to take ownership of the exception value contained in this error.

pub fn traceback<'py>(&'py self, py: Python<'py>) -> Option<&'py PyTraceback>

Returns the traceback of this exception object.

The object will be normalized first if needed.

Examples

use pyo3::{exceptions::PyTypeError, Python};

Python::with_gil(|py| {
    let err = PyTypeError::new_err(("some type error",));
    assert!(err.traceback(py).is_none());
});

pub fn occurred(_: Python<'_>) -> bool

Gets whether an error is present in the Python interpreter’s global state.

pub fn take(py: Python<'_>) -> Option<PyErr>

Takes the current error from the Python interpreter’s global state and clears the global state. If no error is set, returns None.

If the error is a PanicException (which would have originated from a panic in a pyo3 callback) then this function will resume the panic.

Use this function when it is not known if an error should be present. If the error is expected to have been set, for example from PyErr::occurred or by an error return value from a C FFI function, use PyErr::fetch.

pub fn fetch(py: Python<'_>) -> PyErr

Equivalent to PyErr::take, but when no error is set:

• Panics in debug mode.
• Returns a SystemError in release mode.

This behavior is consistent with Python’s internal handling of what happens when a C return value indicates an error occurred but the global error state is empty. (A lack of exception should be treated as a bug in the code which returned an error code but did not set an exception.)

Use this function when the error is expected to have been set, for example from PyErr::occurred or by an error return value from a C FFI function.

pub fn new_type( py: Python<'_>, name: &str, doc: Option<&str>, base: Option<&PyType>, dict: Option<PyObject> ) -> PyResult<Py<PyType>>

Creates a new exception type with the given name and docstring.

• base can be an existing exception type to subclass, or a tuple of classes.
• dict specifies an optional dictionary of class variables and methods.
• doc will be the docstring seen by python users.

Errors

This function returns an error if name is not of the form <module>.<ExceptionName>.

Panics

This function will panic if name or doc cannot be converted to CStrings.

pub fn print(&self, py: Python<'_>)

Prints a standard traceback to sys.stderr.

pub fn print_and_set_sys_last_vars(&self, py: Python<'_>)

Prints a standard traceback to sys.stderr, and sets sys.last_{type,value,traceback} attributes to this exception’s data.

pub fn matches<T>(&self, py: Python<'_>, exc: T) -> boolwhere T: ToPyObject,

Returns true if the current exception matches the exception in exc.

If exc is a class object, this also returns true when self is an instance of a subclass. If exc is a tuple, all exceptions in the tuple (and recursively in subtuples) are searched for a match.

pub fn is_instance(&self, py: Python<'_>, ty: &PyAny) -> bool

Returns true if the current exception is instance of T.

pub fn is_instance_of<T>(&self, py: Python<'_>) -> boolwhere T: PyTypeInfo,

Returns true if the current exception is instance of T.

pub fn restore(self, py: Python<'_>)

Writes the error back to the Python interpreter’s global state. This is the opposite of PyErr::fetch().

pub fn write_unraisable(self, py: Python<'_>, obj: Option<&PyAny>)

Reports the error as unraisable.

This calls sys.unraisablehook() using the current exception and obj argument.

This method is useful to report errors in situations where there is no good mechanism to report back to the Python land. In Python this is used to indicate errors in background threads or destructors which are protected. In Rust code this is commonly useful when you are calling into a Python callback which might fail, but there is no obvious way to handle this error other than logging it.

Calling this method has the benefit that the error goes back into a standardized callback in Python which for instance allows unittests to ensure that no unraisable error actually happend by hooking sys.unraisablehook.

Example:

Python::with_gil(|py| {
    match failing_function() {
        Err(pyerr) => pyerr.write_unraisable(py, None),
        Ok(..) => { /* do something here */ }
    }
    Ok(())
})

pub fn warn( py: Python<'_>, category: &PyAny, message: &str, stacklevel: i32 ) -> PyResult<()>

Issues a warning message.

May return an Err(PyErr) if warnings-as-errors is enabled.

Equivalent to warnings.warn() in Python.

The category should be one of the Warning classes available in pyo3::exceptions, or a subclass. The Python object can be retrieved using Python::get_type().

Example:

Python::with_gil(|py| {
    let user_warning = py.get_type::<pyo3::exceptions::PyUserWarning>();
    PyErr::warn(py, user_warning, "I am warning you", 0)?;
    Ok(())
})

pub fn warn_explicit( py: Python<'_>, category: &PyAny, message: &str, filename: &str, lineno: i32, module: Option<&str>, registry: Option<&PyAny> ) -> PyResult<()>

Issues a warning message, with more control over the warning attributes.

May return a PyErr if warnings-as-errors is enabled.

Equivalent to warnings.warn_explicit() in Python.

The category should be one of the Warning classes available in pyo3::exceptions, or a subclass.

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

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

Examples

use pyo3::{exceptions::PyTypeError, PyErr, Python};
Python::with_gil(|py| {
    let err: PyErr = PyTypeError::new_err(("some type error",));
    let err_clone = err.clone_ref(py);
    assert!(err.get_type(py).is(err_clone.get_type(py)));
    assert!(err.value(py).is(err_clone.value(py)));
    match err.traceback(py) {
        None => assert!(err_clone.traceback(py).is_none()),
        Some(tb) => assert!(err_clone.traceback(py).unwrap().is(tb)),
    }
});

pub fn cause(&self, py: Python<'_>) -> Option<PyErr>

Return the cause (either an exception instance, or None, set by raise ... from ...) associated with the exception, as accessible from Python through __cause__.

pub fn set_cause(&self, py: Python<'_>, cause: Option<Self>)

Set the cause associated with the exception, pass None to clear it.

Trait Implementations

impl Debug for PyErr

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

Formats the value using the given formatter.

impl Display for PyErr

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

Formats the value using the given formatter.

impl Error for PyErr

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

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, demand: &mut Demand<'a>)

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

Provides type based access to context intended for error reports.

impl From<&CancelledError> for PyErr

fn from(err: &CancelledError) -> PyErr

Converts to this type from the input type.

impl From<&IncompleteReadError> for PyErr

fn from(err: &IncompleteReadError) -> PyErr

Converts to this type from the input type.

impl From<&InvalidStateError> for PyErr

fn from(err: &InvalidStateError) -> PyErr

Converts to this type from the input type.

impl From<&LimitOverrunError> for PyErr

fn from(err: &LimitOverrunError) -> PyErr

Converts to this type from the input type.

impl From<&PanicException> for PyErr

fn from(err: &PanicException) -> PyErr

Converts to this type from the input type.

impl From<&PyArithmeticError> for PyErr

fn from(err: &PyArithmeticError) -> PyErr

Converts to this type from the input type.

impl From<&PyAssertionError> for PyErr

fn from(err: &PyAssertionError) -> PyErr

Converts to this type from the input type.

impl From<&PyAttributeError> for PyErr

fn from(err: &PyAttributeError) -> PyErr

Converts to this type from the input type.

impl From<&PyBaseException> for PyErr

fn from(err: &PyBaseException) -> PyErr

Converts to this type from the input type.

impl From<&PyBlockingIOError> for PyErr

fn from(err: &PyBlockingIOError) -> PyErr

Converts to this type from the input type.

impl From<&PyBrokenPipeError> for PyErr

fn from(err: &PyBrokenPipeError) -> PyErr

Converts to this type from the input type.

impl From<&PyBufferError> for PyErr

fn from(err: &PyBufferError) -> PyErr

Converts to this type from the input type.

impl From<&PyBytesWarning> for PyErr

fn from(err: &PyBytesWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyChildProcessError> for PyErr

fn from(err: &PyChildProcessError) -> PyErr

Converts to this type from the input type.

impl From<&PyConnectionAbortedError> for PyErr

fn from(err: &PyConnectionAbortedError) -> PyErr

Converts to this type from the input type.

impl From<&PyConnectionError> for PyErr

fn from(err: &PyConnectionError) -> PyErr

Converts to this type from the input type.

impl From<&PyConnectionRefusedError> for PyErr

fn from(err: &PyConnectionRefusedError) -> PyErr

Converts to this type from the input type.

impl From<&PyConnectionResetError> for PyErr

fn from(err: &PyConnectionResetError) -> PyErr

Converts to this type from the input type.

impl From<&PyDeprecationWarning> for PyErr

fn from(err: &PyDeprecationWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyEOFError> for PyErr

fn from(err: &PyEOFError) -> PyErr

Converts to this type from the input type.

impl From<&PyEncodingWarning> for PyErr

fn from(err: &PyEncodingWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyEnvironmentError> for PyErr

fn from(err: &PyEnvironmentError) -> PyErr

Converts to this type from the input type.

impl From<&PyException> for PyErr

fn from(err: &PyException) -> PyErr

Converts to this type from the input type.

impl From<&PyFileExistsError> for PyErr

fn from(err: &PyFileExistsError) -> PyErr

Converts to this type from the input type.

impl From<&PyFileNotFoundError> for PyErr

fn from(err: &PyFileNotFoundError) -> PyErr

Converts to this type from the input type.

impl From<&PyFloatingPointError> for PyErr

fn from(err: &PyFloatingPointError) -> PyErr

Converts to this type from the input type.

impl From<&PyFutureWarning> for PyErr

fn from(err: &PyFutureWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyGeneratorExit> for PyErr

fn from(err: &PyGeneratorExit) -> PyErr

Converts to this type from the input type.

impl From<&PyIOError> for PyErr

fn from(err: &PyIOError) -> PyErr

Converts to this type from the input type.

impl From<&PyImportError> for PyErr

fn from(err: &PyImportError) -> PyErr

Converts to this type from the input type.

impl From<&PyImportWarning> for PyErr

fn from(err: &PyImportWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyIndexError> for PyErr

fn from(err: &PyIndexError) -> PyErr

Converts to this type from the input type.

impl From<&PyInterruptedError> for PyErr

fn from(err: &PyInterruptedError) -> PyErr

Converts to this type from the input type.

impl From<&PyIsADirectoryError> for PyErr

fn from(err: &PyIsADirectoryError) -> PyErr

Converts to this type from the input type.

impl From<&PyKeyError> for PyErr

fn from(err: &PyKeyError) -> PyErr

Converts to this type from the input type.

impl From<&PyKeyboardInterrupt> for PyErr

fn from(err: &PyKeyboardInterrupt) -> PyErr

Converts to this type from the input type.

impl From<&PyLookupError> for PyErr

fn from(err: &PyLookupError) -> PyErr

Converts to this type from the input type.

impl From<&PyMemoryError> for PyErr

fn from(err: &PyMemoryError) -> PyErr

Converts to this type from the input type.

impl From<&PyModuleNotFoundError> for PyErr

fn from(err: &PyModuleNotFoundError) -> PyErr

Converts to this type from the input type.

impl From<&PyNameError> for PyErr

fn from(err: &PyNameError) -> PyErr

Converts to this type from the input type.

impl From<&PyNotADirectoryError> for PyErr

fn from(err: &PyNotADirectoryError) -> PyErr

Converts to this type from the input type.

impl From<&PyNotImplementedError> for PyErr

fn from(err: &PyNotImplementedError) -> PyErr

Converts to this type from the input type.

impl From<&PyOSError> for PyErr

fn from(err: &PyOSError) -> PyErr

Converts to this type from the input type.

impl From<&PyOverflowError> for PyErr

fn from(err: &PyOverflowError) -> PyErr

Converts to this type from the input type.

impl From<&PyPendingDeprecationWarning> for PyErr

fn from(err: &PyPendingDeprecationWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyPermissionError> for PyErr

fn from(err: &PyPermissionError) -> PyErr

Converts to this type from the input type.

impl From<&PyProcessLookupError> for PyErr

fn from(err: &PyProcessLookupError) -> PyErr

Converts to this type from the input type.

impl From<&PyRecursionError> for PyErr

fn from(err: &PyRecursionError) -> PyErr

Converts to this type from the input type.

impl From<&PyReferenceError> for PyErr

fn from(err: &PyReferenceError) -> PyErr

Converts to this type from the input type.

impl From<&PyResourceWarning> for PyErr

fn from(err: &PyResourceWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyRuntimeError> for PyErr

fn from(err: &PyRuntimeError) -> PyErr

Converts to this type from the input type.

impl From<&PyRuntimeWarning> for PyErr

fn from(err: &PyRuntimeWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyStopAsyncIteration> for PyErr

fn from(err: &PyStopAsyncIteration) -> PyErr

Converts to this type from the input type.

impl From<&PyStopIteration> for PyErr

fn from(err: &PyStopIteration) -> PyErr

Converts to this type from the input type.

impl From<&PySyntaxError> for PyErr

fn from(err: &PySyntaxError) -> PyErr

Converts to this type from the input type.

impl From<&PySyntaxWarning> for PyErr

fn from(err: &PySyntaxWarning) -> PyErr

Converts to this type from the input type.

impl From<&PySystemError> for PyErr

fn from(err: &PySystemError) -> PyErr

Converts to this type from the input type.

impl From<&PySystemExit> for PyErr

fn from(err: &PySystemExit) -> PyErr

Converts to this type from the input type.

impl From<&PyTimeoutError> for PyErr

fn from(err: &PyTimeoutError) -> PyErr

Converts to this type from the input type.

impl From<&PyTypeError> for PyErr

fn from(err: &PyTypeError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnboundLocalError> for PyErr

fn from(err: &PyUnboundLocalError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnicodeDecodeError> for PyErr

fn from(err: &PyUnicodeDecodeError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnicodeEncodeError> for PyErr

fn from(err: &PyUnicodeEncodeError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnicodeError> for PyErr

fn from(err: &PyUnicodeError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnicodeTranslateError> for PyErr

fn from(err: &PyUnicodeTranslateError) -> PyErr

Converts to this type from the input type.

impl From<&PyUnicodeWarning> for PyErr

fn from(err: &PyUnicodeWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyUserWarning> for PyErr

fn from(err: &PyUserWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyValueError> for PyErr

fn from(err: &PyValueError) -> PyErr

Converts to this type from the input type.

impl From<&PyWarning> for PyErr

fn from(err: &PyWarning) -> PyErr

Converts to this type from the input type.

impl From<&PyZeroDivisionError> for PyErr

fn from(err: &PyZeroDivisionError) -> PyErr

Converts to this type from the input type.

impl From<&QueueEmpty> for PyErr

fn from(err: &QueueEmpty) -> PyErr

Converts to this type from the input type.

impl From<&QueueFull> for PyErr

fn from(err: &QueueFull) -> PyErr

Converts to this type from the input type.

impl From<&TimeoutError> for PyErr

fn from(err: &TimeoutError) -> PyErr

Converts to this type from the input type.

impl From<&gaierror> for PyErr

fn from(err: &gaierror) -> PyErr

Converts to this type from the input type.

impl From<&herror> for PyErr

fn from(err: &herror) -> PyErr

Converts to this type from the input type.

impl From<&timeout> for PyErr

fn from(err: &timeout) -> PyErr

Converts to this type from the input type.

impl From<AddrParseError> for PyErr

fn from(err: AddrParseError) -> PyErr

Converts to this type from the input type.

impl From<DecodeUtf16Error> for PyErr

fn from(err: DecodeUtf16Error) -> PyErr

Converts to this type from the input type.

impl From<Error> for PyErr

Create OSError from io::Error

fn from(err: Error) -> PyErr

Converts to this type from the input type.

impl From<FromUtf16Error> for PyErr

fn from(err: FromUtf16Error) -> PyErr

Converts to this type from the input type.

impl From<FromUtf8Error> for PyErr

fn from(err: FromUtf8Error) -> PyErr

Converts to this type from the input type.

impl From<Infallible> for PyErr

fn from(_: Infallible) -> PyErr

Converts to this type from the input type.

impl<W: 'static + Send + Sync + Debug> From<IntoInnerError<W>> for PyErr

fn from(err: IntoInnerError<W>) -> PyErr

Converts to this type from the input type.

impl From<IntoStringError> for PyErr

fn from(err: IntoStringError) -> PyErr

Converts to this type from the input type.

impl From<NulError> for PyErr

fn from(err: NulError) -> PyErr

Converts to this type from the input type.

impl From<ParseBoolError> for PyErr

fn from(err: ParseBoolError) -> PyErr

Converts to this type from the input type.

impl From<ParseFloatError> for PyErr

fn from(err: ParseFloatError) -> PyErr

Converts to this type from the input type.

impl From<ParseIntError> for PyErr

fn from(err: ParseIntError) -> PyErr

Converts to this type from the input type.

impl From<PyBorrowError> for PyErr

fn from(other: PyBorrowError) -> Self

Converts to this type from the input type.

impl From<PyBorrowMutError> for PyErr

fn from(other: PyBorrowMutError) -> Self

Converts to this type from the input type.

impl<'a> From<PyDowncastError<'a>> for PyErr

Convert PyDowncastError to Python TypeError.

fn from(err: PyDowncastError<'_>) -> PyErr

Converts to this type from the input type.

impl From<PyErr> for Error

Convert PyErr to io::Error

fn from(err: PyErr) -> Self

Converts to this type from the input type.

impl From<Report> for PyErr

Available on crate feature eyre only.

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.

fn from(error: Report) -> Self

Converts to this type from the input type.

impl From<TryFromIntError> for PyErr

fn from(err: TryFromIntError) -> PyErr

Converts to this type from the input type.

impl From<TryFromSliceError> for PyErr

fn from(err: TryFromSliceError) -> PyErr

Converts to this type from the input type.

impl From<Utf8Error> for PyErr

fn from(err: Utf8Error) -> PyErr

Converts to this type from the input type.

impl<'a> IntoPy<Py<PyAny>> for &'a PyErr

fn into_py(self, py: Python<'_>) -> PyObject

Performs the conversion.

impl IntoPy<Py<PyAny>> for PyErr

fn into_py(self, py: Python<'_>) -> PyObject

Performs the conversion.

impl ToPyObject for PyErr

fn to_object(&self, py: Python<'_>) -> PyObject

Converts self into a Python object.

impl Send for PyErr

impl Sync for PyErr