Section 7.4. Mapping Type Built-in Methods

7.4. Mapping Type Built-in Methods

Dictionaries have an abundance of methods to help you get the job done, as indicated in Table 7.2.

Table 7.2. Dictionary Type Methods

Method Name	Operation
dict.clear[a] ()	Removes all elements of dict
dict.clear[a] ()	Returns a (shallow[b]) copy of dict
dict.fromkeys[c] (seq, val=None)	Creates and returns a new dictionary with the elements of seq as the keys and val as the initial value (defaults to None if not given) for all keys
dict.get(key, default=None)[a]	For key key, returns value or default if key not in dict (note that default's default is None)
dict.has_key (key)	Returns TRue if key is in dict, False otherwise; partially deprecated by the in and not in operators in 2.2 but still provides a functional interface
dict.items()	Returns a list of the (key, value) tuple pairs of dict
dict.keys()	Returns a list of the keys of dict
dict.iter *[d] ()	iteritems(), iterkeys(), itervalues() are all methods that behave the same as their non-iterator counterparts but return an iterator instead of a list
dict.pop[c](key [, default])	Similar to get() but removes and returns dict[key] if key present and raises KeyError if key not in dict and default not given
dict.setdefault (key, default=None)[e]	Similar to get(), but sets dict[key]=default if key is not already in dict
dict.update(dict2)[a]	Add the key-value pairs of dict2 to dict
dict.values()	Returns a list of the values of dict

^[a] New in Python 1.5.

^[b] More information regarding shallow and deep copies can be found in Section 6.19.

^[c] New in Python 2.3.

^[d] New in Python 2.2.

^[e] New in Python 2.0.

Below, we showcase some of the more common dictionary methods. We have already seen has_key() and its replacements in and not in at work above. Attempting to access a nonexistent key will result in an exception (KeyError) as we saw in Section 7.1.

Basic dictionary methods focus on their keys and values. These are keys(), which returns a list of the dictionary's keys, values(), which returns a list of the dictionary's values, and items(), which returns a list of (key, value) tuple pairs. These are useful when you wish to iterate through a dictionary's keys or values, albeit in no particular order.

>>> dict2.keys() ['port', 'name'] >>> >>> dict2.values() [80, 'earth'] >>> >>> dict2.items() [('port', 80), ('name', 'earth')] >>> >>> for eachKey in dict2.keys(): ... print 'dict2 key', eachKey, 'has value', dict2[eachKey] ... dict2 key port has value 80 dict2 key name has value earth

The keys() method is fairly useful when used in conjunction with a for loop to retrieve a dictionary's values as it returns a list of a dictionary's keys. However, because its items (as with any keys of a hash table) are unordered, imposing some type of order is usually desired.

In Python versions prior to 2.4, you would have to call a dictionary's keys() method to get the list of its keys, then call that list's sort() method to get a sorted list to iterate over. Now a built-in function named sorted(), made especially for iterators, exists, which returns a sorted iterator:

>>> for eachKey in sorted(dict2): ...     print 'dict2 key', eachKey, 'has value', dict2[eachKey] ... dict2 key name has value earth dict2 key port has value 80

The update() method can be used to add the contents of one directory to another. Any existing entries with duplicate keys will be overridden by the new incoming entries. Nonexistent ones will be added. All entries in a dictionary can be removed with the clear() method.

>>> dict2= {'host':'earth', 'port':80} >>> dict3= {'host':'venus', 'server':'http'} >>> dict2.update(dict3) >>> dict2 {'server': 'http', 'port': 80, 'host': 'venus'} >>> dict3.clear() >>> dict3 {}

The copy() method simply returns a copy of a dictionary. Note that this is a shallow copy only. Again, see Section 6.19 regarding shallow and deep copies. Finally, the get() method is similar to using the key-lookup operator ( [ ] ), but allows you to provide a default value returned if a key does not exist. If a key does not exist and a default value is not given, then None is returned. This is a more flexible option than just using key-lookup because you do not have to worry about an exception being raised if a key does not exist.

>>> dict4 = dict2.copy() >>> dict4 {'server': 'http', 'port': 80, 'host': 'venus'} >>> dict4.get('host') 'venus' >>> dict4.get('xxx') >>> type(dict4.get('xxx')) <type 'None'> >>> dict4.get('xxx', 'no such key') 'no such key'

The built-in method, setdefault(), added in version 2.0, has the sole purpose of making code shorter by collapsing a common idiom: you want to check if a dictionary has a key. If it does, you want its value. If the dictionary does not have the key you are seeking, you want to set a default value and then return it. That is precisely what setdefault() does:

>>> myDict = {'host': 'earth', 'port': 80} >>> myDict.keys() ['host', 'port'] >>> myDict.items() [('host', 'earth'), ('port', 80)] >>> myDict.setdefault('port', 8080) 80 >>> myDict.setdefault('prot', 'tcp') 'tcp' >>> myDict.items() [('prot', 'tcp'), ('host', 'earth'), ('port', 80)]

Earlier, we took a brief look at the fromkeys() method, but here are a few more examples:

>>> {}.fromkeys('xyz') {'y': None, 'x': None, 'z': None} >>> >>> {}.fromkeys(('love', 'honor'), True) {'love': True, 'honor': True}

Currently, the keys(), items(), and values() methods return lists. This can be unwieldy if such data collections are large, and the main reason why iteritems(), iterkeys(), and itervalues() were added to Python in 2.2. They function just like their list counterparts only they return iterators, which by lazier evaluation, are more memory-friendly. In future versions of Python, even more flexible and powerful objects will be returned, tentatively called views. Views are collection interfaces which give you access to container objects. For example, you may be able to delete a key from a view, which would then alter the corresponding dictionary accordingly.