3.8 Mapping Types -- dict

#
3.8 Mapping Types -- `dict`

A mapping object maps immutable values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping type, the dictionary. A dictionary's keys are almost arbitrary values. Only values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys. Numeric types used for keys obey the normal rules for numeric comparison: if two numbers compare equal (such as `1` and `1.0`) then they can be used interchangeably to index the same dictionary entry.

Dictionaries are created by placing a comma-separated list of `key: value` pairs within braces, for example: `{'jack': 4098, 'sjoerd': 4127}` or `{4098: 'jack', 4127: 'sjoerd'}`.

The following operations are defined on mappings (where a and b are mappings, k is a key, and v and x are arbitrary objects):

Operation | Result | Notes
--- | --- | ---
`len(a)` | the number of items in a |
`a[k]` | the item of a with key k | (1), (10)
`a[k] = v` | set `a[k]` to v |
`del a[k]` | remove `a[k]` from a | (1)
`a.clear()` | remove all items from `a` |
`a.copy()` | a (shallow) copy of `a` |
`k in a` | `True` if a has a key k, else `False` | (2)
`k not in a` | Equivalent to `not` k in a | (2)
`a.has_key(k)` | Equivalent to k `in` a, use that form in new code |
`a.items()` | a copy of a's list of (key, value) pairs | (3)
`a.keys()` | a copy of a's list of keys | (3)
`a.update([b])` | updates a with key/value pairs from b, overwriting existing keys, returns `None` | (9)
`a.fromkeys(seq[, value])` | Creates a new dictionary with keys from seq and values set to value | (7)
`a.values()` | a copy of a's list of values | (3)
`a.get(k[, x])` | `a[k]` if `k in a`, else x | (4)
`a.setdefault(k[, x])` | `a[k]` if `k in a`, else x (also setting it) | (5)
`a.pop(k[, x])` | `a[k]` if `k in a`, else x (and remove k) | (8)
`a.popitem()` | remove and return an arbitrary (key, value) pair | (6)
`a.iteritems()` | return an iterator over (key, value) pairs | (2), (3)
`a.iterkeys()` | return an iterator over the mapping's keys | (2), (3)
`a.itervalues()` | return an iterator over the mapping's values | (2), (3)

Notes:

(1)
  Raises a `KeyError` exception if k is not in the map.

(2)
  New in version 2.2.

(3)
  Keys and values are listed in an arbitrary order which is non-random, varies across Python implementations, and depends on the dictionary's history of insertions and deletions. If `items()`, `keys()`, `values()`, `iteritems()`, `iterkeys()`, and `itervalues()` are called with no intervening modifications to the dictionary, the lists will directly correspond. This allows the creation of `(value, key)` pairs using `zip()`: "`pairs = zip(a.values(), a.keys())`". The same relationship holds for the `iterkeys()` and `itervalues()` methods: "`pairs = zip(a.itervalues(), a.iterkeys())`" provides the same value for `pairs`. Another way to create the same list is "`pairs = [(v, k) for (k, v) in a.iteritems()]`".

(4)
  Never raises an exception if k is not in the map, instead it returns x. x is optional; when x is not provided and k is not in the map, `None` is returned.

(5)
  `setdefault()` is like `get()`, except that if k is missing, x is both returned and inserted into the dictionary as the value of k. x defaults to `None`.

(6)
  `popitem()` is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, calling `popitem()` raises a `KeyError`.

(7)
  `fromkeys()` is a class method that returns a new dictionary. value defaults to `None`. New in version 2.3.

(8)
  `pop()` raises a `KeyError` when no default value is given and the key is not found. New in version 2.3.

(9)
  `update()` accepts either another mapping object or an iterable of key/value pairs (as a tuple or other iterable of length two). If keyword arguments are specified, the mapping is then is updated with those key/value pairs: "`d.update(red=1, blue=2)`". Changed in version 2.4: Allowed the argument to be an iterable of key/value pairs and allowed keyword arguments.

(10)
  If a subclass of dict defines a method `__missing__`, if the key k is not present, the a[k] operation calls that method with the key k as argument. The a[k] operation then returns or raises whatever is returned or raised by the `__missing__`(k) call if the key is not present. No other operations or methods invoke `__missing__`(). If `__missing__` is not defined, `KeyError` is raised. `__missing__` must be a method; it cannot be an instance variable. For an example, see `collections`.`defaultdict`. New in version 2.5.