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 448 – Additional Unpacking Generalizations | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0448/"> <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 448 – Additional Unpacking Generalizations | peps.python.org'> <meta property="og:description" content="This PEP proposes extended usages of the * iterable unpacking operator and ** dictionary unpacking operators to allow unpacking in more positions, an arbitrary number of times, and in function calls and displays."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0448/"> <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 extended usages of the * iterable unpacking operator and ** dictionary unpacking operators to allow unpacking in more positions, an arbitrary number of times, and in function calls and displays."> <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 448</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 448 – Additional Unpacking Generalizations</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Joshua Landau <joshua at landau.ws></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/python-ideas@python.org/">Python-Ideas list</a></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">29-Jun-2013</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.5</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd"></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="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#disadvantages">Disadvantages</a></li> <li><a class="reference internal" href="#variations">Variations</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> This PEP proposes extended usages of the <code class="docutils literal notranslate">*</code> iterable unpacking operator and <code class="docutils literal notranslate">**</code> dictionary unpacking operators to allow unpacking in more positions, an arbitrary number of times, and in function calls and displays. Function calls are proposed to support an arbitrary number of unpackings rather than just one: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> print(*[1], *[2], 3) 1 2 3 >>> dict(**{'x': 1}, y=2, **{'z': 3}) {'x': 1, 'y': 2, 'z': 3} </pre></div> </div> Unpacking is proposed to be allowed inside tuple, list, set, and dictionary displays: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> *range(4), 4 (0, 1, 2, 3, 4) >>> [*range(4), 4] [0, 1, 2, 3, 4] >>> {*range(4), 4} {0, 1, 2, 3, 4} >>> {'x': 1, **{'y': 2}} {'x': 1, 'y': 2} </pre></div> </div> In dictionaries, later values will always override earlier ones: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> {'x': 1, **{'x': 2}} {'x': 2} >>> {**{'x': 2}, 'x': 1} {'x': 1} </pre></div> </div> This PEP does not include unpacking operators inside list, set and dictionary comprehensions although this has not been ruled out for future proposals. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Current usage of the <code class="docutils literal notranslate">*</code> iterable unpacking operator features unnecessary restrictions that can harm readability. Unpacking multiple times has an obvious rationale. When you want to unpack several iterables into a function definition or follow an unpack with more positional arguments, the most natural way would be to write: <div class="highlight-default notranslate"><div class="highlight"><pre>function(**kw_arguments, **more_arguments) function(*arguments, argument) </pre></div> </div> Simple examples where this is useful are <code class="docutils literal notranslate">print</code> and <code class="docutils literal notranslate">str.format</code>. Instead, you could be forced to write: <div class="highlight-default notranslate"><div class="highlight"><pre>kwargs = dict(kw_arguments) kwargs.update(more_arguments) function(**kwargs) args = list(arguments) args.append(arg) function(*args) </pre></div> </div> or, if you know to do so: <div class="highlight-default notranslate"><div class="highlight"><pre>from collections import ChainMap function(**ChainMap(more_arguments, arguments)) from itertools import chain function(*chain(args, [arg])) </pre></div> </div> which add unnecessary line-noise and, with the first methods, causes duplication of work. There are two primary rationales for unpacking inside of containers. Firstly there is a symmetry of assignment, where <code class="docutils literal notranslate">fst, *other, lst = elems</code> and <code class="docutils literal notranslate">elems = fst, *other, lst</code> are approximate inverses, ignoring the specifics of types. This, in effect, simplifies the language by removing special cases. Secondly, it vastly simplifies types of “addition” such as combining dictionaries, and does so in an unambiguous and well-defined way: <div class="highlight-default notranslate"><div class="highlight"><pre>combination = {**first_dictionary, "x": 1, "y": 2} </pre></div> </div> instead of: <div class="highlight-default notranslate"><div class="highlight"><pre>combination = first_dictionary.copy() combination.update({"x": 1, "y": 2}) </pre></div> </div> which is especially important in contexts where expressions are preferred. This is also useful as a more readable way of summing iterables into a list, such as <code class="docutils literal notranslate">my_list + list(my_tuple) + list(my_range)</code> which is now equivalent to just <code class="docutils literal notranslate">[*my_list, *my_tuple, *my_range]</code>. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> Function calls may accept an unbounded number of <code class="docutils literal notranslate">*</code> and <code class="docutils literal notranslate">**</code> unpackings. There will be no restriction of the order of positional arguments with relation to <code class="docutils literal notranslate">*</code> unpackings nor any restriction of the order of keyword arguments with relation to <code class="docutils literal notranslate">**</code> unpackings. Function calls continue to have the restriction that keyword arguments must follow positional arguments and <code class="docutils literal notranslate">**</code> unpackings must additionally follow <code class="docutils literal notranslate">*</code> unpackings. Currently, if an argument is given multiple times — such as a positional argument given both positionally and by keyword — a <code class="docutils literal notranslate">TypeError</code> is raised. This remains true for duplicate arguments provided through multiple <code class="docutils literal notranslate">**</code> unpackings, e.g. <code class="docutils literal notranslate">f(**{'x': 2}, **{'x': 3})</code>, except that the error will be detected at runtime. A function looks like this: <div class="highlight-default notranslate"><div class="highlight"><pre>function( argument or *args, argument or *args, ..., kwargument or *args, kwargument or *args, ..., kwargument or **kwargs, kwargument or **kwargs, ... ) </pre></div> </div> Tuples, lists, sets and dictionaries will allow unpacking. This will act as if the elements from unpacked items were inserted in order at the site of unpacking, much as happens in unpacking in a function-call. Dictionaries require <code class="docutils literal notranslate">**</code> unpacking; all the others require <code class="docutils literal notranslate">*</code> unpacking. The keys in a dictionary remain in a right-to-left priority order, so <code class="docutils literal notranslate">{**{'a': 1}, 'a': 2, **{'a': 3}}</code> evaluates to <code class="docutils literal notranslate">{'a': 3}</code>. There is no restriction on the number or position of unpackings. </section> <section id="disadvantages"> <h2><a class="toc-backref" href="#disadvantages" role="doc-backlink">Disadvantages</a></h2> The allowable orders for arguments in a function call are more complicated than before. The simplest explanation for the rules may be “positional arguments precede keyword arguments and <code class="docutils literal notranslate">**</code> unpacking; <code class="docutils literal notranslate">*</code> unpacking precedes <code class="docutils literal notranslate">**</code> unpacking”. Whilst <code class="docutils literal notranslate">*elements, = iterable</code> causes <code class="docutils literal notranslate">elements</code> to be a list, <code class="docutils literal notranslate">elements = *iterable,</code> causes <code class="docutils literal notranslate">elements</code> to be a tuple. The reason for this may confuse people unfamiliar with the construct. Concerns have been raised about the unexpected difference between duplicate keys in dictionaries being allowed but duplicate keys in function call syntax raising an error. Although this is already the case with current syntax, this proposal might exacerbate the issue. It remains to be seen how much of an issue this is in practice. </section> <section id="variations"> <h2><a class="toc-backref" href="#variations" role="doc-backlink">Variations</a></h2> The PEP originally considered whether the ordering of argument types in a function call (positional, keyword, <code class="docutils literal notranslate">*</code> or <code class="docutils literal notranslate">**</code>) could become less strict. This met little support so the idea was shelved. Earlier iterations of this PEP allowed unpacking operators inside list, set, and dictionary comprehensions as a flattening operator over iterables of containers: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> ranges = [range(i) for i in range(5)] >>> [*item for item in ranges] [0, 0, 1, 0, 1, 2, 0, 1, 2, 3] >>> {*item for item in ranges} {0, 1, 2, 3} </pre></div> </div> This was met with a mix of strong concerns about readability and mild support. In order not to disadvantage the less controversial aspects of the PEP, this was not accepted with the rest of the proposal. Unbracketed comprehensions in function calls, such as <code class="docutils literal notranslate">f(x for x in it)</code>, are already valid. These could be extended to: <div class="highlight-default notranslate"><div class="highlight"><pre>f(*x for x in it) == f((*x for x in it)) f(**x for x in it) == f({**x for x in it}) </pre></div> </div> However, it wasn’t clear if this was the best behaviour or if it should unpack into the arguments of the call to <code class="docutils literal notranslate">f</code>. Since this is likely to be confusing and is of only very marginal utility, it is not included in this PEP. Instead, these will throw a <code class="docutils literal notranslate">SyntaxError</code> and comprehensions with explicit brackets should be used instead. </section> <section id="approval"> <h2><a class="toc-backref" href="#approval" role="doc-backlink">Approval</a></h2> This PEP was accepted by Guido on February 25, 2015 <a class="footnote-reference brackets" href="#id3" id="id1">[1]</a>. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> An implementation for Python 3.5 is found at Issue 2292 on bug tracker <a class="footnote-reference brackets" href="#id4" id="id2">[2]</a>. This currently includes support for unpacking inside comprehensions, which should be removed. </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>PEP accepted, “PEP 448 review”, Guido van Rossum (<a class="reference external" href="https://mail.python.org/pipermail/python-dev/2015-February/138564.html">https://mail.python.org/pipermail/python-dev/2015-February/138564.html</a>)</aside> <aside class="footnote brackets" id="id4" role="doc-footnote"> <dt class="label" id="id4">[<a href="#id2">2</a>]</dt> <dd>Issue 2292, “Missing <code class="docutils literal notranslate">*</code>-unpacking generalizations”, Thomas Wouters (<a class="reference external" href="https://github.com/python/cpython/issues/46545">https://github.com/python/cpython/issues/46545</a>)</aside> </aside> [3] Discussion on Python-ideas list, “list / array comprehensions extension”, Alexander Heger (<a class="reference external" href="https://mail.python.org/pipermail/python-ideas/2011-December/013097.html">https://mail.python.org/pipermail/python-ideas/2011-December/013097.html</a>) </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-0448.rst">https://github.com/python/peps/blob/main/peps/pep-0448.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0448.rst">2023-12-11 18:58:32 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="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a></li> <li><a class="reference internal" href="#disadvantages">Disadvantages</a></li> <li><a class="reference internal" href="#variations">Variations</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-0448.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>