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 584 – Add Union Operators To dict | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0584/"> <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 584 – Add Union Operators To dict | peps.python.org'> <meta property="og:description" content="This PEP proposes adding merge (|) and update (|=) operators to the built-in dict class."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0584/"> <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 proposes adding merge (|) and update (|=) operators to the built-in dict class."> <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 584</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 584 – Add Union Operators To dict</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Steven D’Aprano <steve at pearwood.info>, Brandt Bucher <brandt at python.org></dd> <dt class="field-even">BDFL-Delegate:</dt> <dd class="field-even">Guido van Rossum <guido at python.org></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><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-odd">Created:</dt> <dd class="field-odd">01-Mar-2019</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.9</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd">01-Mar-2019, 16-Oct-2019, 02-Dec-2019, 04-Feb-2020, 17-Feb-2020</dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/thread/6KT2KIOTYXMDCD2CCAOLOI7LUGTN6MBS">Python-Dev thread</a></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="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#dict-update"><code class="docutils literal notranslate">dict.update</code></a></li> <li><a class="reference internal" href="#d1-d2"><code class="docutils literal notranslate">{**d1, **d2}</code></a></li> <li><a class="reference internal" href="#collections-chainmap"><code class="docutils literal notranslate">collections.ChainMap</code></a></li> <li><a class="reference internal" href="#dict-d1-d2"><code class="docutils literal notranslate">dict(d1, **d2)</code></a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#major-objections">Major Objections</a><ul> <li><a class="reference internal" href="#dict-union-is-not-commutative">Dict Union Is Not Commutative</a><ul> <li><a class="reference internal" href="#response">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-will-be-inefficient">Dict Union Will Be Inefficient</a><ul> <li><a class="reference internal" href="#id1">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-is-lossy">Dict Union Is Lossy</a><ul> <li><a class="reference internal" href="#id2">Response</a></li> </ul> </li> <li><a class="reference internal" href="#only-one-way-to-do-it">Only One Way To Do It</a><ul> <li><a class="reference internal" href="#id3">Response</a></li> </ul> </li> <li><a class="reference internal" href="#more-than-one-way-to-do-it">More Than One Way To Do It</a><ul> <li><a class="reference internal" href="#id4">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-makes-code-harder-to-understand">Dict Union Makes Code Harder To Understand</a><ul> <li><a class="reference internal" href="#id5">Response</a></li> </ul> </li> <li><a class="reference internal" href="#what-about-the-full-set-api">What About The Full <code class="docutils literal notranslate">set</code> API?</a><ul> <li><a class="reference internal" href="#id6">Response</a></li> </ul> </li> <li><a class="reference internal" href="#what-about-mapping-and-mutablemapping">What About <code class="docutils literal notranslate">Mapping</code> And <code class="docutils literal notranslate">MutableMapping</code>?</a><ul> <li><a class="reference internal" href="#id7">Response</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#rejected-semantics">Rejected Semantics</a><ul> <li><a class="reference internal" href="#raise">Raise</a></li> <li><a class="reference internal" href="#add-the-values-as-counter-does-with">Add The Values (As Counter Does, with <code class="docutils literal notranslate">+</code>)</a></li> <li><a class="reference internal" href="#leftmost-value-first-seen-wins">Leftmost Value (First-Seen) Wins</a></li> <li><a class="reference internal" href="#concatenate-values-in-a-list">Concatenate Values In A List</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#use-the-addition-operator">Use The Addition Operator</a></li> <li><a class="reference internal" href="#use-the-left-shift-operator">Use The Left Shift Operator</a></li> <li><a class="reference internal" href="#use-a-new-left-arrow-operator">Use A New Left Arrow Operator</a></li> <li><a class="reference internal" href="#use-a-method">Use A Method</a><ul> <li><a class="reference internal" href="#advantages">Advantages</a></li> <li><a class="reference internal" href="#disadvantages">Disadvantages</a></li> </ul> </li> <li><a class="reference internal" href="#use-a-function">Use a Function</a><ul> <li><a class="reference internal" href="#id8">Advantages</a></li> <li><a class="reference internal" href="#id9">Disadvantages</a></li> </ul> </li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#ipython-zmq-ipkernel-py">IPython/zmq/ipkernel.py</a></li> <li><a class="reference internal" href="#ipython-zmq-kernelapp-py">IPython/zmq/kernelapp.py</a></li> <li><a class="reference internal" href="#matplotlib-backends-backend-svg-py">matplotlib/backends/backend_svg.py</a></li> <li><a class="reference internal" href="#matplotlib-delaunay-triangulate-py">matplotlib/delaunay/triangulate.py</a></li> <li><a class="reference internal" href="#matplotlib-legend-py">matplotlib/legend.py</a></li> <li><a class="reference internal" href="#numpy-ma-core-py">numpy/ma/core.py</a></li> <li><a class="reference internal" href="#praw-internal-py">praw/internal.py</a></li> <li><a class="reference internal" href="#pygments-lexer-py">pygments/lexer.py</a></li> <li><a class="reference internal" href="#requests-sessions-py">requests/sessions.py</a></li> <li><a class="reference internal" href="#sphinx-domains-init-py">sphinx/domains/__init__.py</a></li> <li><a class="reference internal" href="#sphinx-ext-doctest-py">sphinx/ext/doctest.py</a></li> <li><a class="reference internal" href="#sphinx-ext-inheritance-diagram-py">sphinx/ext/inheritance_diagram.py</a></li> <li><a class="reference internal" href="#sphinx-highlighting-py">sphinx/highlighting.py</a></li> <li><a class="reference internal" href="#sphinx-quickstart-py">sphinx/quickstart.py</a></li> <li><a class="reference internal" href="#sympy-abc-py">sympy/abc.py</a></li> <li><a class="reference internal" href="#sympy-parsing-maxima-py">sympy/parsing/maxima.py</a></li> <li><a class="reference internal" href="#sympy-printing-ccode-py-and-sympy-printing-fcode-py">sympy/printing/ccode.py and sympy/printing/fcode.py</a></li> <li><a class="reference internal" href="#sympy-utilities-runtests-py">sympy/utilities/runtests.py</a></li> </ul> </li> <li><a class="reference internal" href="#related-discussions">Related Discussions</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 PEP proposes adding merge (<code class="docutils literal notranslate">|</code>) and update (<code class="docutils literal notranslate">|=</code>) operators to the built-in <code class="docutils literal notranslate">dict</code> class. <div class="admonition note"> Note After this PEP was accepted, the decision was made to also implement the new operators for <a class="reference external" href="https://bugs.python.org/issue36144">several other standard library mappings</a>. </div> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> The current ways to merge two dicts have several disadvantages: <section id="dict-update"> <h3><a class="toc-backref" href="#dict-update" role="doc-backlink"><code class="docutils literal notranslate">dict.update</code></a></h3> <code class="docutils literal notranslate">d1.update(d2)</code> modifies <code class="docutils literal notranslate">d1</code> in-place. <code class="docutils literal notranslate">e = d1.copy(); e.update(d2)</code> is not an expression and needs a temporary variable. </section> <section id="d1-d2"> <h3><a class="toc-backref" href="#d1-d2" role="doc-backlink"><code class="docutils literal notranslate">{**d1, **d2}</code></a></h3> Dict unpacking looks ugly and is not easily discoverable. Few people would be able to guess what it means the first time they see it, or think of it as the “obvious way” to merge two dicts. <a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/message/K4IC74IXE23K4KEL7OUFK3VBC62HGGVF/">As Guido said</a>: <blockquote> <div>I’m sorry for PEP 448, but even if you know about <code class="docutils literal notranslate">**d</code> in simpler contexts, if you were to ask a typical Python user how to combine two dicts into a new one, I doubt many people would think of <code class="docutils literal notranslate">{**d1, **d2}</code>. I know I myself had forgotten about it when this thread started!</div></blockquote> <code class="docutils literal notranslate">{**d1, **d2}</code> ignores the types of the mappings and always returns a <code class="docutils literal notranslate">dict</code>. <code class="docutils literal notranslate">type(d1)({**d1, **d2})</code> fails for dict subclasses such as <code class="docutils literal notranslate">defaultdict</code> that have an incompatible <code class="docutils literal notranslate">__init__</code> method. </section> <section id="collections-chainmap"> <h3><a class="toc-backref" href="#collections-chainmap" role="doc-backlink"><code class="docutils literal notranslate">collections.ChainMap</code></a></h3> <code class="docutils literal notranslate">ChainMap</code> is unfortunately poorly-known and doesn’t qualify as “obvious”. It also resolves duplicate keys in the opposite order to that expected (“first seen wins” instead of “last seen wins”). Like dict unpacking, it is tricky to get it to honor the desired subclass. For the same reason, <code class="docutils literal notranslate">type(d1)(ChainMap(d2, d1))</code> fails for some subclasses of dict. Further, ChainMaps wrap their underlying dicts, so writes to the ChainMap will modify the original dict: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d1 = {'spam': 1} >>> d2 = {'eggs': 2} >>> merged = ChainMap(d2, d1) >>> merged['eggs'] = 999 >>> d2 {'eggs': 999} </pre></div> </div> </section> <section id="dict-d1-d2"> <h3><a class="toc-backref" href="#dict-d1-d2" role="doc-backlink"><code class="docutils literal notranslate">dict(d1, **d2)</code></a></h3> This “neat trick” is not well-known, and only works when <code class="docutils literal notranslate">d2</code> is entirely string-keyed: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d1 = {"spam": 1} >>> d2 = {3665: 2} >>> dict(d1, **d2) Traceback (most recent call last): ... TypeError: keywords must be strings </pre></div> </div> </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> The new operators will have the same relationship to the <code class="docutils literal notranslate">dict.update</code> method as the list concatenate (<code class="docutils literal notranslate">+</code>) and extend (<code class="docutils literal notranslate">+=</code>) operators have to <code class="docutils literal notranslate">list.extend</code>. Note that this is somewhat different from the relationship that <code class="docutils literal notranslate">|</code>/<code class="docutils literal notranslate">|=</code> have with <code class="docutils literal notranslate">set.update</code>; the authors have determined that allowing the in-place operator to accept a wider range of types (as <code class="docutils literal notranslate">list</code> does) is a more useful design, and that restricting the types of the binary operator’s operands (again, as <code class="docutils literal notranslate">list</code> does) will help avoid silent errors caused by complicated implicit type casting on both sides. Key conflicts will be resolved by keeping the rightmost value. This matches the existing behavior of similar <code class="docutils literal notranslate">dict</code> operations, where the last seen value always wins: <div class="highlight-default notranslate"><div class="highlight"><pre>{'a': 1, 'a': 2} {**d, **e} d.update(e) d[k] = v {k: v for x in (d, e) for (k, v) in x.items()} </pre></div> </div> All of the above follow the same rule. This PEP takes the position that this behavior is simple, obvious, usually the behavior we want, and should be the default behavior for dicts. This means that dict union is not commutative; in general <code class="docutils literal notranslate">d | e != e | d</code>. Similarly, the iteration order of the key-value pairs in the dictionary will follow the same semantics as the examples above, with each newly added key (and its value) being appended to the current sequence. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> Dict union will return a new <code class="docutils literal notranslate">dict</code> consisting of the left operand merged with the right operand, each of which must be a <code class="docutils literal notranslate">dict</code> (or an instance of a <code class="docutils literal notranslate">dict</code> subclass). If a key appears in both operands, the last-seen value (i.e. that from the right-hand operand) wins: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d = {'spam': 1, 'eggs': 2, 'cheese': 3} >>> e = {'cheese': 'cheddar', 'aardvark': 'Ethel'} >>> d | e {'spam': 1, 'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel'} >>> e | d {'cheese': 3, 'aardvark': 'Ethel', 'spam': 1, 'eggs': 2} </pre></div> </div> The augmented assignment version operates in-place: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d |= e >>> d {'spam': 1, 'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel'} </pre></div> </div> Augmented assignment behaves identically to the <code class="docutils literal notranslate">update</code> method called with a single positional argument, so it also accepts anything implementing the Mapping protocol (more specifically, anything with the <code class="docutils literal notranslate">keys</code> and <code class="docutils literal notranslate">__getitem__</code> methods) or iterables of key-value pairs. This is analogous to <code class="docutils literal notranslate">list +=</code> and <code class="docutils literal notranslate">list.extend</code>, which accept any iterable, not just lists. Continued from above: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> d | [('spam', 999)] Traceback (most recent call last): ... TypeError: can only merge dict (not "list") to dict >>> d |= [('spam', 999)] >>> d {'spam': 999, 'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel'} </pre></div> </div> When new keys are added, their order matches their order within the right-hand mapping, if any exists for its type. </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> One of the authors has <a class="reference external" href="https://github.com/python/cpython/pull/12088">written a C implementation</a>. An approximate pure-Python implementation is: <div class="highlight-default notranslate"><div class="highlight"><pre>def __or__(self, other): if not isinstance(other, dict): return NotImplemented new = dict(self) new.update(other) return new def __ror__(self, other): if not isinstance(other, dict): return NotImplemented new = dict(other) new.update(self) return new def __ior__(self, other): dict.update(self, other) return self </pre></div> </div> </section> <section id="major-objections"> <h2><a class="toc-backref" href="#major-objections" role="doc-backlink">Major Objections</a></h2> <section id="dict-union-is-not-commutative"> <h3><a class="toc-backref" href="#dict-union-is-not-commutative" role="doc-backlink">Dict Union Is Not Commutative</a></h3> Union is commutative, but dict union will not be (<code class="docutils literal notranslate">d | e != e | d</code>). <section id="response"> <h4><a class="toc-backref" href="#response" role="doc-backlink">Response</a></h4> There is precedent for non-commutative unions in Python: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> {0} | {False} {0} >>> {False} | {0} {False} </pre></div> </div> While the results may be equal, they are distinctly different. In general, <code class="docutils literal notranslate">a | b</code> is not the same operation as <code class="docutils literal notranslate">b | a</code>. </section> </section> <section id="dict-union-will-be-inefficient"> <h3><a class="toc-backref" href="#dict-union-will-be-inefficient" role="doc-backlink">Dict Union Will Be Inefficient</a></h3> Giving a pipe operator to mappings is an invitation to writing code that doesn’t scale well. Repeated dict union is inefficient: <code class="docutils literal notranslate">d | e | f | g | h</code> creates and destroys three temporary mappings. <section id="id1"> <h4><a class="toc-backref" href="#id1" role="doc-backlink">Response</a></h4> The same argument applies to sequence concatenation. Sequence concatenation grows with the total number of items in the sequences, leading to O(N**2) (quadratic) performance. Dict union is likely to involve duplicate keys, so the temporary mappings will not grow as fast. Just as it is rare for people to concatenate large numbers of lists or tuples, the authors of this PEP believe that it will be rare for people to merge large numbers of dicts. <code class="docutils literal notranslate">collections.Counter</code> is a dict subclass that supports many operators, and there are no known examples of people having performance issues due to combining large numbers of Counters. Further, a survey of the standard library by the authors found no examples of merging more than two dicts, so this is unlikely to be a performance problem in practice… “Everything is fast for small enough N”. If one expects to be merging a large number of dicts where performance is an issue, it may be better to use an explicit loop and in-place merging: <div class="highlight-default notranslate"><div class="highlight"><pre>new = {} for d in many_dicts: new |= d </pre></div> </div> </section> </section> <section id="dict-union-is-lossy"> <h3><a class="toc-backref" href="#dict-union-is-lossy" role="doc-backlink">Dict Union Is Lossy</a></h3> Dict union can lose data (values may disappear); no other form of union is lossy. <section id="id2"> <h4><a class="toc-backref" href="#id2" role="doc-backlink">Response</a></h4> It isn’t clear why the first part of this argument is a problem. <code class="docutils literal notranslate">dict.update()</code> may throw away values, but not keys; that is expected behavior, and will remain expected behavior regardless of whether it is spelled as <code class="docutils literal notranslate">update()</code> or <code class="docutils literal notranslate">|</code>. Other types of union are also lossy, in the sense of not being reversible; you cannot get back the two operands given only the union. <code class="docutils literal notranslate">a | b == 365</code>… what are <code class="docutils literal notranslate">a</code> and <code class="docutils literal notranslate">b</code>? </section> </section> <section id="only-one-way-to-do-it"> <h3><a class="toc-backref" href="#only-one-way-to-do-it" role="doc-backlink">Only One Way To Do It</a></h3> Dict union will violate the Only One Way koan from the Zen. <section id="id3"> <h4><a class="toc-backref" href="#id3" role="doc-backlink">Response</a></h4> There is no such koan. “Only One Way” is a calumny about Python originating long ago from the Perl community. </section> </section> <section id="more-than-one-way-to-do-it"> <h3><a class="toc-backref" href="#more-than-one-way-to-do-it" role="doc-backlink">More Than One Way To Do It</a></h3> Okay, the Zen doesn’t say that there should be Only One Way To Do It. But it does have a prohibition against allowing “more than one way to do it”. <section id="id4"> <h4><a class="toc-backref" href="#id4" role="doc-backlink">Response</a></h4> There is no such prohibition. The “Zen of Python” merely expresses a preference for “only one obvious way”: <div class="highlight-default notranslate"><div class="highlight"><pre>There should be one-- and preferably only one --obvious way to do it. </pre></div> </div> The emphasis here is that there should be an obvious way to do “it”. In the case of dict update operations, there are at least two different operations that we might wish to do: <ul class="simple"> <li>Update a dict in place: The Obvious Way is to use the <code class="docutils literal notranslate">update()</code> method. If this proposal is accepted, the <code class="docutils literal notranslate">|=</code> augmented assignment operator will also work, but that is a side-effect of how augmented assignments are defined. Which you choose is a matter of taste.</li> <li>Merge two existing dicts into a third, new dict: This PEP proposes that the Obvious Way is to use the <code class="docutils literal notranslate">|</code> merge operator.</li> </ul> In practice, this preference for “only one way” is frequently violated in Python. For example, every <code class="docutils literal notranslate">for</code> loop could be re-written as a <code class="docutils literal notranslate">while</code> loop; every <code class="docutils literal notranslate">if</code> block could be written as an <code class="docutils literal notranslate">if</code>/ <code class="docutils literal notranslate">else</code> block. List, set and dict comprehensions could all be replaced by generator expressions. Lists offer no fewer than five ways to implement concatenation: <ul class="simple"> <li>Concatenation operator: <code class="docutils literal notranslate">a + b</code></li> <li>In-place concatenation operator: <code class="docutils literal notranslate">a += b</code></li> <li>Slice assignment: <code class="docutils literal notranslate">a[len(a):] = b</code></li> <li>Sequence unpacking: <code class="docutils literal notranslate">[*a, *b]</code></li> <li>Extend method: <code class="docutils literal notranslate">a.extend(b)</code></li> </ul> We should not be too strict about rejecting useful functionality because it violates “only one way”. </section> </section> <section id="dict-union-makes-code-harder-to-understand"> <h3><a class="toc-backref" href="#dict-union-makes-code-harder-to-understand" role="doc-backlink">Dict Union Makes Code Harder To Understand</a></h3> Dict union makes it harder to tell what code means. To paraphrase the objection rather than quote anyone in specific: “If I see <code class="docutils literal notranslate">spam | eggs</code>, I can’t tell what it does unless I know what <code class="docutils literal notranslate">spam</code> and <code class="docutils literal notranslate">eggs</code> are”. <section id="id5"> <h4><a class="toc-backref" href="#id5" role="doc-backlink">Response</a></h4> This is very true. But it is equally true today, where the use of the <code class="docutils literal notranslate">|</code> operator could mean any of: <ul class="simple"> <li><code class="docutils literal notranslate">int</code>/<code class="docutils literal notranslate">bool</code> bitwise-or</li> <li><code class="docutils literal notranslate">set</code>/<code class="docutils literal notranslate">frozenset</code> union</li> <li>any other overloaded operation</li> </ul> Adding dict union to the set of possibilities doesn’t seem to make it harder to understand the code. No more work is required to determine that <code class="docutils literal notranslate">spam</code> and <code class="docutils literal notranslate">eggs</code> are mappings than it would take to determine that they are sets, or integers. And good naming conventions will help: <div class="highlight-default notranslate"><div class="highlight"><pre>flags |= WRITEABLE # Probably numeric bitwise-or. DO_NOT_RUN = WEEKENDS | HOLIDAYS # Probably set union. settings = DEFAULT_SETTINGS | user_settings | workspace_settings # Probably dict union. </pre></div> </div> </section> </section> <section id="what-about-the-full-set-api"> <h3><a class="toc-backref" href="#what-about-the-full-set-api" role="doc-backlink">What About The Full <code class="docutils literal notranslate">set</code> API?</a></h3> dicts are “set like”, and should support the full collection of set operators: <code class="docutils literal notranslate">|</code>, <code class="docutils literal notranslate">&</code>, <code class="docutils literal notranslate">^</code>, and <code class="docutils literal notranslate">-</code>. <section id="id6"> <h4><a class="toc-backref" href="#id6" role="doc-backlink">Response</a></h4> This PEP does not take a position on whether dicts should support the full collection of set operators, and would prefer to leave that for a later PEP (one of the authors is interested in drafting such a PEP). For the benefit of any later PEP, a brief summary follows. Set symmetric difference (<code class="docutils literal notranslate">^</code>) is obvious and natural. For example, given two dicts: <div class="highlight-default notranslate"><div class="highlight"><pre>d1 = {"spam": 1, "eggs": 2} d2 = {"ham": 3, "eggs": 4} </pre></div> </div> the symmetric difference <code class="docutils literal notranslate">d1 ^ d2</code> would be <code class="docutils literal notranslate">{"spam": 1, "ham": 3}</code>. Set difference (<code class="docutils literal notranslate">-</code>) is also obvious and natural, and an earlier version of this PEP included it in the proposal. Given the dicts above, we would have <code class="docutils literal notranslate">d1 - d2</code> be <code class="docutils literal notranslate">{"spam": 1}</code> and <code class="docutils literal notranslate">d2 - d1</code> be <code class="docutils literal notranslate">{"ham": 3}</code>. Set intersection (<code class="docutils literal notranslate">&</code>) is a bit more problematic. While it is easy to determine the intersection of keys in two dicts, it is not clear what to do with the values. Given the two dicts above, it is obvious that the only key of <code class="docutils literal notranslate">d1 & d2</code> must be <code class="docutils literal notranslate">"eggs"</code>. “Last seen wins”, however, has the advantage of consistency with other dict operations (and the proposed union operators). </section> </section> <section id="what-about-mapping-and-mutablemapping"> <h3><a class="toc-backref" href="#what-about-mapping-and-mutablemapping" role="doc-backlink">What About <code class="docutils literal notranslate">Mapping</code> And <code class="docutils literal notranslate">MutableMapping</code>?</a></h3> <code class="docutils literal notranslate">collections.abc.Mapping</code> and <code class="docutils literal notranslate">collections.abc.MutableMapping</code> should define <code class="docutils literal notranslate">|</code> and <code class="docutils literal notranslate">|=</code>, so subclasses could just inherit the new operators instead of having to define them. <section id="id7"> <h4><a class="toc-backref" href="#id7" role="doc-backlink">Response</a></h4> There are two primary reasons why adding the new operators to these classes would be problematic: <ul class="simple"> <li>Currently, neither defines a <code class="docutils literal notranslate">copy</code> method, which would be necessary for <code class="docutils literal notranslate">|</code> to create a new instance.</li> <li>Adding <code class="docutils literal notranslate">|=</code> to <code class="docutils literal notranslate">MutableMapping</code> (or a <code class="docutils literal notranslate">copy</code> method to <code class="docutils literal notranslate">Mapping</code>) would create compatibility issues for virtual subclasses.</li> </ul> </section> </section> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="rejected-semantics"> <h3><a class="toc-backref" href="#rejected-semantics" role="doc-backlink">Rejected Semantics</a></h3> There were at least four other proposed solutions for handling conflicting keys. These alternatives are left to subclasses of dict. <section id="raise"> <h4><a class="toc-backref" href="#raise" role="doc-backlink">Raise</a></h4> It isn’t clear that this behavior has many use-cases or will be often useful, but it will likely be annoying as any use of the dict union operator would have to be guarded with a <code class="docutils literal notranslate">try</code>/<code class="docutils literal notranslate">except</code> clause. </section> <section id="add-the-values-as-counter-does-with"> <h4><a class="toc-backref" href="#add-the-values-as-counter-does-with" role="doc-backlink">Add The Values (As Counter Does, with <code class="docutils literal notranslate">+</code>)</a></h4> Too specialised to be used as the default behavior. </section> <section id="leftmost-value-first-seen-wins"> <h4><a class="toc-backref" href="#leftmost-value-first-seen-wins" role="doc-backlink">Leftmost Value (First-Seen) Wins</a></h4> It isn’t clear that this behavior has many use-cases. In fact, one can simply reverse the order of the arguments: <div class="highlight-default notranslate"><div class="highlight"><pre>d2 | d1 # d1 merged with d2, keeping existing values in d1 </pre></div> </div> </section> <section id="concatenate-values-in-a-list"> <h4><a class="toc-backref" href="#concatenate-values-in-a-list" role="doc-backlink">Concatenate Values In A List</a></h4> This is likely to be too specialised to be the default. It is not clear what to do if the values are already lists: <div class="highlight-default notranslate"><div class="highlight"><pre>{'a': [1, 2]} | {'a': [3, 4]} </pre></div> </div> Should this give <code class="docutils literal notranslate">{'a': [1, 2, 3, 4]}</code> or <code class="docutils literal notranslate">{'a': [[1, 2], [3, 4]]}</code>? </section> </section> <section id="rejected-alternatives"> <h3><a class="toc-backref" href="#rejected-alternatives" role="doc-backlink">Rejected Alternatives</a></h3> <section id="use-the-addition-operator"> <h4><a class="toc-backref" href="#use-the-addition-operator" role="doc-backlink">Use The Addition Operator</a></h4> This PEP originally started life as a proposal for dict addition, using the <code class="docutils literal notranslate">+</code> and <code class="docutils literal notranslate">+=</code> operator. That choice proved to be exceedingly controversial, with many people having serious objections to the choice of operator. For details, see <a class="reference external" href="https://github.com/python/peps/commits/master/pep-0584.rst">previous versions</a> of the PEP and the mailing list <a class="reference internal" href="#discussions">discussions</a>. </section> <section id="use-the-left-shift-operator"> <h4><a class="toc-backref" href="#use-the-left-shift-operator" role="doc-backlink">Use The Left Shift Operator</a></h4> The <code class="docutils literal notranslate"><<</code> operator didn’t seem to get much support on Python-Ideas, but no major objections either. Perhaps the strongest objection was Chris Angelico’s comment <blockquote> <div>The “cuteness” value of abusing the operator to indicate information flow got old shortly after C++ did it.</div></blockquote> </section> <section id="use-a-new-left-arrow-operator"> <h4><a class="toc-backref" href="#use-a-new-left-arrow-operator" role="doc-backlink">Use A New Left Arrow Operator</a></h4> Another suggestion was to create a new operator <code class="docutils literal notranslate"><-</code>. Unfortunately this would be ambiguous, <code class="docutils literal notranslate">d <- e</code> could mean <code class="docutils literal notranslate">d merge e</code> or <code class="docutils literal notranslate">d less-than minus e</code>. </section> <section id="use-a-method"> <h4><a class="toc-backref" href="#use-a-method" role="doc-backlink">Use A Method</a></h4> A <code class="docutils literal notranslate">dict.merged()</code> method would avoid the need for an operator at all. One subtlety is that it would likely need slightly different implementations when called as an unbound method versus as a bound method. As an unbound method, the behavior could be similar to: <div class="highlight-default notranslate"><div class="highlight"><pre>def merged(cls, *mappings, **kw): new = cls() # Will this work for defaultdict? for m in mappings: new.update(m) new.update(kw) return new </pre></div> </div> As a bound method, the behavior could be similar to: <div class="highlight-default notranslate"><div class="highlight"><pre>def merged(self, *mappings, **kw): new = self.copy() for m in mappings: new.update(m) new.update(kw) return new </pre></div> </div> <section id="advantages"> <h5><a class="toc-backref" href="#advantages" role="doc-backlink">Advantages</a></h5> <ul class="simple"> <li>Arguably, methods are more discoverable than operators.</li> <li>The method could accept any number of positional and keyword arguments, avoiding the inefficiency of creating temporary dicts.</li> <li>Accepts sequences of <code class="docutils literal notranslate">(key, value)</code> pairs like the <code class="docutils literal notranslate">update</code> method.</li> <li>Being a method, it is easy to override in a subclass if you need alternative behaviors such as “first wins”, “unique keys”, etc.</li> </ul> </section> <section id="disadvantages"> <h5><a class="toc-backref" href="#disadvantages" role="doc-backlink">Disadvantages</a></h5> <ul class="simple"> <li>Would likely require a new kind of method decorator which combined the behavior of regular instance methods and <code class="docutils literal notranslate">classmethod</code>. It would need to be public (but not necessarily a builtin) for those needing to override the method. There is a <a class="reference external" href="http://code.activestate.com/recipes/577030">proof of concept</a>.</li> <li>It isn’t an operator. Guido discusses <a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/message/52DLME5DKNZYFEETCTRENRNKWJ2B4DD5/">why operators are useful</a>. For another viewpoint, see <a class="reference external" href="https://www.curiousefficiency.org/posts/2019/03/what-does-x-equals-a-plus-b-mean.html">Alyssa Coghlan’s blog post</a>.</li> </ul> </section> </section> <section id="use-a-function"> <h4><a class="toc-backref" href="#use-a-function" role="doc-backlink">Use a Function</a></h4> Instead of a method, use a new built-in function <code class="docutils literal notranslate">merged()</code>. One possible implementation could be something like this: <div class="highlight-default notranslate"><div class="highlight"><pre>def merged(*mappings, **kw): if mappings and isinstance(mappings[0], dict): # If the first argument is a dict, use its type. new = mappings[0].copy() mappings = mappings[1:] else: # No positional arguments, or the first argument is a # sequence of (key, value) pairs. new = dict() for m in mappings: new.update(m) new.update(kw) return new </pre></div> </div> An alternative might be to forgo the arbitrary keywords, and take a single keyword parameter that specifies the behavior on collisions: <div class="highlight-default notranslate"><div class="highlight"><pre>def merged(*mappings, on_collision=lambda k, v1, v2: v2): # implementation left as an exercise to the reader </pre></div> </div> <section id="id8"> <h5><a class="toc-backref" href="#id8" role="doc-backlink">Advantages</a></h5> <ul class="simple"> <li>Most of the same advantages of the method solutions above.</li> <li>Doesn’t require a subclass to implement alternative behavior on collisions, just a function.</li> </ul> </section> <section id="id9"> <h5><a class="toc-backref" href="#id9" role="doc-backlink">Disadvantages</a></h5> <ul class="simple"> <li>May not be important enough to be a builtin.</li> <li>Hard to override behavior if you need something like “first wins”, without losing the ability to process arbitrary keyword arguments.</li> </ul> </section> </section> </section> </section> <section id="examples"> <h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2> The authors of this PEP did a survey of third party libraries for dictionary merging which might be candidates for dict union. This is a cursory list based on a subset of whatever arbitrary third-party packages happened to be installed on one of the authors’ computers, and may not reflect the current state of any package. Also note that, while further (unrelated) refactoring may be possible, the rewritten version only adds usage of the new operators for an apples-to-apples comparison. It also reduces the result to an expression when it is efficient to do so. <section id="ipython-zmq-ipkernel-py"> <h3><a class="toc-backref" href="#ipython-zmq-ipkernel-py" role="doc-backlink">IPython/zmq/ipkernel.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>aliases = dict(kernel_aliases) aliases.update(shell_aliases) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>aliases = kernel_aliases | shell_aliases </pre></div> </div> </section> <section id="ipython-zmq-kernelapp-py"> <h3><a class="toc-backref" href="#ipython-zmq-kernelapp-py" role="doc-backlink">IPython/zmq/kernelapp.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>kernel_aliases = dict(base_aliases) kernel_aliases.update({ 'ip' : 'KernelApp.ip', 'hb' : 'KernelApp.hb_port', 'shell' : 'KernelApp.shell_port', 'iopub' : 'KernelApp.iopub_port', 'stdin' : 'KernelApp.stdin_port', 'parent': 'KernelApp.parent', }) if sys.platform.startswith('win'): kernel_aliases['interrupt'] = 'KernelApp.interrupt' kernel_flags = dict(base_flags) kernel_flags.update({ 'no-stdout' : ( {'KernelApp' : {'no_stdout' : True}}, "redirect stdout to the null device"), 'no-stderr' : ( {'KernelApp' : {'no_stderr' : True}}, "redirect stderr to the null device"), }) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>kernel_aliases = base_aliases | { 'ip' : 'KernelApp.ip', 'hb' : 'KernelApp.hb_port', 'shell' : 'KernelApp.shell_port', 'iopub' : 'KernelApp.iopub_port', 'stdin' : 'KernelApp.stdin_port', 'parent': 'KernelApp.parent', } if sys.platform.startswith('win'): kernel_aliases['interrupt'] = 'KernelApp.interrupt' kernel_flags = base_flags | { 'no-stdout' : ( {'KernelApp' : {'no_stdout' : True}}, "redirect stdout to the null device"), 'no-stderr' : ( {'KernelApp' : {'no_stderr' : True}}, "redirect stderr to the null device"), } </pre></div> </div> </section> <section id="matplotlib-backends-backend-svg-py"> <h3><a class="toc-backref" href="#matplotlib-backends-backend-svg-py" role="doc-backlink">matplotlib/backends/backend_svg.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>attrib = attrib.copy() attrib.update(extra) attrib = attrib.items() </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>attrib = (attrib | extra).items() </pre></div> </div> </section> <section id="matplotlib-delaunay-triangulate-py"> <h3><a class="toc-backref" href="#matplotlib-delaunay-triangulate-py" role="doc-backlink">matplotlib/delaunay/triangulate.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>edges = {} edges.update(dict(zip(self.triangle_nodes[border[:,0]][:,1], self.triangle_nodes[border[:,0]][:,2]))) edges.update(dict(zip(self.triangle_nodes[border[:,1]][:,2], self.triangle_nodes[border[:,1]][:,0]))) edges.update(dict(zip(self.triangle_nodes[border[:,2]][:,0], self.triangle_nodes[border[:,2]][:,1]))) </pre></div> </div> Rewrite as: <div class="highlight-default notranslate"><div class="highlight"><pre>edges = {} edges |= zip(self.triangle_nodes[border[:,0]][:,1], self.triangle_nodes[border[:,0]][:,2]) edges |= zip(self.triangle_nodes[border[:,1]][:,2], self.triangle_nodes[border[:,1]][:,0]) edges |= zip(self.triangle_nodes[border[:,2]][:,0], self.triangle_nodes[border[:,2]][:,1]) </pre></div> </div> </section> <section id="matplotlib-legend-py"> <h3><a class="toc-backref" href="#matplotlib-legend-py" role="doc-backlink">matplotlib/legend.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>hm = default_handler_map.copy() hm.update(self._handler_map) return hm </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>return default_handler_map | self._handler_map </pre></div> </div> </section> <section id="numpy-ma-core-py"> <h3><a class="toc-backref" href="#numpy-ma-core-py" role="doc-backlink">numpy/ma/core.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>_optinfo = {} _optinfo.update(getattr(obj, '_optinfo', {})) _optinfo.update(getattr(obj, '_basedict', {})) if not isinstance(obj, MaskedArray): _optinfo.update(getattr(obj, '__dict__', {})) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>_optinfo = {} _optinfo |= getattr(obj, '_optinfo', {}) _optinfo |= getattr(obj, '_basedict', {}) if not isinstance(obj, MaskedArray): _optinfo |= getattr(obj, '__dict__', {}) </pre></div> </div> </section> <section id="praw-internal-py"> <h3><a class="toc-backref" href="#praw-internal-py" role="doc-backlink">praw/internal.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>data = {'name': six.text_type(user), 'type': relationship} data.update(kwargs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>data = {'name': six.text_type(user), 'type': relationship} | kwargs </pre></div> </div> </section> <section id="pygments-lexer-py"> <h3><a class="toc-backref" href="#pygments-lexer-py" role="doc-backlink">pygments/lexer.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>kwargs.update(lexer.options) lx = lexer.__class__(**kwargs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>lx = lexer.__class__(**(kwargs | lexer.options)) </pre></div> </div> </section> <section id="requests-sessions-py"> <h3><a class="toc-backref" href="#requests-sessions-py" role="doc-backlink">requests/sessions.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>merged_setting = dict_class(to_key_val_list(session_setting)) merged_setting.update(to_key_val_list(request_setting)) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>merged_setting = dict_class(to_key_val_list(session_setting)) | to_key_val_list(request_setting) </pre></div> </div> </section> <section id="sphinx-domains-init-py"> <h3><a class="toc-backref" href="#sphinx-domains-init-py" role="doc-backlink">sphinx/domains/__init__.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>self.attrs = self.known_attrs.copy() self.attrs.update(attrs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>self.attrs = self.known_attrs | attrs </pre></div> </div> </section> <section id="sphinx-ext-doctest-py"> <h3><a class="toc-backref" href="#sphinx-ext-doctest-py" role="doc-backlink">sphinx/ext/doctest.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>new_opt = code[0].options.copy() new_opt.update(example.options) example.options = new_opt </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>example.options = code[0].options | example.options </pre></div> </div> </section> <section id="sphinx-ext-inheritance-diagram-py"> <h3><a class="toc-backref" href="#sphinx-ext-inheritance-diagram-py" role="doc-backlink">sphinx/ext/inheritance_diagram.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>n_attrs = self.default_node_attrs.copy() e_attrs = self.default_edge_attrs.copy() g_attrs.update(graph_attrs) n_attrs.update(node_attrs) e_attrs.update(edge_attrs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>g_attrs |= graph_attrs n_attrs = self.default_node_attrs | node_attrs e_attrs = self.default_edge_attrs | edge_attrs </pre></div> </div> </section> <section id="sphinx-highlighting-py"> <h3><a class="toc-backref" href="#sphinx-highlighting-py" role="doc-backlink">sphinx/highlighting.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>kwargs.update(self.formatter_args) return self.formatter(**kwargs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>return self.formatter(**(kwargs | self.formatter_args)) </pre></div> </div> </section> <section id="sphinx-quickstart-py"> <h3><a class="toc-backref" href="#sphinx-quickstart-py" role="doc-backlink">sphinx/quickstart.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>d2 = DEFAULT_VALUE.copy() d2.update(dict(("ext_"+ext, False) for ext in EXTENSIONS)) d2.update(d) d = d2 </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>d = DEFAULT_VALUE | dict(("ext_"+ext, False) for ext in EXTENSIONS) | d </pre></div> </div> </section> <section id="sympy-abc-py"> <h3><a class="toc-backref" href="#sympy-abc-py" role="doc-backlink">sympy/abc.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>clash = {} clash.update(clash1) clash.update(clash2) return clash1, clash2, clash </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>return clash1, clash2, clash1 | clash2 </pre></div> </div> </section> <section id="sympy-parsing-maxima-py"> <h3><a class="toc-backref" href="#sympy-parsing-maxima-py" role="doc-backlink">sympy/parsing/maxima.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>dct = MaximaHelpers.__dict__.copy() dct.update(name_dict) obj = sympify(str, locals=dct) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>obj = sympify(str, locals=MaximaHelpers.__dict__|name_dict) </pre></div> </div> </section> <section id="sympy-printing-ccode-py-and-sympy-printing-fcode-py"> <h3><a class="toc-backref" href="#sympy-printing-ccode-py-and-sympy-printing-fcode-py" role="doc-backlink">sympy/printing/ccode.py and sympy/printing/fcode.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>self.known_functions = dict(known_functions) userfuncs = settings.get('user_functions', {}) self.known_functions.update(userfuncs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>self.known_functions = known_functions | settings.get('user_functions', {}) </pre></div> </div> </section> <section id="sympy-utilities-runtests-py"> <h3><a class="toc-backref" href="#sympy-utilities-runtests-py" role="doc-backlink">sympy/utilities/runtests.py</a></h3> Before: <div class="highlight-default notranslate"><div class="highlight"><pre>globs = globs.copy() if extraglobs is not None: globs.update(extraglobs) </pre></div> </div> After: <div class="highlight-default notranslate"><div class="highlight"><pre>globs = globs | (extraglobs if extraglobs is not None else {}) </pre></div> </div> The above examples show that sometimes the <code class="docutils literal notranslate">|</code> operator leads to a clear increase in readability, reducing the number of lines of code and improving clarity. However other examples using the <code class="docutils literal notranslate">|</code> operator lead to long, complex single expressions, possibly well over the <a class="pep reference internal" href="../pep-0008/" title="PEP 8 – Style Guide for Python Code">PEP 8</a> maximum line length of 80 columns. As with any other language feature, the programmer should use their own judgement about whether <code class="docutils literal notranslate">|</code> improves their code. </section> </section> <section id="related-discussions"> <h2><a class="toc-backref" href="#related-discussions" role="doc-backlink">Related Discussions</a></h2> Mailing list threads (this is by no means an exhaustive list): <ul class="simple"> <li><a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/BHIJX6MHGMMD3S6D7GVTPZQL4N5V7T42/">Dict joining using + and +=</a></li> <li><a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/KLDQAPOIJEANCKYCHQZ536WHQ45I6UVW/">PEP: Dict addition and subtraction</a></li> <li><a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/W2FCSC3JDA7NUBXAVSTVCUDEGAKWWPTH/">PEP 584: Add + and += operators to the built-in dict class.</a></li> <li><a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/SWBLMTNQXNL3O5LN3327IYNPFIL2QSH5/">Moving PEP 584 forward (dict + and += operators)</a></li> <li><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/thread/TTIKCDIPC2CDHX23Y57CPHDSVYOWCCER/">PEP 584: Add Union Operators To dict</a></li> <li><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/thread/6KT2KIOTYXMDCD2CCAOLOI7LUGTN6MBS">Accepting PEP 584: Add Union Operators To dict</a></li> </ul> <a class="reference external" href="https://bugs.python.org/issue36144">Ticket on the bug tracker</a> Merging two dictionaries in an expression is a frequently requested feature. For example: <a class="reference external" href="https://stackoverflow.com/questions/38987/how-to-merge-two-dictionaries-in-a-single-expression">https://stackoverflow.com/questions/38987/how-to-merge-two-dictionaries-in-a-single-expression</a> <a class="reference external" href="https://stackoverflow.com/questions/1781571/how-to-concatenate-two-dictionaries-to-create-a-new-one-in-python">https://stackoverflow.com/questions/1781571/how-to-concatenate-two-dictionaries-to-create-a-new-one-in-python</a> <a class="reference external" href="https://stackoverflow.com/questions/6005066/adding-dictionaries-together-python">https://stackoverflow.com/questions/6005066/adding-dictionaries-together-python</a> Occasionally people request alternative behavior for the merge: <a class="reference external" href="https://stackoverflow.com/questions/1031199/adding-dictionaries-in-python">https://stackoverflow.com/questions/1031199/adding-dictionaries-in-python</a> <a class="reference external" href="https://stackoverflow.com/questions/877295/python-dict-add-by-valuedict-2">https://stackoverflow.com/questions/877295/python-dict-add-by-valuedict-2</a> …including one proposal to treat dicts as <a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/message/YY3KZZGEX6VEFX5QZJ33P7NTTXGPZQ7N/">sets of keys</a>. <a class="reference external" href="https://lwn.net/Articles/635444/">Ian Lee’s proto-PEP</a>, and <a class="reference external" href="https://lwn.net/Articles/635397/">discussion</a> in 2015. Further discussion took place on <a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/43OZV3MR4XLFRPCI27I7BB6HVBD25M2E/">Python-Ideas</a>. (Observant readers will notice that one of the authors of this PEP was more skeptical of the idea in 2015.) Adding <a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/thread/EKWMDJKMVOJCOROQVHJFQX7W2L55I5RA/">a full complement of operators to dicts</a>. <a class="reference external" href="https://news.ycombinator.com/item?id=19314646">Discussion on Y-Combinator</a>. <a class="reference external" href="https://treyhunner.com/2016/02/how-to-merge-dictionaries-in-python/">https://treyhunner.com/2016/02/how-to-merge-dictionaries-in-python/</a> <a class="reference external" href="https://code.tutsplus.com/tutorials/how-to-merge-two-python-dictionaries--cms-26230">https://code.tutsplus.com/tutorials/how-to-merge-two-python-dictionaries–cms-26230</a> In direct response to an earlier draft of this PEP, Serhiy Storchaka raised <a class="reference external" href="https://bugs.python.org/issue36431">a ticket in the bug tracker</a> to replace the <code class="docutils literal notranslate">copy(); update()</code> idiom with dict unpacking. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0584.rst">https://github.com/python/peps/blob/main/peps/pep-0584.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0584.rst">2023-10-11 12:05:51 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="#motivation">Motivation</a><ul> <li><a class="reference internal" href="#dict-update"><code class="docutils literal notranslate">dict.update</code></a></li> <li><a class="reference internal" href="#d1-d2"><code class="docutils literal notranslate">{**d1, **d2}</code></a></li> <li><a class="reference internal" href="#collections-chainmap"><code class="docutils literal notranslate">collections.ChainMap</code></a></li> <li><a class="reference internal" href="#dict-d1-d2"><code class="docutils literal notranslate">dict(d1, **d2)</code></a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#major-objections">Major Objections</a><ul> <li><a class="reference internal" href="#dict-union-is-not-commutative">Dict Union Is Not Commutative</a><ul> <li><a class="reference internal" href="#response">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-will-be-inefficient">Dict Union Will Be Inefficient</a><ul> <li><a class="reference internal" href="#id1">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-is-lossy">Dict Union Is Lossy</a><ul> <li><a class="reference internal" href="#id2">Response</a></li> </ul> </li> <li><a class="reference internal" href="#only-one-way-to-do-it">Only One Way To Do It</a><ul> <li><a class="reference internal" href="#id3">Response</a></li> </ul> </li> <li><a class="reference internal" href="#more-than-one-way-to-do-it">More Than One Way To Do It</a><ul> <li><a class="reference internal" href="#id4">Response</a></li> </ul> </li> <li><a class="reference internal" href="#dict-union-makes-code-harder-to-understand">Dict Union Makes Code Harder To Understand</a><ul> <li><a class="reference internal" href="#id5">Response</a></li> </ul> </li> <li><a class="reference internal" href="#what-about-the-full-set-api">What About The Full <code class="docutils literal notranslate">set</code> API?</a><ul> <li><a class="reference internal" href="#id6">Response</a></li> </ul> </li> <li><a class="reference internal" href="#what-about-mapping-and-mutablemapping">What About <code class="docutils literal notranslate">Mapping</code> And <code class="docutils literal notranslate">MutableMapping</code>?</a><ul> <li><a class="reference internal" href="#id7">Response</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#rejected-semantics">Rejected Semantics</a><ul> <li><a class="reference internal" href="#raise">Raise</a></li> <li><a class="reference internal" href="#add-the-values-as-counter-does-with">Add The Values (As Counter Does, with <code class="docutils literal notranslate">+</code>)</a></li> <li><a class="reference internal" href="#leftmost-value-first-seen-wins">Leftmost Value (First-Seen) Wins</a></li> <li><a class="reference internal" href="#concatenate-values-in-a-list">Concatenate Values In A List</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#use-the-addition-operator">Use The Addition Operator</a></li> <li><a class="reference internal" href="#use-the-left-shift-operator">Use The Left Shift Operator</a></li> <li><a class="reference internal" href="#use-a-new-left-arrow-operator">Use A New Left Arrow Operator</a></li> <li><a class="reference internal" href="#use-a-method">Use A Method</a><ul> <li><a class="reference internal" href="#advantages">Advantages</a></li> <li><a class="reference internal" href="#disadvantages">Disadvantages</a></li> </ul> </li> <li><a class="reference internal" href="#use-a-function">Use a Function</a><ul> <li><a class="reference internal" href="#id8">Advantages</a></li> <li><a class="reference internal" href="#id9">Disadvantages</a></li> </ul> </li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a><ul> <li><a class="reference internal" href="#ipython-zmq-ipkernel-py">IPython/zmq/ipkernel.py</a></li> <li><a class="reference internal" href="#ipython-zmq-kernelapp-py">IPython/zmq/kernelapp.py</a></li> <li><a class="reference internal" href="#matplotlib-backends-backend-svg-py">matplotlib/backends/backend_svg.py</a></li> <li><a class="reference internal" href="#matplotlib-delaunay-triangulate-py">matplotlib/delaunay/triangulate.py</a></li> <li><a class="reference internal" href="#matplotlib-legend-py">matplotlib/legend.py</a></li> <li><a class="reference internal" href="#numpy-ma-core-py">numpy/ma/core.py</a></li> <li><a class="reference internal" href="#praw-internal-py">praw/internal.py</a></li> <li><a class="reference internal" href="#pygments-lexer-py">pygments/lexer.py</a></li> <li><a class="reference internal" href="#requests-sessions-py">requests/sessions.py</a></li> <li><a class="reference internal" href="#sphinx-domains-init-py">sphinx/domains/__init__.py</a></li> <li><a class="reference internal" href="#sphinx-ext-doctest-py">sphinx/ext/doctest.py</a></li> <li><a class="reference internal" href="#sphinx-ext-inheritance-diagram-py">sphinx/ext/inheritance_diagram.py</a></li> <li><a class="reference internal" href="#sphinx-highlighting-py">sphinx/highlighting.py</a></li> <li><a class="reference internal" href="#sphinx-quickstart-py">sphinx/quickstart.py</a></li> <li><a class="reference internal" href="#sympy-abc-py">sympy/abc.py</a></li> <li><a class="reference internal" href="#sympy-parsing-maxima-py">sympy/parsing/maxima.py</a></li> <li><a class="reference internal" href="#sympy-printing-ccode-py-and-sympy-printing-fcode-py">sympy/printing/ccode.py and sympy/printing/fcode.py</a></li> <li><a class="reference internal" href="#sympy-utilities-runtests-py">sympy/utilities/runtests.py</a></li> </ul> </li> <li><a class="reference internal" href="#related-discussions">Related Discussions</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-0584.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>