Added add_note method to PyErr

Author: alex

guide/src/function/error-handling.md

@@ -231,6 +231,9 @@ fn wrapped_get_x() -> Result<i32, MyOtherError> {
 # }
 ```
 
+## Notes
+
+In Python 3.11 and up, notes can be added to Python exceptions to provide additional debugging information when printing the exception. In PyO3, you can use the `add_note` method on `PyErr` to accomplish this functionality.
 
 [`From`]: https://doc.rust-lang.org/stable/std/convert/trait.From.html
 [`Result<T, E>`]: https://doc.rust-lang.org/stable/std/result/enum.Result.html

newsfragments/5489.added.md

@@ -0,0 +1 @@
+Added `PyErr::add_note`

src/err/mod.rs

@@ -1,7 +1,11 @@
 use crate::instance::Bound;
+#[cfg(Py_3_11)]
+use crate::intern;
 use crate::panic::PanicException;
 use crate::type_object::PyTypeInfo;
 use crate::types::any::PyAnyMethods;
+#[cfg(Py_3_11)]
+use crate::types::PyString;
 use crate::types::{
     string::PyStringMethods, traceback::PyTracebackMethods, typeobject::PyTypeMethods, PyTraceback,
     PyTuple, PyTupleMethods, PyType,
@@ -655,6 +659,17 @@ impl PyErr {
         }
     }
 
+    /// Equivalent to calling `add_note` on the exception in Python.
+    #[cfg(Py_3_11)]
+    pub fn add_note<N: for<'py> IntoPyObject<'py, Target = PyString>>(
+        &self,
+        py: Python<'_>,
+        n: N,
+    ) -> PyResult<()> {
+        self.value(py).call_method1(intern!(py, "add_note"), (n,))?;
+        Ok(())
+    }
+
     #[inline]
     fn from_state(state: PyErrState) -> PyErr {
         PyErr { state }
@@ -1152,4 +1167,21 @@ mod tests {
             warnings.call_method0("resetwarnings").unwrap();
         });
     }
+
+    #[test]
+    #[cfg(Py_3_11)]
+    fn test_add_note() {
+        use crate::types::any::PyAnyMethods;
+        Python::attach(|py| {
+            let err = PyErr::new::<exceptions::PyValueError, _>("original error");
+            err.add_note(py, "additional context").unwrap();
+
+            let notes = err.value(py).getattr("__notes__").unwrap();
+            assert_eq!(notes.len().unwrap(), 1);
+            assert_eq!(
+                notes.get_item(0).unwrap().extract::<String>().unwrap(),
+                "additional context"
+            );
+        });
+    }
 }