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 3114 – Renaming iterator.next() to iterator.__next__() | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-3114/"> <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 3114 – Renaming iterator.next() to iterator.__next__() | peps.python.org'> <meta property="og:description" content="The iterator protocol in Python 2.x consists of two methods: __iter__() called on an iterable object to yield an iterator, and next() called on an iterator object to yield the next item in the sequence. Using a for loop to iterate over an iterable obje..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-3114/"> <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="The iterator protocol in Python 2.x consists of two methods: __iter__() called on an iterable object to yield an iterator, and next() called on an iterator object to yield the next item in the sequence. Using a for loop to iterate over an iterable obje..."> <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 3114</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 3114 – Renaming iterator.next() to iterator.__next__()</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Ka-Ping Yee <ping at zesty.ca></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">04-Mar-2007</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.0</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even"></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="#names-with-double-underscores">Names With Double Underscores</a></li> <li><a class="reference internal" href="#double-underscore-methods-and-built-in-functions">Double-Underscore Methods and Built-In Functions</a></li> <li><a class="reference internal" href="#previous-proposals">Previous Proposals</a></li> <li><a class="reference internal" href="#objections">Objections</a></li> <li><a class="reference internal" href="#transition-plan">Transition Plan</a></li> <li><a class="reference internal" href="#approval">Approval</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</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> The iterator protocol in Python 2.x consists of two methods: <code class="docutils literal notranslate">__iter__()</code> called on an iterable object to yield an iterator, and <code class="docutils literal notranslate">next()</code> called on an iterator object to yield the next item in the sequence. Using a <code class="docutils literal notranslate">for</code> loop to iterate over an iterable object implicitly calls both of these methods. This PEP proposes that the <code class="docutils literal notranslate">next</code> method be renamed to <code class="docutils literal notranslate">__next__</code>, consistent with all the other protocols in Python in which a method is implicitly called as part of a language-level protocol, and that a built-in function named <code class="docutils literal notranslate">next</code> be introduced to invoke <code class="docutils literal notranslate">__next__</code> method, consistent with the manner in which other protocols are explicitly invoked. </section> <section id="names-with-double-underscores"> <h2><a class="toc-backref" href="#names-with-double-underscores" role="doc-backlink">Names With Double Underscores</a></h2> In Python, double underscores before and after a name are used to distinguish names that belong to the language itself. Attributes and methods that are implicitly used or created by the interpreter employ this naming convention; some examples are: <ul class="simple"> <li><code class="docutils literal notranslate">__file__</code> - an attribute automatically created by the interpreter</li> <li><code class="docutils literal notranslate">__dict__</code> - an attribute with special meaning to the interpreter</li> <li><code class="docutils literal notranslate">__init__</code> - a method implicitly called by the interpreter</li> </ul> Note that this convention applies to methods such as <code class="docutils literal notranslate">__init__</code> that are explicitly defined by the programmer, as well as attributes such as <code class="docutils literal notranslate">__file__</code> that can only be accessed by naming them explicitly, so it includes names that are used or created by the interpreter. (Not all things that are called “protocols” are made of methods with double-underscore names. For example, the <code class="docutils literal notranslate">__contains__</code> method has double underscores because the language construct <code class="docutils literal notranslate">x in y</code> implicitly calls <code class="docutils literal notranslate">__contains__</code>. But even though the <code class="docutils literal notranslate">read</code> method is part of the file protocol, it does not have double underscores because there is no language construct that implicitly invokes <code class="docutils literal notranslate">x.read()</code>.) The use of double underscores creates a separate namespace for names that are part of the Python language definition, so that programmers are free to create variables, attributes, and methods that start with letters, without fear of silently colliding with names that have a language-defined purpose. (Colliding with reserved keywords is still a concern, but at least this will immediately yield a syntax error.) The naming of the <code class="docutils literal notranslate">next</code> method on iterators is an exception to this convention. Code that nowhere contains an explicit call to a <code class="docutils literal notranslate">next</code> method can nonetheless be silently affected by the presence of such a method. Therefore, this PEP proposes that iterators should have a <code class="docutils literal notranslate">__next__</code> method instead of a <code class="docutils literal notranslate">next</code> method (with no change in semantics). </section> <section id="double-underscore-methods-and-built-in-functions"> <h2><a class="toc-backref" href="#double-underscore-methods-and-built-in-functions" role="doc-backlink">Double-Underscore Methods and Built-In Functions</a></h2> The Python language defines several protocols that are implemented or customized by defining methods with double-underscore names. In each case, the protocol is provided by an internal method implemented as a C function in the interpreter. For objects defined in Python, this C function supports customization by implicitly invoking a Python method with a double-underscore name (it often does a little bit of additional work beyond just calling the Python method.) Sometimes the protocol is invoked by a syntactic construct: <ul class="simple"> <li><code class="docutils literal notranslate">x[y]</code> –> internal <code class="docutils literal notranslate">tp_getitem</code> –> <code class="docutils literal notranslate">x.__getitem__(y)</code></li> <li><code class="docutils literal notranslate">x + y</code> –> internal <code class="docutils literal notranslate">nb_add</code> –> <code class="docutils literal notranslate">x.__add__(y)</code></li> <li><code class="docutils literal notranslate">-x</code> –> internal <code class="docutils literal notranslate">nb_negative</code> –> <code class="docutils literal notranslate">x.__neg__()</code></li> </ul> Sometimes there is no syntactic construct, but it is still useful to be able to explicitly invoke the protocol. For such cases Python offers a built-in function of the same name but without the double underscores. <ul class="simple"> <li><code class="docutils literal notranslate">len(x)</code> –> internal <code class="docutils literal notranslate">sq_length</code> –> <code class="docutils literal notranslate">x.__len__()</code></li> <li><code class="docutils literal notranslate">hash(x)</code> –> internal <code class="docutils literal notranslate">tp_hash</code> –> <code class="docutils literal notranslate">x.__hash__()</code></li> <li><code class="docutils literal notranslate">iter(x)</code> –> internal <code class="docutils literal notranslate">tp_iter</code> –> <code class="docutils literal notranslate">x.__iter__()</code></li> </ul> Following this pattern, the natural way to handle <code class="docutils literal notranslate">next</code> is to add a <code class="docutils literal notranslate">next</code> built-in function that behaves in exactly the same fashion. <ul class="simple"> <li><code class="docutils literal notranslate">next(x)</code> –> internal <code class="docutils literal notranslate">tp_iternext</code> –> <code class="docutils literal notranslate">x.__next__()</code></li> </ul> Further, it is proposed that the <code class="docutils literal notranslate">next</code> built-in function accept a sentinel value as an optional second argument, following the style of the <code class="docutils literal notranslate">getattr</code> and <code class="docutils literal notranslate">iter</code> built-in functions. When called with two arguments, <code class="docutils literal notranslate">next</code> catches the StopIteration exception and returns the sentinel value instead of propagating the exception. This creates a nice duality between <code class="docutils literal notranslate">iter</code> and <code class="docutils literal notranslate">next</code>: <blockquote> <div>iter(function, sentinel) <–> next(iterator, sentinel)</div></blockquote> </section> <section id="previous-proposals"> <h2><a class="toc-backref" href="#previous-proposals" role="doc-backlink">Previous Proposals</a></h2> This proposal is not a new idea. The idea proposed here was supported by the BDFL on python-dev <a class="footnote-reference brackets" href="#id7" id="id1">[1]</a> and is even mentioned in the original iterator PEP, <a class="pep reference internal" href="../pep-0234/" title="PEP 234 – Iterators">PEP 234</a>: <div class="highlight-default notranslate"><div class="highlight"><pre>(In retrospect, it might have been better to go for __next__() and have a new built-in, next(it), which calls it.__next__(). But alas, it's too late; this has been deployed in Python 2.2 since December 2001.) </pre></div> </div> </section> <section id="objections"> <h2><a class="toc-backref" href="#objections" role="doc-backlink">Objections</a></h2> There have been a few objections to the addition of more built-ins. In particular, Martin von Loewis writes <a class="footnote-reference brackets" href="#id8" id="id2">[2]</a>: <div class="highlight-default notranslate"><div class="highlight"><pre>I dislike the introduction of more builtins unless they have a true generality (i.e. are likely to be needed in many programs). For this one, I think the normal usage of __next__ will be with a for loop, so I don't think one would often need an explicit next() invocation. It is also not true that most protocols are explicitly invoked through builtin functions. Instead, most protocols are can be explicitly invoked through methods in the operator module. So following tradition, it should be operator.next. ... As an alternative, I propose that object grows a .next() method, which calls __next__ by default. </pre></div> </div> </section> <section id="transition-plan"> <h2><a class="toc-backref" href="#transition-plan" role="doc-backlink">Transition Plan</a></h2> Two additional transformations will be added to the 2to3 translation tool <a class="footnote-reference brackets" href="#id9" id="id3">[3]</a>: <ul class="simple"> <li>Method definitions named <code class="docutils literal notranslate">next</code> will be renamed to <code class="docutils literal notranslate">__next__</code>.</li> <li>Explicit calls to the <code class="docutils literal notranslate">next</code> method will be replaced with calls to the built-in <code class="docutils literal notranslate">next</code> function. For example, <code class="docutils literal notranslate">x.next()</code> will become <code class="docutils literal notranslate">next(x)</code>.</li> </ul> Collin Winter looked into the possibility of automatically deciding whether to perform the second transformation depending on the presence of a module-level binding to <code class="docutils literal notranslate">next</code> <a class="footnote-reference brackets" href="#id10" id="id4">[4]</a> and found that it would be “ugly and slow”. Instead, the translation tool will emit warnings upon detecting such a binding. Collin has proposed warnings for the following conditions <a class="footnote-reference brackets" href="#id11" id="id5">[5]</a>: <ul class="simple"> <li>Module-level assignments to <code class="docutils literal notranslate">next</code>.</li> <li>Module-level definitions of a function named <code class="docutils literal notranslate">next</code>.</li> <li>Module-level imports of the name <code class="docutils literal notranslate">next</code>.</li> <li>Assignments to <code class="docutils literal notranslate">__builtin__.next</code>.</li> </ul> </section> <section id="approval"> <h2><a class="toc-backref" href="#approval" role="doc-backlink">Approval</a></h2> This PEP was accepted by Guido on March 6, 2007 <a class="footnote-reference brackets" href="#id12" id="id6">[6]</a>. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> A patch with the necessary changes (except the 2to3 tool) was written by Georg Brandl and committed as revision 54910. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id7" role="doc-footnote"> <dt class="label" id="id7">[<a href="#id1">1</a>]</dt> <dd>Single- vs. Multi-pass iterability (Guido van Rossum) <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2002-July/026814.html">https://mail.python.org/pipermail/python-dev/2002-July/026814.html</a></aside> <aside class="footnote brackets" id="id8" role="doc-footnote"> <dt class="label" id="id8">[<a href="#id2">2</a>]</dt> <dd>PEP: rename it.next() to it.__next__()… (Martin von Loewis) <a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-March/005965.html">https://mail.python.org/pipermail/python-3000/2007-March/005965.html</a></aside> <aside class="footnote brackets" id="id9" role="doc-footnote"> <dt class="label" id="id9">[<a href="#id3">3</a>]</dt> <dd>2to3 refactoring tool <a class="reference external" href="https://github.com/python/cpython/tree/ef04c44e29a8276a484f58d03a75a2dec516302d/Lib/lib2to3">https://github.com/python/cpython/tree/ef04c44e29a8276a484f58d03a75a2dec516302d/Lib/lib2to3</a></aside> <aside class="footnote brackets" id="id10" role="doc-footnote"> <dt class="label" id="id10">[<a href="#id4">4</a>]</dt> <dd>PEP: rename it.next() to it.__next__()… (Collin Winter) <a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-March/006020.html">https://mail.python.org/pipermail/python-3000/2007-March/006020.html</a></aside> <aside class="footnote brackets" id="id11" role="doc-footnote"> <dt class="label" id="id11">[<a href="#id5">5</a>]</dt> <dd>PEP 3113 transition plan <a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-March/006044.html">https://mail.python.org/pipermail/python-3000/2007-March/006044.html</a></aside> <aside class="footnote brackets" id="id12" role="doc-footnote"> <dt class="label" id="id12">[<a href="#id6">6</a>]</dt> <dd>PEP: rename it.next() to it.__next__()… (Guido van Rossum) <a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-March/006027.html">https://mail.python.org/pipermail/python-3000/2007-March/006027.html</a></aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-3114.rst">https://github.com/python/peps/blob/main/peps/pep-3114.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-3114.rst">2023-09-09 17:39:29 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="#names-with-double-underscores">Names With Double Underscores</a></li> <li><a class="reference internal" href="#double-underscore-methods-and-built-in-functions">Double-Underscore Methods and Built-In Functions</a></li> <li><a class="reference internal" href="#previous-proposals">Previous Proposals</a></li> <li><a class="reference internal" href="#objections">Objections</a></li> <li><a class="reference internal" href="#transition-plan">Transition Plan</a></li> <li><a class="reference internal" href="#approval">Approval</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</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-3114.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>