Struct pyo3::prelude::PyErr

pub struct PyErr { /* fields omitted */ }

Represents a Python exception that was raised.

Implementations

impl PyErr

pub fn new<T, A>(args: A) -> PyErr where
    T: PyTypeObject,
    A: PyErrArguments + Send + Sync + 'static, 

Creates a new PyErr of type T.

value can be:

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

Note: if value is not Send or Sync, consider using PyErr::from_instance instead.

Panics if T is not a Python class derived from BaseException.

Example:

return Err(PyErr::new::<exceptions::PyTypeError, _>("Error message"));

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

return Err(exceptions::PyTypeError::new_err("Error message"));

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

Constructs a new error, with the usual lazy initialization of Python exceptions.

exc is the exception type; usually one of the standard exceptions like exceptions::PyRuntimeError. args is the a tuple of arguments to pass to the exception constructor.

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

Creates a new PyErr.

obj must be an Python exception instance, the PyErr will use that instance. If obj is a Python exception type object, the PyErr will (lazily) create a new instance of that type. Otherwise, a TypeError is created instead.

Examples

use pyo3::{Python, PyErr, IntoPy, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
    // Case #1: Exception instance
    let err = PyErr::from_instance(PyTypeError::new_err("some type error",).instance(py));
    assert_eq!(err.to_string(), "TypeError: some type error");

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

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

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

Get the type of this exception object.

The object will be normalized first if needed.

Examples

use pyo3::{Python, PyErr, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
    let err = PyTypeError::new_err(("some type error",));
    assert_eq!(err.ptype(py), PyType::new::<PyTypeError>(py));
});

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

Get the value of this exception object.

The object will be normalized first if needed.

Examples

use pyo3::{Python, PyErr, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
    let err = PyTypeError::new_err(("some type error",));
    assert!(err.is_instance::<PyTypeError>(py));
    assert_eq!(err.pvalue(py).to_string(), "some type error");
});

pub fn ptraceback<'py>(&'py self, py: Python<'py>) -> Option<&'py PyAny>

Get the value of this exception object.

The object will be normalized first if needed.

Examples

use pyo3::{Python, PyErr, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
    let err = PyTypeError::new_err(("some type error",));
    assert_eq!(err.ptraceback(py), None);
});

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

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

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

Retrieves the current error from the Python interpreter’s global state.

The error is cleared from the Python interpreter. If no error is set, returns a SystemError.

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

pub fn new_type<'p>(
    _: Python<'p>,
    name: &str,
    base: Option<&PyType>,
    dict: Option<PyObject>
) -> NonNull<PyTypeObject>

Creates a new exception type with the given name, which must be of the form <module>.<ExceptionName>, as required by PyErr_NewException.

base can be an existing exception type to subclass, or a tuple of classes dict specifies an optional dictionary of class variables and methods

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) -> bool where
    T: ToBorrowedObject, 

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<T>(&self, py: Python<'_>) -> bool where
    T: PyTypeObject, 

Returns true if the current exception is instance of T.

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

Retrieves the exception instance for this error.

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

Consumes self to take ownership of the exception instance for this error.

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 warn(
    py: Python<'_>,
    category: &PyAny,
    message: &str,
    stacklevel: i32
) -> PyResult<()>

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

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::{Python, PyErr, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
    let err = PyTypeError::new_err(("some type error",));
    let err_clone = err.clone_ref(py);
    assert_eq!(err.ptype(py), err_clone.ptype(py));
    assert_eq!(err.pvalue(py), err_clone.pvalue(py));
    assert_eq!(err.ptraceback(py), err_clone.ptraceback(py));
});

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 backtrace(&self) -> Option<&Backtrace>

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

Returns a stack backtrace, if available, of where this error occurred.

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

impl From<&'_ CancelledError> for PyErr

fn from(err: &CancelledError) -> PyErr

Performs the conversion.

impl From<&'_ IncompleteReadError> for PyErr

fn from(err: &IncompleteReadError) -> PyErr

Performs the conversion.

impl From<&'_ InvalidStateError> for PyErr

fn from(err: &InvalidStateError) -> PyErr

Performs the conversion.

impl From<&'_ LimitOverrunError> for PyErr

fn from(err: &LimitOverrunError) -> PyErr

Performs the conversion.

impl From<&'_ PanicException> for PyErr

fn from(err: &PanicException) -> PyErr

Performs the conversion.

impl From<&'_ PyArithmeticError> for PyErr

fn from(err: &PyArithmeticError) -> PyErr

Performs the conversion.

impl From<&'_ PyAssertionError> for PyErr

fn from(err: &PyAssertionError) -> PyErr

Performs the conversion.

impl From<&'_ PyAttributeError> for PyErr

fn from(err: &PyAttributeError) -> PyErr

Performs the conversion.

impl From<&'_ PyBaseException> for PyErr

fn from(err: &PyBaseException) -> PyErr

Performs the conversion.

impl From<&'_ PyBlockingIOError> for PyErr

fn from(err: &PyBlockingIOError) -> PyErr

Performs the conversion.

impl From<&'_ PyBrokenPipeError> for PyErr

fn from(err: &PyBrokenPipeError) -> PyErr

Performs the conversion.

impl From<&'_ PyBufferError> for PyErr

fn from(err: &PyBufferError) -> PyErr

Performs the conversion.

impl From<&'_ PyChildProcessError> for PyErr

fn from(err: &PyChildProcessError) -> PyErr

Performs the conversion.

impl From<&'_ PyConnectionAbortedError> for PyErr

fn from(err: &PyConnectionAbortedError) -> PyErr

Performs the conversion.

impl From<&'_ PyConnectionError> for PyErr

fn from(err: &PyConnectionError) -> PyErr

Performs the conversion.

impl From<&'_ PyConnectionRefusedError> for PyErr

fn from(err: &PyConnectionRefusedError) -> PyErr

Performs the conversion.

impl From<&'_ PyConnectionResetError> for PyErr

fn from(err: &PyConnectionResetError) -> PyErr

Performs the conversion.

impl From<&'_ PyEOFError> for PyErr

fn from(err: &PyEOFError) -> PyErr

Performs the conversion.

impl From<&'_ PyEnvironmentError> for PyErr

fn from(err: &PyEnvironmentError) -> PyErr

Performs the conversion.

impl From<&'_ PyException> for PyErr

fn from(err: &PyException) -> PyErr

Performs the conversion.

impl From<&'_ PyFileExistsError> for PyErr

fn from(err: &PyFileExistsError) -> PyErr

Performs the conversion.

impl From<&'_ PyFileNotFoundError> for PyErr

fn from(err: &PyFileNotFoundError) -> PyErr

Performs the conversion.

impl From<&'_ PyFloatingPointError> for PyErr

fn from(err: &PyFloatingPointError) -> PyErr

Performs the conversion.

impl From<&'_ PyGeneratorExit> for PyErr

fn from(err: &PyGeneratorExit) -> PyErr

Performs the conversion.

impl From<&'_ PyIOError> for PyErr

fn from(err: &PyIOError) -> PyErr

Performs the conversion.

impl From<&'_ PyImportError> for PyErr

fn from(err: &PyImportError) -> PyErr

Performs the conversion.

impl From<&'_ PyIndexError> for PyErr

fn from(err: &PyIndexError) -> PyErr

Performs the conversion.

impl From<&'_ PyInterruptedError> for PyErr

fn from(err: &PyInterruptedError) -> PyErr

Performs the conversion.

impl From<&'_ PyIsADirectoryError> for PyErr

fn from(err: &PyIsADirectoryError) -> PyErr

Performs the conversion.

impl From<&'_ PyKeyError> for PyErr

fn from(err: &PyKeyError) -> PyErr

Performs the conversion.

impl From<&'_ PyKeyboardInterrupt> for PyErr

fn from(err: &PyKeyboardInterrupt) -> PyErr

Performs the conversion.

impl From<&'_ PyLookupError> for PyErr

fn from(err: &PyLookupError) -> PyErr

Performs the conversion.

impl From<&'_ PyMemoryError> for PyErr

fn from(err: &PyMemoryError) -> PyErr

Performs the conversion.

impl From<&'_ PyModuleNotFoundError> for PyErr

fn from(err: &PyModuleNotFoundError) -> PyErr

Performs the conversion.

impl From<&'_ PyNameError> for PyErr

fn from(err: &PyNameError) -> PyErr

Performs the conversion.

impl From<&'_ PyNotADirectoryError> for PyErr

fn from(err: &PyNotADirectoryError) -> PyErr

Performs the conversion.

impl From<&'_ PyNotImplementedError> for PyErr

fn from(err: &PyNotImplementedError) -> PyErr

Performs the conversion.

impl From<&'_ PyOSError> for PyErr

fn from(err: &PyOSError) -> PyErr

Performs the conversion.

impl From<&'_ PyOverflowError> for PyErr

fn from(err: &PyOverflowError) -> PyErr

Performs the conversion.

impl From<&'_ PyPermissionError> for PyErr

fn from(err: &PyPermissionError) -> PyErr

Performs the conversion.

impl From<&'_ PyProcessLookupError> for PyErr

fn from(err: &PyProcessLookupError) -> PyErr

Performs the conversion.

impl From<&'_ PyRecursionError> for PyErr

fn from(err: &PyRecursionError) -> PyErr

Performs the conversion.

impl From<&'_ PyReferenceError> for PyErr

fn from(err: &PyReferenceError) -> PyErr

Performs the conversion.

impl From<&'_ PyRuntimeError> for PyErr

fn from(err: &PyRuntimeError) -> PyErr

Performs the conversion.

impl From<&'_ PyStopAsyncIteration> for PyErr

fn from(err: &PyStopAsyncIteration) -> PyErr

Performs the conversion.

impl From<&'_ PyStopIteration> for PyErr

fn from(err: &PyStopIteration) -> PyErr

Performs the conversion.

impl From<&'_ PySyntaxError> for PyErr

fn from(err: &PySyntaxError) -> PyErr

Performs the conversion.

impl From<&'_ PySystemError> for PyErr

fn from(err: &PySystemError) -> PyErr

Performs the conversion.

impl From<&'_ PySystemExit> for PyErr

fn from(err: &PySystemExit) -> PyErr

Performs the conversion.

impl From<&'_ PyTimeoutError> for PyErr

fn from(err: &PyTimeoutError) -> PyErr

Performs the conversion.

impl From<&'_ PyTypeError> for PyErr

fn from(err: &PyTypeError) -> PyErr

Performs the conversion.

impl From<&'_ PyUnboundLocalError> for PyErr

fn from(err: &PyUnboundLocalError) -> PyErr

Performs the conversion.

impl From<&'_ PyUnicodeDecodeError> for PyErr

fn from(err: &PyUnicodeDecodeError) -> PyErr

Performs the conversion.

impl From<&'_ PyUnicodeEncodeError> for PyErr

fn from(err: &PyUnicodeEncodeError) -> PyErr

Performs the conversion.

impl From<&'_ PyUnicodeError> for PyErr

fn from(err: &PyUnicodeError) -> PyErr

Performs the conversion.

impl From<&'_ PyUnicodeTranslateError> for PyErr

fn from(err: &PyUnicodeTranslateError) -> PyErr

Performs the conversion.

impl From<&'_ PyValueError> for PyErr

fn from(err: &PyValueError) -> PyErr

Performs the conversion.

impl From<&'_ PyZeroDivisionError> for PyErr

fn from(err: &PyZeroDivisionError) -> PyErr

Performs the conversion.

impl From<&'_ QueueEmpty> for PyErr

fn from(err: &QueueEmpty) -> PyErr

Performs the conversion.

impl From<&'_ QueueFull> for PyErr

fn from(err: &QueueFull) -> PyErr

Performs the conversion.

impl From<&'_ TimeoutError> for PyErr

fn from(err: &TimeoutError) -> PyErr

Performs the conversion.

impl From<&'_ gaierror> for PyErr

fn from(err: &gaierror) -> PyErr

Performs the conversion.

impl From<&'_ herror> for PyErr

fn from(err: &herror) -> PyErr

Performs the conversion.

impl From<&'_ timeout> for PyErr

fn from(err: &timeout) -> PyErr

Performs the conversion.

impl From<AddrParseError> for PyErr

fn from(err: AddrParseError) -> PyErr

Performs the conversion.

impl From<DecodeUtf16Error> for PyErr

fn from(err: DecodeUtf16Error) -> PyErr

Performs the conversion.

impl From<Error> for PyErr

Create OSError from io::Error

fn from(err: Error) -> PyErr

Performs the conversion.

impl From<FromUtf16Error> for PyErr

fn from(err: FromUtf16Error) -> PyErr

Performs the conversion.

impl From<FromUtf8Error> for PyErr

fn from(err: FromUtf8Error) -> PyErr

Performs the conversion.

impl From<Infallible> for PyErr

fn from(_: Infallible) -> PyErr

Performs the conversion.

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

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

Performs the conversion.

impl From<IntoStringError> for PyErr

fn from(err: IntoStringError) -> PyErr

Performs the conversion.

impl From<NulError> for PyErr

fn from(err: NulError) -> PyErr

Performs the conversion.

impl From<ParseBoolError> for PyErr

fn from(err: ParseBoolError) -> PyErr

Performs the conversion.

impl From<ParseFloatError> for PyErr

fn from(err: ParseFloatError) -> PyErr

Performs the conversion.

impl From<ParseIntError> for PyErr

fn from(err: ParseIntError) -> PyErr

Performs the conversion.

impl From<PyBorrowError> for PyErr

fn from(other: PyBorrowError) -> Self

Performs the conversion.

impl From<PyBorrowMutError> for PyErr

fn from(other: PyBorrowMutError) -> Self

Performs the conversion.

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

Convert PyDowncastError to Python TypeError.

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

Performs the conversion.

impl From<PyErr> for Error

Convert PyErr to io::Error

fn from(err: PyErr) -> Self

Performs the conversion.

impl From<TryFromIntError> for PyErr

fn from(err: TryFromIntError) -> PyErr

Performs the conversion.

impl From<TryFromSliceError> for PyErr

fn from(err: TryFromSliceError) -> PyErr

Performs the conversion.

impl From<Utf8Error> for PyErr

fn from(err: Utf8Error) -> PyErr

Performs the conversion.

impl IntoPy<Py<PyAny>> for PyErr

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

Performs the conversion.

impl<'a> IntoPy<Py<PyAny>> for &'a 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