10.1. itertools — Fonctions créant des itérateurs pour boucler efficacement.

---

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.

Par exemple, SML fournit un outil de tabulation tabulate(f) qui produit une séquence f(0), f(1), .... Le même résultat peut être achevé en Python en combinant map() et count() pour former map(f, count()).

Ces outils et leurs équivalents intégrés fonctionnent aussi bien avec les fonction à grande vitesse dans le module operator. Par exemple, l’opérateur de multiplication peut être appliqué à deux vecteurs pour créer un produit scalaire efficace sum(map(operator.mul, vecteur1, vecteur2)).

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 fois	repeat(10, 3) --> 10 10 10

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

Itérateur	Arguments	Résultats	Exemple
accumulate()	p [,func]	p0, p0+p1, p0+p1+p2, …	accumulate([1,2,3,4,5]) --> 1 3 6 10 15
chain()	p, q, …	p0, p1, … plast, q0, q1, …	chain('ABC', 'DEF') --> A B C D E F
chain.from_iterable()	itérable	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()	pred, seq	seq[n], seq[n+1], commençant quand pred échoue	dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
filterfalse()	pred, seq	éléments de seq quand pred(elem) est faux	filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
groupby()	iterable[, keyfunc]	sous-itérateurs groupés par la valeur de keyfunc(v)
islice()	seq, [start,] stop [, step]	éléments de seq[start:stop:step]	islice('ABCDEFG', 2, None) --> C D E F G
starmap()	func, seq	func(*seq[0]), func(*seq[1]), …	starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000
takewhile()	pred, seq	seq[0], seq[1], jusqu’à ce que pred échoue	takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4
tee()	it, n	it1, it2, … itn sépare un itérateur en n
zip_longest()	p, q, …	(p[0], q[0]), (p[1], q[1]), …	zip_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

10.1.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.accumulate(iterable[, func])

Créer un itérateur qui renvoie les sommes accumulées, ou les résultats accumulés d’autres fonctions binaires (spécifiées par l’argument optionnel func). Si func est renseigné, il doit être une fonction à deux arguments. Les éléments de l’itérable d’entrée peuvent être de n’importe quel type qui peuvent être acceptés comme arguments de func. (Par exemple, avec l’opération par défaut d’addition, les éléments peuvent être de n’importe quel type additionnable incluant Decimal ou Fraction.) Si l’itérable d’entrée est vide, l’itérable de sortie sera aussi vide.

Sensiblement équivalent à :

def accumulate(iterable, func=operator.add):
    'Return running totals'
    # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
    # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
    it = iter(iterable)
    try:
        total = next(it)
    except StopIteration:
        return
    yield total
    for element in it:
        total = func(total, element)
        yield total

Il y a de nombreuses utilisations pour l’argument func. Il peut être min() pour un minimum glissant, max() pour un maximum glissant, ou operator.mul() pour un produit glissant. Des tableaux de remboursement peuvent être construites en accumulant l’intérêt et en déposant des paiements. Des suites de récurrences de premier ordre peuvent être modélisées en renseignant la valeur initiale dans l’itérable et en utilisant seulement le total accumulé dans l’argument func :

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

# Amortize a 5% loan of 1000 with 4 annual payments of 90
>>> cashflows = [1000, -90, -90, -90, -90]
>>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
[1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]

# Chaotic recurrence relation https://en.wikipedia.org/wiki/Logistic_map
>>> logistic_map = lambda x, _:  r * x * (1 - x)
>>> r = 3.8
>>> x0 = 0.4
>>> inputs = repeat(x0, 36)     # only the initial value is used
>>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]
['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', '0.63',
 '0.88', '0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', '0.57',
 '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', '0.32',
 '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']

Voir functools.reduce() pour une fonction similaire qui ne renvoie que la valeur accumulée finale.

Nouveau dans la version 3.2.

Modifié dans la version 3.3: Le paramètre optionnel func a été ajouté.

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

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

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.

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 3.1.

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 zip(data, selectors) if s)

Nouveau dans la version 3.1.

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

Créer un itérateur qui renvoie les valeurs espacées également commençant par le nombre start. Souvent utilisée comme un argument de map() pour générer des points de données consécutifs. Aussi utilisé avec zip() pour ajouter des nombres de séquence. Sensiblement équivalent à :

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 3.1: Ajout de l’argument step et ajout du support pour les arguments non-entiers.

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.filterfalse(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 filterfalse(predicate, iterable):
    # filterfalse(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.groupby(iterable, key=None)

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:
    # [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
            try:
                self.currvalue = next(self.it)
            except StopIteration:
                return
            self.currkey = self.keyfunc(self.currvalue)

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)
    it = iter(range(s.start or 0, s.stop or sys.maxsize, s.step or 1))
    try:
        nexti = next(it)
    except StopIteration:
        return
    for i, element in enumerate(iterable):
        if i == nexti:
            yield element
            nexti = next(it)

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

itertools.permutations(iterable, r=None)

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

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.

itertools.product(*iterables, repeat=1)

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, 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 args] * repeat
    result = [[]]
    for pool in pools:
        result = [x+[y] for x in result for y in pool]
    for prod in result:
        yield tuple(prod)

itertools.repeat(object[, times])

Créer un itérateur qui renvoie object à l’infini. S’exécute indéfiniment sauf si l’argument times est spécifié. Utilisée comme argument de map() pour les paramètres invariants de la fonction appelée. Aussi utilisée avec zip() pour créer une partie invariante d’un tuple.

Sensiblement équivalent à :

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

Une utilisation commune de repeat est de fournir un flux constant de valeurs à map ou zip :

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

itertools.starmap(function, iterable)

Créer un itérateur qui exécute la fonction avec les arguments obtenus de l’itérable. Utilisée à la place de map() quand les arguments sont déjà groupés en tuples depuis un seul itérable (la donnée a déjà été « pré-zippée »). La différence entre map() et starmap() est similaire à la différence entre fonction(a,b) et fonction(*c). Sensiblement équivalent à :

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)

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
                try:
                    newval = next(it)   # fetch a new value and
                except StopIteration:
                    return
                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.

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().

itertools.zip_longest(*iterables, fillvalue=None)

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 zip_longest(*args, **kwds):
    # zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
    fillvalue = kwds.get('fillvalue')
    counter = len(args) - 1
    def sentinel():
        nonlocal counter
        if not counter:
            raise ZipExhausted
        counter -= 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

Si un des itérables est potentiellement infini, alors la fonction zip_longest() devrait être entourée avec quelque chose qui limite le nombre d’appels (par exemple, islice() ou takewhile()). Si fillvalue n’est pas spécifié, il vaut None par défaut.

10.1.2. Recettes itertools

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érateurs 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 map(function, count(start))

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):
    "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(map(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(map(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 zip(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 zip_longest(*args, fillvalue=fillvalue)

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 partition(pred, iterable):
    'Use a predicate to partition entries into false entries and true entries'
    # partition(is_odd, range(10)) --> 0 2 4 6 8   and  1 3 5 7 9
    t1, t2 = tee(iterable)
    return filterfalse(pred, t1), filter(pred, t2)

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 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_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 map(next, map(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 builtins.iter(func, sentinel) but uses an exception instead
    of a sentinel to end the loop.

    Examples:
        iter_except(functools.partial(heappop, h), IndexError)   # priority queue iterator
        iter_except(d.popitem, KeyError)                         # non-blocking dict iterator
        iter_except(d.popleft, IndexError)                       # non-blocking deque iterator
        iter_except(q.get_nowait, Queue.Empty)                   # loop over a producer Queue
        iter_except(s.pop, KeyError)                             # non-blocking set iterator

    """
    try:
        if first is not None:
            yield first()            # For database APIs needing an initial cast to db.first()
        while True:
            yield func()
    except exception:
        pass

def first_true(iterable, default=False, pred=None):
    """Returns the first true value in the iterable.

    If no true value is found, returns *default*

    If *pred* is not None, returns the first item
    for which pred(item) is true.

    """
    # 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(pred, iterable), default)

def random_product(*args, repeat=1):
    "Random selection from itertools.product(*args, **kwds)"
    pools = [tuple(pool) for pool in args] * repeat
    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(range(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 range(r))
    return tuple(pool[i] for i in indices)

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, map=map, mul=operator.mul):
    return sum(map(mul, vec1, vec2))