err: tweak names, inlining and docs

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))