[Python-checkins] Docs: Clarify the before_and_after() example (GH-28458) (#28464)

[rhettinger]

https://github.com/python/cpython/commit/697b6650ed29cdd4c347e9d35c43e084eff22c5f
commit: 697b6650ed29cdd4c347e9d35c43e084eff22c5f
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2021-09-19T20:53:37-05:00
summary:

Docs: Clarify the before_and_after() example (GH-28458) (#28464)

(cherry picked from commit fcbf9b176b1190301c760a921601c6488ef8b070)

Co-authored-by: Raymond Hettinger <rhettinger at users.noreply.github.com>

Co-authored-by: Raymond Hettinger <rhettinger at users.noreply.github.com>

files:
M Doc/library/itertools.rst
M Lib/test/test_itertools.py

diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index ac6b354138b6e..61d8b869711fa 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -859,10 +859,11 @@ which incur interpreter overhead.
        """ Variant of takewhile() that allows complete
            access to the remainder of the iterator.
 
-           >>> all_upper, remainder = before_and_after(str.isupper, 'ABCdEfGhI')
-           >>> str.join('', all_upper)
+           >>> it = iter('ABCdEfGhI')
+           >>> all_upper, remainder = before_and_after(str.isupper, it)
+           >>> ''.join(all_upper)
            'ABC'
-           >>> str.join('', remainder)
+           >>> ''.join(remainder)     # takewhile() would lose the 'd'
            'dEfGhI'
 
            Note that the first iterator must be fully
diff --git a/Lib/test/test_itertools.py b/Lib/test/test_itertools.py
index aa81076f32d00..a12f6f0b9773e 100644
--- a/Lib/test/test_itertools.py
+++ b/Lib/test/test_itertools.py
@@ -2605,10 +2605,11 @@ def test_permutations_sizeof(self):
 >>> list(odds)
 [1, 3, 5, 7, 9]
 
->>> all_upper, remainder = before_and_after(str.isupper, 'ABCdEfGhI')
->>> str.join('', all_upper)
+>>> it = iter('ABCdEfGhI')
+>>> all_upper, remainder = before_and_after(str.isupper, it)
+>>> ''.join(all_upper)
 'ABC'
->>> str.join('', remainder)
+>>> ''.join(remainder)
 'dEfGhI'
 
 >>> list(powerset([1,2,3]))