Next / Previous / Contents / TCC Help System / NM Tech homepage

16.1. Operations on dictionaries

These operations are available on any dictionary object D:

len(D)

Returns the number of key-value pairs in D.

D[k]

If dictionary D has a key whose value is equal to k, this operation returns the corresponding value for that key. If there is no matching key, it raises a KeyError exception.

>>> signals = {0: 'red', 1: 'yellow', 2: 'green'}
>>> signals[2]
'green'
>>> signals[88]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 88

D[k] = v

If dictionary D does not have a key-value pair whose key equals k, a new pair is added with key k and value v.

If D already has a key-value pair whose key equals k, the value of that pair is replaced by v.

k in D

A predicate that tests whether D has a key equal to k.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> 3 in roster
True
>>> 88 in roster
False

k not in D

A predicate that tests whether D does not have a key equal to k.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> 3 not in roster
False
>>> 88 not in roster
True

del D[k]

In Python, del is a statement, not a function; see Section 22.3, “The del statement: Delete a name or part of a value”.

If dictionary D has a key-value pair whose key equals k, that key-value pair is deleted from D. If there is no matching key-value pair, the statement will raise a KeyError exception.

>>> rgb = {'red':'#ff0000', 'green':'#00ff00', 'blue':'#0000ff'}
>>> del rgb['red']
>>> rgb
{'blue': '#0000ff', 'green': '#00ff00'}
>>> del rgb['cerise']
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'cerise'

D.get(k, x)

If dictionary D has a key equal to x, it returns the corresponding value, that is, it is the same as the expression “D[x]”.

However, if D has no key-value pair for key k, this method returns the default value x. The second argument is optional; if omitted, and D has no key equal to k, it returns None.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> roster.get(2)
'Ray'
>>> v = roster.get(8)
>>> print v
None
>>> roster.get(2, 'Not found')
'Ray'
>>> roster.get(8, 'Not found')
'Not found'

D.has_key(k)

A predicate that returns True if D has a key k.

>>> signals = {0: 'red', 1: 'yellow', 2: 'green'}
>>> signals.has_key(1)
True
>>> signals.has_key(88)
False

D.items()

Returns the contents of dictionary D as a list of two-element tuples (k, v), in no particular order.

>>> signals = {0: 'red', 1: 'yellow', 2: 'green'}
>>> signals.items()
[(0, 'red'), (1, 'yellow'), (2, 'green')]

D.iteritems()

Returns an iterator that generates the values from dictionary D as a sequence of two-element tuples (k, v). See Section 24.2, “Iterators: Values that can produce a sequence of values”.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> rosterScan = roster.iteritems()
>>> for n, name in rosterScan:
...     print "{0:04d}: {1}".format(n, name)
... 
0001: Pat
0002: Ray
0003: Min

D.iterkeys()

Returns an iterator that generates the keys from dictionary D. See Section 24.2, “Iterators: Values that can produce a sequence of values”.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> nScan = roster.iterkeys()
>>> for n in nScan:
...     print n,
... 
1 2 3

D.itervalues()

Returns an iterator that generates the values from dictionary D. See Section 24.2, “Iterators: Values that can produce a sequence of values”.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> nameScan = roster.itervalues()
>>> for name in nameScan:
...     print name,
... 
Pat Ray Min

D.keys()

Returns a list of the key values in dictionary D, in no particular order.

>>> signals = {0: 'red', 1: 'yellow', 2: 'green'}
>>> signals.keys()
[1, 0, 2]

D.popitem()

Returns an arbitrary entry from dictionary D as a (key, value) tuple, and also removes that entry. If D is empty, raises a KeyError exception.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> roster.popitem()
(1, 'Pat')
>>> roster
{2: 'Ray', 3: 'Min'}

D.setdefault(k, x)

If dictionary D has a key equal to k, this method returns the corresponding value D[k].

If D has no key equal to k, the method returns the default value x. However, unlike the .get() method, it also creates a new key-value pair (k, x) in D.

As with the .get() method, the second argument is optional, and defaults to the value None.

D.values()

Returns a list of the values from key-value pairs in dictionary D, in no particular order. However, if you call both the .items() and .values() methods of a dictionary without changing that dictionary's contents between those calls, Python guarantees that the ordering of the two results will be the same.

>>> signals = {0: 'red', 1: 'yellow', 2: 'green'}
>>> signals.values()
['yellow', 'red', 'green']
>>> signals.keys()
[1, 0, 2]

D.update(D2)

Merge the contents of dictionary D2 into dictionary D. For any key-value pairs that have the same key in both D and D2, the value for that key in D after this operation will be the value from D2, not the value from D.

>>> roster={1:'Pat', 2:'Ray', 3:'Min'}
>>> newer={3:'Bev', 4:'Wes'}
>>> roster.update(newer)
>>> roster
{1: 'Pat', 4: 'Wes', 2: 'Ray', 3: 'Bev'}
>>> newer
{3: 'Bev', 4: 'Wes'}