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 203 – Augmented Assignments | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0203/"> <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 203 – Augmented Assignments | peps.python.org'> <meta property="og:description" content="This PEP describes the augmented assignment proposal for Python 2.0. This PEP tracks the status and ownership of this feature, slated for introduction in Python 2.0. It contains a description of the feature and outlines changes necessary to support th..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0203/"> <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 PEP describes the augmented assignment proposal for Python 2.0. This PEP tracks the status and ownership of this feature, slated for introduction in Python 2.0. It contains a description of the feature and outlines changes necessary to support th..."> <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 203</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 203 – Augmented Assignments</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Thomas Wouters <thomas 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">13-Jul-2000</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.0</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">14-Aug-2000</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#introduction">Introduction</a></li> <li><a class="reference internal" href="#proposed-semantics">Proposed Semantics</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#new-methods">New methods</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#references">References</a></li> </ul> </details></section> <section id="introduction"> <h2><a class="toc-backref" href="#introduction" role="doc-backlink">Introduction</a></h2> This PEP describes the augmented assignment proposal for Python 2.0. This PEP tracks the status and ownership of this feature, slated for introduction in Python 2.0. It contains a description of the feature and outlines changes necessary to support the feature. This PEP summarizes discussions held in mailing list forums <a class="footnote-reference brackets" href="#id3" id="id1">[1]</a>, and provides URLs for further information where appropriate. The CVS revision history of this file contains the definitive historical record. </section> <section id="proposed-semantics"> <h2><a class="toc-backref" href="#proposed-semantics" role="doc-backlink">Proposed Semantics</a></h2> The proposed patch that adds augmented assignment to Python introduces the following new operators: <div class="highlight-default notranslate"><div class="highlight"><pre>+= -= *= /= %= **= <<= >>= &= ^= |= </pre></div> </div> They implement the same operator as their normal binary form, except that the operation is done in-place when the left-hand side object supports it, and that the left-hand side is only evaluated once. They truly behave as augmented assignment, in that they perform all of the normal load and store operations, in addition to the binary operation they are intended to do. So, given the expression: <div class="highlight-default notranslate"><div class="highlight"><pre>x += y </pre></div> </div> The object <code class="docutils literal notranslate">x</code> is loaded, then <code class="docutils literal notranslate">y</code> is added to it, and the resulting object is stored back in the original place. The precise action performed on the two arguments depends on the type of <code class="docutils literal notranslate">x</code>, and possibly of <code class="docutils literal notranslate">y</code>. The idea behind augmented assignment in Python is that it isn’t just an easier way to write the common practice of storing the result of a binary operation in its left-hand operand, but also a way for the left-hand operand in question to know that it should operate on itself, rather than creating a modified copy of itself. To make this possible, a number of new hooks are added to Python classes and C extension types, which are called when the object in question is used as the left hand side of an augmented assignment operation. If the class or type does not implement the in-place hooks, the normal hooks for the particular binary operation are used. So, given an instance object <code class="docutils literal notranslate">x</code>, the expression: <div class="highlight-default notranslate"><div class="highlight"><pre>x += y </pre></div> </div> tries to call <code class="docutils literal notranslate">x.__iadd__(y)</code>, which is the in-place variant of <code class="docutils literal notranslate">__add__</code> . If <code class="docutils literal notranslate">__iadd__</code> is not present, <code class="docutils literal notranslate">x.__add__(y)</code> is attempted, and finally <code class="docutils literal notranslate">y.__radd__(x)</code> if <code class="docutils literal notranslate">__add__</code> is missing too. There is no right-hand-side variant of <code class="docutils literal notranslate">__iadd__</code>, because that would require for <code class="docutils literal notranslate">y</code> to know how to in-place modify <code class="docutils literal notranslate">x</code>, which is unsafe to say the least. The <code class="docutils literal notranslate">__iadd__</code> hook should behave similar to <code class="docutils literal notranslate">__add__</code>, returning the result of the operation (which could be <code class="docutils literal notranslate">self</code>) which is to be assigned to the variable <code class="docutils literal notranslate">x</code>. For C extension types, the hooks are members of the <code class="docutils literal notranslate">PyNumberMethods</code> and <code class="docutils literal notranslate">PySequenceMethods</code> structures. Some special semantics apply to make the use of these methods, and the mixing of Python instance objects and C types, as unsurprising as possible. In the generic case of <code class="docutils literal notranslate">x <augop> y</code> (or a similar case using the <code class="docutils literal notranslate">PyNumber_InPlace</code> API functions) the principal object being operated on is <code class="docutils literal notranslate">x</code>. This differs from normal binary operations, where <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> could be considered co-operating, because unlike in binary operations, the operands in an in-place operation cannot be swapped. However, in-place operations do fall back to normal binary operations when in-place modification is not supported, resulting in the following rules: <ul> <li>If the left-hand object (<code class="docutils literal notranslate">x</code>) is an instance object, and it has a <code class="docutils literal notranslate">__coerce__</code> method, call that function with <code class="docutils literal notranslate">y</code> as the argument. If coercion succeeds, and the resulting left-hand object is a different object than <code class="docutils literal notranslate">x</code>, stop processing it as in-place and call the appropriate function for the normal binary operation, with the coerced <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> as arguments. The result of the operation is whatever that function returns.If coercion does not yield a different object for <code class="docutils literal notranslate">x</code>, or <code class="docutils literal notranslate">x</code> does not define a <code class="docutils literal notranslate">__coerce__</code> method, and <code class="docutils literal notranslate">x</code> has the appropriate <code class="docutils literal notranslate">__ihook__</code> for this operation, call that method with <code class="docutils literal notranslate">y</code> as the argument, and the result of the operation is whatever that method returns. </li> <li>Otherwise, if the left-hand object is not an instance object, but its type does define the in-place function for this operation, call that function with <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> as the arguments, and the result of the operation is whatever that function returns.Note that no coercion on either <code class="docutils literal notranslate">x</code> or <code class="docutils literal notranslate">y</code> is done in this case, and it’s perfectly valid for a C type to receive an instance object as the second argument; that is something that cannot happen with normal binary operations. </li> <li>Otherwise, process it exactly as a normal binary operation (not in-place), including argument coercion. In short, if either argument is an instance object, resolve the operation through <code class="docutils literal notranslate">__coerce__</code>, <code class="docutils literal notranslate">__hook__</code> and <code class="docutils literal notranslate">__rhook__</code>. Otherwise, both objects are C types, and they are coerced and passed to the appropriate function.</li> <li>If no way to process the operation can be found, raise a <code class="docutils literal notranslate">TypeError</code> with an error message specific to the operation.</li> <li>Some special casing exists to account for the case of <code class="docutils literal notranslate">+</code> and <code class="docutils literal notranslate">*</code>, which have a special meaning for sequences: for <code class="docutils literal notranslate">+</code>, sequence concatenation, no coercion what so ever is done if a C type defines <code class="docutils literal notranslate">sq_concat</code> or <code class="docutils literal notranslate">sq_inplace_concat</code>. For <code class="docutils literal notranslate">*</code>, sequence repeating, <code class="docutils literal notranslate">y</code> is converted to a C integer before calling either <code class="docutils literal notranslate">sq_inplace_repeat</code> and <code class="docutils literal notranslate">sq_repeat</code>. This is done even if <code class="docutils literal notranslate">y</code> is an instance, though not if <code class="docutils literal notranslate">x</code> is an instance.</li> </ul> The in-place function should always return a new reference, either to the old <code class="docutils literal notranslate">x</code> object if the operation was indeed performed in-place, or to a new object. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> There are two main reasons for adding this feature to Python: simplicity of expression, and support for in-place operations. The end result is a tradeoff between simplicity of syntax and simplicity of expression; like most new features, augmented assignment doesn’t add anything that was previously impossible. It merely makes these things easier to do. Adding augmented assignment will make Python’s syntax more complex. Instead of a single assignment operation, there are now twelve assignment operations, eleven of which also perform a binary operation. However, these eleven new forms of assignment are easy to understand as the coupling between assignment and the binary operation, and they require no large conceptual leap to understand. Furthermore, languages that do have augmented assignment have shown that they are a popular, much used feature. Expressions of the form: <div class="highlight-default notranslate"><div class="highlight"><pre><x> = <x> <operator> <y> </pre></div> </div> are common enough in those languages to make the extra syntax worthwhile, and Python does not have significantly fewer of those expressions. Quite the opposite, in fact, since in Python you can also concatenate lists with a binary operator, something that is done quite frequently. Writing the above expression as: <div class="highlight-default notranslate"><div class="highlight"><pre><x> <operator>= <y> </pre></div> </div> is both more readable and less error prone, because it is instantly obvious to the reader that it is <code class="docutils literal notranslate"><x></code> that is being changed, and not <code class="docutils literal notranslate"><x></code> that is being replaced by something almost, but not quite, entirely unlike <code class="docutils literal notranslate"><x></code>. The new in-place operations are especially useful to matrix calculation and other applications that require large objects. In order to efficiently deal with the available program memory, such packages cannot blindly use the current binary operations. Because these operations always create a new object, adding a single item to an existing (large) object would result in copying the entire object (which may cause the application to run out of memory), add the single item, and then possibly delete the original object, depending on reference count. To work around this problem, the packages currently have to use methods or functions to modify an object in-place, which is definitely less readable than an augmented assignment expression. Augmented assignment won’t solve all the problems for these packages, since some operations cannot be expressed in the limited set of binary operators to start with, but it is a start. <a class="pep reference internal" href="../pep-0211/" title="PEP 211 – Adding A New Outer Product Operator">PEP 211</a> is looking at adding new operators. </section> <section id="new-methods"> <h2><a class="toc-backref" href="#new-methods" role="doc-backlink">New methods</a></h2> The proposed implementation adds the following 11 possible hooks which Python classes can implement to overload the augmented assignment operations: <div class="highlight-default notranslate"><div class="highlight"><pre>__iadd__ __isub__ __imul__ __idiv__ __imod__ __ipow__ __ilshift__ __irshift__ __iand__ __ixor__ __ior__ </pre></div> </div> The i in <code class="docutils literal notranslate">__iadd__</code> stands for in-place. For C extension types, the following struct members are added. To <code class="docutils literal notranslate">PyNumberMethods</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>binaryfunc nb_inplace_add; binaryfunc nb_inplace_subtract; binaryfunc nb_inplace_multiply; binaryfunc nb_inplace_divide; binaryfunc nb_inplace_remainder; binaryfunc nb_inplace_power; binaryfunc nb_inplace_lshift; binaryfunc nb_inplace_rshift; binaryfunc nb_inplace_and; binaryfunc nb_inplace_xor; binaryfunc nb_inplace_or; </pre></div> </div> To <code class="docutils literal notranslate">PySequenceMethods</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>binaryfunc sq_inplace_concat; intargfunc sq_inplace_repeat; </pre></div> </div> In order to keep binary compatibility, the <code class="docutils literal notranslate">tp_flags</code> TypeObject member is used to determine whether the TypeObject in question has allocated room for these slots. Until a clean break in binary compatibility is made (which may or may not happen before 2.0) code that wants to use one of the new struct members must first check that they are available with the <code class="docutils literal notranslate">PyType_HasFeature()</code> macro: <div class="highlight-default notranslate"><div class="highlight"><pre>if (PyType_HasFeature(x->ob_type, Py_TPFLAGS_HAVE_INPLACE_OPS) && x->ob_type->tp_as_number && x->ob_type->tp_as_number->nb_inplace_add) { /* ... */ </pre></div> </div> This check must be made even before testing the method slots for <code class="docutils literal notranslate">NULL</code> values! The macro only tests whether the slots are available, not whether they are filled with methods or not. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> The current implementation of augmented assignment <a class="footnote-reference brackets" href="#id4" id="id2">[2]</a> adds, in addition to the methods and slots already covered, 13 new bytecodes and 13 new API functions. The API functions are simply in-place versions of the current binary-operation API functions: <div class="highlight-default notranslate"><div class="highlight"><pre>PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2); PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2); PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2); PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2); PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2); PyNumber_InPlacePower(PyObject *o1, PyObject *o2); PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2); PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2); PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2); PyNumber_InPlaceXor(PyObject *o1, PyObject *o2); PyNumber_InPlaceOr(PyObject *o1, PyObject *o2); PySequence_InPlaceConcat(PyObject *o1, PyObject *o2); PySequence_InPlaceRepeat(PyObject *o, int count); </pre></div> </div> They call either the Python class hooks (if either of the objects is a Python class instance) or the C type’s number or sequence methods. The new bytecodes are: <div class="highlight-default notranslate"><div class="highlight"><pre>INPLACE_ADD INPLACE_SUBTRACT INPLACE_MULTIPLY INPLACE_DIVIDE INPLACE_REMAINDER INPLACE_POWER INPLACE_LEFTSHIFT INPLACE_RIGHTSHIFT INPLACE_AND INPLACE_XOR INPLACE_OR ROT_FOUR DUP_TOPX </pre></div> </div> The <code class="docutils literal notranslate">INPLACE_*</code> bytecodes mirror the <code class="docutils literal notranslate">BINARY_*</code> bytecodes, except that they are implemented as calls to the <code class="docutils literal notranslate">InPlace</code> API functions. The other two bytecodes are utility bytecodes: <code class="docutils literal notranslate">ROT_FOUR</code> behaves like <code class="docutils literal notranslate">ROT_THREE</code> except that the four topmost stack items are rotated. <code class="docutils literal notranslate">DUP_TOPX</code> is a bytecode that takes a single argument, which should be an integer between 1 and 5 (inclusive) which is the number of items to duplicate in one block. Given a stack like this (where the right side of the list is the top of the stack): <div class="highlight-default notranslate"><div class="highlight"><pre>[1, 2, 3, 4, 5] </pre></div> </div> <code class="docutils literal notranslate">DUP_TOPX 3</code> would duplicate the top 3 items, resulting in this stack: <div class="highlight-default notranslate"><div class="highlight"><pre>[1, 2, 3, 4, 5, 3, 4, 5] </pre></div> </div> <code class="docutils literal notranslate">DUP_TOPX</code> with an argument of 1 is the same as <code class="docutils literal notranslate">DUP_TOP</code>. The limit of 5 is purely an implementation limit . The implementation of augmented assignment requires only <code class="docutils literal notranslate">DUP_TOPX</code> with an argument of 2 and 3, and could do without this new opcode at the cost of a fair number of <code class="docutils literal notranslate">DUP_TOP</code> and <code class="docutils literal notranslate">ROT_*</code>. </section> <section id="open-issues"> <h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2> The <code class="docutils literal notranslate">PyNumber_InPlace</code> API is only a subset of the normal <code class="docutils literal notranslate">PyNumber</code> API: only those functions that are required to support the augmented assignment syntax are included. If other in-place API functions are needed, they can be added later. The <code class="docutils literal notranslate">DUP_TOPX</code> bytecode is a conveniency bytecode, and is not actually necessary. It should be considered whether this bytecode is worth having. There seems to be no other possible use for this bytecode at this time. </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 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="id3" role="doc-footnote"> <dt class="label" id="id3">[<a href="#id1">1</a>]</dt> <dd><a class="reference external" href="http://www.python.org/pipermail/python-list/2000-June/059556.html">http://www.python.org/pipermail/python-list/2000-June/059556.html</a></aside> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id2">2</a>]</dt> <dd><a class="reference external" href="http://sourceforge.net/patch?func=detailpatch&patch_id=100699&group_id=5470">http://sourceforge.net/patch?func=detailpatch&patch_id=100699&group_id=5470</a></aside> </aside> </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0203.rst">https://github.com/python/peps/blob/main/peps/pep-0203.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0203.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#introduction">Introduction</a></li> <li><a class="reference internal" href="#proposed-semantics">Proposed Semantics</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#new-methods">New methods</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#references">References</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0203.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>