From 0787b670e8598a2d0b232fee491fcda9bd0fa7ff Mon Sep 17 00:00:00 2001 From: David Hewitt <1939362+davidhewitt@users.noreply.github.com> Date: Thu, 21 Apr 2022 20:19:14 +0100 Subject: [PATCH] pyproto: make deprecated feature opt-in --- Architecture.md | 4 ++-- CHANGELOG.md | 4 ++++ Cargo.toml | 2 +- guide/src/class/protocols.md | 6 +++--- guide/src/features.md | 5 +---- guide/src/migration.md | 6 ++++++ 6 files changed, 17 insertions(+), 10 deletions(-) diff --git a/Architecture.md b/Architecture.md index d0e873f80a8..4fb84f4f05a 100644 --- a/Architecture.md +++ b/Architecture.md @@ -153,8 +153,8 @@ implemented in Python, such as GC support. ## 5. Procedural macros to simplify usage for users. -[`pyo3-macros`] provides six proc-macro APIs: `pymodule`, `pyproto`, `pyfunction`, `pyclass`, -`pymethods`, and `#[derive(FromPyObject)]`. +[`pyo3-macros`] provides five proc-macro APIs: `pymodule`, `pyfunction`, `pyclass`, +`pymethods`, and `#[derive(FromPyObject)]`. (And a deprecated `pyproto` macro.) [`pyo3-macros-backend`] has the actual implementations of these APIs. [`src/derive_utils.rs`] contains some utilities used in code generated by these proc-macros, such as parsing function arguments. diff --git a/CHANGELOG.md b/CHANGELOG.md index ddfece05260..eb6c484bcdd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Implement `ToPyObject` for `[T; N]`. [#2313](https://github.com/PyO3/pyo3/pull/2313) +### Changed + +- The deprecated `pyproto` feature is now disabled by default. [#2321](https://github.com/PyO3/pyo3/pull/2321) + ## [0.16.4] - 2022-04-14 ### Added diff --git a/Cargo.toml b/Cargo.toml index 5b91293d9d8..d6a20774d9e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -53,7 +53,7 @@ serde_json = "1.0.61" pyo3-build-config = { path = "pyo3-build-config", version = "0.16.4", features = ["resolve-config"] } [features] -default = ["macros", "pyproto"] +default = ["macros"] # Enables macros: #[pyclass], #[pymodule], #[pyfunction] etc. macros = ["pyo3-macros", "indoc", "unindent"] diff --git a/guide/src/class/protocols.md b/guide/src/class/protocols.md index 88e76d64372..716f45d51f6 100644 --- a/guide/src/class/protocols.md +++ b/guide/src/class/protocols.md @@ -4,8 +4,8 @@ Python's object model defines several protocols for different object behavior, s In the Python C-API which PyO3 is implemented upon, many of these magic methods have to be placed into special "slots" on the class type object, as covered in the previous section. There are two ways in which this can be done: - - [New in PyO3 0.15, recommended in PyO3 0.16] In `#[pymethods]`, if the name of the method is a recognised magic method, PyO3 will place it in the type object automatically. - - [Deprecated in PyO3 0.16] In special traits combined with the `#[pyproto]` attribute. + - In `#[pymethods]`, if the name of the method is a recognised magic method, PyO3 will place it in the type object automatically. + - [Deprecated since PyO3 0.16] In special traits combined with the `#[pyproto]` attribute. (There are also many magic methods which don't have a special slot, such as `__dir__`. These methods can be implemented as normal in `#[pymethods]`.) @@ -404,7 +404,7 @@ impl ClassWithGCSupport { PyO3 can use the `#[pyproto]` attribute in combination with special traits to implement the magic methods which need slots. The special traits are listed below. See also the [documentation for the `pyo3::class` module]({{#PYO3_DOCS_URL}}/pyo3/class/index.html). -Due to complexity in the implementation and usage, these traits are deprecated in PyO3 0.16 in favour of the `#[pymethods]` solution. +Due to complexity in the implementation and usage, these traits were deprecated in PyO3 0.16 in favour of the `#[pymethods]` solution. 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. diff --git a/guide/src/features.md b/guide/src/features.md index d37059582da..c67de97ec30 100644 --- a/guide/src/features.md +++ b/guide/src/features.md @@ -59,7 +59,6 @@ This feature enables a dependency on the `pyo3-macros` crate, which provides the - `#[pyfunction]` - `#[pyclass]` - `#[pymethods]` -- `#[pyproto]` - `#[derive(FromPyObject)]` It also provides the `py_run!` macro. @@ -78,9 +77,7 @@ See [the `#[pyclass]` implementation details](class.md#implementation-details) f ### `pyproto` -This feature enables the `#[pyproto]` macro, which is an alternative (older, soon-to-be-deprecated) to `#[pymethods]` for defining magic methods such as `__eq__`. - -> This feature is enabled by default. To disable it, set `default-features = false` for the `pyo3` entry in your Cargo.toml. +This feature enables the `#[pyproto]` macro, which is a deprecated alternative to `#[pymethods]` for defining magic methods such as `__eq__`. ### `nightly` diff --git a/guide/src/migration.md b/guide/src/migration.md index 7a763e667c3..725ff2cb3b3 100644 --- a/guide/src/migration.md +++ b/guide/src/migration.md @@ -3,6 +3,12 @@ This guide can help you upgrade code through breaking changes from one PyO3 version to the next. For a detailed list of all changes, see the [CHANGELOG](changelog.md). +## from 0.16.* to 0.17 + +### The `pyproto` feature is now disabled by default + +In preparation for removing the deprecated `#[pyproto]` attribute macro in a future PyO3 version, it is now gated behind an opt-in feature flag. This also gives a slight saving to compile times for code which does not use the deprecated macro. + ## from 0.15.* to 0.16 ### Drop support for older technologies