Struct pyo3::PyErr[][src]

pub struct PyErr { /* fields omitted */ }
Expand description

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

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.

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"));

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.

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::{exceptions::PyTypeError, types::PyType, IntoPy, PyErr, Python};
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("foo".into_py(py).as_ref(py));
    assert_eq!(
        err.to_string(),
        "TypeError: exceptions must derive from BaseException"
    );
});

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_eq!(err.get_type(py), PyType::new::<PyTypeError>(py));
});

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");
});

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

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_eq!(err.traceback(py), None);
});

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

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.

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.

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

Prints a standard traceback to sys.stderr.

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

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.

Returns true if the current exception is instance of T.

Returns true if the current exception is instance of T.

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

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

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_eq!(err.get_type(py), err_clone.get_type(py));
    assert_eq!(err.value(py), err_clone.value(py));
    assert_eq!(err.traceback(py), err_clone.traceback(py));
});

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

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

👎 Deprecated since 0.16.0:

Use err.get_type(py) instead of err.ptype(py)

Deprecated name for PyErr::get_type.

👎 Deprecated since 0.16.0:

Use err.value(py) instead of err.pvalue(py)

Deprecated name for PyErr::value.

👎 Deprecated since 0.16.0:

Use err.traceback(py) instead of err.ptraceback(py)

Deprecated name for PyErr::traceback.

👎 Deprecated since 0.16.0:

Use err.value(py) instead of err.instance(py)

Deprecated name for PyErr::value.

👎 Deprecated since 0.16.0:

Use err.from_value(py, obj) instead of err.from_instance(py, obj)

Deprecated name for PyErr::from_value.

👎 Deprecated since 0.16.0:

Use err.into_value(py) instead of err.into_instance(py)

Deprecated name for PyErr::into_value.

Trait Implementations

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

The lower-level source of this error, if any. Read more

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

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

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Create OSError from io::Error

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Convert PyDowncastError to Python TypeError.

Performs the conversion.

Convert PyErr to io::Error

Performs the conversion.

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.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Converts self into a Python object.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Converts self into a Python object and calls the specified closure on the native FFI pointer underlying the Python object. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.