Dive Into Python Python for experienced programmers |

## 1.7. Dictionaries 101

A short digression is in order, because you need to know about dictionaries, tuples, and lists (oh my!). If you're a Perl hacker, you can probably skim the bits about dictionaries and lists, but you should still pay attention to tuples.

One of Python's built-in datatypes is the dictionary, which defines one-to-one relationships between keys and values.

A dictionary in Python is like a hash in Perl. In Perl, variables which store hashes always start with a `%` character; in Python, variables can be named anything, and Python keeps track of the datatype internally.

A dictionary in Python is like an instance of the `Hashtable` class in Java.

A dictionary in Python is like an instance of the `Scripting.Dictionary` object in Visual Basic.

Example 1.10. Defining a dictionary

    >>> d = {"server":"mpilgrim", "database":"master"}
    >>> d
    {'server': 'mpilgrim', 'database': 'master'}
    >>> d["server"]
    'mpilgrim'
    >>> d["database"]
    'master'
    >>> d["mpilgrim"]
    Traceback (innermost last):
      File "<interactive input>", line 1, in ?
    KeyError: mpilgrim

| First, we create a new dictionary with two elements and assign it to the variable `d`. Each element is a key-value pair, and the whole set of elements is enclosed in curly braces.
| `'server'` is a key, and its associated value, referenced by `d["server"]`, is `'mpilgrim'`.
| `'database'` is a key, and its associated value, referenced by `d["database"]`, is `'master'`.
| You can get values by key, but you can't get keys by value. So `d["server"]` is `'mpilgrim'`, but `d["mpilgrim"]` raises an exception, because `'mpilgrim'` is not a key.

Example 1.11. Modifying a dictionary

    >>> d
    {'server': 'mpilgrim', 'database': 'master'}
    >>> d["database"] = "pubs"
    >>> d
    {'server': 'mpilgrim', 'database': 'pubs'}
    >>> d["uid"] = "sa"
    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'pubs'}

| You can not have duplicate keys in a dictionary. Assigning a value to an existing key will wipe out the old value.
| You can add new key-value pairs at any time. This syntax is identical to modifying existing values. (Yes, this will annoy you someday when you think you are adding new values but are actually just modifying the same value over and over because your key isn't changing the way you think it is.)

Note that the new element (key `'uid'`, value `'sa'`) appears to be in the middle. In fact, it was just a coincidence that the elements appeared to be in order in the first example; it is just as much a coincidence that they appear to be out of order now.

Dictionaries have no concept of order among elements. It is incorrect to say that the elements are “out of order”; they are simply unordered. This is an important distinction which will annoy you when you want to access the elements of a dictionary in a specific, repeatable order (like alphabetical order by key). There are ways of doing this, they're just not built into the dictionary.

Example 1.12. Mixing datatypes in a dictionary

    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'pubs'}
    >>> d["retrycount"] = 3
    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'master', 'retrycount': 3}
    >>> d[42] = "douglas"
    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'master', 42: 'douglas', 'retrycount': 3}

| Dictionaries aren't just for strings. Dictionary values can be any datatype, including strings, integers, objects, or even other dictionaries. And within a single dictionary, the values don't all have to be the same type; you can mix and match as needed.
| Dictionary keys are more restricted, but they can be strings, integers, and a few other types (more on this later). You can also mix and match key datatypes within a dictionary.

Example 1.13. Deleting items from a dictionary

    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'master', 42: 'douglas', 'retrycount': 3}
    >>> del d[42]
    >>> d
    {'server': 'mpilgrim', 'uid': 'sa', 'database': 'master', 'retrycount': 3}
    >>> d.clear()
    >>> d
    {}

| `del` lets you delete individual items from a dictionary by key.
| `clear` deletes all items from a dictionary. Note that the set of empty curly braces signifies a dictionary with no items.

Example 1.14. Strings are case-sensitive

    >>> d = {}
    >>> d["key"] = "value"
    >>> d["key"] = "other value"
    >>> d
    {'key': 'other value'}
    >>> d["Key"] = "third value"
    >>> d
    {'Key': 'third value', 'key': 'other value'}

| Assigning a value to an existing dictionary key simply replaces the old value with a new one.
| This is not assigning a value to an existing dictionary key, because strings in Python are case-sensitive, so `'key'` is not the same as `'Key'`. This creates a new key/value pair in the dictionary; it may look similar to you, but as far as Python is concerned, it's completely different.

Further reading

- How to Think Like a Computer Scientist teaches about dictionaries and shows how to use dictionaries to model sparse matrices.
- Python Knowledge Base has lots of example code using dictionaries.
- Python Cookbook discusses how to sort the values of a dictionary by key.
- Python Library Reference summarizes all the dictionary methods.