pub struct PyErr { /* private fields */ }
Expand description
Represents a Python exception.
To avoid needing access to Python
in Into
conversions to create PyErr
(thus improving
compatibility with ?
and other Rust errors) this type supports creating exceptions instances
in a lazy fashion, where the full Python object for the exception is created only when needed.
Accessing the contained exception in any way, such as with value_bound
,
get_type_bound
, or is_instance_bound
will create the full exception object if it was not already created.
Implementations§
Source§impl PyErr
impl PyErr
Sourcepub fn new<T, A>(args: A) -> PyErr
pub fn new<T, A>(args: A) -> PyErr
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 exception instance will be initialized lazily. 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_bound
instead.
If T
does not inherit from BaseException
, then a TypeError
will be returned.
If calling T’s constructor with args
raises an exception, that exception will be returned.
§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"))
}
Sourcepub fn from_type_bound<A>(ty: Bound<'_, PyType>, args: A) -> PyErr
pub fn from_type_bound<A>(ty: Bound<'_, PyType>, args: A) -> PyErr
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 ty
does not inherit from BaseException
, then a TypeError
will be returned.
If calling ty
with args
raises an exception, that exception will be returned.
Sourcepub fn from_value_bound(obj: Bound<'_, PyAny>) -> PyErr
pub fn from_value_bound(obj: Bound<'_, PyAny>) -> PyErr
Creates a new PyErr.
If obj
is a Python exception object, the PyErr will contain that object.
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::PyTypeInfo;
use pyo3::exceptions::PyTypeError;
use pyo3::types::PyString;
Python::with_gil(|py| {
// Case #1: Exception object
let err = PyErr::from_value_bound(PyTypeError::new_err("some type error")
.value_bound(py).clone().into_any());
assert_eq!(err.to_string(), "TypeError: some type error");
// Case #2: Exception type
let err = PyErr::from_value_bound(PyTypeError::type_object_bound(py).into_any());
assert_eq!(err.to_string(), "TypeError: ");
// Case #3: Invalid exception value
let err = PyErr::from_value_bound(PyString::new_bound(py, "foo").into_any());
assert_eq!(
err.to_string(),
"TypeError: exceptions must derive from BaseException"
);
});
Sourcepub fn get_type_bound<'py>(&self, py: Python<'py>) -> Bound<'py, PyType>
pub fn get_type_bound<'py>(&self, py: Python<'py>) -> Bound<'py, PyType>
Returns the type of this exception.
§Examples
use pyo3::{prelude::*, exceptions::PyTypeError, types::PyType};
Python::with_gil(|py| {
let err: PyErr = PyTypeError::new_err(("some type error",));
assert!(err.get_type_bound(py).is(&PyType::new_bound::<PyTypeError>(py)));
});
Sourcepub fn value_bound<'py>(&self, py: Python<'py>) -> &Bound<'py, PyBaseException>
pub fn value_bound<'py>(&self, py: Python<'py>) -> &Bound<'py, PyBaseException>
Returns the value of this exception.
§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_bound(py).to_string(), "some type error");
});
Sourcepub fn into_value(self, py: Python<'_>) -> Py<PyBaseException>
pub fn into_value(self, py: Python<'_>) -> Py<PyBaseException>
Consumes self to take ownership of the exception value contained in this error.
Sourcepub fn traceback_bound<'py>(
&self,
py: Python<'py>,
) -> Option<Bound<'py, PyTraceback>>
pub fn traceback_bound<'py>( &self, py: Python<'py>, ) -> Option<Bound<'py, PyTraceback>>
Returns the traceback of this exception object.
§Examples
use pyo3::{exceptions::PyTypeError, Python};
Python::with_gil(|py| {
let err = PyTypeError::new_err(("some type error",));
assert!(err.traceback_bound(py).is_none());
});
Sourcepub fn occurred(_: Python<'_>) -> bool
pub fn occurred(_: Python<'_>) -> bool
Gets whether an error is present in the Python interpreter’s global state.
Sourcepub fn take(py: Python<'_>) -> Option<PyErr>
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
.
Sourcepub fn fetch(py: Python<'_>) -> PyErr
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.
Sourcepub fn new_type_bound<'py>(
py: Python<'py>,
name: &str,
doc: Option<&str>,
base: Option<&Bound<'py, PyType>>,
dict: Option<PyObject>,
) -> PyResult<Py<PyType>>
pub fn new_type_bound<'py>( py: Python<'py>, name: &str, doc: Option<&str>, base: Option<&Bound<'py, 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 CString
s.
Sourcepub fn print(&self, py: Python<'_>)
pub fn print(&self, py: Python<'_>)
Calls sys.excepthook
and then prints a standard traceback to sys.stderr
.
Sourcepub fn print_and_set_sys_last_vars(&self, py: Python<'_>)
pub fn print_and_set_sys_last_vars(&self, py: Python<'_>)
Calls sys.excepthook
and then prints a standard traceback to sys.stderr
.
Additionally sets sys.last_{type,value,traceback,exc}
attributes to this exception.
Sourcepub fn matches<T>(&self, py: Python<'_>, exc: T) -> boolwhere
T: ToPyObject,
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.
Sourcepub fn is_instance_bound(&self, py: Python<'_>, ty: &Bound<'_, PyAny>) -> bool
pub fn is_instance_bound(&self, py: Python<'_>, ty: &Bound<'_, PyAny>) -> bool
Returns true if the current exception is instance of T
.
Sourcepub fn is_instance_of<T>(&self, py: Python<'_>) -> boolwhere
T: PyTypeInfo,
pub fn is_instance_of<T>(&self, py: Python<'_>) -> boolwhere
T: PyTypeInfo,
Returns true if the current exception is instance of T
.
Sourcepub fn restore(self, py: Python<'_>)
pub fn restore(self, py: Python<'_>)
Writes the error back to the Python interpreter’s global state.
This is the opposite of PyErr::fetch()
.
Sourcepub fn write_unraisable_bound(
self,
py: Python<'_>,
obj: Option<&Bound<'_, PyAny>>,
)
pub fn write_unraisable_bound( self, py: Python<'_>, obj: Option<&Bound<'_, 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_bound(py, None),
Ok(..) => { /* do something here */ }
}
Ok(())
})
Sourcepub fn warn_bound<'py>(
py: Python<'py>,
category: &Bound<'py, PyAny>,
message: &str,
stacklevel: i32,
) -> PyResult<()>
pub fn warn_bound<'py>( py: Python<'py>, category: &Bound<'py, 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_bound()
.
Example:
Python::with_gil(|py| {
let user_warning = py.get_type_bound::<pyo3::exceptions::PyUserWarning>();
PyErr::warn_bound(py, &user_warning, "I am warning you", 0)?;
Ok(())
})
Sourcepub fn warn_explicit_bound<'py>(
py: Python<'py>,
category: &Bound<'py, PyAny>,
message: &str,
filename: &str,
lineno: i32,
module: Option<&str>,
registry: Option<&Bound<'py, PyAny>>,
) -> PyResult<()>
pub fn warn_explicit_bound<'py>( py: Python<'py>, category: &Bound<'py, PyAny>, message: &str, filename: &str, lineno: i32, module: Option<&str>, registry: Option<&Bound<'py, 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.
Sourcepub fn clone_ref(&self, py: Python<'_>) -> PyErr
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, prelude::PyAnyMethods};
Python::with_gil(|py| {
let err: PyErr = PyTypeError::new_err(("some type error",));
let err_clone = err.clone_ref(py);
assert!(err.get_type_bound(py).is(&err_clone.get_type_bound(py)));
assert!(err.value_bound(py).is(err_clone.value_bound(py)));
match err.traceback_bound(py) {
None => assert!(err_clone.traceback_bound(py).is_none()),
Some(tb) => assert!(err_clone.traceback_bound(py).unwrap().is(&tb)),
}
});
Trait Implementations§
Source§impl Error for PyErr
impl Error for PyErr
1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
Source§impl From<AddrParseError> for PyErr
impl From<AddrParseError> for PyErr
Source§fn from(err: AddrParseError) -> PyErr
fn from(err: AddrParseError) -> PyErr
Source§impl From<DecodeUtf16Error> for PyErr
impl From<DecodeUtf16Error> for PyErr
Source§fn from(err: DecodeUtf16Error) -> PyErr
fn from(err: DecodeUtf16Error) -> PyErr
Source§impl From<DowncastError<'_, '_>> for PyErr
Convert DowncastError
to Python TypeError
.
impl From<DowncastError<'_, '_>> for PyErr
Convert DowncastError
to Python TypeError
.
Source§fn from(err: DowncastError<'_, '_>) -> PyErr
fn from(err: DowncastError<'_, '_>) -> PyErr
Source§impl From<DowncastIntoError<'_>> for PyErr
Convert DowncastIntoError
to Python TypeError
.
impl From<DowncastIntoError<'_>> for PyErr
Convert DowncastIntoError
to Python TypeError
.
Source§fn from(err: DowncastIntoError<'_>) -> PyErr
fn from(err: DowncastIntoError<'_>) -> PyErr
Source§impl From<Error> for PyErr
Create PyErr
from io::Error
(OSError
except if the io::Error
is wrapping a Python exception,
in this case the exception is returned)
impl From<Error> for PyErr
Create PyErr
from io::Error
(OSError
except if the io::Error
is wrapping a Python exception,
in this case the exception is returned)