<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/6.4.0/_book.yaml">
</head>
<body>

<h1 class="page-title" id="modules.dict">dict</h1>

<!-- {% raw %} -->

dict is a built-in type representing an associative mapping or <i>dictionary</i>. A dictionary supports indexing using <code>d[k]</code> and key membership testing using <code>k in d</code>; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key.
<pre>d = {0: 0, 2: 2, 1: 1}
[k for k in d]  # [0, 2, 1]
d.pop(2)
d[0], d[2] = "a", "b"
0 in d, "a" in d  # (True, False)
[(k, v) for k, v in d.items()]  # [(0, "a"), (1, 1), (2, "b")]
</pre>
<p>There are four ways to construct a dictionary:
<ol>
<li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.
<li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value.
<pre class="language-python">
{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))}  # {"a": 2, "b": 1}
{i: 2*i for i in range(3)}  # {0: 0, 1: 2, 2: 4}
</pre>
<li>A call to the built-in <a href="globals.html#dict">dict</a> function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.
<li>The union expression <code>x | y</code> yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key <code>k</code> in common, the right hand side dictionary's value of the key (in other words, <code>y[k]</code>) wins. The <code>|=</code> variant of the union operator modifies a dictionary in-place. Example:<br><pre class=language-python>d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"}
# d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"}
d = {"a": 1, "b": 2}
d |= {"b": 3, "c": 4}
# d == {"a": 1, "b": 3, "c": 4}</pre></ol>

<h2>Members</h2>
<ul>
    <li>
    <a href="#clear">clear</a>
  </li>
      <li>
    <a href="#get">get</a>
  </li>
      <li>
    <a href="#items">items</a>
  </li>
      <li>
    <a href="#keys">keys</a>
  </li>
      <li>
    <a href="#pop">pop</a>
  </li>
      <li>
    <a href="#popitem">popitem</a>
  </li>
      <li>
    <a href="#setdefault">setdefault</a>
  </li>
      <li>
    <a href="#update">update</a>
  </li>
      <li>
    <a href="#values">values</a>
  </li>
  </ul>

      <h2 id="clear">clear</h2>
        <p><pre class="rule-signature"><a class="anchor" href="globals.html#None">None</a> dict.clear()</pre></p>

    Remove all items from the dictionary.


        <h2 id="get">get</h2>
        <p><pre class="rule-signature">unknown dict.get(key, default=None)</pre></p>

    Returns the value for <code>key</code> if <code>key</code> is in the dictionary, else <code>default</code>. If <code>default</code> is not given, it defaults to <code>None</code>, so that this method never throws an error.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="get.key">
              <code>key</code>
            </td>
            <td>
                                     required<br/>
                          The key to look for.
            </td>
          </tr>
                  <tr>
            <td id="get.default">
              <code>default</code>
            </td>
            <td>
                                     default = None<br/>
                          The default value to use (instead of None) if the key is not found.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="items">items</h2>
        <p><pre class="rule-signature"><a class="anchor" href="list.html">list</a> dict.items()</pre></p>

    Returns the list of key-value tuples:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]</pre>



        <h2 id="keys">keys</h2>
        <p><pre class="rule-signature"><a class="anchor" href="list.html">list</a> dict.keys()</pre></p>

    Returns the list of keys:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]</pre>



        <h2 id="pop">pop</h2>
        <p><pre class="rule-signature">unknown dict.pop(key, default=unbound)</pre></p>

    Removes a <code>key</code> from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified <code>default</code> value; if no default value was specified, fail instead.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="pop.key">
              <code>key</code>
            </td>
            <td>
                                     required<br/>
                          The key.
            </td>
          </tr>
                  <tr>
            <td id="pop.default">
              <code>default</code>
            </td>
            <td>
                                     default = unbound<br/>
                          a default value if the key is absent.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="popitem">popitem</h2>
        <p><pre class="rule-signature"><a class="anchor" href="tuple.html">tuple</a> dict.popitem()</pre></p>

    Remove and return the first <code>(key, value)</code> pair from the dictionary. <code>popitem</code> is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the <code>popitem</code> call fails.


        <h2 id="setdefault">setdefault</h2>
        <p><pre class="rule-signature">unknown dict.setdefault(key, default=None)</pre></p>

    If <code>key</code> is in the dictionary, return its value. If not, insert key with a value of <code>default</code> and return <code>default</code>. <code>default</code> defaults to <code>None</code>.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="setdefault.key">
              <code>key</code>
            </td>
            <td>
                                     required<br/>
                          The key.
            </td>
          </tr>
                  <tr>
            <td id="setdefault.default">
              <code>default</code>
            </td>
            <td>
                                     default = None<br/>
                          a default value if the key is absent.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="update">update</h2>
        <p><pre class="rule-signature"><a class="anchor" href="globals.html#None">None</a> dict.update(pairs=[], **kwargs)</pre></p>

    Updates the dictionary first with the optional positional argument, <code>pairs</code>,  then with the optional keyword arguments
If the positional argument is present, it must be a dict, iterable, or None.
If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted.
Each keyword argument <code>name=value</code> causes the name/value pair to be inserted into this dict.

          <!-- hide-from-toc is a class used by DevSite for the public Bazel site
      (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
      <h3 class="hide-from-toc">Parameters</h3>
      <table class="table table-bordered table-condensed table-params">
        <colgroup>
          <col class="col-param">
          <col class="param-description">
        </colgroup>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
                  <tr>
            <td id="update.pairs">
              <code>pairs</code>
            </td>
            <td>
                                     default = []<br/>
                          Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.
            </td>
          </tr>
                  <tr>
            <td id="update.kwargs">
              <code>kwargs</code>
            </td>
            <td>
                                     required<br/>
                          Dictionary of additional entries.
            </td>
          </tr>
                </tbody>
      </table>

        <h2 id="values">values</h2>
        <p><pre class="rule-signature"><a class="anchor" href="list.html">list</a> dict.values()</pre></p>

    Returns the list of values:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]</pre>




</body>
</html>

<!-- {% endraw %} -->
