Struct pyo3::PyErr

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

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.

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::{exceptions::PyTypeError, types::PyType, IntoPy, PyErr, Python};
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"
    );
});

Get the type of this exception object.

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.ptype(py), PyType::new::<PyTypeError>(py));
});

Get the value of this exception object.

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::<PyTypeError>(py));
    assert_eq!(err.pvalue(py).to_string(), "some type error");
});

Get the value 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.ptraceback(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.

Retrieves the exception instance for this error.

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

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.ptype(py), err_clone.ptype(py));
    assert_eq!(err.pvalue(py), err_clone.pvalue(py));
    assert_eq!(err.ptraceback(py), err_clone.ptraceback(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.

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

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

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Performs the conversion.

Performs the conversion.

Converts self into a Python object.

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

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

Performs the conversion.

Performs the conversion.