From 559b540b5c9d727df0ad2a138ee82890ec39d2b1 Mon Sep 17 00:00:00 2001 From: cfour2 Date: Mon, 1 May 2023 21:43:49 +0800 Subject: [PATCH 1/3] Fix a crate doc link for IterNextOutput --- guide/src/class/protocols.md | 2 +- src/pyclass.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/src/class/protocols.md b/guide/src/class/protocols.md index 3f3cc769f3d..51df95b4097 100644 --- a/guide/src/class/protocols.md +++ b/guide/src/class/protocols.md @@ -409,6 +409,6 @@ impl ClassWithGCSupport { > Note: these methods are part of the C API, PyPy does not necessarily honor them. If you are building for PyPy you should measure memory consumption to make sure you do not have runaway memory growth. See [this issue on the PyPy bug tracker](https://foss.heptapod.net/pypy/pypy/-/issues/3899). -[`IterNextOutput`]: {{#PYO3_DOCS_URL}}/pyo3/class/iter/enum.IterNextOutput.html +[`IterNextOutput`]: {{#PYO3_DOCS_URL}}/pyo3/pyclass/enum.IterNextOutput.html [`PySequence`]: {{#PYO3_DOCS_URL}}/pyo3/types/struct.PySequence.html [`CompareOp::matches`]: {{#PYO3_DOCS_URL}}/pyo3/pyclass/enum.CompareOp.html#method.matches diff --git a/src/pyclass.rs b/src/pyclass.rs index 028f3591ed4..c9d7f9fdbe2 100644 --- a/src/pyclass.rs +++ b/src/pyclass.rs @@ -90,7 +90,7 @@ impl CompareOp { /// Output of `__next__` which can either `yield` the next value in the iteration, or /// `return` a value to raise `StopIteration` in Python. /// -/// See [`PyIterProtocol`](trait.PyIterProtocol.html) for an example. +/// See [this test](https://github.com/PyO3/pyo3/blob/main/pytests/src/pyclasses.rs#L15-L36) for an example. pub enum IterNextOutput { /// The value yielded by the iterator. Yield(T), From 1ca1dc3ccb255ad012605161ef49df3ef8846e6f Mon Sep 17 00:00:00 2001 From: cfour2 Date: Mon, 1 May 2023 23:38:56 +0800 Subject: [PATCH 2/3] Copy an example for `IterNextOutput` from pytests with comments --- src/pyclass.rs | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/src/pyclass.rs b/src/pyclass.rs index c9d7f9fdbe2..04cda2021e3 100644 --- a/src/pyclass.rs +++ b/src/pyclass.rs @@ -90,7 +90,42 @@ impl CompareOp { /// Output of `__next__` which can either `yield` the next value in the iteration, or /// `return` a value to raise `StopIteration` in Python. /// -/// See [this test](https://github.com/PyO3/pyo3/blob/main/pytests/src/pyclasses.rs#L15-L36) for an example. +/// Usage example: +/// +/// ```rust +/// use pyo3::prelude::*; +/// use pyo3::iter::IterNextOutput; +/// +/// #[pyclass] +/// struct PyClassIter { +/// count: usize, +/// } +/// +/// #[pymethods] +/// impl PyClassIter { +/// #[new] +/// pub fn new() -> Self { +/// PyClassIter { count: 0 } +/// } +/// +/// fn __next__(&mut self) -> IterNextOutput { +/// if self.count < 5 { +/// self.count += 1; +/// // Given an instance `counter`, First five `next(counter)` calls yield 1, 2, 3, 4, 5. +/// IterNextOutput::Yield(self.count) +/// } else { +/// // At the sixth time, we get a `StopIteration` with `'Ended'`. +/// // try: +/// // next(couter) +/// // except StopIteration as e: +/// // assert e.value == 'Ended' +/// IterNextOutput::Return("Ended") +/// } +/// } +/// } +/// ``` +/// +/// The example above is copied from [this test](https://github.com/PyO3/pyo3/blob/main/pytests/src/pyclasses.rs#L15-L36). pub enum IterNextOutput { /// The value yielded by the iterator. Yield(T), From 04f129f70f95c54855534a606fd7a08ced8eb089 Mon Sep 17 00:00:00 2001 From: cfour2 Date: Tue, 2 May 2023 15:03:20 +0800 Subject: [PATCH 3/3] Refine the example for `IterNextOutput` * Remove the (eventually) stale ref link; * Typo: couter -> counter; * Fix the formatting with `cargo fmt`; --- src/pyclass.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/pyclass.rs b/src/pyclass.rs index 04cda2021e3..432f45a1c71 100644 --- a/src/pyclass.rs +++ b/src/pyclass.rs @@ -100,14 +100,14 @@ impl CompareOp { /// struct PyClassIter { /// count: usize, /// } -/// +/// /// #[pymethods] /// impl PyClassIter { /// #[new] /// pub fn new() -> Self { /// PyClassIter { count: 0 } /// } -/// +/// /// fn __next__(&mut self) -> IterNextOutput { /// if self.count < 5 { /// self.count += 1; @@ -116,7 +116,7 @@ impl CompareOp { /// } else { /// // At the sixth time, we get a `StopIteration` with `'Ended'`. /// // try: -/// // next(couter) +/// // next(counter) /// // except StopIteration as e: /// // assert e.value == 'Ended' /// IterNextOutput::Return("Ended") @@ -124,8 +124,6 @@ impl CompareOp { /// } /// } /// ``` -/// -/// The example above is copied from [this test](https://github.com/PyO3/pyo3/blob/main/pytests/src/pyclasses.rs#L15-L36). pub enum IterNextOutput { /// The value yielded by the iterator. Yield(T),