Section 4.8. Dictionary Operations

4.8. Dictionary Operations

Python provides a variety of operations applicable to dictionaries. Since dictionaries are containers, the built-in len function can take a dictionary as its single argument and return the number of items (key/value pairs) in the dictionary object. A dictionary is iterable, so you can pass it to any function or method that takes an iterable argument. In this case, only the keys of the dictionary are iterated upon, in some arbitrary order. For example, for any dictionary D, min(D) returns the smallest key in D.

4.8.1. Dictionary Membership

The k in D operator checks whether object k is one of the keys of the dictionary D. It returns true if it is and False if it isn't. k not in D is just like not (k in D).

4.8.2. Indexing a Dictionary

The value in a dictionary D that is currently associated with key k is denoted by an indexing: D[k]. Indexing with a key that is not present in the dictionary raises an exception. For example:

 d = { 'x':42, 'y':3.14, 'z':7 } d['x']                           # 42 d['z']                           # 7 d['a']                           # raises KeyError exception 

Plain assignment to a dictionary indexed with a key that is not yet in the dictionary (e.g., D[newkey]=value) is a valid operation and adds the key and value as a new item in the dictionary. For instance:

 d = { 'x':42, 'y':3.14} d['a'] = 16                      # d is now {'x':42, 'y':3.14,'a':16} 

The del statement, in the form del D[k], removes from the dictionary the item whose key is k. If k is not a key in dictionary D, del D[k] raises an exception.

4.8.3. Dictionary Methods

Dictionary objects provide several methods, as shown in Table 4-5. Nonmutating methods return a result without altering the object to which they apply, while mutating methods may alter the object to which they apply. In Table 4-5, D and D1 indicate any dictionary object, k any hashable object, and x any object.

Table 4-5. Dictionary object methods

Method	Description
Nonmutating methods
D.copy( )	Returns a shallow copy of the dictionary (a copy whose items are the same objects as D's, not copies thereof)
D.has_key(k)	Returns TRue if k is a key in D; otherwise, returns False, just like k in D
D.items( )	Returns a new list with all items (key/value pairs) in D
D.keys( )	Returns a new list with all keys in D
D.values( )	Returns a new list with all values in D
D.iteritems( )	Returns an iterator on all items (key/value pairs) in D
D.iterkeys( )	Returns an iterator on all keys in D
D.itervalues( )	Returns an iterator on all values in D
D.get(k[, x])	Returns D[k] if k is a key in D; otherwise, returns x (or None, if x is not given)
Mutating methods
D.clear( )	Removes all items from D, leaving D empty
D.update(D1)	For each k in D1, sets D[k] equal to D1[k]
D.setdefault(k[, x])	Returns D[k] if k is a key in D; otherwise, sets D[k] equal to x and returns x
D.pop(k[, x])	Removes and returns D[k] if k is a key in D; otherwise, returns x (or raises an exception if x is not given)
D.popitem( )	Removes and returns an arbitrary item (key/value pair)

The items, keys, and values methods return their resulting lists in arbitrary order. If you call more than one of these methods without any intervening change to the dictionary, however, the order of the results is the same for all. The iteritems, iterkeys, and itervalues methods return iterators equivalent to these lists (iterators are discussed in "Iterators" on page 65). An iterator consumes less memory than a list, but you must never modify the set of keys in a dictionary (i.e., you must never add nor remove keys) while iterating on any of that dictionary's iterators. Iterating on the lists returned by items, keys, or values carries no such constraint. Iterating directly on a dictionary D is exactly like iterating on D.iterkeys( ).

The popitem method can be used for destructive iteration on a dictionary. Both items and popitem return dictionary items as key/value pairs, but using popitem consumes less memory, as it does not rely on a separate list of items. The memory savings make the idiom usable for a loop on a huge dictionary, when what you want is to "consume" the dictionary in the course of the loop.

The setdefault method returns the same result as get, but if k is not a key in D, setdefault also has the side effect of binding D[k] to the value x. Similarly, the pop method returns the same result as get, but if k is a key in D, pop also has the side effect of removing D[k] (when x is not specified, and k is not a key in D, get returns None, but pop raises an exception).

In Python 2.4, the update method can also accept an iterable of key/value pairs as an alternative argument instead of a mapping, and can accept keyword arguments instead of or in addition to its only positional argument; the semantics are the same as for passing such arguments when calling the built-in dict type, as covered in "Dictionaries" on page 44.