L'itérateur : __iter__, __next__, StopIteration The iterator: __iter__, __next__, StopIteration

for x in y n'est pas une primitive du langage : c'est iter(y) puis next() en boucle jusqu'à StopIteration. Cette désucre cache une distinction que la plupart des devs ne font jamais — un itérable et un itérateur ne sont pas la même chose. L'un se reparcourt à volonté ; l'autre s'épuise, une fois, et ne le dit à personne. for x in y isn't a language primitive: it's iter(y) then next() in a loop until StopIteration. That desugaring hides a distinction most devs never make — an iterable and an iterator aren't the same thing. One can be walked again and again; the other gets exhausted, once, and tells no one.

Audience
Dev qui a déjà vu une deuxième boucle for tourner à vide sans comprendre pourquoi Dev who's seen a second for loop run empty without understanding why
ChapitresChapters
5
LectureReading
≈ 18 min
NiveauLevel
●●○○
Date
Juil 2026 Jul 2026

ItérateursData modelfor

SommaireContents ·
№ 01CadrageFraming3 min

for n'est pas une boucle native — c'est un while qui attrape une exception.for isn't a native loop — it's a while catching an exception.

Le Vol. III a posé le principe : la syntaxe désucre en dunders, cherchés sur le type. Ce volume applique ce même principe à un axe qu'on n'avait pas encore touché — le temps. for x in y appelle d'abord y.__iter__() pour obtenir un itérateur, puis appelle __next__() sur ce résultat, encore et encore, jusqu'à ce qu'il lève StopIteration. Cette exception n'est pas une erreur : c'est le signal normal, attendu, de fin de parcours. La boucle for n'est qu'une façade élégante sur ce protocole en deux temps — obtenir un itérateur, puis le tirer jusqu'à épuisement.Vol. III established the principle: syntax desugars into dunders, looked up on the type. This volume applies that same principle to an axis we hadn't touched yet — time. for x in y first calls y.__iter__() to get an iterator, then calls __next__() on that result, again and again, until it raises StopIteration. That exception isn't an error: it's the normal, expected signal that the walk is done. The for loop is just an elegant façade over this two-step protocol — get an iterator, then pull it until exhausted.

Le for désucré en toutes lettresThe for loop desugared in full
for x in y:
    corps(x)

# désucré :
it = iter(y)            # y.__iter__()  -> obtient un itérateur
while True:
    try:
        x = next(it)    # it.__next__() -> une valeur, ou lève StopIteration
    except StopIteration:
        break            # la boucle s'arrête PROPREMENT sur cette exception
    corps(x)
Le sous-réflexe du numéroThis issue's sub-reflex

Chaque fois que tu écris for, demande : l'objet que je parcours produit-il un itérateur frais à chaque appel de iter(), ou EST-il déjà l'itérateur ? La réponse change tout pour un second passage.Every time you write for, ask: does the object I'm walking produce a fresh iterator on each call to iter(), or IS it already the iterator? The answer changes everything for a second pass.

StopIteration n'est pas un échecStopIteration isn't a failure

C'est le cas le plus visible en Python où une exception sert de mécanisme de contrôle normal, pas d'erreur — le for l'attrape en silence et s'arrête. Laisser StopIteration s'échapper ailleurs que d'un __next__ est en revanche une faute : dans un générateur, depuis Python 3.7 (PEP 479), elle est convertie en RuntimeError.It's the most visible case in Python where an exception serves as a normal control mechanism, not an error — for catches it silently and stops. Letting StopIteration escape from anywhere but a __next__ is however a mistake: inside a generator, since Python 3.7 (PEP 479), it is converted into a RuntimeError.

№ 02La surpriseThe surprise4 min

Un itérable se reparcourt. Un itérateur est le parcours — une fois.An iterable can be re-walked. An iterator is the walk — once.

Voici la distinction que la plupart des devs ne font jamais, parce que dans le cas le plus courant elle ne se voit pas. Une liste est un itérable : son __iter__ fabrique un nouvel objet itérateur à chaque appel, donc chaque for repart de zéro. Mais le résultat de iter(x) est lui-même un itérateur — et son __iter__ à lui ne fabrique rien de nouveau, il retourne self. Boucler une seconde fois dessus ne relance rien : l'objet garde en mémoire où il s'était arrêté, et il est déjà arrivé au bout.Here's the distinction most devs never make, because in the common case it's invisible. A list is an iterable: its __iter__ builds a brand-new iterator object on every call, so each for loop starts fresh. But the result of iter(x) is itself an iterator — and its own __iter__ builds nothing new, it returns self. Looping over it a second time restarts nothing: the object remembers where it stopped, and it already reached the end.

Une liste refabrique un itérateur neuf à chaque forA list rebuilds a fresh iterator on every for
nombres = [1, 2, 3]        # un ITÉRABLE : sait produire un itérateur

for x in nombres: ...       # 1er passage : iter(nombres) -> itérateur #1, épuisé
for x in nombres: ...       # 2e passage  : iter(nombres) -> itérateur #2, NEUF
# nombres.__iter__() fabrique un objet nouveau à chaque appel -> reparcourable

C'est le cas confortable, celui qu'on rencontre 95 % du temps : list, dict, str, set sont des itérables « purs » — ils ne gardent aucun état de parcours eux-mêmes, ils délèguent à un itérateur jetable créé à la volée. D'où l'illusion que « tout se reparcourt » en Python.This is the comfortable case, the one you hit 95% of the time: list, dict, str, set are "pure" iterables — they hold no walk state themselves, they delegate to a disposable iterator built on the fly. Hence the illusion that "everything re-walks" in Python.

Le test qui distingue les deuxThe test that tells them apart

iter(x) is x — si True, x est déjà son propre itérateur : à usage unique. Si False, x est un itérable pur : reparcourable à volonté.iter(x) is x — if True, x is already its own iterator: single-use. If False, x is a pure iterable: re-walkable at will.

№ 03La mécaniqueThe mechanics5 min

Écrire un itérateur, c'est porter l'état ; écrire un itérable, c'est le déléguer.Writing an iterator means holding state; writing an iterable means delegating it.

La différence entre les deux tient à une seule ligne : ce que __iter__ retourne. Un itérateur retourne self — il est sa propre mémoire de parcours, stockée dans ses attributs d'instance, et __next__ la fait avancer d'un cran à chaque appel jusqu'à lever StopIteration. Un itérable, lui, ne garde aucun état : son __iter__ construit et retourne un objet itérateur neuf, qui lui portera l'état. C'est tout le secret de la reparcourabilité — pas de magie, juste la question de savoir qui porte le curseur.The difference between the two comes down to a single line: what __iter__ returns. An iterator returns self — it is its own walk memory, stored in its instance attributes, and __next__ advances it one step per call until it raises StopIteration. An iterable, on the other hand, holds no state: its __iter__ builds and returns a fresh iterator object, which will carry the state instead. That's the entire secret of re-walkability — no magic, just a question of who holds the cursor.

L'objet porte lui-même son curseur de parcoursThe object itself carries its walk cursor
class Compteur:                      # un ITÉRATEUR : porte l'état du parcours
    def __init__(self, fin):
        self.n, self.fin = 0, fin
    def __iter__(self):
        return self                  # <- retourne self : c'est SA marque de fabrique
    def __next__(self):
        if self.n >= self.fin:
            raise StopIteration       # le signal de fin, explicite
        self.n += 1
        return self.n

c = Compteur(3)
list(c)              # [1, 2, 3]
list(c)               # []  — self.n vaut déjà 3, épuisé pour de bon

self.n est l'état gelé entre deux appels de __next__ — c'est la même idée que le générateur du prochain numéro, en version manuelle et explicite. Une fois self.n == self.fin, l'objet est épuisé pour toujours : rien ne le réinitialise, sauf en recréer un.self.n is the state frozen between two __next__ calls — the same idea as next issue's generator, in a manual, explicit form. Once self.n == self.fin, the object is exhausted forever: nothing resets it, short of building a new one.

Un itérateur qui retourne self depuis __iter__ n'est pas un raccourci. C'est l'aveu qu'il ne sait faire le parcours qu'une fois.An iterator returning self from __iter__ isn't a shortcut. It's the admission that it can only walk once.
№ 04Le piègeThe trap4 min

Un itérateur épuisé ne redevient jamais vide par erreur — il l'est, tout simplement.An exhausted iterator never goes empty by mistake — it simply is empty.

Le piège de ce numéro ne ressemble à rien d'autre dans la série : il n'y a pas d'exception à intercepter, pas de valeur fausse à corriger. Il y a juste une seconde opération qui, silencieusement, ne trouve plus rien à traiter — parce que la première l'a déjà tout consommé. map(), zip(), filter() renvoient des itérateurs, pas des listes : les enchaîner comme si on pouvait les relire deux fois est l'erreur la plus commune du volume, et la plus difficile à repérer en revue de code, parce que la ligne fautive est syntaxiquement irréprochable.This issue's trap doesn't resemble anything else in the series: there's no exception to catch, no wrong value to fix. There's just a second operation that, silently, finds nothing left to process — because the first one already consumed it all. map(), zip(), filter() return iterators, not lists: chaining them as if you could read them twice is this volume's most common mistake, and the hardest to spot in code review, because the offending line is syntactically flawless.

sum() vide carres avant que max() ne s'en approchesum() drains carres before max() gets near it
carres = map(lambda x: x * x, [1, 2, 3])

total = sum(carres)          # 14 — carres est consommé jusqu'au bout
maximum = max(carres)        # ValueError: max() iterable argument is empty
                              # carres n'a plus rien à donner : personne ne l'a signalé
                              # avant que max() tombe sur un StopIteration immédiat

sum() a fait exactement son travail : parcourir carres jusqu'à StopIteration. Le problème n'est pas dans sum(), ni dans max() — il est dans l'hypothèse implicite que carres se reparcourt. Rien dans la syntaxe ne distingue un map() (itérateur) d'une liste (itérable) ; seule la documentation, ou l'habitude, le sait.sum() did exactly its job: walk carres until StopIteration. The problem isn't in sum(), nor in max() — it's the implicit assumption that carres re-walks. Nothing in the syntax distinguishes a map() (iterator) from a list (iterable); only documentation, or habit, tells you.

Le contre-emploiThe counter-use

Ne matérialise pas par réflexe un itérateur qui ne sera parcouru qu'une fois — sum(map(...)) seul, sans second passage, n'a besoin d'aucune liste intermédiaire. list() n'est un fix que si un second parcours est réellement prévu.Don't materialize an iterator by reflex when it'll only ever be walked once — a lone sum(map(...)), with no second pass, needs no intermediate list. list() is only a fix when a second walk is actually planned.

Le réflexe en une phraseThe reflex in one sentence

Si un résultat doit être lu plus d'une fois, matérialise-le une seule fois avec list() — sinon, laisse-le itérateur, et parcours-le exactement une fois.If a result needs reading more than once, materialize it once with list() — otherwise, leave it an iterator, and walk it exactly once.

№ 05Bilan & éditoWrap-up & editorial2 min

Le protocole appliqué au temps : produire une valeur, pas la posséder.The protocol applied to time: producing a value, not owning it.

Un itérateur ne stocke pas une collection : il sait juste répondre à une question, une fois de plus, jusqu'à ce qu'il n'ait plus rien à dire. C'est un déplacement radical par rapport à tout ce qu'on a vu jusqu'ici dans la série — les Vol. I et II parlaient d'objets qui existent, qu'on référence, qu'on copie. Un itérateur, lui, n'a d'existence que dans l'acte de le tirer : entre deux appels à next(), il ne « fait » rien, il attend, son état gelé dans quelques attributs d'instance.An iterator doesn't store a collection: it just knows how to answer a question, one more time, until it has nothing left to say. That's a radical shift from everything we've seen so far in the series — Vol. I and II were about objects that exist, that you reference, that you copy. An iterator only exists in the act of pulling it: between two calls to next(), it 'does' nothing, it waits, its state frozen in a few instance attributes.

NotionConceptCe qu'il faut en retenirWhat to take away
ItérableIterableSait produire un itérateur neuf à chaque iter() — reparcourable à volonté.Knows how to produce a fresh iterator on every iter() — re-walkable at will.
ItérateurIterator__iter__ retourne self ; __next__ avance un état interne, s'épuise une fois.__iter__ returns self; __next__ advances internal state, exhausts once.
StopIterationLe signal normal de fin de parcours — pas une erreur, un protocole.The normal end-of-walk signal — not an error, a protocol.
list()Le prix de la reparcourabilité : toute la mémoire, d'un coup.The price of re-walkability: all the memory, at once.
Un itérateur ne te ment jamais. Il te dit juste la vérité une fois, et considère l'affaire close.An iterator never lies to you. It just tells you the truth once, and considers the matter closed.
Mot de l'éditeurFrom the editor

Écrire un itérateur à la main, comme au Ch3, est mécanique et répétitif.Writing an iterator by hand, as in Ch3, is mechanical and repetitive.

__init__ pour poser l'état, __iter__ qui retourne self, __next__ qui avance et lève StopIteration au bon moment : trois méthodes, toujours la même forme, pour la moindre séquence paresseuse. Python offre un raccourci qui génère tout ça depuis une simple fonction — au prix d'une mécanique interne plus étonnante encore que le protocole qu'on vient de voir : une fonction qui se met en pause, littéralement, entre deux appels, et qui reprend exactement où elle en était.__init__ to set the state, __iter__ returning self, __next__ advancing and raising StopIteration at the right moment: three methods, always the same shape, for the smallest lazy sequence. Python offers a shortcut that generates all of this from a plain function — at the cost of an internal mechanic even more surprising than the protocol we just saw: a function that pauses, literally, between two calls, and resumes exactly where it left off.

Prochain numéro : le générateur — yield, la fonction qui se suspend. L'état gelé entre deux next() sans une seule ligne d'attribut d'instance ; la paresse poussée à son terme ; pourquoi une liste de dix millions d'éléments et un générateur qui les produit un par un ne se comparent pas sur les mêmes critères.Next issue: the generator — yield, the function that suspends itself. State frozen between two next() calls without a single instance-attribute line; laziness taken to its limit; why a ten-million-element list and a generator producing them one at a time don't compare on the same criteria.