4.7 Dictionary Operations

Python provides a variety of operations that can be applied 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.

4.7.1 Dictionary Membership

In Python 2.2 and later, the k in D operator tests to see whether object k is one of the keys of the dictionary D. It returns True if it is and False if it isn't. Similarly, the k not in D operator is just like not (k in D).

4.7.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 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 that adds the key and value as a new item in the dictionary. For instance:

d = { 'x':42, 'y':3.14, 'z':7 } 
d['a'] = 16                      # d is now {'x':42,'y':3.14,'z':7,'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.7.3 Dictionary Methods

Dictionary objects provide several methods, as shown in Table 4-4. Non-mutating 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-4, D and D1 indicate any dictionary object, k any valid key in D, and x any object.

Table 4-4. Dictionary object methods

Method	Description
Non-mutating methods
D.copy( )	Returns a (shallow) copy of the dictionary
D.has_key(k)	Returns True if k is a key in D, otherwise returns False
D.items( )	Returns a copy of the list of all items (key/value pairs) in D
D.keys( )	Returns a copy of the list of all keys in D
D.values( )	Returns a copy of the list of 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
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.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, which are new as of Python 2.2, return iterators equivalent to these lists (iterators are discussed later in this chapter). An iterator consumes less memory than a list, but you are not allowed to modify a dictionary while iterating on one of its iterators. Iterating on the list 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, if it's okay to destroy the dictionary in the course of the loop. In Python 2.2 and later, iterating directly on the dictionary (or on iterkeys or iteritems) also consumes modest amounts of memory, and does not destroy the dictionary you're iterating on.

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.