Struct pyo3::prelude::PyErr [−][src]
pub struct PyErr { /* fields omitted */ }
Expand description
Represents a Python exception that was raised.
Implementations
pub fn new<T, A>(args: A) -> PyErr where
T: PyTypeObject,
A: PyErrArguments + Send + Sync + 'static,
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"));
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
, 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__
.
Trait Implementations
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.
Convert PyDowncastError
to Python TypeError
.
Performs the conversion.
Convert PyErr
to io::Error
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.