https://github.com/python/cpython/commit/988cdccbe06cd938c83e4fd8dc4bfb6d88e6b9d8
commit: 988cdccbe06cd938c83e4fd8dc4bfb6d88e6b9d8
branch: 3.13
author: Raymond Hettinger <[email protected]>
committer: rhettinger <[email protected]>
date: 2024-10-08T14:29:15-05:00
summary:
[3.13] Itertool docs: Minor clarifications, wording tweaks, spacing, and active
voice. (gh-124690) (gh-125148)
Minor clarifications, wording tweaks, spacing, and active voice.
files:
M Doc/library/itertools.rst
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 8eb8d07b3fb064..e9af6829267fdf 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -58,7 +58,7 @@ Iterator Arguments
Results
:func:`compress` data, selectors (d[0] if
s[0]), (d[1] if s[1]), ... ``compress('ABCDEF', [1,0,1,0,1,1])
→ A C E F``
:func:`dropwhile` predicate, seq seq[n],
seq[n+1], starting when predicate fails ``dropwhile(lambda x: x<5,
[1,4,6,3,8]) → 6 3 8``
:func:`filterfalse` predicate, seq elements of
seq where predicate(elem) fails ``filterfalse(lambda x: x<5,
[1,4,6,3,8]) → 6 8``
-:func:`groupby` iterable[, key] sub-iterators
grouped by value of key(v)
+:func:`groupby` iterable[, key] sub-iterators
grouped by value of key(v) ``groupby(['A','B','DEF'], len) → (1, A
B) (3, DEF)``
:func:`islice` seq, [start,] stop [, step] elements from
seq[start:stop:step] ``islice('ABCDEFG', 2, None) → C D E F G``
:func:`pairwise` iterable (p[0], p[1]),
(p[1], p[2]) ``pairwise('ABCDEFG') → AB BC CD DE EF
FG``
:func:`starmap` func, seq
func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5),
(3,2), (10,3)]) → 32 9 1000``
@@ -93,7 +93,7 @@ Examples Results
Itertool Functions
------------------
-The following module functions all construct and return iterators. Some provide
+The following functions all construct and return iterators. Some provide
streams of infinite length, so they should only be accessed by functions or
loops that truncate the stream.
@@ -131,11 +131,12 @@ loops that truncate the stream.
total = function(total, element)
yield total
- The *function* argument can be set to :func:`min` for a running
- minimum, :func:`max` for a running maximum, or :func:`operator.mul`
- for a running product. `Amortization tables
- <https://www.ramseysolutions.com/real-estate/amortization-schedule>`_
- can be built by accumulating interest and applying payments:
+ To compute a running minimum, set *function* to :func:`min`.
+ For a running maximum, set *function* to :func:`max`.
+ Or for a running product, set *function* to :func:`operator.mul`.
+ To build an `Amortization table
+ <https://www.ramseysolutions.com/real-estate/amortization-schedule>`_,
+ accumulate the interest and apply payments:
.. doctest::
@@ -202,10 +203,10 @@ loops that truncate the stream.
.. function:: chain(*iterables)
- Make an iterator that returns elements from the first iterable until it is
- exhausted, then proceeds to the next iterable, until all of the iterables
are
- exhausted. Used for treating consecutive sequences as a single sequence.
- Roughly equivalent to::
+ Make an iterator that returns elements from the first iterable until
+ it is exhausted, then proceeds to the next iterable, until all of the
+ iterables are exhausted. This combines multiple data sources into a
+ single iterator. Roughly equivalent to::
def chain(*iterables):
# chain('ABC', 'DEF') → A B C D E F
@@ -353,10 +354,12 @@ loops that truncate the stream.
def cycle(iterable):
# cycle('ABCD') → A B C D A B C D A B C D ...
+
saved = []
for element in iterable:
yield element
saved.append(element)
+
while saved:
for element in saved:
yield element
@@ -396,8 +399,10 @@ loops that truncate the stream.
def filterfalse(predicate, iterable):
# filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8
+
if predicate is None:
predicate = bool
+
for x in iterable:
if not predicate(x):
yield x
@@ -474,7 +479,7 @@ loops that truncate the stream.
If *start* is zero or ``None``, iteration starts at zero. Otherwise,
elements from the iterable are skipped until *start* is reached.
- If *stop* is ``None``, iteration continues until the iterable is
+ If *stop* is ``None``, iteration continues until the input is
exhausted, if at all. Otherwise, it stops at the specified position.
If *step* is ``None``, the step defaults to one. Elements are returned
@@ -520,8 +525,10 @@ loops that truncate the stream.
def pairwise(iterable):
# pairwise('ABCDEFG') → AB BC CD DE EF FG
+
iterator = iter(iterable)
a = next(iterator, None)
+
for b in iterator:
yield a, b
a = b
@@ -584,7 +591,8 @@ loops that truncate the stream.
.. function:: product(*iterables, repeat=1)
- Cartesian product of input iterables.
+ `Cartesian product <https://en.wikipedia.org/wiki/Cartesian_product>`_
+ of the input iterables.
Roughly equivalent to nested for-loops in a generator expression. For
example,
``product(A, B)`` returns the same as ``((x,y) for x in A for y in B)``.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
