Extensions > API reference > dict

dict

dict is a built-in type representing an associative mapping or dictionary. A dictionary supports indexing using d[k] and key membership testing using k in d; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to d[k] 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.

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")]

There are three ways to construct a dictionary:

  1. A dictionary expression {k: v, ...} 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.

  2. A dictionary comprehension {k: v for vars in seq} 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.

    {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}
    
  3. A call to the built-in dict 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.

clear

None dict.clear()

Remove all items from the dictionary.

get

unknown dict.get(key, default=None)

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

Parameters

Parameter Description
key

The key to look for.

default

The default value to use (instead of None) if the key is not found.

May return None.

items

list dict.items()

Returns the list of key-value tuples:
{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]

keys

list dict.keys()

Returns the list of keys:
{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]

pop

unknown dict.pop(key, default=unbound)

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

Parameters

Parameter Description
key

The key.

default

a default value if the key is absent.

popitem

tuple dict.popitem()

Remove and return an arbitrary (key, value) pair from the dictionary. popitem() is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, calling popitem() fails. It is deterministic which pair is returned.

setdefault

unknown dict.setdefault(key, default=None)

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

Parameters

Parameter Description
key

The key.

default

a default value if the key is absent.

update

None dict.update(args=[], **kwargs)

Update the dictionary with an optional positional argument [pairs] and an optional set of keyword arguments [, name=value[, ...] If the positional argument pairs is present, it must be None, another dict, or some other iterable. If it is another dict, then its key/value pairs are inserted. 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. For each name=value argument present, the name is converted to a string and used as the key for an insertion into D, with its corresponding value being value.

Parameters

Parameter Description
args

Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.

kwargs

Dictionary of additional entries.

values

list dict.values()

Returns the list of values:
{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]