9.7. "itertools" — Fonctions créant des itérateurs pour boucler efficacement.
*****************************************************************************

Nouveau dans la version 2.3.

Ce module implémente de nombreuses briques *d’itérateurs* inspirées
par des constructions de APL, Haskell et SML. Toutes ont été
retravaillées dans un format adéquat pour Python.

Ce module standardise un noyau d’outils rapide, efficaces en mémoire
qui sont utiles d’eux-mêmes ou en les combinant. Ensemble, ils forment
une « algèbre d’itérateurs » rendant possible la construction
succincte et efficace d’outils spécialisés en Python seulement.

For instance, SML provides a tabulation tool: "tabulate(f)" which
produces a sequence "f(0), f(1), ...".  The same effect can be
achieved in Python by combining "imap()" and "count()" to form
"imap(f, count())".

These tools and their built-in counterparts also work well with the
high-speed functions in the "operator" module.  For example, the
multiplication operator can be mapped across two vectors to form an
efficient dot-product: "sum(imap(operator.mul, vector1, vector2))".

**Itérateurs infinis :**

+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+
| Itérateur          | Arguments         | Résultats                                         | Exemple                                   |
|====================|===================|===================================================|===========================================|
| "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*, … à l’infini ou jusqu’à n | "repeat(10, 3) --> 10 10 10"              |
|                    |                   | fois                                              |                                           |
+--------------------+-------------------+---------------------------------------------------+-------------------------------------------+

**Itérateurs se terminant par la séquence d’entrée la plus courte :**

+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| Itérateur            | Arguments                    | Résultats                                         | Exemple                                                       |
|======================|==============================|===================================================|===============================================================|
| "chain()"            | p, q, …                      | p0, p1, … plast, q0, q1, …                        | "chain('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()"        | pred, seq                    | "seq[n]", "seq[n+1]", commençant quand *pred*     | "dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1"             |
|                      |                              | échoue                                            |                                                               |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "groupby()"          | iterable[, keyfunc]          | sous-itérateurs groupés par la valeur de          |                                                               |
|                      |                              | *keyfunc(v)*                                      |                                                               |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "ifilter()"          | pred, seq                    | elements of seq where pred(elem) is true          | "ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9"             |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "ifilterfalse()"     | pred, seq                    | éléments de *seq* quand *pred(elem)* est faux     | "ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8"        |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "islice()"           | seq, [start,] stop [, step]  | éléments de "seq[start:stop:step]"                | "islice('ABCDEFG', 2, None) --> C D E F G"                    |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "imap()"             | func, p, q, …                | func(p0, q0), func(p1, q1), …                     | "imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000"                  |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "starmap()"          | func, seq                    | func(*seq[0]), func(*seq[1]), …                   | "starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000"          |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "tee()"              | it, n                        | *it1*, *it2*, … *itn* sépare un itérateur en *n*  |                                                               |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "takewhile()"        | pred, seq                    | "seq[0]", "seq[1]", jusqu’à ce que *pred* échoue  | "takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4"               |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "izip()"             | p, q, …                      | (p[0], q[0]), (p[1], q[1]), …                     | "izip('ABCD', 'xy') --> Ax By"                                |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+
| "izip_longest()"     | p, q, …                      | (p[0], q[0]), (p[1], q[1]), …                     | "izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-"   |
+----------------------+------------------------------+---------------------------------------------------+---------------------------------------------------------------+

**Générateurs combinatoires :**

+------------------------------------------------+----------------------+---------------------------------------------------------------+
| Itérateur                                      | Arguments            | Résultats                                                     |
|================================================|======================|===============================================================|
| "product()"                                    | p, q, … [repeat=1]   | produit cartésien, équivalent à une boucle *for* imbriquée    |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "permutations()"                               | p[, r]               | *tuples* de longueur *r*, tous les ré-arrangements possibles, |
|                                                |                      | sans répétition d’éléments                                    |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "combinations()"                               | p, r                 | tuples de longueur r, triés, sans répétition d’éléments       |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "combinations_with_replacement()"              | p, r                 | tuples de longueur r, triés, avec répétition d’éléments       |
+------------------------------------------------+----------------------+---------------------------------------------------------------+
| "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"                               |
+------------------------------------------------+----------------------+---------------------------------------------------------------+


9.7.1. Fonctions d”*itertool*
=============================

Toutes les fonctions de module qui suivent construisent et renvoient
des itérateurs. Certaines fournissent des flux de longueur infinie,
elles devraient seulement être accédées par des fonctions ou boucles
qui tronquent le flux.

itertools.chain(*iterables)

   Créer un itérateur qui renvoie les éléments du premier itérable
   jusqu’à son épuisement, puis continue avec l’itérable suivant
   jusqu’à ce que tous les itérables soient épuisés. Utilisée pour
   traiter des séquences consécutives comme une seule séquence
   Sensiblement équivalente à :

      def chain(*iterables):
          # chain('ABC', 'DEF') --> A B C D E F
          for it in iterables:
              for element in it:
                  yield element

classmethod chain.from_iterable(iterable)

   Constructeur alternatif pour "chain()". Récupère des entrées
   chaînées d’un unique argument itérable qui est évalué de manière
   paresseuse. Sensiblement équivalente à :

      def from_iterable(iterables):
          # chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
          for it in iterables:
              for element in it:
                  yield element

   Nouveau dans la version 2.6.

itertools.combinations(iterable, r)

   Renvoyer les sous-séquences de longueur *r* de l’itérable
   *iterable*.

   Les combinaisons sont émises dans l’ordre lexicographique. Ainsi,
   si l’itérable *iterable* est trié, les *tuples* de combinaison
   seront produits dans l’ordre.

   Les éléments sont considérés comme uniques en fonction de leur
   position, et non pas de leur valeur. Ainsi, si les éléments en
   entrée sont uniques, il n’y aura pas de valeurs répétées dans
   chaque combinaison.

   Sensiblement équivalent à :

      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 = 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)

   Le code de "combinations()" peut aussi être exprimé comme une sous-
   séquence de "permutations()" après avoir filtré les entrées dont
   les éléments ne sont pas triés (selon leur position dans le *pool*
   d’entrée) :

      def combinations(iterable, r):
          pool = tuple(iterable)
          n = len(pool)
          for indices in permutations(range(n), r):
              if sorted(indices) == list(indices):
                  yield tuple(pool[i] for i in indices)

   Le nombre d’éléments renvoyés est "n! / r! / (n-r)!" quand "0 <= r
   <= n" ou zéro quand "r > n".

   Nouveau dans la version 2.6.

itertools.combinations_with_replacement(iterable, r)

   Renvoyer les sous-séquences de longueur *r* des éléments de
   l’itérable *iterable* d’entrée, permettant aux éléments individuels
   d’être répétés plus d’une fois.

   Les combinaisons sont émises dans l’ordre lexicographique. Ainsi,
   si l’itérable *iterable* est trié, les *tuples* de combinaison
   seront produits dans l’ordre.

   Les éléments sont considérés comme uniques en fonction de leur
   position, et non pas de leur valeur. Ainsi si les éléments d’entrée
   sont uniques, les combinaisons générées seront aussi uniques.

   Sensiblement équivalent à :

      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)

   Le code pour "combinations_with_replacement()" peut aussi être
   exprimé comme une sous-séquence de "product()" après avoir filtré
   les entrées où les éléments ne sont pas dans triés (selon leur
   position dans le *pool* d’entrée) :

      def combinations_with_replacement(iterable, r):
          pool = tuple(iterable)
          n = len(pool)
          for indices in product(range(n), repeat=r):
              if sorted(indices) == list(indices):
                  yield tuple(pool[i] for i in indices)

   Le nombre d’éléments renvoyés est "(n+r-1)! / r! / (n-1)!" quand "n
   > 0".

   Nouveau dans la version 2.7.

itertools.compress(data, selectors)

   Créer un itérateur qui filtre les éléments de *data*, renvoyant
   seulement ceux qui ont un élément correspondant dans *selectors*
   qui évalue à "True". S’arrête quand l’itérable *data* ou
   *selectors* a été épuisé. Sensiblement équivalent à :

      def compress(data, selectors):
          # compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F
          return (d for d, s in izip(data, selectors) if s)

   Nouveau dans la version 2.7.

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

   Make an iterator that returns evenly spaced values starting with
   *n*. Often used as an argument to "imap()" to generate consecutive
   data points. Also, used with "izip()" to add sequence numbers.
   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

   Quand on compte avec des nombres à virgule flottante, il est
   parfois possible d’obtenir une meilleure précision en substituant
   du code multiplicateur comme :  "(start + step * i for i in
   count())".

   Modifié dans la version 2.7: added *step* argument and allowed non-
   integer arguments.

itertools.cycle(iterable)

   Créer un itérateur qui renvoie les éléments de l’itérable et qui
   sauvegarde une copie de chaque. Quand l’itérable est épuisé,
   renvoyer les éléments depuis la copie sauvegardée. Répète à
   l’infini. Sensiblement équivalent à :

      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

   Note, cette fonction pourrait avoir besoin d’un stockage auxiliaire
   important (en fonction de la longueur de l’itérable).

itertools.dropwhile(predicate, iterable)

   Créer un itérateur qui saute les éléments de l’itérable tant que le
   prédicat est vrai ; ensuite, renvoyer chaque élément. Note,
   l’itérateur ne produit *aucune* sortie avant que le prédicat ne
   devienne faux, il peut donc avoir un temps de démarrage long.
   Sensiblement équivalent à :

      def dropwhile(predicate, iterable):
          # dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
          iterable = iter(iterable)
          for x in iterable:
              if not predicate(x):
                  yield x
                  break
          for x in iterable:
              yield x

itertools.groupby(iterable[, key])

   Créer un itérateur qui renvoie les clés et les groupes de
   l’itérable *iterable*. La clé *key* est une fonction qui génère une
   clé pour chaque élément. Si *key* n’est pas spécifié ou est "None",
   elle vaut par défaut une fonction d’identité qui renvoie l’élément
   sans le modifier. Généralement, l’itérable a besoin d’être déjà
   trié selon cette même fonction de clé.

   L’opération de  "groupby()" est similaire au filtre "uniq" dans
   Unix. Elle génère un nouveau groupe à chaque fois que la valeur de
   la fonction *key* change (ce pourquoi il est souvent nécessaire
   d’avoir trié les données selon la même fonction de clé).  Ce
   comportement est différent de celui de GROUP BY de SQL qui agrège
   les éléments sans prendre compte de leur ordre d’entrée.

   Le groupe renvoyé est lui-même un itérateur qui partage l’itérable
   sous-jacent avec "groupby()". Puisque que la source est partagée,
   quand l’objet "groupby()" est avancé, le groupe précédent n’est
   plus visible. Ainsi, si cette donnée doit être utilisée plus tard,
   elle devrait être stockée comme une liste :

      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()" est sensiblement équivalent à :

      class groupby(object):
          # [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
          def __init__(self, iterable, key=None):
              if key is None:
                  key = lambda x: x
              self.keyfunc = key
              self.it = iter(iterable)
              self.tgtkey = self.currkey = self.currvalue = object()
          def __iter__(self):
              return self
          def next(self):
              while self.currkey == self.tgtkey:
                  self.currvalue = next(self.it)    # Exit on StopIteration
                  self.currkey = self.keyfunc(self.currvalue)
              self.tgtkey = self.currkey
              return (self.currkey, self._grouper(self.tgtkey))
          def _grouper(self, tgtkey):
              while self.currkey == tgtkey:
                  yield self.currvalue
                  self.currvalue = next(self.it)    # Exit on StopIteration
                  self.currkey = self.keyfunc(self.currvalue)

   Nouveau dans la version 2.4.

itertools.ifilter(predicate, iterable)

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

      def ifilter(predicate, iterable):
          # ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9
          if predicate is None:
              predicate = bool
          for x in iterable:
              if predicate(x):
                  yield x

itertools.ifilterfalse(predicate, iterable)

   Créer un itérateur qui filtre les éléments de *iterable*, ne
   renvoyant seulement ceux pour lesquels le prédicat est "Faux". Si
   *predicate* vaut "None", renvoyer les éléments qui sont faux.
   Sensiblement équivalent à :

      def ifilterfalse(predicate, iterable):
          # ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
          if predicate is None:
              predicate = bool
          for x in iterable:
              if not predicate(x):
                  yield x

itertools.imap(function, *iterables)

   Make an iterator that computes the function using arguments from
   each of the iterables.  If *function* is set to "None", then
   "imap()" returns the arguments as a tuple.  Like "map()" but stops
   when the shortest iterable is exhausted instead of filling in
   "None" for shorter iterables.  The reason for the difference is
   that infinite iterator arguments are typically an error for "map()"
   (because the output is fully evaluated) but represent a common and
   useful way of supplying arguments to "imap()". Roughly equivalent
   to:

      def imap(function, *iterables):
          # imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000
          iterables = map(iter, iterables)
          while True:
              args = [next(it) for it in iterables]
              if function is None:
                  yield tuple(args)
              else:
                  yield function(*args)

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

   Créer un itérateur qui renvoie les élément sélectionnés de
   l’itérable. Si *start* est non-nul, alors les éléments de
   l’itérable sont sautés jusqu’à ce que *start* soit atteint.
   Ensuite, les éléments sont renvoyés consécutivement sauf si *step*
   est plus grand que 1, auquel cas certains éléments seront sautés.
   Si *stop* est "None", alors l’itération continue jusqu’à ce que
   l’itérateur soit épuisé s’il ne l’est pas déjà ; sinon, il s’arrête
   à la position spécifiée. À la différence du *slicing* standard,
   "slice()" ne supporte pas les valeurs négatives pour *start*,
   *stop* ou *step*. Peut être utilisée pour extraire les champs
   apparentés depuis des données dont la structure interne a été
   aplatie (par exemple, un rapport multi-ligne pourrait lister un nom
   de champ toutes les trois lignes). Sensiblement similaire à :

      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, stop, step = s.start or 0, s.stop or sys.maxint, s.step or 1
          it = iter(xrange(start, stop, step)))
          try:
              nexti = next(it)
          except StopIteration:
              # Consume *iterable* up to the *start* position.
              for i, element in izip(xrange(start), iterable):
                  pass
              return
          try:
              for i, element in enumerate(iterable):
                  if i == nexti:
                      yield element
                      nexti = next(it)
          except StopIteration:
              # Consume to *stop*.
              for i, element in izip(xrange(i + 1, stop), iterable):
                  pass

   Si *start* vaut "None", alors l’itération commence à zéro. Si
   *step* vaut "None", alors le pas est à 1 par défaut.

   Modifié dans la version 2.5: accept "None" values for default
   *start* and *step*.

itertools.izip(*iterables)

   Make an iterator that aggregates elements from each of the
   iterables. Like "zip()" except that it returns an iterator instead
   of a list.  Used for lock-step iteration over several iterables at
   a time.  Roughly equivalent to:

      def izip(*iterables):
          # izip('ABCD', 'xy') --> Ax By
          iterators = map(iter, iterables)
          while iterators:
              yield tuple(map(next, iterators))

   Modifié dans la version 2.4: When no iterables are specified,
   returns a zero length iterator instead of raising a "TypeError"
   exception.

   The left-to-right evaluation order of the iterables is guaranteed.
   This makes possible an idiom for clustering a data series into
   n-length groups using "izip(*[iter(s)]*n)".

   "izip()" should only be used with unequal length inputs when you
   don’t care about trailing, unmatched values from the longer
   iterables.  If those values are important, use "izip_longest()"
   instead.

itertools.izip_longest(*iterables[, fillvalue])

   Créer un itérateur qui agrège les éléments de chacun des itérables.
   Si les itérables sont de longueurs différentes, les valeurs
   manquantes sont remplacées par *fillvalue*. L’itération continue
   jusqu’à ce que l’itérable le plus long soit épuisé. Sensiblement
   équivalent à :

      class ZipExhausted(Exception):
          pass

      def izip_longest(*args, **kwds):
          # izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
          fillvalue = kwds.get('fillvalue')
          counter = [len(args) - 1]
          def sentinel():
              if not counter[0]:
                  raise ZipExhausted
              counter[0] -= 1
              yield fillvalue
          fillers = repeat(fillvalue)
          iterators = [chain(it, sentinel(), fillers) for it in args]
          try:
              while iterators:
                  yield tuple(map(next, iterators))
          except ZipExhausted:
              pass

   If one of the iterables is potentially infinite, then the
   "izip_longest()" function should be wrapped with something that
   limits the number of calls (for example "islice()" or
   "takewhile()").  If not specified, *fillvalue* defaults to "None".

   Nouveau dans la version 2.6.

itertools.permutations(iterable[, r])

   Renvoyer les permutations successives de longueur *r* des éléments
   de *iterable*.

   Si *r* n’est pas spécifié ou vaut "None", alors *r* a pour valeur
   la longueur de *iterable* et toutes les permutations de longueur
   *r* possibles sont générées.

   Les permutations sont émises dans l’ordre lexicographique. Ainsi,
   si l’itérable d’entrée *iterable* est trié, les *tuples* de
   permutation seront produits dans l’ordre.

   Les éléments sont considérés comme uniques en fonction de leur
   position, et non pas de leur valeur. Ainsi, si l’élément est
   unique, il n’y aura pas de valeurs répétées dans chaque
   permutation.

   Sensiblement équivalent à :

      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 = range(n)
          cycles = 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

   Le code pour "permutations()" peut aussi être exprimé comme une
   sous-séquence de "product()", filtré pour exclure les entrées avec
   des éléments répétés (celles de la même position dans la *pool*
   d’entrée) :

      def permutations(iterable, r=None):
          pool = tuple(iterable)
          n = len(pool)
          r = n if r is None else r
          for indices in product(range(n), repeat=r):
              if len(set(indices)) == r:
                  yield tuple(pool[i] for i in indices)

   Le nombre d’éléments renvoyés est "n! / (n-r)!" quand "0 <= r <= n"
   ou zéro quand "r > n".

   Nouveau dans la version 2.6.

itertools.product(*iterables[, repeat])

   Produit cartésien des itérables d’entrée.

   Sensiblement équivalent à des boucles *for* imbriquées dans une
   expression de générateur. Par exemple "product(A, B)" renvoie la
   même chose que "((x, y) for x in A for y in B)".

   Les boucles imbriquées tournent comme un compteur kilométrique avec
   l’élément le plus à droite avançant à chaque itération. ce motif
   créé un tri lexicographique afin que si les itérables de l’entrée
   sont triés, les *tuples* de produit sont émis dans l’ordre.

   Pour générer le produit d’un itérable avec lui-même, spécifier le
   nombre de répétitions avec le paramètre nommé optionnel *repeat*.
   Par exemple, "product(A, repeat=4)" veut dire la même chose que
   "product(A, A, A, A)".

   Cette fonction est sensiblement équivalente au code suivant, saut
   que la vraie implémentation ne créé pas les résultats
   intermédiaires en mémoire :

      def product(*args, **kwds):
          # 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 = map(tuple, args) * kwds.get('repeat', 1)
          result = [[]]
          for pool in pools:
              result = [x+[y] for x in result for y in pool]
          for prod in result:
              yield tuple(prod)

   Nouveau dans la version 2.6.

itertools.repeat(object[, times])

   Make an iterator that returns *object* over and over again. Runs
   indefinitely unless the *times* argument is specified. Used as
   argument to "imap()" for invariant function parameters.  Also used
   with "izip()" to create constant fields in a tuple record.  Roughly
   equivalent to:

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

   A common use for *repeat* is to supply a stream of constant values
   to *imap* or *zip*:

      >>> list(imap(pow, xrange(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 "imap()" when argument
   parameters are already grouped in tuples from a single iterable
   (the data has been « pre-zipped »).  The difference between
   "imap()" and "starmap()" parallels the distinction between
   "function(a,b)" and "function(*c)". Roughly equivalent to:

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

   Modifié dans la version 2.6: Previously, "starmap()" required the
   function arguments to be tuples. Now, any iterable is allowed.

itertools.takewhile(predicate, iterable)

   Créer un itérateur qui renvoie les éléments d’un itérable tant que
   le prédicat est vrai. Sensiblement équivalent à :

      def takewhile(predicate, iterable):
          # takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4
          for x in iterable:
              if predicate(x):
                  yield x
              else:
                  break

itertools.tee(iterable[, n=2])

   Return *n* independent iterators from a single iterable.  Roughly
   equivalent to:

      def tee(iterable, n=2):
          it = iter(iterable)
          deques = [collections.deque() for i in range(n)]
          def gen(mydeque):
              while True:
                  if not mydeque:             # when the local deque is empty
                      newval = next(it)       # fetch a new value and
                      for d in deques:        # load it to all the deques
                          d.append(newval)
                  yield mydeque.popleft()
          return tuple(gen(d) for d in deques)

   Une fois que "tee()" a créé un branchement, l’itérable *iterable*
   ne devrait être utilisé nulle part ailleurs ; sinon, *iterable*
   pourrait être avancé sans que les objets tee soient informés.

   "tee" iterators are not threadsafe. A "RuntimeError" may be raised
   when using simultaneously iterators returned by the same "tee()"
   call, even if the original *iterable* is threadsafe.

   Cet outil pourrait avoir besoin d’un stockage auxiliaire important
   (en fonction de la taille des données temporaires nécessaires). En
   général, si un itérateur utilise la majorité ou toute la donnée
   avant qu’un autre itérateur ne commence, il est plus rapide
   d’utiliser "list()" à la place de "tee()".

   Nouveau dans la version 2.4.


9.7.2. Cas pratiques
====================

Cette section montre des recettes pour créer une boîte à outil étendue
en se servant des *itertools* existants comme de briques.

Ces outils dérivés offrent la même bonne performance que les outils
sous-jacents. La performance mémoire supérieure est gardée en traitant
les éléments un à la fois plutôt que de charger tout l’itérable en
mémoire en même temps. Le volume de code reste bas grâce à un chaînage
de style fonctionnel qui aide à éliminer des variables temporaires. La
grande vitesse est gardée en préférant les briques « vectorisées »
plutôt que les boucles *for* et les *générateur*s qui engendrent du
sur-coût de traitement.

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

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

   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:
           # feed the entire iterator into a zero-length deque
           collections.deque(iterator, maxlen=0)
       else:
           # advance to the empty slice starting at position n
           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 all_equal(iterable):
       "Returns True if all the elements are equal to each other"
       g = groupby(iterable)
       return next(g, True) and not next(g, False)

   def quantify(iterable, pred=bool):
       "Count how many times the predicate is true"
       return sum(imap(pred, iterable))

   def padnone(iterable):
       """Returns the sequence elements and then returns None indefinitely.

       Useful for emulating the behavior of the built-in map() function.
       """
       return chain(iterable, repeat(None))

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

   def dotproduct(vec1, vec2):
       return sum(imap(operator.mul, vec1, vec2))

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

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

       Example:  repeatfunc(random.random)
       """
       if times is None:
           return starmap(func, repeat(args))
       return starmap(func, repeat(args, times))

   def pairwise(iterable):
       "s -> (s0,s1), (s1,s2), (s2, s3), ..."
       a, b = tee(iterable)
       next(b, None)
       return izip(a, b)

   def grouper(iterable, n, fillvalue=None):
       "Collect data into fixed-length chunks or blocks"
       # grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx
       args = [iter(iterable)] * n
       return izip_longest(fillvalue=fillvalue, *args)

   def roundrobin(*iterables):
       "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
       # Recipe credited to George Sakkis
       pending = len(iterables)
       nexts = cycle(iter(it).next for it in iterables)
       while pending:
           try:
               for next in nexts:
                   yield next()
           except StopIteration:
               pending -= 1
               nexts = cycle(islice(nexts, pending))

   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 unique_everseen(iterable, key=None):
       "List unique elements, preserving order. Remember all elements ever seen."
       # unique_everseen('AAAABBBCCDAABBB') --> A B C D
       # unique_everseen('ABBCcAD', str.lower) --> A B C D
       seen = set()
       seen_add = seen.add
       if key is None:
           for element in ifilterfalse(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_justseen(iterable, key=None):
       "List unique elements, preserving order. Remember only the element just seen."
       # unique_justseen('AAAABBBCCDAABBB') --> A B C D A B
       # unique_justseen('ABBCcAD', str.lower) --> A B C A D
       return imap(next, imap(itemgetter(1), groupby(iterable, key)))

   def iter_except(func, exception, first=None):
       """ Call a function repeatedly until an exception is raised.

       Converts a call-until-exception interface to an iterator interface.
       Like __builtin__.iter(func, sentinel) but uses an exception instead
       of a sentinel to end the loop.

       Examples:
           bsddbiter = iter_except(db.next, bsddb.error, db.first)
           heapiter = iter_except(functools.partial(heappop, h), IndexError)
           dictiter = iter_except(d.popitem, KeyError)
           dequeiter = iter_except(d.popleft, IndexError)
           queueiter = iter_except(q.get_nowait, Queue.Empty)
           setiter = iter_except(s.pop, KeyError)

       """
       try:
           if first is not None:
               yield first()
           while 1:
               yield func()
       except exception:
           pass

   def random_product(*args, **kwds):
       "Random selection from itertools.product(*args, **kwds)"
       pools = map(tuple, args) * kwds.get('repeat', 1)
       return tuple(random.choice(pool) for pool in pools)

   def random_permutation(iterable, r=None):
       "Random selection from itertools.permutations(iterable, r)"
       pool = tuple(iterable)
       r = len(pool) if r is None else r
       return tuple(random.sample(pool, r))

   def random_combination(iterable, r):
       "Random selection from itertools.combinations(iterable, r)"
       pool = tuple(iterable)
       n = len(pool)
       indices = sorted(random.sample(xrange(n), r))
       return tuple(pool[i] for i in indices)

   def random_combination_with_replacement(iterable, r):
       "Random selection from itertools.combinations_with_replacement(iterable, r)"
       pool = tuple(iterable)
       n = len(pool)
       indices = sorted(random.randrange(n) for i in xrange(r))
       return tuple(pool[i] for i in indices)

   def tee_lookahead(t, i):
       """Inspect the i-th upcomping value from a tee object
          while leaving the tee object at its current position.

          Raise an IndexError if the underlying iterator doesn't
          have enough values.

       """
       for value in islice(t.__copy__(), i, None):
           return value
       raise IndexError(i)

Note, beaucoup des recettes ci-dessus peuvent être optimisées en
replaçant les recherches globales par des recherches locales avec des
variables locales définies comme des valeurs par défaut. Par exemple,
la recette *dotproduct* peut être écrite comme :

   def dotproduct(vec1, vec2, sum=sum, imap=imap, mul=operator.mul):
       return sum(imap(mul, vec1, vec2))
