itertools — Funktioner som skapar iteratorer för effektiv loopning

---

Denna modul implementerar ett antal iterator-byggstenar inspirerade av konstruktioner från APL, Haskell och SML. Var och en har omarbetats i en form som passar Python.

Modulen standardiserar en kärna av snabba, minneseffektiva verktyg som är användbara var för sig eller i kombination. Tillsammans bildar de en ”iteratoralgebra” som gör det möjligt att konstruera specialiserade verktyg på ett kortfattat och effektivt sätt i ren Python.

I SML finns till exempel ett verktyg för tabulering: tabulate(f) som producerar en sekvens f(0), f(1), .... Samma effekt kan uppnås i Python genom att kombinera map() och count() för att bilda map(f, count()).

Obegränsade iteratorer:

Iterator	Argument	Resultat	Exempel
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, … oändligt eller upp till n gånger	repeat(10, 3) → 10 10 10

Iteratorer som slutar på den kortaste inmatningssekvensen:

Iterator	Argument	Resultat	Exempel
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=2) → AB CD EF G
chain()	p, q, …	p0, p1, … plast, q0, q1, …	chain('ABC', 'DEF') → A B C D E F
chain.from_iterable()	itererbar	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], startar när predikatet misslyckas	dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8
filterfalse()	predicate, seq	element i seq där predikat(elem) misslyckas	filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8
groupby()	iterable[, key]	underiteratorer grupperade efter nyckelns värde(v)	groupby(['A','B','DEF'], len) → (1, A B) (3, DEF)
islice()	seq, [start,] stop [, step]	element från seq[start:stopp:steg]	islice('ABCDEFG', 2, None) → C D E F G
pairwise()	itererbar	(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], tills predikatet misslyckas	takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4
tee()	it, n	it1, it2, … itn delar upp en iterator i n	tee('ABC', 2) → A B C, A B C
zip_longest()	p, q, …	(p[0], q[0]), (p[1], q[1]), …	zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-

Kombinatoriska iteratorer:

Iterator	Argument	Resultat
product()	p, q, … [repeat=1]	cartesiansk produkt, motsvarande en nästlad for-loop
permutations()	p[, r]	r-längds tupler, alla möjliga ordningar, inga upprepade element
combinations()	p, r	r-långa tupler, i sorterad ordning, inga upprepade element
combinations_with_replacement()	p, r	r-långa tuples, i sorterad ordning, med upprepade element

Exempel	Resultat
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-funktioner

Följande funktioner konstruerar och returnerar alla iteratorer. Vissa ger oändligt långa strömmar, så de bör endast användas av funktioner eller loopar som förkortar strömmen.

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

Skapa en iterator som returnerar ackumulerade summor eller ackumulerade resultat från andra binära funktioner.

Standardvärdet för funktionen är addition. Funktionen ska acceptera två argument, en ackumulerad summa och ett värde från iterabeln.

Om ett initial värde anges kommer ackumuleringen att börja med det värdet och utmatningen kommer att ha ett element mer än den ingående iterabeln.

Ungefär motsvarande:

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

För att beräkna ett löpande minimum, sätt function till min(). För ett löpande maximum, sätt function till max(). Eller för en löpande produkt, sätt function till operator.mul(). För att bygga en amorteringstabell, ackumulera räntan och använd betalningar:

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

Se functools.reduce() för en liknande funktion som bara returnerar det slutliga ackumulerade värdet.

Tillagd i version 3.2.

Ändrad i version 3.3: Lagt till den valfria parametern function.

Ändrad i version 3.8: Den valfria parametern initial har lagts till.

itertools.batched(iterable, n, *, strict=False)

Batcha data från iterable till tupler av längden n. Den sista satsen kan vara kortare än n.

Om strict är true, kommer ett ValueError att uppstå om den slutliga batchen är kortare än n.

Loopar över inmatningens iterabel och ackumulerar data i tupler upp till storlek n. Indata konsumeras lättsinnigt, bara tillräckligt för att fylla en batch. Resultatet ges så snart batchen är full eller när den ingående iterabeln är uttömd:

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

Ungefär motsvarande:

def batched(iterabel, n, *, strict=False):
    # batched('ABCDEFG', 2) → AB CD EF G
    om n < 1:
        raise ValueError('n måste vara minst ett')
    iterator = iter(iterabel)
    while batch := tuple(islice(iterator, n)):
        if strict och len(batch) != n:
            raise ValueError('batched(): ofullständig batch')
        avkastning batch

Tillagd i version 3.12.

Ändrad i version 3.13: Lagt till alternativet strict.

itertools.chain(*iterables)

Skapa en iterator som returnerar element från den första iterabeln tills den är uttömd, sedan fortsätter den till nästa iterabel tills alla iterabler är uttömda. Detta kombinerar flera datakällor till en enda iterator. Ungefär likvärdigt med:

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

classmethod chain.from_iterable(iterable)

Alternativ konstruktör för chain(). Får kedjade ingångar från ett enda iterabelt argument som utvärderas latent. Ungefär likvärdig med:

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)

Returnerar r långa undersekvenser av element från indata iterable.

Utdata är en undersekvens av product() som bara innehåller poster som är undersekvenser av iterable. Längden på utmatningen ges av math.comb() som beräknar n! / r! / (n - r)! när 0 ≤ r ≤ n eller noll när r > n.

Kombinationstuplarna skickas ut i lexikografisk ordning enligt ordningen i indata iterable. Om indata iterable är sorterad, kommer utdatatuplarna att produceras i sorterad ordning.

Element behandlas som unika baserat på deras position, inte på deras värde. Om inmatningselementen är unika kommer det inte att finnas några upprepade värden inom varje kombination.

Ungefär motsvarande:

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)

Returnerar r långa undersekvenser av element från indata iterable vilket gör att enskilda element kan upprepas mer än en gång.

Utdata är en undersekvens av product() som endast innehåller poster som är undersekvenser (med möjliga upprepade element) av iterable. Antalet undersekvenser som returneras är (n + r - 1)! / r! / (n - 1)! när n > 0.

Kombinationstuplerna skickas ut i lexikografisk ordning enligt ordningen på indata iterable. Om indata iterable är sorterad kommer utdatatuplerna att produceras i sorterad ordning.

Element behandlas som unika baserat på deras position, inte på deras värde. Om inmatningselementen är unika kommer de genererade kombinationerna också att vara unika.

Ungefär motsvarande:

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)

Tillagd i version 3.1.

itertools.compress(data, selectors)

Skapa en iterator som returnerar element från data där motsvarande element i selectors är sant. Stoppar när antingen iteratorerna data eller selectors har uttömts. Ungefär likvärdig med:

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)

Tillagd i version 3.1.

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

Skapa en iterator som returnerar jämnt fördelade värden som börjar med start. Kan användas med map() för att generera konsekutiva datapunkter eller med zip() för att lägga till sekvensnummer. Ungefär likvärdig med:

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

När man räknar med flyttal kan man ibland uppnå bättre noggrannhet genom att ersätta multiplikativ kod som t.ex: (start + steg * i för i i count()).

Ändrad i version 3.1: Lagt till step-argumentet och tillåter argument som inte är heltal.

itertools.cycle(iterable)

Skapa en iterator som returnerar element från iterabeln och sparar en kopia av varje element. När iterabeln är uttömd returnerar du element från den sparade kopian. Upprepas på obestämd tid. Ungefär likvärdig med:

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

Detta itertool kan kräva betydande extra lagring (beroende på iterabelns längd).

itertools.dropwhile(predicate, iterable)

Skapa en iterator som tar bort element från iterable medan predicate är sant och därefter returnerar varje element. Ungefär likvärdig med:

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

    iterator = iter(iterabel)
    för x i iterator:
        if not predicate(x):
            ge x
            bryt

    för x i iterator:
        avkastning x

Observera att detta inte producerar någon utdata förrän predikatet först blir falskt, så detta itertool kan ha en lång starttid.

itertools.filterfalse(predicate, iterable)

Skapa en iterator som filtrerar element från iterable och returnerar endast de element för vilka predicate returnerar ett falskt värde. Om predicate är None, returneras de objekt som är falska. Ungefär likvärdig med:

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)

Skapa en iterator som returnerar på varandra följande nycklar och grupper från iterable. key är en funktion som beräknar ett nyckelvärde för varje element. Om den inte specificeras eller är None, är key som standard en identitetsfunktion och returnerar elementet oförändrat. I allmänhet måste iterabeln redan vara sorterad på samma nyckelfunktion.

groupby() fungerar på samma sätt som uniq-filtret i Unix. Det genererar en paus eller en ny grupp varje gång värdet på nyckelfunktionen ändras (vilket är anledningen till att det vanligtvis är nödvändigt att ha sorterat data med samma nyckelfunktion). Detta beteende skiljer sig från SQL:s GROUP BY som aggregerar gemensamma element oberoende av deras inmatningsordning.

Den returnerade gruppen är i sig en iterator som delar den underliggande iterabeln med groupby(). Eftersom källan är delad är den föregående gruppen inte längre synlig när groupby()-objektet flyttas fram. Så om dessa data behövs senare bör de lagras som en lista:

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() är ungefär likvärdigt med:

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

Skapa en iterator som returnerar valda element från iterabeln. Fungerar som sequence slicing men stöder inte negativa värden för start, stop eller step.

Om start är noll eller None börjar iterationen vid noll. I annat fall hoppas element från iterationen över tills start nås.

Om stop är None fortsätter iterationen tills inmatningen är uttömd, om alls. Annars stannar den vid den angivna positionen.

Om step är None är standardsteget ett. Element returneras i följd såvida inte step är högre än ett, vilket resulterar i att element hoppas över.

Ungefär motsvarande:

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

Om indata är en iterator, kommer fullständig konsumtion av islice att flytta fram indata-iteratorn med max(start, stop) steg oavsett step-värdet.

itertools.pairwise(iterable)

Returnerar successiva överlappande par hämtade från indata iterable.

Antalet 2-tupler i utgångsiteratorn kommer att vara en färre än antalet ingångar. Den kommer att vara tom om inmatningsiterabeln har färre än två värden.

Ungefär motsvarande:

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

Tillagd i version 3.10.

itertools.permutations(iterable, r=None)

Returnera successiva r långa permutationer av element från iterable.

Om r inte anges eller är None, är r standardvärdet för längden på iterable och alla möjliga permutationer med full längd genereras.

Utdata är en delsekvens av product() där poster med upprepade element har filtrerats bort. Längden på utmatningen ges av math.perm() som beräknar n! / (n - r)! när 0 ≤ r ≤ n eller noll när r > n.

Permutationstuplerna skickas ut i lexikografisk ordning enligt ordningen i indata iterable. Om indata iterable är sorterad, kommer utdatatuplarna att produceras i sorterad ordning.

Elementen behandlas som unika baserat på deras position, inte på deras värde. Om inmatningselementen är unika kommer det inte att finnas några upprepade värden inom en permutation.

Ungefär motsvarande:

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)

Cartesiansk produkt av de ingående iterablerna.

Motsvarar i stort sett kapslade for-slingor i ett generatoruttryck. Till exempel ger product(A, B) samma resultat som ((x,y) for x in A for y in B).

De nästlade looparna går som en odometer där elementet längst till höger avancerar vid varje iteration. Detta mönster skapar en lexikografisk ordning så att om indatans iterabler är sorterade, skickas produkttuplerna ut i sorterad ordning.

Om du vill beräkna produkten av en iterabel med sig själv anger du antalet repetitioner med det valfria nyckelordsargumentet repeat. Till exempel betyder product(A, repeat=4) samma sak som product(A, A, A, A).

Denna funktion motsvarar i stort sett följande kod, förutom att den faktiska implementeringen inte bygger upp mellanresultat i minnet:

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

    if repeat < 0:
        raise ValueError('repeat argument cannot be negative')
    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)

Innan product() körs förbrukar den helt de ingående iterablerna och behåller värdepooler i minnet för att generera produkterna. Följaktligen är den endast användbar med ändliga indata.

itertools.repeat(object[, times])

Skapa en iterator som returnerar objekt om och om igen. Körs på obestämd tid om inte argumentet times anges.

Ungefär motsvarande:

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

En vanlig användning av repeat är att leverera en ström av konstanta värden till map eller zip:

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

itertools.starmap(function, iterable)

Skapa en iterator som beräknar funktionen med hjälp av argument som hämtas från iterabeln. Används istället för map() när argumentparametrar redan har ”förzippats” till tupler.

Skillnaden mellan map() och starmap() motsvarar skillnaden mellan function(a,b) och function(*c). Ungefär likvärdig med:

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)

Gör en iterator som returnerar element från iterable så länge som predicate är sant. Ungefär likvärdig med:

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

Observera att det element som först misslyckas med predikatsvillkoret konsumeras från inmatningsiteratorn och det finns inget sätt att komma åt det. Detta kan vara ett problem om en applikation vill fortsätta att konsumera inmatningsiteratorn efter att takewhile har körts till utmattning. För att komma runt detta problem kan du överväga att använda more-itertools before_and_after() istället.

itertools.tee(iterable, n=2)

Returnerar n oberoende iteratorer från en enda iterabel.

Ungefär motsvarande:

def tee(iterable, n=2):
    if n < 0:
        raise ValueError
    if n == 0:
        return ()
    iterator = _tee(iterable)
    result = [iterator]
    for _ in range(n - 1):
        result.append(_tee(iterator))
    return tuple(result)

class _tee:

    def __init__(self, iterable):
        it = iter(iterable)
        if isinstance(it, _tee):
            self.iterator = it.iterator
            self.link = it.link
        else:
            self.iterator = it
            self.link = [None, None]

    def __iter__(self):
        return self

    def __next__(self):
        link = self.link
        if link[1] is None:
            link[0] = next(self.iterator)
            link[1] = [None, None]
        value, self.link = link
        return value

När indata iterable redan är ett tee iterator-objekt, konstrueras alla medlemmar i retur-tupeln som om de hade producerats av tee()-anropet uppströms. Detta ”utjämningssteg” gör att nästlade tee()-anrop kan dela samma underliggande datakedja och ha ett enda uppdateringssteg i stället för en kedja av anrop.

Flattening-egenskapen gör att tee-iteratorer effektivt kan tittas på:

def lookahead(tee_iterator):
     "Return the next value without moving the input forward"
     [forked_iterator] = tee(tee_iterator, 1)
     return next(forked_iterator)

>>> iterator = iter('abcdef')
>>> [iterator] = tee(iterator, 1)   # Make the input peekable
>>> next(iterator)                  # Move the iterator forward
'a'
>>> lookahead(iterator)             # Check next value
'b'
>>> next(iterator)                  # Continue moving forward
'b'

tee iteratorer är inte trådsäkra. Ett RuntimeError kan uppstå vid samtidig användning av iteratorer som returneras av samma tee()-anrop, även om den ursprungliga iterable är trådlös.

Detta itertool kan kräva betydande extra lagring (beroende på hur mycket temporär data som behöver lagras). Om en iterator använder det mesta eller all data innan en annan iterator startar, är det i allmänhet snabbare att använda list() i stället för tee().

itertools.zip_longest(*iterables, fillvalue=None)

Skapa en iterator som aggregerar element från var och en av iteratorerna.

Om iterablerna är av ojämn längd fylls saknade värden i med fillvalue. Om det inte anges är fillvalue standardvärdet None.

Iterationen fortsätter tills den längsta iteratorn är uttömd.

Ungefär motsvarande:

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)

Om en av iterationerna är potentiellt oändlig bör funktionen zip_longest() omslutas av något som begränsar antalet anrop (t.ex. islice() eller takewhile()).

Itertools Recept

I det här avsnittet visas recept för att skapa en utökad verktygssats med hjälp av befintliga itertools som byggstenar.

Det primära syftet med itertools-recepten är pedagogiskt. Recepten visar olika sätt att tänka på enskilda verktyg - till exempel att chain.from_iterable är relaterat till begreppet utplattning. Recepten ger också idéer om hur verktygen kan kombineras - till exempel hur starmap() och repeat() kan fungera tillsammans. Recepten visar också mönster för hur itertools kan användas med modulerna operator och collections samt med de inbyggda itertools som map(), filter(), reversed() och enumerate().

Ett sekundärt syfte med recepten är att fungera som en inkubator. Itertools accumulate(), compress() och pairwise() började som recept. För närvarande testas recepten liding_window(), iter_index() och sieve() för att se om de visar sitt värde.

I stort sett alla dessa recept och många, många andra kan installeras från more-itertools-projektet som finns på Python Package Index:

python -m pip install more-itertools

Många av recepten erbjuder samma höga prestanda som den underliggande verktygsmängden. Överlägsen minnesprestanda bibehålls genom att bearbeta element ett i taget snarare än att föra in hela iterabeln i minnet på en gång. Kodvolymen hålls liten genom att verktygen länkas samman i en funktionell stil. Hög hastighet bibehålls genom att föredra ”vektoriserade” byggblock framför användning av for-loopar och generators som medför tolkningsoverhead.

from collections import Counter, deque
from contextlib import suppress
from functools import reduce
from math import comb, prod, sumprod, isqrt
from operator import itemgetter, getitem, mul, neg

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(function, times=None, *args):
    "Repeat calls to a function with specified arguments."
    if times is None:
        return starmap(function, repeat(args))
    return starmap(function, 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 loops(n):
    "Loop n times. Like range(n) but without creating integers."
    # for _ in loops(100): ...
    return repeat(None, n)

def tail(n, iterable):
    "Return an iterator over the last n items."
    # tail(3, 'ABCDEFG') → E F G
    return iter(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:
        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(itemgetter(0), groupby(iterable))
    return map(next, map(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]
   sequenced = sorted(iterable, key=key, reverse=reverse)
   return unique_justseen(sequenced, 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 = 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 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(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 suppress(ValueError):
            while True:
                yield (i := seq_index(value, i, stop))
                i += 1

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

Följande recept har en mer matematisk smak:

def multinomial(*counts):
    "Number of distinct arrangements of a multiset."
    # Counter('abracadabra').values() → 5 2 2 1 1
    # multinomial(5, 2, 2, 1, 1) → 83160
    return prod(map(comb, accumulate(counts), counts))

def powerset(iterable):
    "Subsequences of the iterable from shortest to longest."
    # 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 sumprod(*tee(iterable))

def reshape(matrix, columns):
    "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), columns, strict=True)

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(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(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(neg, roots))
    return list(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 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(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=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(isqrt(n) + 1):
        while not n % prime:
            yield prime
            n //= prime
            if n == 1:
                return
    if n > 1:
        yield n

def is_prime(n):
    "Return True if n is prime."
    # is_prime(1_000_000_000_000_403) → True
    return n > 1 and next(factor(n)) == 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