[−][src]Struct pyo3::PyErr

pub struct PyErr { /* fields omitted */ }

Represents a Python exception that was raised.

Implementations

`impl PyErr`[src]

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

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,` [src]

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`[src]

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.

Example

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`[src]

Get the type of this exception object.

The object will be normalized first if needed.

Example

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`[src]

Get the value of this exception object.

The object will be normalized first if needed.

Example

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

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

Get the value of this exception object.

The object will be normalized first if needed.

Example

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`[src]

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

`pub fn fetch(py: Python<'_>) -> PyErr`[src]

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>`[src]

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<'_>)`[src]

Prints a standard traceback to sys.stderr.

`pub fn print_and_set_sys_last_vars(&self, py: Python<'_>)`[src]

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,` [src]

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,` [src]

Returns true if the current exception is instance of T.

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

Retrieves the exception instance for this error.

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

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

`pub fn restore(self, py: Python<'_>)`[src]

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<()>`[src]

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

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

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

Example

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