Merge pull request #2026 from davidhewitt/err-method-names

err: tweak names, inlining and docs

Author: davidhewitt

CHANGELOG.md

@@ -25,6 +25,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - `PyType::is_subclass`, `PyErr::is_instance` and `PyAny::is_instance` now operate run-time type object instead of a type known at compile-time. The old behavior is still available as `PyType::is_subclass_of`, `PyErr::is_instance_of` and `PyAny::is_instance_of`.  [#1985](https://github.com/PyO3/pyo3/pull/1985)
+- Rename some methods on `PyErr` (the old names are just marked deprecated for now): [#2026](https://github.com/PyO3/pyo3/pull/2026)
+  - `pytype` -> `get_type`
+  - `pvalue` -> `value` (and deprecate equivalent `instance`)
+  - `ptraceback` -> `traceback`
+  - `from_instance` -> `from_value`
+  - `into_instance` -> `into_value`
 
 ### Removed
 
@@ -34,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Fix undefined symbol for `PyObject_HasAttr` on PyPy. [#2025](https://github.com/PyO3/pyo3/pull/2025)
+- Fix memory leak in `PyErr::into_value`. [#2026](https://github.com/PyO3/pyo3/pull/2026)
 
 ## [0.15.1] - 2021-11-19
 

guide/src/exception.md

@@ -90,10 +90,10 @@ Python::with_gil(|py| {
 });
 ```
 
-If you already have a Python exception instance, you can simply call [`PyErr::from_instance`].
+If you already have a Python exception object, you can simply call [`PyErr::from_value`].
 
 ```rust,ignore
-PyErr::from_instance(py, err).restore(py);
+PyErr::from_value(py, err).restore(py);
 ```
 
 
@@ -134,7 +134,7 @@ which is an alias for the type `Result<T, PyErr>`.
 A [`PyErr`] represents a Python exception. Errors within the PyO3 library are also exposed as
 Python exceptions.
 
-If your code has a custom error type, adding an implementation of `std::convert::From<MyError> for PyErr` 
+If your code has a custom error type, adding an implementation of `std::convert::From<MyError> for PyErr`
 is usually enough. PyO3 will then automatically convert your error to a Python exception when needed.
 
 The following code snippet defines a Rust error named `CustomIOError`. In its `From<CustomIOError> for PyErr`
@@ -188,7 +188,7 @@ fn main() {
 ```
 
 This has been implemented for most of Rust's standard library errors, so that you can use the `?`
-("try") operator with them. The following code snippet will raise a `ValueError` in Python if 
+("try") operator with them. The following code snippet will raise a `ValueError` in Python if
 `String::parse()` returns an error.
 
 ```rust
@@ -254,6 +254,6 @@ defines exceptions for several standard library modules.
 
 [`PyErr`]: {{#PYO3_DOCS_URL}}/pyo3/struct.PyErr.html
 [`PyResult`]: {{#PYO3_DOCS_URL}}/pyo3/type.PyResult.html
-[`PyErr::from_instance`]: {{#PYO3_DOCS_URL}}/pyo3/struct.PyErr.html#method.from_instance
+[`PyErr::from_value`]: {{#PYO3_DOCS_URL}}/pyo3/struct.PyErr.html#method.from_value
 [`PyAny::is_instance`]: {{#PYO3_DOCS_URL}}/pyo3/struct.PyAny.html#method.is_instance
 [`PyAny::is_instance_of`]: {{#PYO3_DOCS_URL}}/pyo3/struct.PyAny.html#method.is_instance_of

guide/src/migration.md

@@ -170,7 +170,7 @@ let err: PyErr = TypeError::py_err("error message");
 
 After:
 
-```rust
+```rust,ignore
 # use pyo3::{PyErr, PyResult, Python, type_object::PyTypeObject};
 # use pyo3::exceptions::{PyBaseException, PyTypeError};
 # Python::with_gil(|py| -> PyResult<()> {

guide/src/python_from_rust.md

@@ -280,7 +280,7 @@ class House(object):
             Err(e) => {
                 house.call_method1(
                     "__exit__",
-                    (e.ptype(py), e.pvalue(py), e.ptraceback(py))
+                    (e.get_type(py), e.value(py), e.traceback(py))
                 ).unwrap();
             }
         }

pyo3-macros-backend/src/from_pyobject.rs

@@ -61,9 +61,9 @@ impl<'a> Enum<'a> {
 
                 match maybe_ret {
                     ok @ ::std::result::Result::Ok(_) => return ok,
-                    ::std::result::Result::Err(inner) => {
+                    ::std::result::Result::Err(err) => {
                         let py = ::pyo3::PyNativeType::py(obj);
-                        err_reasons.push_str(&::std::format!("{}\n", inner.instance(py).str()?));
+                        err_reasons.push_str(&::std::format!("{}\n", err.value(py).str()?));
                     }
                 }
             );
@@ -221,11 +221,11 @@ impl<'a> Container<'a> {
                 format!("failed to extract inner field of {}", quote!(#self_ty))
             };
             quote!(
-                ::std::result::Result::Ok(#self_ty(obj.extract().map_err(|inner| {
+                ::std::result::Result::Ok(#self_ty(obj.extract().map_err(|err| {
                     let py = ::pyo3::PyNativeType::py(obj);
                     let err_msg = ::std::format!("{}: {}",
                         #error_msg,
-                        inner.instance(py).str().unwrap());
+                        err.value(py).str().unwrap());
                     ::pyo3::exceptions::PyTypeError::new_err(err_msg)
                 })?))
             )

src/conversions/anyhow.rs

@@ -144,7 +144,7 @@ mod test_anyhow {
         Python::with_gil(|py| {
             let locals = [("err", pyerr)].into_py_dict(py);
             let pyerr = py.run("raise err", None, Some(locals)).unwrap_err();
-            assert_eq!(pyerr.pvalue(py).to_string(), expected_contents);
+            assert_eq!(pyerr.value(py).to_string(), expected_contents);
         })
     }
 
@@ -161,7 +161,7 @@ mod test_anyhow {
         Python::with_gil(|py| {
             let locals = [("err", pyerr)].into_py_dict(py);
             let pyerr = py.run("raise err", None, Some(locals)).unwrap_err();
-            assert_eq!(pyerr.pvalue(py).to_string(), expected_contents);
+            assert_eq!(pyerr.value(py).to_string(), expected_contents);
         })
     }
 }

src/conversions/eyre.rs

@@ -145,7 +145,7 @@ mod tests {
         Python::with_gil(|py| {
             let locals = [("err", pyerr)].into_py_dict(py);
             let pyerr = py.run("raise err", None, Some(locals)).unwrap_err();
-            assert_eq!(pyerr.pvalue(py).to_string(), expected_contents);
+            assert_eq!(pyerr.value(py).to_string(), expected_contents);
         })
     }
 }

src/derive_utils.rs

@@ -273,9 +273,9 @@ impl FunctionDescription {
 
 /// Add the argument name to the error message of an error which occurred during argument extraction
 pub fn argument_extraction_error(py: Python, arg_name: &str, error: PyErr) -> PyErr {
-    if error.ptype(py) == py.get_type::<PyTypeError>() {
+    if error.is_instance_of::<PyTypeError>(py) {
         let reason = error
-            .instance(py)
+            .value(py)
             .str()
             .unwrap_or_else(|_| PyString::new(py, ""));
         PyTypeError::new_err(format!("argument '{}': {}", arg_name, reason))