pyo3/err/mod.rs
1use crate::instance::Bound;
2use crate::panic::PanicException;
3use crate::type_object::PyTypeInfo;
4use crate::types::any::PyAnyMethods;
5use crate::types::{
6 string::PyStringMethods, traceback::PyTracebackMethods, typeobject::PyTypeMethods, PyTraceback,
7 PyType,
8};
9use crate::{
10 exceptions::{self, PyBaseException},
11 ffi,
12};
13use crate::{Borrowed, BoundObject, Py, PyAny, PyObject, Python};
14use std::borrow::Cow;
15use std::ffi::CStr;
16
17mod err_state;
18mod impls;
19
20use crate::conversion::IntoPyObject;
21use err_state::{PyErrState, PyErrStateLazyFnOutput, PyErrStateNormalized};
22use std::convert::Infallible;
23
24/// Represents a Python exception.
25///
26/// To avoid needing access to [`Python`] in `Into` conversions to create `PyErr` (thus improving
27/// compatibility with `?` and other Rust errors) this type supports creating exceptions instances
28/// in a lazy fashion, where the full Python object for the exception is created only when needed.
29///
30/// Accessing the contained exception in any way, such as with [`value`](PyErr::value),
31/// [`get_type`](PyErr::get_type), or [`is_instance`](PyErr::is_instance)
32/// will create the full exception object if it was not already created.
33pub struct PyErr {
34 state: PyErrState,
35}
36
37// The inner value is only accessed through ways that require proving the gil is held
38#[cfg(feature = "nightly")]
39unsafe impl crate::marker::Ungil for PyErr {}
40
41/// Represents the result of a Python call.
42pub type PyResult<T> = Result<T, PyErr>;
43
44/// Error that indicates a failure to convert a PyAny to a more specific Python type.
45#[derive(Debug)]
46pub struct DowncastError<'a, 'py> {
47 from: Borrowed<'a, 'py, PyAny>,
48 to: Cow<'static, str>,
49}
50
51impl<'a, 'py> DowncastError<'a, 'py> {
52 /// Create a new `PyDowncastError` representing a failure to convert the object
53 /// `from` into the type named in `to`.
54 pub fn new(from: &'a Bound<'py, PyAny>, to: impl Into<Cow<'static, str>>) -> Self {
55 DowncastError {
56 from: from.as_borrowed(),
57 to: to.into(),
58 }
59 }
60 pub(crate) fn new_from_borrowed(
61 from: Borrowed<'a, 'py, PyAny>,
62 to: impl Into<Cow<'static, str>>,
63 ) -> Self {
64 DowncastError {
65 from,
66 to: to.into(),
67 }
68 }
69}
70
71/// Error that indicates a failure to convert a PyAny to a more specific Python type.
72#[derive(Debug)]
73pub struct DowncastIntoError<'py> {
74 from: Bound<'py, PyAny>,
75 to: Cow<'static, str>,
76}
77
78impl<'py> DowncastIntoError<'py> {
79 /// Create a new `DowncastIntoError` representing a failure to convert the object
80 /// `from` into the type named in `to`.
81 pub fn new(from: Bound<'py, PyAny>, to: impl Into<Cow<'static, str>>) -> Self {
82 DowncastIntoError {
83 from,
84 to: to.into(),
85 }
86 }
87
88 /// Consumes this `DowncastIntoError` and returns the original object, allowing continued
89 /// use of it after a failed conversion.
90 ///
91 /// See [`downcast_into`][PyAnyMethods::downcast_into] for an example.
92 pub fn into_inner(self) -> Bound<'py, PyAny> {
93 self.from
94 }
95}
96
97/// Helper conversion trait that allows to use custom arguments for lazy exception construction.
98pub trait PyErrArguments: Send + Sync {
99 /// Arguments for exception
100 fn arguments(self, py: Python<'_>) -> PyObject;
101}
102
103impl<T> PyErrArguments for T
104where
105 T: for<'py> IntoPyObject<'py> + Send + Sync,
106{
107 fn arguments(self, py: Python<'_>) -> PyObject {
108 // FIXME: `arguments` should become fallible
109 match self.into_pyobject(py) {
110 Ok(obj) => obj.into_any().unbind(),
111 Err(e) => panic!("Converting PyErr arguments failed: {}", e.into()),
112 }
113 }
114}
115
116impl PyErr {
117 /// Creates a new PyErr of type `T`.
118 ///
119 /// `args` can be:
120 /// * a tuple: the exception instance will be created using the equivalent to the Python
121 /// expression `T(*tuple)`
122 /// * any other value: the exception instance will be created using the equivalent to the Python
123 /// expression `T(value)`
124 ///
125 /// This exception instance will be initialized lazily. This avoids the need for the Python GIL
126 /// to be held, but requires `args` to be `Send` and `Sync`. If `args` is not `Send` or `Sync`,
127 /// consider using [`PyErr::from_value`] instead.
128 ///
129 /// If `T` does not inherit from `BaseException`, then a `TypeError` will be returned.
130 ///
131 /// If calling T's constructor with `args` raises an exception, that exception will be returned.
132 ///
133 /// # Examples
134 ///
135 /// ```
136 /// use pyo3::prelude::*;
137 /// use pyo3::exceptions::PyTypeError;
138 ///
139 /// #[pyfunction]
140 /// fn always_throws() -> PyResult<()> {
141 /// Err(PyErr::new::<PyTypeError, _>("Error message"))
142 /// }
143 /// #
144 /// # Python::with_gil(|py| {
145 /// # let fun = pyo3::wrap_pyfunction!(always_throws, py).unwrap();
146 /// # let err = fun.call0().expect_err("called a function that should always return an error but the return value was Ok");
147 /// # assert!(err.is_instance_of::<PyTypeError>(py))
148 /// # });
149 /// ```
150 ///
151 /// In most cases, you can use a concrete exception's constructor instead:
152 ///
153 /// ```
154 /// use pyo3::prelude::*;
155 /// use pyo3::exceptions::PyTypeError;
156 ///
157 /// #[pyfunction]
158 /// fn always_throws() -> PyResult<()> {
159 /// Err(PyTypeError::new_err("Error message"))
160 /// }
161 /// #
162 /// # Python::with_gil(|py| {
163 /// # let fun = pyo3::wrap_pyfunction!(always_throws, py).unwrap();
164 /// # let err = fun.call0().expect_err("called a function that should always return an error but the return value was Ok");
165 /// # assert!(err.is_instance_of::<PyTypeError>(py))
166 /// # });
167 /// ```
168 #[inline]
169 pub fn new<T, A>(args: A) -> PyErr
170 where
171 T: PyTypeInfo,
172 A: PyErrArguments + Send + Sync + 'static,
173 {
174 PyErr::from_state(PyErrState::lazy(Box::new(move |py| {
175 PyErrStateLazyFnOutput {
176 ptype: T::type_object(py).into(),
177 pvalue: args.arguments(py),
178 }
179 })))
180 }
181
182 /// Constructs a new PyErr from the given Python type and arguments.
183 ///
184 /// `ty` is the exception type; usually one of the standard exceptions
185 /// like `exceptions::PyRuntimeError`.
186 ///
187 /// `args` is either a tuple or a single value, with the same meaning as in [`PyErr::new`].
188 ///
189 /// If `ty` does not inherit from `BaseException`, then a `TypeError` will be returned.
190 ///
191 /// If calling `ty` with `args` raises an exception, that exception will be returned.
192 pub fn from_type<A>(ty: Bound<'_, PyType>, args: A) -> PyErr
193 where
194 A: PyErrArguments + Send + Sync + 'static,
195 {
196 PyErr::from_state(PyErrState::lazy_arguments(ty.unbind().into_any(), args))
197 }
198
199 /// Creates a new PyErr.
200 ///
201 /// If `obj` is a Python exception object, the PyErr will contain that object.
202 ///
203 /// If `obj` is a Python exception type object, this is equivalent to `PyErr::from_type(obj, ())`.
204 ///
205 /// Otherwise, a `TypeError` is created.
206 ///
207 /// # Examples
208 /// ```rust
209 /// use pyo3::prelude::*;
210 /// use pyo3::PyTypeInfo;
211 /// use pyo3::exceptions::PyTypeError;
212 /// use pyo3::types::PyString;
213 ///
214 /// Python::with_gil(|py| {
215 /// // Case #1: Exception object
216 /// let err = PyErr::from_value(PyTypeError::new_err("some type error")
217 /// .value(py).clone().into_any());
218 /// assert_eq!(err.to_string(), "TypeError: some type error");
219 ///
220 /// // Case #2: Exception type
221 /// let err = PyErr::from_value(PyTypeError::type_object(py).into_any());
222 /// assert_eq!(err.to_string(), "TypeError: ");
223 ///
224 /// // Case #3: Invalid exception value
225 /// let err = PyErr::from_value(PyString::new(py, "foo").into_any());
226 /// assert_eq!(
227 /// err.to_string(),
228 /// "TypeError: exceptions must derive from BaseException"
229 /// );
230 /// });
231 /// ```
232 pub fn from_value(obj: Bound<'_, PyAny>) -> PyErr {
233 let state = match obj.downcast_into::<PyBaseException>() {
234 Ok(obj) => PyErrState::normalized(PyErrStateNormalized::new(obj)),
235 Err(err) => {
236 // Assume obj is Type[Exception]; let later normalization handle if this
237 // is not the case
238 let obj = err.into_inner();
239 let py = obj.py();
240 PyErrState::lazy_arguments(obj.unbind(), py.None())
241 }
242 };
243
244 PyErr::from_state(state)
245 }
246
247 /// Returns the type of this exception.
248 ///
249 /// # Examples
250 /// ```rust
251 /// use pyo3::{prelude::*, exceptions::PyTypeError, types::PyType};
252 ///
253 /// Python::with_gil(|py| {
254 /// let err: PyErr = PyTypeError::new_err(("some type error",));
255 /// assert!(err.get_type(py).is(&PyType::new::<PyTypeError>(py)));
256 /// });
257 /// ```
258 pub fn get_type<'py>(&self, py: Python<'py>) -> Bound<'py, PyType> {
259 self.normalized(py).ptype(py)
260 }
261
262 /// Returns the value of this exception.
263 ///
264 /// # Examples
265 ///
266 /// ```rust
267 /// use pyo3::{exceptions::PyTypeError, PyErr, Python};
268 ///
269 /// Python::with_gil(|py| {
270 /// let err: PyErr = PyTypeError::new_err(("some type error",));
271 /// assert!(err.is_instance_of::<PyTypeError>(py));
272 /// assert_eq!(err.value(py).to_string(), "some type error");
273 /// });
274 /// ```
275 pub fn value<'py>(&self, py: Python<'py>) -> &Bound<'py, PyBaseException> {
276 self.normalized(py).pvalue.bind(py)
277 }
278
279 /// Consumes self to take ownership of the exception value contained in this error.
280 pub fn into_value(self, py: Python<'_>) -> Py<PyBaseException> {
281 // NB technically this causes one reference count increase and decrease in quick succession
282 // on pvalue, but it's probably not worth optimizing this right now for the additional code
283 // complexity.
284 let normalized = self.normalized(py);
285 let exc = normalized.pvalue.clone_ref(py);
286 if let Some(tb) = normalized.ptraceback(py) {
287 unsafe {
288 ffi::PyException_SetTraceback(exc.as_ptr(), tb.as_ptr());
289 }
290 }
291 exc
292 }
293
294 /// Returns the traceback of this exception object.
295 ///
296 /// # Examples
297 /// ```rust
298 /// use pyo3::{exceptions::PyTypeError, Python};
299 ///
300 /// Python::with_gil(|py| {
301 /// let err = PyTypeError::new_err(("some type error",));
302 /// assert!(err.traceback(py).is_none());
303 /// });
304 /// ```
305 pub fn traceback<'py>(&self, py: Python<'py>) -> Option<Bound<'py, PyTraceback>> {
306 self.normalized(py).ptraceback(py)
307 }
308
309 /// Gets whether an error is present in the Python interpreter's global state.
310 #[inline]
311 pub fn occurred(_: Python<'_>) -> bool {
312 unsafe { !ffi::PyErr_Occurred().is_null() }
313 }
314
315 /// Takes the current error from the Python interpreter's global state and clears the global
316 /// state. If no error is set, returns `None`.
317 ///
318 /// If the error is a `PanicException` (which would have originated from a panic in a pyo3
319 /// callback) then this function will resume the panic.
320 ///
321 /// Use this function when it is not known if an error should be present. If the error is
322 /// expected to have been set, for example from [`PyErr::occurred`] or by an error return value
323 /// from a C FFI function, use [`PyErr::fetch`].
324 pub fn take(py: Python<'_>) -> Option<PyErr> {
325 let state = PyErrStateNormalized::take(py)?;
326 let pvalue = state.pvalue.bind(py);
327 if pvalue.get_type().as_ptr() == PanicException::type_object_raw(py).cast() {
328 let msg: String = pvalue
329 .str()
330 .map(|py_str| py_str.to_string_lossy().into())
331 .unwrap_or_else(|_| String::from("Unwrapped panic from Python code"));
332 Self::print_panic_and_unwind(py, PyErrState::normalized(state), msg)
333 }
334
335 Some(PyErr::from_state(PyErrState::normalized(state)))
336 }
337
338 fn print_panic_and_unwind(py: Python<'_>, state: PyErrState, msg: String) -> ! {
339 eprintln!("--- PyO3 is resuming a panic after fetching a PanicException from Python. ---");
340 eprintln!("Python stack trace below:");
341
342 state.restore(py);
343
344 unsafe {
345 ffi::PyErr_PrintEx(0);
346 }
347
348 std::panic::resume_unwind(Box::new(msg))
349 }
350
351 /// Equivalent to [PyErr::take], but when no error is set:
352 /// - Panics in debug mode.
353 /// - Returns a `SystemError` in release mode.
354 ///
355 /// This behavior is consistent with Python's internal handling of what happens when a C return
356 /// value indicates an error occurred but the global error state is empty. (A lack of exception
357 /// should be treated as a bug in the code which returned an error code but did not set an
358 /// exception.)
359 ///
360 /// Use this function when the error is expected to have been set, for example from
361 /// [PyErr::occurred] or by an error return value from a C FFI function.
362 #[cfg_attr(debug_assertions, track_caller)]
363 #[inline]
364 pub fn fetch(py: Python<'_>) -> PyErr {
365 const FAILED_TO_FETCH: &str = "attempted to fetch exception but none was set";
366 match PyErr::take(py) {
367 Some(err) => err,
368 #[cfg(debug_assertions)]
369 None => panic!("{}", FAILED_TO_FETCH),
370 #[cfg(not(debug_assertions))]
371 None => exceptions::PySystemError::new_err(FAILED_TO_FETCH),
372 }
373 }
374
375 /// Creates a new exception type with the given name and docstring.
376 ///
377 /// - `base` can be an existing exception type to subclass, or a tuple of classes.
378 /// - `dict` specifies an optional dictionary of class variables and methods.
379 /// - `doc` will be the docstring seen by python users.
380 ///
381 ///
382 /// # Errors
383 ///
384 /// This function returns an error if `name` is not of the form `<module>.<ExceptionName>`.
385 pub fn new_type<'py>(
386 py: Python<'py>,
387 name: &CStr,
388 doc: Option<&CStr>,
389 base: Option<&Bound<'py, PyType>>,
390 dict: Option<PyObject>,
391 ) -> PyResult<Py<PyType>> {
392 let base: *mut ffi::PyObject = match base {
393 None => std::ptr::null_mut(),
394 Some(obj) => obj.as_ptr(),
395 };
396
397 let dict: *mut ffi::PyObject = match dict {
398 None => std::ptr::null_mut(),
399 Some(obj) => obj.as_ptr(),
400 };
401
402 let doc_ptr = match doc.as_ref() {
403 Some(c) => c.as_ptr(),
404 None => std::ptr::null(),
405 };
406
407 let ptr = unsafe { ffi::PyErr_NewExceptionWithDoc(name.as_ptr(), doc_ptr, base, dict) };
408
409 unsafe { Py::from_owned_ptr_or_err(py, ptr) }
410 }
411
412 /// Prints a standard traceback to `sys.stderr`.
413 pub fn display(&self, py: Python<'_>) {
414 #[cfg(Py_3_12)]
415 unsafe {
416 ffi::PyErr_DisplayException(self.value(py).as_ptr())
417 }
418
419 #[cfg(not(Py_3_12))]
420 unsafe {
421 // keep the bound `traceback` alive for entire duration of
422 // PyErr_Display. if we inline this, the `Bound` will be dropped
423 // after the argument got evaluated, leading to call with a dangling
424 // pointer.
425 let traceback = self.traceback(py);
426 let type_bound = self.get_type(py);
427 ffi::PyErr_Display(
428 type_bound.as_ptr(),
429 self.value(py).as_ptr(),
430 traceback
431 .as_ref()
432 .map_or(std::ptr::null_mut(), |traceback| traceback.as_ptr()),
433 )
434 }
435 }
436
437 /// Calls `sys.excepthook` and then prints a standard traceback to `sys.stderr`.
438 pub fn print(&self, py: Python<'_>) {
439 self.clone_ref(py).restore(py);
440 unsafe { ffi::PyErr_PrintEx(0) }
441 }
442
443 /// Calls `sys.excepthook` and then prints a standard traceback to `sys.stderr`.
444 ///
445 /// Additionally sets `sys.last_{type,value,traceback,exc}` attributes to this exception.
446 pub fn print_and_set_sys_last_vars(&self, py: Python<'_>) {
447 self.clone_ref(py).restore(py);
448 unsafe { ffi::PyErr_PrintEx(1) }
449 }
450
451 /// Returns true if the current exception matches the exception in `exc`.
452 ///
453 /// If `exc` is a class object, this also returns `true` when `self` is an instance of a subclass.
454 /// If `exc` is a tuple, all exceptions in the tuple (and recursively in subtuples) are searched for a match.
455 pub fn matches<'py, T>(&self, py: Python<'py>, exc: T) -> Result<bool, T::Error>
456 where
457 T: IntoPyObject<'py>,
458 {
459 Ok(self.is_instance(py, &exc.into_pyobject(py)?.into_any().as_borrowed()))
460 }
461
462 /// Returns true if the current exception is instance of `T`.
463 #[inline]
464 pub fn is_instance(&self, py: Python<'_>, ty: &Bound<'_, PyAny>) -> bool {
465 let type_bound = self.get_type(py);
466 (unsafe { ffi::PyErr_GivenExceptionMatches(type_bound.as_ptr(), ty.as_ptr()) }) != 0
467 }
468
469 /// Returns true if the current exception is instance of `T`.
470 #[inline]
471 pub fn is_instance_of<T>(&self, py: Python<'_>) -> bool
472 where
473 T: PyTypeInfo,
474 {
475 self.is_instance(py, &T::type_object(py))
476 }
477
478 /// Writes the error back to the Python interpreter's global state.
479 /// This is the opposite of `PyErr::fetch()`.
480 #[inline]
481 pub fn restore(self, py: Python<'_>) {
482 self.state.restore(py)
483 }
484
485 /// Reports the error as unraisable.
486 ///
487 /// This calls `sys.unraisablehook()` using the current exception and obj argument.
488 ///
489 /// This method is useful to report errors in situations where there is no good mechanism
490 /// to report back to the Python land. In Python this is used to indicate errors in
491 /// background threads or destructors which are protected. In Rust code this is commonly
492 /// useful when you are calling into a Python callback which might fail, but there is no
493 /// obvious way to handle this error other than logging it.
494 ///
495 /// Calling this method has the benefit that the error goes back into a standardized callback
496 /// in Python which for instance allows unittests to ensure that no unraisable error
497 /// actually happend by hooking `sys.unraisablehook`.
498 ///
499 /// Example:
500 /// ```rust
501 /// # use pyo3::prelude::*;
502 /// # use pyo3::exceptions::PyRuntimeError;
503 /// # fn failing_function() -> PyResult<()> { Err(PyRuntimeError::new_err("foo")) }
504 /// # fn main() -> PyResult<()> {
505 /// Python::with_gil(|py| {
506 /// match failing_function() {
507 /// Err(pyerr) => pyerr.write_unraisable(py, None),
508 /// Ok(..) => { /* do something here */ }
509 /// }
510 /// Ok(())
511 /// })
512 /// # }
513 #[inline]
514 pub fn write_unraisable(self, py: Python<'_>, obj: Option<&Bound<'_, PyAny>>) {
515 self.restore(py);
516 unsafe { ffi::PyErr_WriteUnraisable(obj.map_or(std::ptr::null_mut(), Bound::as_ptr)) }
517 }
518
519 /// Issues a warning message.
520 ///
521 /// May return an `Err(PyErr)` if warnings-as-errors is enabled.
522 ///
523 /// Equivalent to `warnings.warn()` in Python.
524 ///
525 /// The `category` should be one of the `Warning` classes available in
526 /// [`pyo3::exceptions`](crate::exceptions), or a subclass. The Python
527 /// object can be retrieved using [`Python::get_type()`].
528 ///
529 /// Example:
530 /// ```rust
531 /// # use pyo3::prelude::*;
532 /// # use pyo3::ffi::c_str;
533 /// # fn main() -> PyResult<()> {
534 /// Python::with_gil(|py| {
535 /// let user_warning = py.get_type::<pyo3::exceptions::PyUserWarning>();
536 /// PyErr::warn(py, &user_warning, c_str!("I am warning you"), 0)?;
537 /// Ok(())
538 /// })
539 /// # }
540 /// ```
541 pub fn warn<'py>(
542 py: Python<'py>,
543 category: &Bound<'py, PyAny>,
544 message: &CStr,
545 stacklevel: i32,
546 ) -> PyResult<()> {
547 error_on_minusone(py, unsafe {
548 ffi::PyErr_WarnEx(
549 category.as_ptr(),
550 message.as_ptr(),
551 stacklevel as ffi::Py_ssize_t,
552 )
553 })
554 }
555
556 /// Issues a warning message, with more control over the warning attributes.
557 ///
558 /// May return a `PyErr` if warnings-as-errors is enabled.
559 ///
560 /// Equivalent to `warnings.warn_explicit()` in Python.
561 ///
562 /// The `category` should be one of the `Warning` classes available in
563 /// [`pyo3::exceptions`](crate::exceptions), or a subclass.
564 pub fn warn_explicit<'py>(
565 py: Python<'py>,
566 category: &Bound<'py, PyAny>,
567 message: &CStr,
568 filename: &CStr,
569 lineno: i32,
570 module: Option<&CStr>,
571 registry: Option<&Bound<'py, PyAny>>,
572 ) -> PyResult<()> {
573 let module_ptr = match module {
574 None => std::ptr::null_mut(),
575 Some(s) => s.as_ptr(),
576 };
577 let registry: *mut ffi::PyObject = match registry {
578 None => std::ptr::null_mut(),
579 Some(obj) => obj.as_ptr(),
580 };
581 error_on_minusone(py, unsafe {
582 ffi::PyErr_WarnExplicit(
583 category.as_ptr(),
584 message.as_ptr(),
585 filename.as_ptr(),
586 lineno,
587 module_ptr,
588 registry,
589 )
590 })
591 }
592
593 /// Clone the PyErr. This requires the GIL, which is why PyErr does not implement Clone.
594 ///
595 /// # Examples
596 /// ```rust
597 /// use pyo3::{exceptions::PyTypeError, PyErr, Python, prelude::PyAnyMethods};
598 /// Python::with_gil(|py| {
599 /// let err: PyErr = PyTypeError::new_err(("some type error",));
600 /// let err_clone = err.clone_ref(py);
601 /// assert!(err.get_type(py).is(&err_clone.get_type(py)));
602 /// assert!(err.value(py).is(err_clone.value(py)));
603 /// match err.traceback(py) {
604 /// None => assert!(err_clone.traceback(py).is_none()),
605 /// Some(tb) => assert!(err_clone.traceback(py).unwrap().is(&tb)),
606 /// }
607 /// });
608 /// ```
609 #[inline]
610 pub fn clone_ref(&self, py: Python<'_>) -> PyErr {
611 PyErr::from_state(PyErrState::normalized(self.normalized(py).clone_ref(py)))
612 }
613
614 /// Return the cause (either an exception instance, or None, set by `raise ... from ...`)
615 /// associated with the exception, as accessible from Python through `__cause__`.
616 pub fn cause(&self, py: Python<'_>) -> Option<PyErr> {
617 use crate::ffi_ptr_ext::FfiPtrExt;
618 let obj =
619 unsafe { ffi::PyException_GetCause(self.value(py).as_ptr()).assume_owned_or_opt(py) };
620 // PyException_GetCause is documented as potentially returning PyNone, but only GraalPy seems to actually do that
621 #[cfg(GraalPy)]
622 if let Some(cause) = &obj {
623 if cause.is_none() {
624 return None;
625 }
626 }
627 obj.map(Self::from_value)
628 }
629
630 /// Set the cause associated with the exception, pass `None` to clear it.
631 pub fn set_cause(&self, py: Python<'_>, cause: Option<Self>) {
632 let value = self.value(py);
633 let cause = cause.map(|err| err.into_value(py));
634 unsafe {
635 // PyException_SetCause _steals_ a reference to cause, so must use .into_ptr()
636 ffi::PyException_SetCause(
637 value.as_ptr(),
638 cause.map_or(std::ptr::null_mut(), Py::into_ptr),
639 );
640 }
641 }
642
643 #[inline]
644 fn from_state(state: PyErrState) -> PyErr {
645 PyErr { state }
646 }
647
648 #[inline]
649 fn normalized(&self, py: Python<'_>) -> &PyErrStateNormalized {
650 self.state.as_normalized(py)
651 }
652}
653
654impl std::fmt::Debug for PyErr {
655 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
656 Python::with_gil(|py| {
657 f.debug_struct("PyErr")
658 .field("type", &self.get_type(py))
659 .field("value", self.value(py))
660 .field(
661 "traceback",
662 &self.traceback(py).map(|tb| match tb.format() {
663 Ok(s) => s,
664 Err(err) => {
665 err.write_unraisable(py, Some(&tb));
666 // It would be nice to format what we can of the
667 // error, but we can't guarantee that the error
668 // won't have another unformattable traceback inside
669 // it and we want to avoid an infinite recursion.
670 format!("<unformattable {:?}>", tb)
671 }
672 }),
673 )
674 .finish()
675 })
676 }
677}
678
679impl std::fmt::Display for PyErr {
680 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
681 Python::with_gil(|py| {
682 let value = self.value(py);
683 let type_name = value.get_type().qualname().map_err(|_| std::fmt::Error)?;
684 write!(f, "{}", type_name)?;
685 if let Ok(s) = value.str() {
686 write!(f, ": {}", &s.to_string_lossy())
687 } else {
688 write!(f, ": <exception str() failed>")
689 }
690 })
691 }
692}
693
694impl std::error::Error for PyErr {}
695
696impl<'py> IntoPyObject<'py> for PyErr {
697 type Target = PyBaseException;
698 type Output = Bound<'py, Self::Target>;
699 type Error = Infallible;
700
701 #[inline]
702 fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
703 Ok(self.into_value(py).into_bound(py))
704 }
705}
706
707impl<'py> IntoPyObject<'py> for &PyErr {
708 type Target = PyBaseException;
709 type Output = Bound<'py, Self::Target>;
710 type Error = Infallible;
711
712 #[inline]
713 fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
714 self.clone_ref(py).into_pyobject(py)
715 }
716}
717
718struct PyDowncastErrorArguments {
719 from: Py<PyType>,
720 to: Cow<'static, str>,
721}
722
723impl PyErrArguments for PyDowncastErrorArguments {
724 fn arguments(self, py: Python<'_>) -> PyObject {
725 const FAILED_TO_EXTRACT: Cow<'_, str> = Cow::Borrowed("<failed to extract type name>");
726 let from = self.from.bind(py).qualname();
727 let from = match &from {
728 Ok(qn) => qn.to_cow().unwrap_or(FAILED_TO_EXTRACT),
729 Err(_) => FAILED_TO_EXTRACT,
730 };
731 format!("'{}' object cannot be converted to '{}'", from, self.to)
732 .into_pyobject(py)
733 .unwrap()
734 .into_any()
735 .unbind()
736 }
737}
738
739/// Python exceptions that can be converted to [`PyErr`].
740///
741/// This is used to implement [`From<Bound<'_, T>> for PyErr`].
742///
743/// Users should not need to implement this trait directly. It is implemented automatically in the
744/// [`crate::import_exception!`] and [`crate::create_exception!`] macros.
745pub trait ToPyErr {}
746
747impl<'py, T> std::convert::From<Bound<'py, T>> for PyErr
748where
749 T: ToPyErr,
750{
751 #[inline]
752 fn from(err: Bound<'py, T>) -> PyErr {
753 PyErr::from_value(err.into_any())
754 }
755}
756
757/// Convert `DowncastError` to Python `TypeError`.
758impl std::convert::From<DowncastError<'_, '_>> for PyErr {
759 fn from(err: DowncastError<'_, '_>) -> PyErr {
760 let args = PyDowncastErrorArguments {
761 from: err.from.get_type().into(),
762 to: err.to,
763 };
764
765 exceptions::PyTypeError::new_err(args)
766 }
767}
768
769impl std::error::Error for DowncastError<'_, '_> {}
770
771impl std::fmt::Display for DowncastError<'_, '_> {
772 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
773 display_downcast_error(f, &self.from, &self.to)
774 }
775}
776
777/// Convert `DowncastIntoError` to Python `TypeError`.
778impl std::convert::From<DowncastIntoError<'_>> for PyErr {
779 fn from(err: DowncastIntoError<'_>) -> PyErr {
780 let args = PyDowncastErrorArguments {
781 from: err.from.get_type().into(),
782 to: err.to,
783 };
784
785 exceptions::PyTypeError::new_err(args)
786 }
787}
788
789impl std::error::Error for DowncastIntoError<'_> {}
790
791impl std::fmt::Display for DowncastIntoError<'_> {
792 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
793 display_downcast_error(f, &self.from, &self.to)
794 }
795}
796
797fn display_downcast_error(
798 f: &mut std::fmt::Formatter<'_>,
799 from: &Bound<'_, PyAny>,
800 to: &str,
801) -> std::fmt::Result {
802 write!(
803 f,
804 "'{}' object cannot be converted to '{}'",
805 from.get_type().qualname().map_err(|_| std::fmt::Error)?,
806 to
807 )
808}
809
810#[track_caller]
811pub fn panic_after_error(_py: Python<'_>) -> ! {
812 unsafe {
813 ffi::PyErr_Print();
814 }
815 panic!("Python API call failed");
816}
817
818/// Returns Ok if the error code is not -1.
819#[inline]
820pub(crate) fn error_on_minusone<T: SignedInteger>(py: Python<'_>, result: T) -> PyResult<()> {
821 if result != T::MINUS_ONE {
822 Ok(())
823 } else {
824 Err(PyErr::fetch(py))
825 }
826}
827
828pub(crate) trait SignedInteger: Eq {
829 const MINUS_ONE: Self;
830}
831
832macro_rules! impl_signed_integer {
833 ($t:ty) => {
834 impl SignedInteger for $t {
835 const MINUS_ONE: Self = -1;
836 }
837 };
838}
839
840impl_signed_integer!(i8);
841impl_signed_integer!(i16);
842impl_signed_integer!(i32);
843impl_signed_integer!(i64);
844impl_signed_integer!(i128);
845impl_signed_integer!(isize);
846
847#[cfg(test)]
848mod tests {
849 use super::PyErrState;
850 use crate::exceptions::{self, PyTypeError, PyValueError};
851 use crate::{ffi, PyErr, PyTypeInfo, Python};
852
853 #[test]
854 fn no_error() {
855 assert!(Python::with_gil(PyErr::take).is_none());
856 }
857
858 #[test]
859 fn set_valueerror() {
860 Python::with_gil(|py| {
861 let err: PyErr = exceptions::PyValueError::new_err("some exception message");
862 assert!(err.is_instance_of::<exceptions::PyValueError>(py));
863 err.restore(py);
864 assert!(PyErr::occurred(py));
865 let err = PyErr::fetch(py);
866 assert!(err.is_instance_of::<exceptions::PyValueError>(py));
867 assert_eq!(err.to_string(), "ValueError: some exception message");
868 })
869 }
870
871 #[test]
872 fn invalid_error_type() {
873 Python::with_gil(|py| {
874 let err: PyErr = PyErr::new::<crate::types::PyString, _>(());
875 assert!(err.is_instance_of::<exceptions::PyTypeError>(py));
876 err.restore(py);
877 let err = PyErr::fetch(py);
878
879 assert!(err.is_instance_of::<exceptions::PyTypeError>(py));
880 assert_eq!(
881 err.to_string(),
882 "TypeError: exceptions must derive from BaseException"
883 );
884 })
885 }
886
887 #[test]
888 fn set_typeerror() {
889 Python::with_gil(|py| {
890 let err: PyErr = exceptions::PyTypeError::new_err(());
891 err.restore(py);
892 assert!(PyErr::occurred(py));
893 drop(PyErr::fetch(py));
894 });
895 }
896
897 #[test]
898 #[should_panic(expected = "new panic")]
899 fn fetching_panic_exception_resumes_unwind() {
900 use crate::panic::PanicException;
901
902 Python::with_gil(|py| {
903 let err: PyErr = PanicException::new_err("new panic");
904 err.restore(py);
905 assert!(PyErr::occurred(py));
906
907 // should resume unwind
908 let _ = PyErr::fetch(py);
909 });
910 }
911
912 #[test]
913 #[should_panic(expected = "new panic")]
914 #[cfg(not(Py_3_12))]
915 fn fetching_normalized_panic_exception_resumes_unwind() {
916 use crate::panic::PanicException;
917
918 Python::with_gil(|py| {
919 let err: PyErr = PanicException::new_err("new panic");
920 // Restoring an error doesn't normalize it before Python 3.12,
921 // so we have to explicitly test this case.
922 let _ = err.normalized(py);
923 err.restore(py);
924 assert!(PyErr::occurred(py));
925
926 // should resume unwind
927 let _ = PyErr::fetch(py);
928 });
929 }
930
931 #[test]
932 fn err_debug() {
933 // Debug representation should be like the following (without the newlines):
934 // PyErr {
935 // type: <class 'Exception'>,
936 // value: Exception('banana'),
937 // traceback: Some(\"Traceback (most recent call last):\\n File \\\"<string>\\\", line 1, in <module>\\n\")
938 // }
939
940 Python::with_gil(|py| {
941 let err = py
942 .run(ffi::c_str!("raise Exception('banana')"), None, None)
943 .expect_err("raising should have given us an error");
944
945 let debug_str = format!("{:?}", err);
946 assert!(debug_str.starts_with("PyErr { "));
947 assert!(debug_str.ends_with(" }"));
948
949 // Strip "PyErr { " and " }". Split into 3 substrings to separate type,
950 // value, and traceback while not splitting the string within traceback.
951 let mut fields = debug_str["PyErr { ".len()..debug_str.len() - 2].splitn(3, ", ");
952
953 assert_eq!(fields.next().unwrap(), "type: <class 'Exception'>");
954 assert_eq!(fields.next().unwrap(), "value: Exception('banana')");
955 assert_eq!(
956 fields.next().unwrap(),
957 "traceback: Some(\"Traceback (most recent call last):\\n File \\\"<string>\\\", line 1, in <module>\\n\")"
958 );
959
960 assert!(fields.next().is_none());
961 });
962 }
963
964 #[test]
965 fn err_display() {
966 Python::with_gil(|py| {
967 let err = py
968 .run(ffi::c_str!("raise Exception('banana')"), None, None)
969 .expect_err("raising should have given us an error");
970 assert_eq!(err.to_string(), "Exception: banana");
971 });
972 }
973
974 #[test]
975 fn test_pyerr_send_sync() {
976 fn is_send<T: Send>() {}
977 fn is_sync<T: Sync>() {}
978
979 is_send::<PyErr>();
980 is_sync::<PyErr>();
981
982 is_send::<PyErrState>();
983 is_sync::<PyErrState>();
984 }
985
986 #[test]
987 fn test_pyerr_matches() {
988 Python::with_gil(|py| {
989 let err = PyErr::new::<PyValueError, _>("foo");
990 assert!(err.matches(py, PyValueError::type_object(py)).unwrap());
991
992 assert!(err
993 .matches(
994 py,
995 (PyValueError::type_object(py), PyTypeError::type_object(py))
996 )
997 .unwrap());
998
999 assert!(!err.matches(py, PyTypeError::type_object(py)).unwrap());
1000
1001 // String is not a valid exception class, so we should get a TypeError
1002 let err: PyErr = PyErr::from_type(crate::types::PyString::type_object(py), "foo");
1003 assert!(err.matches(py, PyTypeError::type_object(py)).unwrap());
1004 })
1005 }
1006
1007 #[test]
1008 fn test_pyerr_cause() {
1009 Python::with_gil(|py| {
1010 let err = py
1011 .run(ffi::c_str!("raise Exception('banana')"), None, None)
1012 .expect_err("raising should have given us an error");
1013 assert!(err.cause(py).is_none());
1014
1015 let err = py
1016 .run(
1017 ffi::c_str!("raise Exception('banana') from Exception('apple')"),
1018 None,
1019 None,
1020 )
1021 .expect_err("raising should have given us an error");
1022 let cause = err
1023 .cause(py)
1024 .expect("raising from should have given us a cause");
1025 assert_eq!(cause.to_string(), "Exception: apple");
1026
1027 err.set_cause(py, None);
1028 assert!(err.cause(py).is_none());
1029
1030 let new_cause = exceptions::PyValueError::new_err("orange");
1031 err.set_cause(py, Some(new_cause));
1032 let cause = err
1033 .cause(py)
1034 .expect("set_cause should have given us a cause");
1035 assert_eq!(cause.to_string(), "ValueError: orange");
1036 });
1037 }
1038
1039 #[test]
1040 fn warnings() {
1041 use crate::types::any::PyAnyMethods;
1042 // Note: although the warning filter is interpreter global, keeping the
1043 // GIL locked should prevent effects to be visible to other testing
1044 // threads.
1045 Python::with_gil(|py| {
1046 let cls = py.get_type::<exceptions::PyUserWarning>();
1047
1048 // Reset warning filter to default state
1049 let warnings = py.import("warnings").unwrap();
1050 warnings.call_method0("resetwarnings").unwrap();
1051
1052 // First, test the warning is emitted
1053 #[cfg(not(Py_GIL_DISABLED))]
1054 assert_warnings!(
1055 py,
1056 { PyErr::warn(py, &cls, ffi::c_str!("I am warning you"), 0).unwrap() },
1057 [(exceptions::PyUserWarning, "I am warning you")]
1058 );
1059
1060 // Test with raising
1061 warnings
1062 .call_method1("simplefilter", ("error", &cls))
1063 .unwrap();
1064 PyErr::warn(py, &cls, ffi::c_str!("I am warning you"), 0).unwrap_err();
1065
1066 // Test with error for an explicit module
1067 warnings.call_method0("resetwarnings").unwrap();
1068 warnings
1069 .call_method1("filterwarnings", ("error", "", &cls, "pyo3test"))
1070 .unwrap();
1071
1072 // This has the wrong module and will not raise, just be emitted
1073 #[cfg(not(Py_GIL_DISABLED))]
1074 assert_warnings!(
1075 py,
1076 { PyErr::warn(py, &cls, ffi::c_str!("I am warning you"), 0).unwrap() },
1077 [(exceptions::PyUserWarning, "I am warning you")]
1078 );
1079
1080 let err = PyErr::warn_explicit(
1081 py,
1082 &cls,
1083 ffi::c_str!("I am warning you"),
1084 ffi::c_str!("pyo3test.py"),
1085 427,
1086 None,
1087 None,
1088 )
1089 .unwrap_err();
1090 assert!(err
1091 .value(py)
1092 .getattr("args")
1093 .unwrap()
1094 .get_item(0)
1095 .unwrap()
1096 .eq("I am warning you")
1097 .unwrap());
1098
1099 // Finally, reset filter again
1100 warnings.call_method0("resetwarnings").unwrap();
1101 });
1102 }
1103}