Merge pull request #2173 from davidhewitt/deprecate-pyproto

pyproto: deprecate protocol traits

Architecture.md

@@ -144,20 +144,12 @@ For example, you can see `type({})` shows `dict` and `type(type({}))` shows `typ
 
 ## 4. Protocol methods
 
-Python has some built-in special methods called dunder, such as `__iter__`.
-They are called [abstract objects layer](https://docs.python.org/3/c-api/abstract.html) in
+Python has some built-in special methods called dunder methods, such as `__iter__`.
+They are called "slots" in the [abstract objects layer](https://docs.python.org/3/c-api/abstract.html) in
 Python/C API.
-We provide a way to implement those protocols by using `#[pyproto]` and specific traits, such
-as `PyIterProtocol`.
-[`src/class`] defines these traits.
-Each protocol method has a corresponding FFI function.
-For example, `PyIterProtocol::__iter__` has
-`pub unsafe extern "C" fn iter<T>(slf: *mut PyObject) -> *mut PyObject`.
-When `#[pyproto]` finds that `T` implements `PyIterProtocol::__iter__`, it automatically
-sets `iter<T>` on the type object of `T`.
-
-Also, [`src/class/methods.rs`] has utilities for `#[pyfunction]` and [`src/class/impl_.rs`] has
-some internal tricks for making `#[pyproto]` flexible.
+We provide a way to implement those protocols similarly, by recognizing special
+names in `#[pymethods]`, with a few new ones for slots that can not be
+implemented in Python, such as GC support.
 
 ## 5. Procedural macros to simplify usage for users.
 

CHANGELOG.md

@@ -73,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `PyDate_FromTimestamp`
 - Deprecate the `gc` option for `pyclass` (e.g. `#[pyclass(gc)]`). Just implement a `__traverse__` `#[pymethod]`. [#2159](https://github.com/PyO3/pyo3/pull/2159)
 - The `ml_meth` field of `PyMethodDef` is now represented by the `PyMethodDefPointer` union [2166](https://github.com/PyO3/pyo3/pull/2166)
-- The `PyTypeError` thrown when argument parsing failed now contains the nested causes [2177](https://github.com/PyO3/pyo3/pull/2178)
+- Deprecate the `#[pyproto]` traits. [#2173](https://github.com/PyO3/pyo3/pull/2173)
 
 ### Removed
 
@@ -92,6 +92,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add missing FFI definitions `_PyLong_NumBits` and `_PyLong_AsByteArray` on PyPy. [#2146](https://github.com/PyO3/pyo3/pull/2146)
 - Fix memory leak in implementation of `AsPyPointer` for `Option<T>`. [#2160](https://github.com/PyO3/pyo3/pull/2160)
 - Fix the signature of `_PyLong_NumBits` [#2161](https://github.com/PyO3/pyo3/pull/2161)
+- Fix `TypeError` thrown when argument parsing failed missing the originating causes. [2177](https://github.com/PyO3/pyo3/pull/2178)
 
 ## [0.15.1] - 2021-11-19
 

benches/bench_pyclass.rs

@@ -1,5 +1,5 @@
 use criterion::{criterion_group, criterion_main, Criterion};
-use pyo3::{class::PyObjectProtocol, prelude::*, type_object::LazyStaticType};
+use pyo3::{prelude::*, type_object::LazyStaticType};
 
 /// This is a feature-rich class instance used to benchmark various parts of the pyclass lifecycle.
 #[pyclass]
@@ -19,10 +19,7 @@ impl MyClass {
         self.elements.push(new_element);
         self.elements.len()
     }
-}
 
-#[pyproto]
-impl PyObjectProtocol for MyClass {
     /// A basic __str__ implementation.
     fn __str__(&self) -> &'static str {
         "MyClass"

guide/src/class.md

@@ -2,7 +2,7 @@
 
 PyO3 exposes a group of attributes powered by Rust's proc macro system for defining Python classes as Rust structs.
 
-The main attribute is `#[pyclass]`, which is placed upon a Rust `struct` or a fieldless `enum` (a.k.a. C-like enum) to generate a Python type for it. They will usually also have *one* `#[pymethods]`-annotated `impl` block for the struct, which is used to define Python methods and constants for the generated Python type. (If the [`multiple-pymethods`] feature is enabled each `#[pyclass]` is allowed to have multiple `#[pymethods]` blocks.) Finally, there may be multiple `#[pyproto]` trait implementations for the struct, which are used to define certain python magic methods such as `__str__`.
+The main attribute is `#[pyclass]`, which is placed upon a Rust `struct` or a fieldless `enum` (a.k.a. C-like enum) to generate a Python type for it. They will usually also have *one* `#[pymethods]`-annotated `impl` block for the struct, which is used to define Python methods and constants for the generated Python type. (If the [`multiple-pymethods`] feature is enabled each `#[pyclass]` is allowed to have multiple `#[pymethods]` blocks.) `#[pymethods]` may also have implementations for Python magic methods such as `__str__`.
 
 This chapter will discuss the functionality and configuration these attributes offer. Below is a list of links to the relevant section of this chapter for each:
 
@@ -16,7 +16,7 @@ This chapter will discuss the functionality and configuration these attributes o
   - [`#[classmethod]`](#class-methods)
   - [`#[classattr]`](#class-attributes)
   - [`#[args]`](#method-arguments)
-- [`#[pyproto]`](class/protocols.html)
+- [Magic methods and slots](class/protocols.html)
 
 ## Defining a new class
 
@@ -926,9 +926,9 @@ enum BadSubclass{
 
 ## Implementation details
 
-The `#[pyclass]` macros rely on a lot of conditional code generation: each `#[pyclass]` can optionally have a `#[pymethods]` block as well as several different possible `#[pyproto]` trait implementations.
+The `#[pyclass]` macros rely on a lot of conditional code generation: each `#[pyclass]` can optionally have a `#[pymethods]` block.
 
-To support this flexibility the `#[pyclass]` macro expands to a blob of boilerplate code which sets up the structure for ["dtolnay specialization"](https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md). This implementation pattern enables the Rust compiler to use `#[pymethods]` and `#[pyproto]` implementations when they are present, and fall back to default (empty) definitions when they are not.
+To support this flexibility the `#[pyclass]` macro expands to a blob of boilerplate code which sets up the structure for ["dtolnay specialization"](https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md). This implementation pattern enables the Rust compiler to use `#[pymethods]` implementations when they are present, and fall back to default (empty) definitions when they are not.
 
 This simple technique works for the case when there is zero or one implementations. To support multiple `#[pymethods]` for a `#[pyclass]` (in the [`multiple-pymethods`] feature), a registry mechanism provided by the [`inventory`](https://github.com/dtolnay/inventory) crate is used instead. This collects `impl`s at library load time, but isn't supported on all platforms. See [inventory: how it works](https://github.com/dtolnay/inventory#how-it-works) for more details.