From 48823e22d6a58cfded05ea0fba127411ef7f450c Mon Sep 17 00:00:00 2001 From: David Hewitt <1939362+davidhewitt@users.noreply.github.com> Date: Mon, 12 Apr 2021 13:28:18 +0100 Subject: [PATCH] pyproto: deprecate py_methods --- CHANGELOG.md | 7 ++++++ benches/bench_pyclass.rs | 4 ---- guide/src/class/protocols.md | 31 +++++++------------------ guide/src/migration.md | 41 +++++++++++++++++++++++++++++++++ pyo3-macros-backend/src/defs.rs | 4 ++-- src/class/basic.rs | 8 +++++++ src/class/context.rs | 8 +++++++ src/class/descr.rs | 8 +++++++ src/class/mapping.rs | 4 ++++ src/class/number.rs | 8 +++++++ src/class/pyasync.rs | 8 +++++++ tests/test_arithmetics.rs | 2 ++ tests/test_dunder.rs | 2 ++ tests/test_mapping.rs | 2 ++ 14 files changed, 108 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d0d8510114..52b189385c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Deprecate `PyModule` methods `call`, `call0`, `call1` and `get`. [#1492](https://github.com/PyO3/pyo3/pull/1492) - Add length information to `PyBufferError`s raised from `PyBuffer::copy_to_slice` and `PyBuffer::copy_from_slice`. [#1534](https://github.com/PyO3/pyo3/pull/1534) - Automatically provide `-undefined` and `dynamic_lookup` linker arguments on macOS with `extension-module` feature. [#1539](https://github.com/PyO3/pyo3/pull/1539) +- Deprecate `#[pyproto]` methods which are easier to implement as `#[pymethods]`: [#1560](https://github.com/PyO3/pyo3/pull/1560) + - `PyBasicProtocol::__bytes__` and `PyBasicProtocol::__format__` + - `PyContextProtocol::__enter__` and `PyContextProtocol::__exit__` + - `PyDescrProtocol::__delete__` and `PyDescrProtocol::__set_name__` + - `PyMappingProtocol::__reversed__` + - `PyNumberProtocol::__complex__` and `PyNumberProtocol::__round__` + - `PyAsyncProtocol::__aenter__` and `PyAsyncProtocol::__aexit__` ### Removed - Remove deprecated exception names `BaseException` etc. [#1426](https://github.com/PyO3/pyo3/pull/1426) diff --git a/benches/bench_pyclass.rs b/benches/bench_pyclass.rs index c1a41d8d84b..efff4442074 100644 --- a/benches/bench_pyclass.rs +++ b/benches/bench_pyclass.rs @@ -31,10 +31,6 @@ impl PyObjectProtocol for MyClass { fn __str__(&self) -> &'static str { "MyClass" } - - fn __bytes__(&self) -> &'static [u8] { - b"MyClass" - } } #[bench] diff --git a/guide/src/class/protocols.md b/guide/src/class/protocols.md index b138568ca77..83ab8c592a9 100644 --- a/guide/src/class/protocols.md +++ b/guide/src/class/protocols.md @@ -1,12 +1,14 @@ ## Class customizations -Python's object model defines several protocols for different object behavior, like sequence, -mapping or number protocols. PyO3 defines separate traits for each of them. To provide specific -Python object behavior, you need to implement the specific trait for your struct. Important note, -each protocol implementation block has to be annotated with the `#[pyproto]` attribute. +PyO3 uses the `#[pyproto]` attribute in combination with special traits to implement certain protocol (aka `__dunder__`) methods of Python classes. The special traits are listed in this chapter of the guide. See also the [documentation for the `pyo3::class` module]({{#PYO3_DOCS_URL}}/pyo3/class/index.html). -All `#[pyproto]` methods which can be defined below can return `T` instead of `PyResult` if the -method implementation is infallible. In addition, if the return type is `()`, it can be omitted altogether. +Python's object model defines several protocols for different object behavior, such as the sequence, mapping, and number protocols. You may be familiar with implementing these protocols in Python classes by "dunder" methods, such as `__str__` or `__repr__`. + +In the Python C-API which PyO3 is dependent upon, many of these protocol methods have to be provided into special "slots" on the class type object. To fill these slots PyO3 uses the `#[pyproto]` attribute in combination with special traits. + +All `#[pyproto]` methods can return `T` instead of `PyResult` if the method implementation is infallible. In addition, if the return type is `()`, it can be omitted altogether. + +There are many "dunder" methods which are not included in any of PyO3's protocol traits, such as `__dir__`. These methods can be implemented in `#[pymethods]` as already covered in the previous section. ### Basic object customization @@ -29,15 +31,6 @@ Each method corresponds to Python's `self.attr`, `self.attr = value` and `del se Possible return types for `__str__` and `__repr__` are `PyResult` or `PyResult`. - * `fn __bytes__(&self) -> PyResult` - - Provides the conversion to `bytes`. - - * `fn __format__(&self, format_spec: &str) -> PyResult>` - - Special method that is used by the `format()` builtin and the `str.format()` method. - Possible return types are `PyResult` or `PyResult`. - #### Comparison operators * `fn __richcmp__(&self, other: impl FromPyObject, op: CompareOp) -> PyResult` @@ -132,14 +125,12 @@ The following methods implement the unary arithmetic operations (`-`, `+`, `abs( Support for coercions: - * `fn __complex__(&'p self) -> PyResult` * `fn __int__(&'p self) -> PyResult` * `fn __float__(&'p self) -> PyResult` Other: * `fn __index__(&'p self) -> PyResult` - * `fn __round__(&'p self, ndigits: Option) -> PyResult` ### Emulating sequential containers (such as lists or tuples) @@ -237,12 +228,6 @@ For a mapping, the keys may be Python objects of arbitrary type. The same exceptions should be raised for improper key values as for the `__getitem__()` method. - * `fn __reversed__(&self) -> PyResult` - - Called (if present) by the `reversed()` built-in to implement reverse iteration. - It should return a new iterator object that iterates over all the objects in - the container in reverse order. - ### Garbage Collector Integration If your type owns references to other Python objects, you will need to diff --git a/guide/src/migration.md b/guide/src/migration.md index 1b1cb725f4b..b0855381076 100644 --- a/guide/src/migration.md +++ b/guide/src/migration.md @@ -15,6 +15,47 @@ For projects embedding Python in Rust, PyO3 no longer automatically initalizes a The limitation of the new default implementation is that it cannot support multiple `#[pymethods]` blocks for the same `#[pyclass]`. If you need this functionality, you must enable the `multiple-pymethods` feature which will switch `#[pymethods]` to the inventory-based implementation. +### Deprecated `#[pyproto]` methods + +Some protocol (aka `__dunder__`) methods such as `__bytes__` and `__format__` have been possible to implement two ways in PyO3 for some time: via a `#[pyproto]` (e.g. `PyBasicProtocol` for the methods listed here), or by writing them directly in `#[pymethods]`. This is only true for a handful of the `#[pyproto]` methods (for technical reasons to do with the way PyO3 currently interacts with the Python C-API). + +In the interest of having onle one way to do things, the `#[pyproto]` forms of these methods have been deprecated. + +To migrate just move the affected methods from a `#[pyproto]` to a `#[pymethods]` block. + +Before: + +```rust,ignore +use pyo3::prelude::*; +use pyo3::class::basic::PyBasicProtocol; + +#[pyclass] +struct MyClass { } + +#[pyproto] +impl PyBasicProtocol for MyClass { + fn __bytes__(&self) -> &'static [u8] { + b"hello, world" + } +} +``` + +After: + +```rust +use pyo3::prelude::*; + +#[pyclass] +struct MyClass { } + +#[pymethods] +impl MyClass { + fn __bytes__(&self) -> &'static [u8] { + b"hello, world" + } +} +``` + ## from 0.12.* to 0.13 ### Minimum Rust version increased to Rust 1.45 diff --git a/pyo3-macros-backend/src/defs.rs b/pyo3-macros-backend/src/defs.rs index e6fa8391abf..d64cd7bd78a 100644 --- a/pyo3-macros-backend/src/defs.rs +++ b/pyo3-macros-backend/src/defs.rs @@ -268,7 +268,7 @@ pub const DESCR: Proto = Proto { methods: &[ MethodProto::new("__get__", "PyDescrGetProtocol").args(&["Receiver", "Inst", "Owner"]), MethodProto::new("__set__", "PyDescrSetProtocol").args(&["Receiver", "Inst", "Value"]), - MethodProto::new("__det__", "PyDescrDelProtocol") + MethodProto::new("__delete__", "PyDescrDelProtocol") .args(&["Inst"]) .has_self(), MethodProto::new("__set_name__", "PyDescrSetNameProtocol") @@ -276,7 +276,7 @@ pub const DESCR: Proto = Proto { .has_self(), ], py_methods: &[ - PyMethod::new("__del__", "PyDescrDelProtocolImpl"), + PyMethod::new("__delete__", "PyDescrDelProtocolImpl"), PyMethod::new("__set_name__", "PyDescrNameProtocolImpl"), ], slot_defs: &[ diff --git a/src/class/basic.rs b/src/class/basic.rs index d796343c57a..a6e6027436c 100644 --- a/src/class/basic.rs +++ b/src/class/basic.rs @@ -61,6 +61,10 @@ pub trait PyObjectProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__format__` in `#[pymethods]` instead of in a protocol" + )] fn __format__(&'p self, format_spec: Self::Format) -> Self::Result where Self: PyObjectFormatProtocol<'p>, @@ -75,6 +79,10 @@ pub trait PyObjectProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__bytes__` in `#[pymethods]` instead of in a protocol" + )] fn __bytes__(&'p self) -> Self::Result where Self: PyObjectBytesProtocol<'p>, diff --git a/src/class/context.rs b/src/class/context.rs index a5aa83a7852..ac0cc24834a 100644 --- a/src/class/context.rs +++ b/src/class/context.rs @@ -10,6 +10,10 @@ use crate::{PyClass, PyObject}; /// Context manager interface #[allow(unused_variables)] pub trait PyContextProtocol<'p>: PyClass { + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__enter__` in `#[pymethods]` instead of in a protocol" + )] fn __enter__(&'p mut self) -> Self::Result where Self: PyContextEnterProtocol<'p>, @@ -17,6 +21,10 @@ pub trait PyContextProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__exit__` in `#[pymethods]` instead of in a protocol" + )] fn __exit__( &'p mut self, exc_type: Option, diff --git a/src/class/descr.rs b/src/class/descr.rs index d489bb59643..9cc775a9900 100644 --- a/src/class/descr.rs +++ b/src/class/descr.rs @@ -31,6 +31,10 @@ pub trait PyDescrProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__delete__` in `#[pymethods]` instead of in a protocol" + )] fn __delete__(&'p self, instance: &'p PyAny) -> Self::Result where Self: PyDescrDeleteProtocol<'p>, @@ -38,6 +42,10 @@ pub trait PyDescrProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__set_name__` in `#[pymethods]` instead of in a protocol" + )] fn __set_name__(&'p self, instance: &'p PyAny) -> Self::Result where Self: PyDescrSetNameProtocol<'p>, diff --git a/src/class/mapping.rs b/src/class/mapping.rs index bad8e556553..870bfb78fa2 100644 --- a/src/class/mapping.rs +++ b/src/class/mapping.rs @@ -37,6 +37,10 @@ pub trait PyMappingProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__reversed__` in `#[pymethods]` instead of in a protocol" + )] fn __reversed__(&'p self) -> Self::Result where Self: PyMappingReversedProtocol<'p>, diff --git a/src/class/number.rs b/src/class/number.rs index 7c7b91bc405..20dc8c3d15f 100644 --- a/src/class/number.rs +++ b/src/class/number.rs @@ -283,6 +283,10 @@ pub trait PyNumberProtocol<'p>: PyClass { { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__complex__` in `#[pymethods]` instead of in a protocol" + )] fn __complex__(&'p self) -> Self::Result where Self: PyNumberComplexProtocol<'p>, @@ -307,6 +311,10 @@ pub trait PyNumberProtocol<'p>: PyClass { { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__round__` in `#[pymethods]` instead of in a protocol" + )] fn __round__(&'p self, ndigits: Option) -> Self::Result where Self: PyNumberRoundProtocol<'p>, diff --git a/src/class/pyasync.rs b/src/class/pyasync.rs index 81efa8379d2..69143e70374 100644 --- a/src/class/pyasync.rs +++ b/src/class/pyasync.rs @@ -39,6 +39,10 @@ pub trait PyAsyncProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__aenter__` in `#[pymethods]` instead of in a protocol" + )] fn __aenter__(&'p mut self) -> Self::Result where Self: PyAsyncAenterProtocol<'p>, @@ -46,6 +50,10 @@ pub trait PyAsyncProtocol<'p>: PyClass { unimplemented!() } + #[deprecated( + since = "0.14.0", + note = "prefer implementing `__aexit__` in `#[pymethods]` instead of in a protocol" + )] fn __aexit__( &'p mut self, exc_type: Option, diff --git a/tests/test_arithmetics.rs b/tests/test_arithmetics.rs index 5fd8195203e..19c30eb98d6 100644 --- a/tests/test_arithmetics.rs +++ b/tests/test_arithmetics.rs @@ -1,3 +1,5 @@ +#![allow(deprecated)] // for deprecated protocol methods + use pyo3::class::basic::CompareOp; use pyo3::class::*; use pyo3::prelude::*; diff --git a/tests/test_dunder.rs b/tests/test_dunder.rs index ab8e6f6d1c9..52c190f40d6 100644 --- a/tests/test_dunder.rs +++ b/tests/test_dunder.rs @@ -1,3 +1,5 @@ +#![allow(deprecated)] // for deprecated protocol methods + use pyo3::class::{ PyAsyncProtocol, PyContextProtocol, PyDescrProtocol, PyIterProtocol, PyMappingProtocol, PyObjectProtocol, PySequenceProtocol, diff --git a/tests/test_mapping.rs b/tests/test_mapping.rs index 34e726dc295..42710094e76 100644 --- a/tests/test_mapping.rs +++ b/tests/test_mapping.rs @@ -1,3 +1,5 @@ +#![allow(deprecated)] // for deprecated protocol methods + use std::collections::HashMap; use pyo3::exceptions::PyKeyError;