CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 234 – Iterators | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0234/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 234 – Iterators | peps.python.org'> <meta property="og:description" content="This document proposes an iteration interface that objects can provide to control the behaviour of for loops. Looping is customized by providing a method that produces an iterator object. The iterator provides a get next value operation that produces ..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0234/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This document proposes an iteration interface that objects can provide to control the behaviour of for loops. Looping is customized by providing a method that produces an iterator object. The iterator provides a get next value operation that produces ..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 234</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 234 – Iterators</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Ka-Ping Yee <ping at zesty.ca>, Guido van Rossum <guido at python.org></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">30-Jan-2001</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.1</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">30-Apr-2001</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#c-api-specification">C API Specification</a></li> <li><a class="reference internal" href="#python-api-specification">Python API Specification</a></li> <li><a class="reference internal" href="#dictionary-iterators">Dictionary Iterators</a></li> <li><a class="reference internal" href="#file-iterators">File Iterators</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#resolved-issues">Resolved Issues</a></li> <li><a class="reference internal" href="#mailing-lists">Mailing Lists</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This document proposes an iteration interface that objects can provide to control the behaviour of <code class="docutils literal notranslate">for</code> loops. Looping is customized by providing a method that produces an iterator object. The iterator provides a get next value operation that produces the next item in the sequence each time it is called, raising an exception when no more items are available. In addition, specific iterators over the keys of a dictionary and over the lines of a file are proposed, and a proposal is made to allow spelling <code class="docutils literal notranslate">dict.has_key(key)</code> as <code class="docutils literal notranslate">key in dict</code>. Note: this is an almost complete rewrite of this PEP by the second author, describing the actual implementation checked into the trunk of the Python 2.2 CVS tree. It is still open for discussion. Some of the more esoteric proposals in the original version of this PEP have been withdrawn for now; these may be the subject of a separate PEP in the future. </section> <section id="c-api-specification"> <h2><a class="toc-backref" href="#c-api-specification" role="doc-backlink">C API Specification</a></h2> A new exception is defined, <code class="docutils literal notranslate">StopIteration</code>, which can be used to signal the end of an iteration. A new slot named <code class="docutils literal notranslate">tp_iter</code> for requesting an iterator is added to the type object structure. This should be a function of one <code class="docutils literal notranslate">PyObject *</code> argument returning a <code class="docutils literal notranslate">PyObject *</code>, or <code class="docutils literal notranslate">NULL</code>. To use this slot, a new C API function <code class="docutils literal notranslate">PyObject_GetIter()</code> is added, with the same signature as the <code class="docutils literal notranslate">tp_iter</code> slot function. Another new slot, named <code class="docutils literal notranslate">tp_iternext</code>, is added to the type structure, for obtaining the next value in the iteration. To use this slot, a new C API function <code class="docutils literal notranslate">PyIter_Next()</code> is added. The signature for both the slot and the API function is as follows, although the <code class="docutils literal notranslate">NULL</code> return conditions differ: the argument is a <code class="docutils literal notranslate">PyObject *</code> and so is the return value. When the return value is non-<code class="docutils literal notranslate">NULL</code>, it is the next value in the iteration. When it is <code class="docutils literal notranslate">NULL</code>, then for the <code class="docutils literal notranslate">tp_iternext slot</code> there are three possibilities: <ul class="simple"> <li>No exception is set; this implies the end of the iteration.</li> <li>The <code class="docutils literal notranslate">StopIteration</code> exception (or a derived exception class) is set; this implies the end of the iteration.</li> <li>Some other exception is set; this means that an error occurred that should be propagated normally.</li> </ul> The higher-level <code class="docutils literal notranslate">PyIter_Next()</code> function clears the <code class="docutils literal notranslate">StopIteration</code> exception (or derived exception) when it occurs, so its <code class="docutils literal notranslate">NULL</code> return conditions are simpler: <ul class="simple"> <li>No exception is set; this means iteration has ended.</li> <li>Some exception is set; this means an error occurred, and should be propagated normally.</li> </ul> Iterators implemented in C should not implement a <code class="docutils literal notranslate">next()</code> method with similar semantics as the <code class="docutils literal notranslate">tp_iternext</code> slot! When the type’s dictionary is initialized (by <code class="docutils literal notranslate">PyType_Ready()</code>), the presence of a <code class="docutils literal notranslate">tp_iternext</code> slot causes a method <code class="docutils literal notranslate">next()</code> wrapping that slot to be added to the type’s <code class="docutils literal notranslate">tp_dict</code>. (Exception: if the type doesn’t use <code class="docutils literal notranslate">PyObject_GenericGetAttr()</code> to access instance attributes, the <code class="docutils literal notranslate">next()</code> method in the type’s <code class="docutils literal notranslate">tp_dict</code> may not be seen.) (Due to a misunderstanding in the original text of this PEP, in Python 2.2, all iterator types implemented a <code class="docutils literal notranslate">next()</code> method that was overridden by the wrapper; this has been fixed in Python 2.3.) To ensure binary backwards compatibility, a new flag <code class="docutils literal notranslate">Py_TPFLAGS_HAVE_ITER</code> is added to the set of flags in the <code class="docutils literal notranslate">tp_flags</code> field, and to the default flags macro. This flag must be tested before accessing the <code class="docutils literal notranslate">tp_iter</code> or <code class="docutils literal notranslate">tp_iternext</code> slots. The macro <code class="docutils literal notranslate">PyIter_Check()</code> tests whether an object has the appropriate flag set and has a non-<code class="docutils literal notranslate">NULL</code> <code class="docutils literal notranslate">tp_iternext</code> slot. There is no such macro for the <code class="docutils literal notranslate">tp_iter</code> slot (since the only place where this slot is referenced should be <code class="docutils literal notranslate">PyObject_GetIter()</code>, and this can check for the <code class="docutils literal notranslate">Py_TPFLAGS_HAVE_ITER</code> flag directly). (Note: the <code class="docutils literal notranslate">tp_iter</code> slot can be present on any object; the <code class="docutils literal notranslate">tp_iternext</code> slot should only be present on objects that act as iterators.) For backwards compatibility, the <code class="docutils literal notranslate">PyObject_GetIter()</code> function implements fallback semantics when its argument is a sequence that does not implement a <code class="docutils literal notranslate">tp_iter</code> function: a lightweight sequence iterator object is constructed in that case which iterates over the items of the sequence in the natural order. The Python bytecode generated for <code class="docutils literal notranslate">for</code> loops is changed to use new opcodes, <code class="docutils literal notranslate">GET_ITER</code> and <code class="docutils literal notranslate">FOR_ITER</code>, that use the iterator protocol rather than the sequence protocol to get the next value for the loop variable. This makes it possible to use a <code class="docutils literal notranslate">for</code> loop to loop over non-sequence objects that support the <code class="docutils literal notranslate">tp_iter</code> slot. Other places where the interpreter loops over the values of a sequence should also be changed to use iterators. Iterators ought to implement the <code class="docutils literal notranslate">tp_iter</code> slot as returning a reference to themselves; this is needed to make it possible to use an iterator (as opposed to a sequence) in a <code class="docutils literal notranslate">for</code> loop. Iterator implementations (in C or in Python) should guarantee that once the iterator has signalled its exhaustion, subsequent calls to <code class="docutils literal notranslate">tp_iternext</code> or to the <code class="docutils literal notranslate">next()</code> method will continue to do so. It is not specified whether an iterator should enter the exhausted state when an exception (other than <code class="docutils literal notranslate">StopIteration</code>) is raised. Note that Python cannot guarantee that user-defined or 3rd party iterators implement this requirement correctly. </section> <section id="python-api-specification"> <h2><a class="toc-backref" href="#python-api-specification" role="doc-backlink">Python API Specification</a></h2> The <code class="docutils literal notranslate">StopIteration</code> exception is made visible as one of the standard exceptions. It is derived from <code class="docutils literal notranslate">Exception</code>. A new built-in function is defined, <code class="docutils literal notranslate">iter()</code>, which can be called in two ways: <ul class="simple"> <li><code class="docutils literal notranslate">iter(obj)</code> calls <code class="docutils literal notranslate">PyObject_GetIter(obj)</code>.</li> <li><code class="docutils literal notranslate">iter(callable, sentinel)</code> returns a special kind of iterator that calls the callable to produce a new value, and compares the return value to the sentinel value. If the return value equals the sentinel, this signals the end of the iteration and <code class="docutils literal notranslate">StopIteration</code> is raised rather than returning normal; if the return value does not equal the sentinel, it is returned as the next value from the iterator. If the callable raises an exception, this is propagated normally; in particular, the function is allowed to raise <code class="docutils literal notranslate">StopIteration</code> as an alternative way to end the iteration. (This functionality is available from the C API as <code class="docutils literal notranslate">PyCallIter_New(callable, sentinel)</code>.)</li> </ul> Iterator objects returned by either form of <code class="docutils literal notranslate">iter()</code> have a <code class="docutils literal notranslate">next()</code> method. This method either returns the next value in the iteration, or raises <code class="docutils literal notranslate">StopIteration</code> (or a derived exception class) to signal the end of the iteration. Any other exception should be considered to signify an error and should be propagated normally, not taken to mean the end of the iteration. Classes can define how they are iterated over by defining an <code class="docutils literal notranslate">__iter__()</code> method; this should take no additional arguments and return a valid iterator object. A class that wants to be an iterator should implement two methods: a <code class="docutils literal notranslate">next()</code> method that behaves as described above, and an <code class="docutils literal notranslate">__iter__()</code> method that returns <code class="docutils literal notranslate">self</code>. The two methods correspond to two distinct protocols: <ol class="arabic simple"> <li>An object can be iterated over with <code class="docutils literal notranslate">for</code> if it implements <code class="docutils literal notranslate">__iter__()</code> or <code class="docutils literal notranslate">__getitem__()</code>.</li> <li>An object can function as an iterator if it implements <code class="docutils literal notranslate">next()</code>.</li> </ol> Container-like objects usually support protocol 1. Iterators are currently required to support both protocols. The semantics of iteration come only from protocol 2; protocol 1 is present to make iterators behave like sequences; in particular so that code receiving an iterator can use a for-loop over the iterator. </section> <section id="dictionary-iterators"> <h2><a class="toc-backref" href="#dictionary-iterators" role="doc-backlink">Dictionary Iterators</a></h2> <ul> <li>Dictionaries implement a <code class="docutils literal notranslate">sq_contains</code> slot that implements the same test as the <code class="docutils literal notranslate">has_key()</code> method. This means that we can write<div class="highlight-default notranslate"><div class="highlight"><pre>if k in dict: ... </pre></div> </div> which is equivalent to <div class="highlight-default notranslate"><div class="highlight"><pre>if dict.has_key(k): ... </pre></div> </div> </li> <li>Dictionaries implement a <code class="docutils literal notranslate">tp_iter</code> slot that returns an efficient iterator that iterates over the keys of the dictionary. During such an iteration, the dictionary should not be modified, except that setting the value for an existing key is allowed (deletions or additions are not, nor is the <code class="docutils literal notranslate">update()</code> method). This means that we can write<div class="highlight-default notranslate"><div class="highlight"><pre>for k in dict: ... </pre></div> </div> which is equivalent to, but much faster than <div class="highlight-default notranslate"><div class="highlight"><pre>for k in dict.keys(): ... </pre></div> </div> as long as the restriction on modifications to the dictionary (either by the loop or by another thread) are not violated. </li> <li>Add methods to dictionaries that return different kinds of iterators explicitly:<div class="highlight-default notranslate"><div class="highlight"><pre>for key in dict.iterkeys(): ... for value in dict.itervalues(): ... for key, value in dict.iteritems(): ... </pre></div> </div> This means that <code class="docutils literal notranslate">for x in dict</code> is shorthand for <code class="docutils literal notranslate">for x in dict.iterkeys()</code>. </li> </ul> Other mappings, if they support iterators at all, should also iterate over the keys. However, this should not be taken as an absolute rule; specific applications may have different requirements. </section> <section id="file-iterators"> <h2><a class="toc-backref" href="#file-iterators" role="doc-backlink">File Iterators</a></h2> The following proposal is useful because it provides us with a good answer to the complaint that the common idiom to iterate over the lines of a file is ugly and slow. <ul> <li>Files implement a <code class="docutils literal notranslate">tp_iter</code> slot that is equivalent to <code class="docutils literal notranslate">iter(f.readline, "")</code>. This means that we can write<div class="highlight-default notranslate"><div class="highlight"><pre>for line in file: ... </pre></div> </div> as a shorthand for <div class="highlight-default notranslate"><div class="highlight"><pre>for line in iter(file.readline, ""): ... </pre></div> </div> which is equivalent to, but faster than <div class="highlight-default notranslate"><div class="highlight"><pre>while 1: line = file.readline() if not line: break ... </pre></div> </div> </li> </ul> This also shows that some iterators are destructive: they consume all the values and a second iterator cannot easily be created that iterates independently over the same values. You could open the file for a second time, or <code class="docutils literal notranslate">seek()</code> to the beginning, but these solutions don’t work for all file types, e.g. they don’t work when the open file object really represents a pipe or a stream socket. Because the file iterator uses an internal buffer, mixing this with other file operations (e.g. <code class="docutils literal notranslate">file.readline()</code>) doesn’t work right. Also, the following code: <div class="highlight-default notranslate"><div class="highlight"><pre>for line in file: if line == "\n": break for line in file: print line, </pre></div> </div> doesn’t work as you might expect, because the iterator created by the second for-loop doesn’t take the buffer read-ahead by the first for-loop into account. A correct way to write this is: <div class="highlight-default notranslate"><div class="highlight"><pre>it = iter(file) for line in it: if line == "\n": break for line in it: print line, </pre></div> </div> (The rationale for these restrictions are that <code class="docutils literal notranslate">for line in file</code> ought to become the recommended, standard way to iterate over the lines of a file, and this should be as fast as can be. The iterator version is considerable faster than calling <code class="docutils literal notranslate">readline()</code>, due to the internal buffer in the iterator.) </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> If all the parts of the proposal are included, this addresses many concerns in a consistent and flexible fashion. Among its chief virtues are the following four – no, five – no, six – points: <ol class="arabic simple"> <li>It provides an extensible iterator interface.</li> <li>It allows performance enhancements to list iteration.</li> <li>It allows big performance enhancements to dictionary iteration.</li> <li>It allows one to provide an interface for just iteration without pretending to provide random access to elements.</li> <li>It is backward-compatible with all existing user-defined classes and extension objects that emulate sequences and mappings, even mappings that only implement a subset of {<code class="docutils literal notranslate">__getitem__</code>, <code class="docutils literal notranslate">keys</code>, <code class="docutils literal notranslate">values</code>, <code class="docutils literal notranslate">items</code>}.</li> <li>It makes code iterating over non-sequence collections more concise and readable.</li> </ol> </section> <section id="resolved-issues"> <h2><a class="toc-backref" href="#resolved-issues" role="doc-backlink">Resolved Issues</a></h2> The following topics have been decided by consensus or BDFL pronouncement. <ul> <li>Two alternative spellings for <code class="docutils literal notranslate">next()</code> have been proposed but rejected: <code class="docutils literal notranslate">__next__()</code>, because it corresponds to a type object slot (<code class="docutils literal notranslate">tp_iternext</code>); and <code class="docutils literal notranslate">__call__()</code>, because this is the only operation.Arguments against <code class="docutils literal notranslate">__next__()</code>: while many iterators are used in for loops, it is expected that user code will also call <code class="docutils literal notranslate">next()</code> directly, so having to write <code class="docutils literal notranslate">__next__()</code> is ugly; also, a possible extension of the protocol would be to allow for <code class="docutils literal notranslate">prev()</code>, <code class="docutils literal notranslate">current()</code> and <code class="docutils literal notranslate">reset()</code> operations; surely we don’t want to use <code class="docutils literal notranslate">__prev__()</code>, <code class="docutils literal notranslate">__current__()</code>, <code class="docutils literal notranslate">__reset__()</code>. Arguments against <code class="docutils literal notranslate">__call__()</code> (the original proposal): taken out of context, <code class="docutils literal notranslate">x()</code> is not very readable, while <code class="docutils literal notranslate">x.next()</code> is clear; there’s a danger that every special-purpose object wants to use <code class="docutils literal notranslate">__call__()</code> for its most common operation, causing more confusion than clarity. (In retrospect, it might have been better to go for <code class="docutils literal notranslate">__next__()</code> and have a new built-in, <code class="docutils literal notranslate">next(it)</code>, which calls <code class="docutils literal notranslate">it.__next__()</code>. But alas, it’s too late; this has been deployed in Python 2.2 since December 2001.) </li> <li>Some folks have requested the ability to restart an iterator. This should be dealt with by calling <code class="docutils literal notranslate">iter()</code> on a sequence repeatedly, not by the iterator protocol itself. (See also requested extensions below.)</li> <li>It has been questioned whether an exception to signal the end of the iteration isn’t too expensive. Several alternatives for the <code class="docutils literal notranslate">StopIteration</code> exception have been proposed: a special value <code class="docutils literal notranslate">End</code> to signal the end, a function <code class="docutils literal notranslate">end()</code> to test whether the iterator is finished, even reusing the <code class="docutils literal notranslate">IndexError</code> exception.<ul class="simple"> <li>A special value has the problem that if a sequence ever contains that special value, a loop over that sequence will end prematurely without any warning. If the experience with null-terminated C strings hasn’t taught us the problems this can cause, imagine the trouble a Python introspection tool would have iterating over a list of all built-in names, assuming that the special <code class="docutils literal notranslate">End</code> value was a built-in name!</li> <li>Calling an <code class="docutils literal notranslate">end()</code> function would require two calls per iteration. Two calls is much more expensive than one call plus a test for an exception. Especially the time-critical for loop can test very cheaply for an exception.</li> <li>Reusing <code class="docutils literal notranslate">IndexError</code> can cause confusion because it can be a genuine error, which would be masked by ending the loop prematurely.</li> </ul> </li> <li>Some have asked for a standard iterator type. Presumably all iterators would have to be derived from this type. But this is not the Python way: dictionaries are mappings because they support <code class="docutils literal notranslate">__getitem__()</code> and a handful other operations, not because they are derived from an abstract mapping type.</li> <li>Regarding <code class="docutils literal notranslate">if key in dict</code>: there is no doubt that the <code class="docutils literal notranslate">dict.has_key(x)</code> interpretation of <code class="docutils literal notranslate">x in dict</code> is by far the most useful interpretation, probably the only useful one. There has been resistance against this because <code class="docutils literal notranslate">x in list</code> checks whether x is present among the values, while the proposal makes <code class="docutils literal notranslate">x in dict</code> check whether x is present among the keys. Given that the symmetry between lists and dictionaries is very weak, this argument does not have much weight.</li> <li>The name <code class="docutils literal notranslate">iter()</code> is an abbreviation. Alternatives proposed include <code class="docutils literal notranslate">iterate()</code>, <code class="docutils literal notranslate">traverse()</code>, but these appear too long. Python has a history of using abbrs for common builtins, e.g. <code class="docutils literal notranslate">repr()</code>, <code class="docutils literal notranslate">str()</code>, <code class="docutils literal notranslate">len()</code>.Resolution: <code class="docutils literal notranslate">iter()</code> it is. </li> <li>Using the same name for two different operations (getting an iterator from an object and making an iterator for a function with a sentinel value) is somewhat ugly. I haven’t seen a better name for the second operation though, and since they both return an iterator, it’s easy to remember.Resolution: the builtin <code class="docutils literal notranslate">iter()</code> takes an optional argument, which is the sentinel to look for. </li> <li>Once a particular iterator object has raised <code class="docutils literal notranslate">StopIteration</code>, will it also raise <code class="docutils literal notranslate">StopIteration</code> on all subsequent <code class="docutils literal notranslate">next()</code> calls? Some say that it would be useful to require this, others say that it is useful to leave this open to individual iterators. Note that this may require an additional state bit for some iterator implementations (e.g. function-wrapping iterators).Resolution: once <code class="docutils literal notranslate">StopIteration</code> is raised, calling <code class="docutils literal notranslate">it.next()</code> continues to raise <code class="docutils literal notranslate">StopIteration</code>. Note: this was in fact not implemented in Python 2.2; there are many cases where an iterator’s <code class="docutils literal notranslate">next()</code> method can raise <code class="docutils literal notranslate">StopIteration</code> on one call but not on the next. This has been remedied in Python 2.3. </li> <li>It has been proposed that a file object should be its own iterator, with a <code class="docutils literal notranslate">next()</code> method returning the next line. This has certain advantages, and makes it even clearer that this iterator is destructive. The disadvantage is that this would make it even more painful to implement the “sticky StopIteration” feature proposed in the previous bullet.Resolution: tentatively rejected (though there are still people arguing for this). </li> <li>Some folks have requested extensions of the iterator protocol, e.g. <code class="docutils literal notranslate">prev()</code> to get the previous item, <code class="docutils literal notranslate">current()</code> to get the current item again, <code class="docutils literal notranslate">finished()</code> to test whether the iterator is finished, and maybe even others, like <code class="docutils literal notranslate">rewind()</code>, <code class="docutils literal notranslate">__len__()</code>, <code class="docutils literal notranslate">position()</code>.While some of these are useful, many of these cannot easily be implemented for all iterator types without adding arbitrary buffering, and sometimes they can’t be implemented at all (or not reasonably). E.g. anything to do with reversing directions can’t be done when iterating over a file or function. Maybe a separate PEP can be drafted to standardize the names for such operations when they are implementable. Resolution: rejected. </li> <li>There has been a long discussion about whether<div class="highlight-default notranslate"><div class="highlight"><pre>for x in dict: ... </pre></div> </div> should assign x the successive keys, values, or items of the dictionary. The symmetry between <code class="docutils literal notranslate">if x in y</code> and <code class="docutils literal notranslate">for x in y</code> suggests that it should iterate over keys. This symmetry has been observed by many independently and has even been used to “explain” one using the other. This is because for sequences, <code class="docutils literal notranslate">if x in y</code> iterates over y comparing the iterated values to x. If we adopt both of the above proposals, this will also hold for dictionaries. The argument against making <code class="docutils literal notranslate">for x in dict</code> iterate over the keys comes mostly from a practicality point of view: scans of the standard library show that there are about as many uses of <code class="docutils literal notranslate">for x in dict.items()</code> as there are of <code class="docutils literal notranslate">for x in dict.keys()</code>, with the <code class="docutils literal notranslate">items()</code> version having a small majority. Presumably many of the loops using <code class="docutils literal notranslate">keys()</code> use the corresponding value anyway, by writing <code class="docutils literal notranslate">dict[x]</code>, so (the argument goes) by making both the key and value available, we could support the largest number of cases. While this is true, I (Guido) find the correspondence between <code class="docutils literal notranslate">for x in dict</code> and <code class="docutils literal notranslate">if x in dict</code> too compelling to break, and there’s not much overhead in having to write <code class="docutils literal notranslate">dict[x]</code> to explicitly get the value. For fast iteration over items, use <code class="docutils literal notranslate">for key, value in dict.iteritems()</code>. I’ve timed the difference between <div class="highlight-default notranslate"><div class="highlight"><pre>for key in dict: dict[key] </pre></div> </div> and <div class="highlight-default notranslate"><div class="highlight"><pre>for key, value in dict.iteritems(): pass </pre></div> </div> and found that the latter is only about 7% faster. Resolution: By BDFL pronouncement, <code class="docutils literal notranslate">for x in dict</code> iterates over the keys, and dictionaries have <code class="docutils literal notranslate">iteritems()</code>, <code class="docutils literal notranslate">iterkeys()</code>, and <code class="docutils literal notranslate">itervalues()</code> to return the different flavors of dictionary iterators. </li> </ul> </section> <section id="mailing-lists"> <h2><a class="toc-backref" href="#mailing-lists" role="doc-backlink">Mailing Lists</a></h2> The iterator protocol has been discussed extensively in a mailing list on SourceForge: <blockquote> <div><a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/python-iterators">http://lists.sourceforge.net/lists/listinfo/python-iterators</a></div></blockquote> Initially, some of the discussion was carried out at Yahoo; archives are still accessible: <blockquote> <div><a class="reference external" href="http://groups.yahoo.com/group/python-iter">http://groups.yahoo.com/group/python-iter</a></div></blockquote> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0234.rst">https://github.com/python/peps/blob/main/peps/pep-0234.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0234.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#c-api-specification">C API Specification</a></li> <li><a class="reference internal" href="#python-api-specification">Python API Specification</a></li> <li><a class="reference internal" href="#dictionary-iterators">Dictionary Iterators</a></li> <li><a class="reference internal" href="#file-iterators">File Iterators</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#resolved-issues">Resolved Issues</a></li> <li><a class="reference internal" href="#mailing-lists">Mailing Lists</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0234.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>