"itertools" --- 为高效循环创建迭代器的函数
******************************************

======================================================================

本模块实现一系列 *iterator* ，这些迭代器受到APL，Haskell和SML的启发。
为了适用于Python，它们都被重新写过。

本模块标准化了一个快速、高效利用内存的核心工具集，这些工具本身或组合都
很有用。它们一起形成了“迭代器代数”，这使得在纯Python中有可能创建简洁又
高效的专用工具。

例如，SML有一个制表工具： "tabulate(f)"，它可产生一个序列 "f(0), f(1),
..."。在Python中可以组合 "map()" 和 "count()" 实现： "map(f, count())"
。

这些工具及其内置对应物也能很好地配合 "operator" 模块中的快速函数来使用
。 例如，乘法运算符可以被映射到两个向量之间执行高效的点积:
"sum(starmap(operator.mul, zip(vec1, vec2, strict=True)))"。

**无穷迭代器：**

+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+
| 迭代器             | 实参              | 结果                                              | 示例                                      |
|====================|===================|===================================================|===========================================|
| "count()"          | [start[, step]]   | start, start+step, start+2*step, ...              | "count(10) → 10 11 12 13 14 ..."          |
+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+
| "cycle()"          | p                 | p0, p1, ... plast, p0, p1, ...                    | "cycle('ABCD') → A B C D A B C D ..."     |
+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+
| "repeat()"         | elem [,n]         | elem, elem, elem, ... 重复无限次或n次             | "repeat(10, 3) → 10 10 10"                |
+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+

**根据最短输入序列长度停止的迭代器：**

+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| 迭代器                       | 实参                         | 结果                                              | 示例                                                          |
|==============================|==============================|===================================================|===============================================================|
| "accumulate()"               | p [,func]                    | p0, p0+p1, p0+p1+p2, ...                          | "accumulate([1,2,3,4,5]) → 1 3 6 10 15"                       |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "batched()"                  | p, n                         | (p0, p1, ..., p_n-1), ...                         | "batched('ABCDEFG', n=3) → ABC DEF G"                         |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "chain()"                    | p, q, ...                    | p0, p1, ... plast, q0, q1, ...                    | "chain('ABC', 'DEF') → A B C D E F"                           |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "chain.from_iterable()"      | iterable -- 可迭代对象       | p0, p1, ... plast, q0, q1, ...                    | "chain.from_iterable(['ABC', 'DEF']) → A B C D E F"           |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "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"                 |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "dropwhile()"                | predicate, seq               | seq[n], seq[n+1], 从 predicate 未通过时开始       | "dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8"               |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "filterfalse()"              | predicate, seq               | predicate(elem) 未通过的 seq 元素                 | "filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8"               |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "groupby()"                  | iterable[, key]              | 根据key(v)值分组的迭代器                          |                                                               |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "islice()"                   | seq, [start,] stop [, step]  | seq[start:stop:step]中的元素                      | "islice('ABCDEFG', 2, None) → C D E F G"                      |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "pairwise()"                 | iterable -- 可迭代对象       | (p[0], p[1]), (p[1], p[2])                        | "pairwise('ABCDEFG') → AB BC CD DE EF FG"                     |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "starmap()"                  | func, seq                    | func(*seq[0]), func(*seq[1]), ...                 | "starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000"            |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "takewhile()"                | predicate, seq               | seq[0], seq[1], 直到 predicate 未通过             | "takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4"                 |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "tee()"                      | it, n                        | it1, it2, ... itn 将一个迭代器拆分为n个迭代器     |                                                               |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "zip_longest()"              | p, q, ...                    | (p[0], q[0]), (p[1], q[1]), ...                   | "zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-"      |
+------------------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+

**排列组合迭代器：**

+------------------------------------------------+----------------------+---------------------------------------------------------------+
| 迭代器                                         | 实参                 | 结果                                                          |
|================================================|======================|===============================================================|
| "product()"                                    | p, q, ... [repeat=1] | 笛卡尔积，相当于嵌套的for循环                                 |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "permutations()"                               | p[, r]               | 长度r元组，所有可能的排列，无重复元素                         |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "combinations()"                               | p, r                 | 长度r元组，有序，无重复元素                                   |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "combinations_with_replacement()"              | p, r                 | 长度r元组，有序，元素可重复                                   |
+------------------------------------------------+----------------------+---------------------------------------------------------------+

+------------------------------------------------+---------------------------------------------------------------+
| 例子                                           | 结果                                                          |
|================================================|===============================================================|
| "product('ABCD', repeat=2)"                    | "AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD"             |
+------------------------------------------------+---------------------------------------------------------------+
| "permutations('ABCD', 2)"                      | "AB AC AD BA BC BD CA CB CD DA DB DC"                         |
+------------------------------------------------+---------------------------------------------------------------+
| "combinations('ABCD', 2)"                      | "AB AC AD BC BD CD"                                           |
+------------------------------------------------+---------------------------------------------------------------+
| "combinations_with_replacement('ABCD', 2)"     | "AA AB AC AD BB BC BD CC CD DD"                               |
+------------------------------------------------+---------------------------------------------------------------+


Itertool 函数
=============

下列模块函数均创建并返回迭代器。有些迭代器不限制输出流长度，所以它们只
应在能截断输出流的函数或循环中使用。

itertools.accumulate(iterable[, function, *, initial=None])

   Make an iterator that returns accumulated sums or accumulated
   results from other binary functions.

   The *function* defaults to addition.  The *function* should accept
   two arguments, an accumulated total and a value from the
   *iterable*.

   If an *initial* value is provided, the accumulation will start with
   that value and the output will have one more element than the input
   iterable.

   大致相当于：

      def accumulate(iterable, function=operator.add, *, initial=None):
          'Return running totals'
          # accumulate([1,2,3,4,5]) → 1 3 6 10 15
          # accumulate([1,2,3,4,5], initial=100) → 100 101 103 106 110 115
          # accumulate([1,2,3,4,5], operator.mul) → 1 2 6 24 120

          iterator = iter(iterable)
          total = initial
          if initial is None:
              try:
                  total = next(iterator)
              except StopIteration:
                  return

          yield total
          for element in iterator:
              total = function(total, element)
              yield total

   The *function* argument can be set to "min()" for a running
   minimum, "max()" for a running maximum, or "operator.mul()" for a
   running product.  Amortization tables can be built by accumulating
   interest and applying payments:

      >>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
      >>> list(accumulate(data, max))              # running maximum
      [3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
      >>> list(accumulate(data, operator.mul))     # running product
      [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]

      # Amortize a 5% loan of 1000 with 10 annual payments of 90
      >>> update = lambda balance, payment: round(balance * 1.05) - payment
      >>> list(accumulate(repeat(90, 10), update, initial=1_000))
      [1000, 960, 918, 874, 828, 779, 728, 674, 618, 559, 497]

   参考一个类似函数  "functools.reduce()"  ，它只返回一个最终累积值。

   Added in version 3.2.

   在 3.3 版本发生变更: Added the optional *function* parameter.

   在 3.8 版本发生变更: 添加了可选的 *initial* 形参。

itertools.batched(iterable, n)

   来自 *iterable* 的长度为 *n* 元组形式的批次数据。 最后一个批次可能
   短于 *n*。

   循环处理输入可迭代对象并将数据积累为长度至多为 *n* 的元组。 输入将
   被惰性地消耗，能填满一个批次即可。 结果将在批次填满或输入可迭代对象
   被耗尽时产生:

      >>> flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
      >>> unflattened = list(batched(flattened_data, 2))
      >>> unflattened
      [('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')]

   大致相当于：

      def batched(iterable, n):
          # batched('ABCDEFG', 3) → ABC DEF G
          if n < 1:
              raise ValueError('n must be at least one')
          iterator = iter(iterable)
          while batch := tuple(islice(iterator, n)):
              yield batch

   Added in version 3.12.

itertools.chain(*iterables)

   创建一个迭代器，它首先返回第一个可迭代对象中所有元素，接着返回下一
   个可迭代对象中所有元素，直到耗尽所有可迭代对象中的元素。可将多个序
   列处理为单个序列。大致相当于：

      def chain(*iterables):
          # chain('ABC', 'DEF') → A B C D E F
          for iterable in iterables:
              yield from iterable

classmethod chain.from_iterable(iterable)

   构建类似 "chain()" 迭代器的另一个选择。从一个单独的可迭代参数中得到
   链式输入，该参数是延迟计算的。大致相当于：

      def from_iterable(iterables):
          # chain.from_iterable(['ABC', 'DEF']) → A B C D E F
          for iterable in iterables:
              yield from iterable

itertools.combinations(iterable, r)

   返回由输入 *iterable* 中元素组成长度为 *r* 的子序列。

   The output is a subsequence of "product()" keeping only entries
   that are subsequences of the *iterable*.  The length of the output
   is given by "math.comb()" which computes "n! / r! / (n - r)!" when
   "0 ≤ r ≤ n" or zero when "r > n".

   The combination tuples are emitted in lexicographic order according
   to the order of the input *iterable*. If the input *iterable* is
   sorted, the output tuples will be produced in sorted order.

   Elements are treated as unique based on their position, not on
   their value.  If the input elements are unique, there will be no
   repeated values within each combination.

   大致相当于：

      def combinations(iterable, r):
          # combinations('ABCD', 2) → AB AC AD BC BD CD
          # combinations(range(4), 3) → 012 013 023 123

          pool = tuple(iterable)
          n = len(pool)
          if r > n:
              return
          indices = list(range(r))

          yield tuple(pool[i] for i in indices)
          while True:
              for i in reversed(range(r)):
                  if indices[i] != i + n - r:
                      break
              else:
                  return
              indices[i] += 1
              for j in range(i+1, r):
                  indices[j] = indices[j-1] + 1
              yield tuple(pool[i] for i in indices)

itertools.combinations_with_replacement(iterable, r)

   返回由输入 *iterable* 中元素组成的长度为 *r* 的子序列，允许每个元素
   可重复出现。

   The output is a subsequence of "product()" that keeps only entries
   that are subsequences (with possible repeated elements) of the
   *iterable*.  The number of subsequence returned is "(n + r - 1)! /
   r! / (n - 1)!" when "n > 0".

   The combination tuples are emitted in lexicographic order according
   to the order of the input *iterable*. if the input *iterable* is
   sorted, the output tuples will be produced in sorted order.

   Elements are treated as unique based on their position, not on
   their value.  If the input elements are unique, the generated
   combinations will also be unique.

   大致相当于：

      def combinations_with_replacement(iterable, r):
          # combinations_with_replacement('ABC', 2) → AA AB AC BB BC CC

          pool = tuple(iterable)
          n = len(pool)
          if not n and r:
              return
          indices = [0] * r

          yield tuple(pool[i] for i in indices)
          while True:
              for i in reversed(range(r)):
                  if indices[i] != n - 1:
                      break
              else:
                  return
              indices[i:] = [indices[i] + 1] * (r - i)
              yield tuple(pool[i] for i in indices)

   Added in version 3.1.

itertools.compress(data, selectors)

   Make an iterator that returns elements from *data* where the
   corresponding element in *selectors* is true.  Stops when either
   the *data* or *selectors* iterables have been exhausted.  Roughly
   equivalent to:

      def compress(data, selectors):
          # compress('ABCDEF', [1,0,1,0,1,1]) → A C E F
          return (datum for datum, selector in zip(data, selectors) if selector)

   Added in version 3.1.

itertools.count(start=0, step=1)

   Make an iterator that returns evenly spaced values beginning with
   *start*. Can be used with "map()" to generate consecutive data
   points or with "zip()" to add sequence numbers.  Roughly equivalent
   to:

      def count(start=0, step=1):
          # count(10) → 10 11 12 13 14 ...
          # count(2.5, 0.5) → 2.5 3.0 3.5 ...
          n = start
          while True:
              yield n
              n += step

   当对浮点数计数时，替换为乘法代码有时精度会更好，例如： "(start +
   step * i for i in count())" 。

   在 3.1 版本发生变更: 增加参数 *step* ，允许非整型。

itertools.cycle(iterable)

   Make an iterator returning elements from the *iterable* and saving
   a copy of each.  When the iterable is exhausted, return elements
   from the saved copy.  Repeats indefinitely.  Roughly equivalent to:

      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

   This itertool may require significant auxiliary storage (depending
   on the length of the iterable).

itertools.dropwhile(predicate, iterable)

   Make an iterator that drops elements from the *iterable* while the
   *predicate* is true and afterwards returns every element.  Roughly
   equivalent to:

      def dropwhile(predicate, iterable):
          # dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8

          iterator = iter(iterable)
          for x in iterator:
              if not predicate(x):
                  yield x
                  break

          for x in iterator:
              yield x

   Note this does not produce *any* output until the predicate first
   becomes false, so this itertool may have a lengthy start-up time.

itertools.filterfalse(predicate, iterable)

   Make an iterator that filters elements from the *iterable*
   returning only those for which the *predicate* returns a false
   value.  If *predicate* is "None", returns the items that are false.
   Roughly equivalent to:

      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

itertools.groupby(iterable, key=None)

   创建一个迭代器，返回 *iterable* 中连续的键和组。*key* 是一个计算元
   素键值函数。如果未指定或为 "None"，*key* 缺省为恒等函数（identity
   function），返回元素不变。一般来说，*iterable* 需用同一个键值函数预
   先排序。

   "groupby()" 操作类似于Unix中的 "uniq"。当每次 *key* 函数产生的键值
   改变时，迭代器会分组或生成一个新组（这就是为什么通常需要使用同一个
   键值函数先对数据进行排序）。这种行为与SQL的GROUP BY操作不同，SQL的
   操作会忽略输入的顺序将相同键值的元素分在同组中。

   返回的组本身也是一个迭代器，它与 "groupby()" 共享底层的可迭代对象。
   因为源是共享的，当 "groupby()" 对象向后迭代时，前一个组将消失。因此
   如果稍后还需要返回结果，可保存为列表：

      groups = []
      uniquekeys = []
      data = sorted(data, key=keyfunc)
      for k, g in groupby(data, keyfunc):
          groups.append(list(g))      # Store group iterator as a list
          uniquekeys.append(k)

   "groupby()" 大致相当于：

      def groupby(iterable, key=None):
          # [k for k, g in groupby('AAAABBBCCDAABBB')] → A B C D A B
          # [list(g) for k, g in groupby('AAAABBBCCD')] → AAAA BBB CC D

          keyfunc = (lambda x: x) if key is None else key
          iterator = iter(iterable)
          exhausted = False

          def _grouper(target_key):
              nonlocal curr_value, curr_key, exhausted
              yield curr_value
              for curr_value in iterator:
                  curr_key = keyfunc(curr_value)
                  if curr_key != target_key:
                      return
                  yield curr_value
              exhausted = True

          try:
              curr_value = next(iterator)
          except StopIteration:
              return
          curr_key = keyfunc(curr_value)

          while not exhausted:
              target_key = curr_key
              curr_group = _grouper(target_key)
              yield curr_key, curr_group
              if curr_key == target_key:
                  for _ in curr_group:
                      pass

itertools.islice(iterable, stop)
itertools.islice(iterable, start, stop[, step])

   Make an iterator that returns selected elements from the iterable.
   Works like sequence slicing but does not support negative values
   for *start*, *stop*, or *step*.

   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 iterator is
   exhausted, if at all.  Otherwise, it stops at the specified
   position.

   If *step* is "None", the step defaults to one.  Elements are
   returned consecutively unless *step* is set higher than one which
   results in items being skipped.

   大致相当于：

      def islice(iterable, *args):
          # islice('ABCDEFG', 2) → A B
          # islice('ABCDEFG', 2, 4) → C D
          # islice('ABCDEFG', 2, None) → C D E F G
          # islice('ABCDEFG', 0, None, 2) → A C E G

          s = slice(*args)
          start = 0 if s.start is None else s.start
          stop = s.stop
          step = 1 if s.step is None else s.step
          if start < 0 or (stop is not None and stop < 0) or step <= 0:
              raise ValueError

          indices = count() if stop is None else range(max(start, stop))
          next_i = start
          for i, element in zip(indices, iterable):
              if i == next_i:
                  yield element
                  next_i += step

itertools.pairwise(iterable)

   返回从输入 *iterable* 中获取的连续重叠对。

   输出迭代器中 2 元组的数量将比输入的数量少一个。 如果输入可迭代对象
   中少于两个值则它将为空。

   大致相当于：

      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

   Added in version 3.10.

itertools.permutations(iterable, r=None)

   Return successive *r* length permutations of elements from the
   *iterable*.

   如果 *r* 未指定或为 "None" ，*r* 默认设置为 *iterable* 的长度，这种
   情况下，生成所有全长排列。

   The output is a subsequence of "product()" where entries with
   repeated elements have been filtered out.  The length of the output
   is given by "math.perm()" which computes "n! / (n - r)!" when "0 ≤
   r ≤ n" or zero when "r > n".

   The permutation tuples are emitted in lexicographic order according
   to the order of the input *iterable*.  If the input *iterable* is
   sorted, the output tuples will be produced in sorted order.

   Elements are treated as unique based on their position, not on
   their value.  If the input elements are unique, there will be no
   repeated values within a permutation.

   大致相当于：

      def permutations(iterable, r=None):
          # permutations('ABCD', 2) → AB AC AD BA BC BD CA CB CD DA DB DC
          # permutations(range(3)) → 012 021 102 120 201 210

          pool = tuple(iterable)
          n = len(pool)
          r = n if r is None else r
          if r > n:
              return

          indices = list(range(n))
          cycles = list(range(n, n-r, -1))
          yield tuple(pool[i] for i in indices[:r])

          while n:
              for i in reversed(range(r)):
                  cycles[i] -= 1
                  if cycles[i] == 0:
                      indices[i:] = indices[i+1:] + indices[i:i+1]
                      cycles[i] = n - i
                  else:
                      j = cycles[i]
                      indices[i], indices[-j] = indices[-j], indices[i]
                      yield tuple(pool[i] for i in indices[:r])
                      break
              else:
                  return

itertools.product(*iterables, repeat=1)

   可迭代对象输入的笛卡儿积。

   大致相当于生成器表达式中的嵌套循环。例如， "product(A, B)" 和
   "((x,y) for x in A for y in B)" 返回结果一样。

   嵌套循环像里程表那样循环变动，每次迭代时将最右侧的元素向后迭代。这
   种模式形成了一种字典序，因此如果输入的可迭代对象是已排序的，笛卡尔
   积元组依次序发出。

   要计算可迭代对象自身的笛卡尔积，将可选参数 *repeat* 设定为要重复的
   次数。例如，"product(A, repeat=4)" 和 "product(A, A, A, A)" 是一样
   的。

   该函数大致相当于下面的代码，只不过实际实现方案不会在内存中创建中间
   结果。

      def product(*iterables, repeat=1):
          # product('ABCD', 'xy') → Ax Ay Bx By Cx Cy Dx Dy
          # product(range(2), repeat=3) → 000 001 010 011 100 101 110 111

          pools = [tuple(pool) for pool in iterables] * repeat

          result = [[]]
          for pool in pools:
              result = [x+[y] for x in result for y in pool]

          for prod in result:
              yield tuple(prod)

   在 "product()" 运行之前，它会完全耗尽输入的可迭代对象，在内存中保留
   值的临时池以生成结果积。 相应地，它只适用于有限的输入。

itertools.repeat(object[, times])

   创建一个持续地返回 *object* 的迭代器。 将会无限期地运行除非指定了
   *times* 参数。

   大致相当于：

      def repeat(object, times=None):
          # repeat(10, 3) → 10 10 10
          if times is None:
              while True:
                  yield object
          else:
              for i in range(times):
                  yield object

   *repeat* 的一个常见用途是向 *map* 或 *zip* 提供一个常量值的流:

      >>> list(map(pow, range(10), repeat(2)))
      [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

itertools.starmap(function, iterable)

   Make an iterator that computes the *function* using arguments
   obtained from the *iterable*.  Used instead of "map()" when
   argument parameters have already been "pre-zipped" into tuples.

   "map()" 和 "starmap()" 之间的区别类似于 "function(a,b)" 和
   "function(*c)" 之间的差异。 大致相当于:

      def starmap(function, iterable):
          # starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000
          for args in iterable:
              yield function(*args)

itertools.takewhile(predicate, iterable)

   Make an iterator that returns elements from the *iterable* as long
   as the *predicate* is true.  Roughly equivalent to:

      def takewhile(predicate, iterable):
          # takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4
          for x in iterable:
              if not predicate(x):
                  break
              yield x

   Note, the element that first fails the predicate condition is
   consumed from the input iterator and there is no way to access it.
   This could be an issue if an application wants to further consume
   the input iterator after *takewhile* has been run to exhaustion.
   To work around this problem, consider using more-iterools
   before_and_after() instead.

itertools.tee(iterable, n=2)

   从一个可迭代对象中返回 *n* 个独立的迭代器。

   大致相当于：

      def tee(iterable, n=2):
          iterator = iter(iterable)
          shared_link = [None, None]
          return tuple(_tee(iterator, shared_link) for _ in range(n))

      def _tee(iterator, link):
          try:
              while True:
                  if link[1] is None:
                      link[0] = next(iterator)
                      link[1] = [None, None]
                  value, link = link
                  yield value
          except StopIteration:
              return

   一旦 "tee()" 已被创建，原有的 *iterable* 就不应在任何其他地方使用；
   否则，*iterable* 可能会被向下执行而不通知 tee 对象。

   "tee" 迭代器不是线程安全的。 当同时使用由同一个 "tee()" 调用所返回
   的迭代器时可能引发 "RuntimeError"，即使原本的 *iterable* 是线程安全
   的。is threadsafe.

   该迭代工具可能需要相当大的辅助存储空间（这取决于要保存多少临时数据
   ）。通常，如果一个迭代器在另一个迭代器开始之前就要使用大部份或全部
   数据，使用 "list()" 会比 "tee()" 更快。

itertools.zip_longest(*iterables, fillvalue=None)

   Make an iterator that aggregates elements from each of the
   *iterables*.

   If the iterables are of uneven length, missing values are filled-in
   with *fillvalue*.  If not specified, *fillvalue* defaults to
   "None".

   Iteration continues until the longest iterable is exhausted.

   大致相当于：

      def zip_longest(*iterables, fillvalue=None):
          # zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-

          iterators = list(map(iter, iterables))
          num_active = len(iterators)
          if not num_active:
              return

          while True:
              values = []
              for i, iterator in enumerate(iterators):
                  try:
                      value = next(iterator)
                  except StopIteration:
                      num_active -= 1
                      if not num_active:
                          return
                      iterators[i] = repeat(fillvalue)
                      value = fillvalue
                  values.append(value)
              yield tuple(values)

   If one of the iterables is potentially infinite, then the
   "zip_longest()" function should be wrapped with something that
   limits the number of calls (for example "islice()" or
   "takewhile()").


itertools 配方
==============

本节将展示如何使用现有的 itertools 作为基础构件来创建扩展的工具集。

这些 itertools 专题的主要目的是教学。 各个专题显示了对单个工具的各种思
维方式 — 例如，"chain.from_iterable" 被关联到展平的概念。 这些专题还给
出了有关这些工具的组合方式的想法 — 例如，"starmap()" 和 "repeat()" 应
当如何一起工作。 这些专题还显示了 itertools 与 "operator" 和
"collections" 模块以及内置迭代工具如 "map()", "filter()", "reversed()"
和 "enumerate()" 相互配合的使用模式。

这些例程的次要目的是作为一个孵化器使用。 "accumulate()", "compress()"
和 "pairwise()" 等迭代工具最初就是作为例程引入的。 目前，
"sliding_window()", "iter_index()" 和 "sieve()" 例程正在被测试以确定它
们是否堪当大任。

基本上所有这些配方和许许多多其他配方都可以通过 Python Package Index 上
的 more-itertools 项目来安装:

   python -m pip install more-itertools

许多例程提供了与底层工具集相当的高性能。 更好的内存效率是通过每次只处
理一个元素而不是将整个可迭代对象放入内存来保证的。 代码量的精简是通过
以 函数式风格 来链接工具来实现的。 运行的早速度是通过选择使用“矢量化”
构件来取代会导致较大解释器开销的 for 循环和 *生成器* 来达成的。

   import collections
   import contextlib
   import functools
   import math
   import operator
   import random

   def take(n, iterable):
       "Return first n items of the iterable as a list."
       return list(islice(iterable, n))

   def prepend(value, iterable):
       "Prepend a single value in front of an iterable."
       # prepend(1, [2, 3, 4]) → 1 2 3 4
       return chain([value], iterable)

   def tabulate(function, start=0):
       "Return function(0), function(1), ..."
       return map(function, count(start))

   def repeatfunc(func, times=None, *args):
       "Repeat calls to func with specified arguments."
       if times is None:
           return starmap(func, repeat(args))
       return starmap(func, repeat(args, times))

   def flatten(list_of_lists):
       "Flatten one level of nesting."
       return chain.from_iterable(list_of_lists)

   def ncycles(iterable, n):
       "Returns the sequence elements n times."
       return chain.from_iterable(repeat(tuple(iterable), n))

   def tail(n, iterable):
       "Return an iterator over the last n items."
       # tail(3, 'ABCDEFG') → E F G
       return iter(collections.deque(iterable, maxlen=n))

   def consume(iterator, n=None):
       "Advance the iterator n-steps ahead. If n is None, consume entirely."
       # Use functions that consume iterators at C speed.
       if n is None:
           collections.deque(iterator, maxlen=0)
       else:
           next(islice(iterator, n, n), None)

   def nth(iterable, n, default=None):
       "Returns the nth item or a default value."
       return next(islice(iterable, n, None), default)

   def quantify(iterable, predicate=bool):
       "Given a predicate that returns True or False, count the True results."
       return sum(map(predicate, iterable))

   def first_true(iterable, default=False, predicate=None):
       "Returns the first true value or the *default* if there is no true value."
       # first_true([a,b,c], x) → a or b or c or x
       # first_true([a,b], x, f) → a if f(a) else b if f(b) else x
       return next(filter(predicate, iterable), default)

   def all_equal(iterable, key=None):
       "Returns True if all the elements are equal to each other."
       # all_equal('4٤௪౪໔', key=int) → True
       return len(take(2, groupby(iterable, key))) <= 1

   def unique_justseen(iterable, key=None):
       "Yield unique elements, preserving order. Remember only the element just seen."
       # unique_justseen('AAAABBBCCDAABBB') → A B C D A B
       # unique_justseen('ABBcCAD', str.casefold) → A B c A D
       if key is None:
           return map(operator.itemgetter(0), groupby(iterable))
       return map(next, map(operator.itemgetter(1), groupby(iterable, key)))

   def unique_everseen(iterable, key=None):
       "Yield unique elements, preserving order. Remember all elements ever seen."
       # unique_everseen('AAAABBBCCDAABBB') → A B C D
       # unique_everseen('ABBcCAD', str.casefold) → A B c D
       seen = set()
       if key is None:
           for element in filterfalse(seen.__contains__, iterable):
               seen.add(element)
               yield element
       else:
           for element in iterable:
               k = key(element)
               if k not in seen:
                   seen.add(k)
                   yield element

   def unique(iterable, key=None, reverse=False):
      "Yield unique elements in sorted order. Supports unhashable inputs."
      # unique([[1, 2], [3, 4], [1, 2]]) → [1, 2] [3, 4]
      return unique_justseen(sorted(iterable, key=key, reverse=reverse), key=key)

   def sliding_window(iterable, n):
       "Collect data into overlapping fixed-length chunks or blocks."
       # sliding_window('ABCDEFG', 4) → ABCD BCDE CDEF DEFG
       iterator = iter(iterable)
       window = collections.deque(islice(iterator, n - 1), maxlen=n)
       for x in iterator:
           window.append(x)
           yield tuple(window)

   def grouper(iterable, n, *, incomplete='fill', fillvalue=None):
       "Collect data into non-overlapping fixed-length chunks or blocks."
       # grouper('ABCDEFG', 3, fillvalue='x') → ABC DEF Gxx
       # grouper('ABCDEFG', 3, incomplete='strict') → ABC DEF ValueError
       # grouper('ABCDEFG', 3, incomplete='ignore') → ABC DEF
       iterators = [iter(iterable)] * n
       match incomplete:
           case 'fill':
               return zip_longest(*iterators, fillvalue=fillvalue)
           case 'strict':
               return zip(*iterators, strict=True)
           case 'ignore':
               return zip(*iterators)
           case _:
               raise ValueError('Expected fill, strict, or ignore')

   def roundrobin(*iterables):
       "Visit input iterables in a cycle until each is exhausted."
       # roundrobin('ABC', 'D', 'EF') → A D E B F C
       # Algorithm credited to George Sakkis
       iterators = map(iter, iterables)
       for num_active in range(len(iterables), 0, -1):
           iterators = cycle(islice(iterators, num_active))
           yield from map(next, iterators)

   def partition(predicate, iterable):
       """Partition entries into false entries and true entries.

       If *predicate* is slow, consider wrapping it with functools.lru_cache().
       """
       # partition(is_odd, range(10)) → 0 2 4 6 8   and  1 3 5 7 9
       t1, t2 = tee(iterable)
       return filterfalse(predicate, t1), filter(predicate, t2)

   def subslices(seq):
       "Return all contiguous non-empty subslices of a sequence."
       # subslices('ABCD') → A AB ABC ABCD B BC BCD C CD D
       slices = starmap(slice, combinations(range(len(seq) + 1), 2))
       return map(operator.getitem, repeat(seq), slices)

   def iter_index(iterable, value, start=0, stop=None):
       "Return indices where a value occurs in a sequence or iterable."
       # iter_index('AABCADEAF', 'A') → 0 1 4 7
       seq_index = getattr(iterable, 'index', None)
       if seq_index is None:
           iterator = islice(iterable, start, stop)
           for i, element in enumerate(iterator, start):
               if element is value or element == value:
                   yield i
       else:
           stop = len(iterable) if stop is None else stop
           i = start
           with contextlib.suppress(ValueError):
               while True:
                   yield (i := seq_index(value, i, stop))
                   i += 1

   def iter_except(func, exception, first=None):
       "Convert a call-until-exception interface to an iterator interface."
       # iter_except(d.popitem, KeyError) → non-blocking dictionary iterator
       with contextlib.suppress(exception):
           if first is not None:
               yield first()
           while True:
               yield func()

下面的例程具有更数学化的风格:

   def powerset(iterable):
       "powerset([1,2,3]) → () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)"
       s = list(iterable)
       return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))

   def sum_of_squares(iterable):
       "Add up the squares of the input values."
       # sum_of_squares([10, 20, 30]) → 1400
       return math.sumprod(*tee(iterable))

   def reshape(matrix, cols):
       "Reshape a 2-D matrix to have a given number of columns."
       # reshape([(0, 1), (2, 3), (4, 5)], 3) →  (0, 1, 2), (3, 4, 5)
       return batched(chain.from_iterable(matrix), cols)

   def transpose(matrix):
       "Swap the rows and columns of a 2-D matrix."
       # transpose([(1, 2, 3), (11, 22, 33)]) → (1, 11) (2, 22) (3, 33)
       return zip(*matrix, strict=True)

   def matmul(m1, m2):
       "Multiply two matrices."
       # matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)]) → (49, 80), (41, 60)
       n = len(m2[0])
       return batched(starmap(math.sumprod, product(m1, transpose(m2))), n)

   def convolve(signal, kernel):
       """Discrete linear convolution of two iterables.
       Equivalent to polynomial multiplication.

       Convolutions are mathematically commutative; however, the inputs are
       evaluated differently.  The signal is consumed lazily and can be
       infinite. The kernel is fully consumed before the calculations begin.

       Article:  https://betterexplained.com/articles/intuitive-convolution/
       Video:    https://www.youtube.com/watch?v=KuXjwB4LzSA
       """
       # convolve([1, -1, -20], [1, -3]) → 1 -4 -17 60
       # convolve(data, [0.25, 0.25, 0.25, 0.25]) → Moving average (blur)
       # convolve(data, [1/2, 0, -1/2]) → 1st derivative estimate
       # convolve(data, [1, -2, 1]) → 2nd derivative estimate
       kernel = tuple(kernel)[::-1]
       n = len(kernel)
       padded_signal = chain(repeat(0, n-1), signal, repeat(0, n-1))
       windowed_signal = sliding_window(padded_signal, n)
       return map(math.sumprod, repeat(kernel), windowed_signal)

   def polynomial_from_roots(roots):
       """Compute a polynomial's coefficients from its roots.

          (x - 5) (x + 4) (x - 3)  expands to:   x³ -4x² -17x + 60
       """
       # polynomial_from_roots([5, -4, 3]) → [1, -4, -17, 60]
       factors = zip(repeat(1), map(operator.neg, roots))
       return list(functools.reduce(convolve, factors, [1]))

   def polynomial_eval(coefficients, x):
       """Evaluate a polynomial at a specific value.

       Computes with better numeric stability than Horner's method.
       """
       # Evaluate x³ -4x² -17x + 60 at x = 5
       # polynomial_eval([1, -4, -17, 60], x=5) → 0
       n = len(coefficients)
       if not n:
           return type(x)(0)
       powers = map(pow, repeat(x), reversed(range(n)))
       return math.sumprod(coefficients, powers)

   def polynomial_derivative(coefficients):
       """Compute the first derivative of a polynomial.

          f(x)  =  x³ -4x² -17x + 60
          f'(x) = 3x² -8x  -17
       """
       # polynomial_derivative([1, -4, -17, 60]) → [3, -8, -17]
       n = len(coefficients)
       powers = reversed(range(1, n))
       return list(map(operator.mul, coefficients, powers))

   def sieve(n):
       "Primes less than n."
       # sieve(30) → 2 3 5 7 11 13 17 19 23 29
       if n > 2:
           yield 2
       data = bytearray((0, 1)) * (n // 2)
       for p in iter_index(data, 1, start=3, stop=math.isqrt(n) + 1):
           data[p*p : n : p+p] = bytes(len(range(p*p, n, p+p)))
       yield from iter_index(data, 1, start=3)

   def factor(n):
       "Prime factors of n."
       # factor(99) → 3 3 11
       # factor(1_000_000_000_000_007) → 47 59 360620266859
       # factor(1_000_000_000_000_403) → 1000000000000403
       for prime in sieve(math.isqrt(n) + 1):
           while not n % prime:
               yield prime
               n //= prime
               if n == 1:
                   return
       if n > 1:
           yield n

   def totient(n):
       "Count of natural numbers up to n that are coprime to n."
       # https://mathworld.wolfram.com/TotientFunction.html
       # totient(12) → 4 because len([1, 5, 7, 11]) == 4
       for prime in set(factor(n)):
           n -= n // prime
       return n
