From 0df3cfe8323bb77d70f1263bc4c1500a4200dcc2 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Tue, 21 Jun 2022 13:10:47 +0200 Subject: [PATCH] [doc] Add some examples for 'stop-iteration-return' --- .../messages/s/stop-iteration-return/bad.py | 20 +++++++++++ .../s/stop-iteration-return/details.rst | 3 +- .../messages/s/stop-iteration-return/good.py | 33 ++++++++++++++++++- .../s/stop-iteration-return/related.rst | 1 + 4 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 doc/data/messages/s/stop-iteration-return/bad.py create mode 100644 doc/data/messages/s/stop-iteration-return/related.rst diff --git a/doc/data/messages/s/stop-iteration-return/bad.py b/doc/data/messages/s/stop-iteration-return/bad.py new file mode 100644 index 0000000000..d4cd2b35aa --- /dev/null +++ b/doc/data/messages/s/stop-iteration-return/bad.py @@ -0,0 +1,20 @@ +def fruit_generator(): + for fruit in ["apple", "banana"]: + yield fruit + raise StopIteration # [stop-iteration-return] + + +def two_fruits_generator(fruits): + for fruit in fruits: + yield fruit, next(fruits) # [stop-iteration-return] + + +def two_good_fruits_generator(fruits): + for fruit in fruits: + if not fruit.is_tasty(): + continue + while True: + next_fruit = next(fruits) # [stop-iteration-return] + if next_fruit.is_tasty(): + yield fruit, next_fruit + break diff --git a/doc/data/messages/s/stop-iteration-return/details.rst b/doc/data/messages/s/stop-iteration-return/details.rst index ab82045295..c03f8e1636 100644 --- a/doc/data/messages/s/stop-iteration-return/details.rst +++ b/doc/data/messages/s/stop-iteration-return/details.rst @@ -1 +1,2 @@ -You can help us make the doc better `by contributing `_ ! +It's possible to give a default value to ``next`` or catch the ``StopIteration``, +or return directly. A ``StopIteration`` cannot be propagated from a generator. diff --git a/doc/data/messages/s/stop-iteration-return/good.py b/doc/data/messages/s/stop-iteration-return/good.py index c40beb573f..eec33d7e42 100644 --- a/doc/data/messages/s/stop-iteration-return/good.py +++ b/doc/data/messages/s/stop-iteration-return/good.py @@ -1 +1,32 @@ -# This is a placeholder for correct code for this message. +def fruit_generator(): + """The example is simple enough you don't need an explicit return.""" + for fruit in ["apple", "banana"]: + yield fruit + + +def two_fruits_generator(fruits): + """Catching the StopIteration.""" + for fruit in fruits: + try: + yield fruit, next(fruits) + except StopIteration: + print("Sorry there is only one fruit left.") + yield fruit, None + + +def two_good_fruits_generator(fruits): + """A return can be used to end the iterator early, but not a StopIteration.""" + for fruit in fruits: + if not fruit.is_tasty(): + continue + while True: + next_fruit = next(fruits, None) + if next_fruit is None: + print("Sorry there is only one fruit left.") + yield fruit, None + # We reached the end of the 'fruits' generator but raising a + # StopIteration instead of returning would create a RuntimeError + return + if next_fruit.is_tasty(): + yield fruit, next_fruit + break diff --git a/doc/data/messages/s/stop-iteration-return/related.rst b/doc/data/messages/s/stop-iteration-return/related.rst new file mode 100644 index 0000000000..60758c8f7b --- /dev/null +++ b/doc/data/messages/s/stop-iteration-return/related.rst @@ -0,0 +1 @@ +- `PEP 479 `_