Package eggbasket :: Module odict :: Class OrderedDict
[show private | hide private]
[frames | no frames]

Type OrderedDict

object --+    
         |    
      dict --+
             |
            OrderedDict

Known Subclasses:
SequenceOrderedDict

A class of dictionary that keeps the insertion order of keys.

All appropriate methods return keys, items, or values in an ordered way.

All normal dictionary methods are available. Update and comparison is restricted to other OrderedDict objects.

Various sequence methods are available, including the ability to explicitly mutate the key ordering.

__contains__ tests:

>>> d = OrderedDict(((1, 3),))
>>> 1 in d
1
>>> 4 in d
0

__getitem__ tests:

>>> OrderedDict(((1, 3), (3, 2), (2, 1)))[2]
1
>>> OrderedDict(((1, 3), (3, 2), (2, 1)))[4]
Traceback (most recent call last):
KeyError: 4

__len__ tests:

>>> len(OrderedDict())
0
>>> len(OrderedDict(((1, 3), (3, 2), (2, 1))))
3

get tests:

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.get(1)
3
>>> d.get(4) is None
1
>>> d.get(4, 5)
5
>>> d
OrderedDict([(1, 3), (3, 2), (2, 1)])

has_key tests:

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.has_key(1)
1
>>> d.has_key(4)
0

Method Summary
  __init__(self, init_val, strict)
Create a new ordered dictionary.
  __deepcopy__(self, memo)
To allow deepcopy to work with OrderedDict.
  __delitem__(self, key)
  __eq__(self, other)
  __ge__(self, other)
  __getattr__(self, name)
Implemented so that access to sequence raises a warning.
  __getitem__(self, key)
Allows slicing.
  __gt__(self, other)
  __iter__(self)
  __le__(self, other)
  __lt__(self, other)
  __ne__(self, other)
  __repr__(self)
Used for __repr__ and __str__
  __setattr__(self, name, value)
Implemented so that accesses to sequence raise a warning and are diverted to the new setkeys method.
  __setitem__(self, key, val)
Allows slice assignment, so long as the slice is an OrderedDict >>> d = OrderedDict() >>> d['a'] = 'b' >>> d['b'] = 'a' >>> d[3] = 12 >>> d OrderedDict([('a', 'b'), ('b', 'a'), (3, 12)]) >>> d[:] = OrderedDict(((1, 2), (2, 3), (3, 4))) >>> d OrderedDict([(1, 2), (2, 3), (3, 4)]) >>> d[::2] = OrderedDict(((7, 8), (9, 10))) >>> d OrderedDict([(7, 8), (2, 3), (9, 10)]) >>> d = OrderedDict(((0, 1), (1, 2), (2, 3), (3, 4))) >>> d[1:3] = OrderedDict(((1, 2), (5, 6), (7, 8))) >>> d OrderedDict([(0, 1), (1, 2), (5, 6), (7, 8), (3, 4)]) >>> d = OrderedDict(((0, 1), (1, 2), (2, 3), (3, 4)), strict=True) >>> d[1:3] = OrderedDict(((1, 2), (5, 6), (7, 8))) >>> d OrderedDict([(0, 1), (1, 2), (5, 6), (7, 8), (3, 4)])
  __str__(self)
Used for __repr__ and __str__
  clear(self)
  copy(self)
  index(self, key)
Return the position of the specified key in the OrderedDict.
  insert(self, index, key, value)
Takes index, key, and value as arguments.
  items(self)
items returns a list of tuples representing all the (key, value) pairs in the dictionary.
  iteritems(self)
  iterkeys(self)
  itervalues(self)
  keys(self)
Return a list of keys in the OrderedDict.
  pop(self, key, *args)
No dict.pop in Python 2.2, gotta reimplement it
  popitem(self, i)
Delete and return an item specified by index, not a random one as in dict.
  rename(self, old_key, new_key)
Rename the key for a given value, without modifying sequence order.
  reverse(self)
Reverse the order of the OrderedDict.
  setdefault(self, key, defval)
  setitems(self, items)
This method allows you to set the items in the dict.
  setkeys(self, keys)
setkeys all ows you to pass in a new list of keys which will replace the current set.
  setvalues(self, values)
You can pass in a list of values, which will replace the current list.
  sort(self, *args, **kwargs)
Sort the key order in the OrderedDict.
  update(self, from_od)
Update from another OrderedDict or sequence of (key, value) pairs
  values(self, values)
Return a list of all the values in the OrderedDict.
    Inherited from dict
  __cmp__(x, y)
x.__cmp__(y) <==> cmp(x,y)
  __contains__(D, k)
D.__contains__(k) -> True if D has a key k, else False
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __len__(x)
x.__len__() <==> len(x)
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  get(D, k, d)
D.get(k[,d]) -> D[k] if k in D, else d.
  has_key(D, k)
D.has_key(k) -> True if D has a key k, else False
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
    Inherited from type
  fromkeys(dict, S, v)
v defaults to None.

Method Details

__init__(self, init_val=(), strict=False)
(Constructor)

Create a new ordered dictionary. Cannot init from a normal dict, nor from kwargs, since items order is undefined in those cases.

If the strict keyword argument is True (False is the default) then when doing slice assignment - the OrderedDict you are assigning from must not contain any keys in the remaining dict.

>>> OrderedDict()
OrderedDict([])
>>> OrderedDict({1: 1})
Traceback (most recent call last):
TypeError: undefined order, cannot get items from dict
>>> OrderedDict({1: 1}.items())
OrderedDict([(1, 1)])
>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d
OrderedDict([(1, 3), (3, 2), (2, 1)])
>>> OrderedDict(d)
OrderedDict([(1, 3), (3, 2), (2, 1)])
Overrides:
__builtin__.dict.__init__

__deepcopy__(self, memo)

To allow deepcopy to work with OrderedDict.

>>> from copy import deepcopy
>>> a = OrderedDict([(1, 1), (2, 2), (3, 3)])
>>> a['test'] = {}
>>> b = deepcopy(a)
>>> b == a
True
>>> b is a
False
>>> a['test'] is b['test']
False

__delitem__(self, key)
(Index deletion operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> del d[3]
>>> d
OrderedDict([(1, 3), (2, 1)])
>>> del d[3]
Traceback (most recent call last):
KeyError: 3
>>> d[3] = 2
>>> d
OrderedDict([(1, 3), (2, 1), (3, 2)])
>>> del d[0:1]
>>> d
OrderedDict([(2, 1), (3, 2)])
Overrides:
__builtin__.dict.__delitem__

__eq__(self, other)
(Equality operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d == OrderedDict(d)
True
>>> d == OrderedDict(((1, 3), (2, 1), (3, 2)))
False
>>> d == OrderedDict(((1, 0), (3, 2), (2, 1)))
False
>>> d == OrderedDict(((0, 3), (3, 2), (2, 1)))
False
>>> d == dict(d)
False
>>> d == False
False
Overrides:
__builtin__.dict.__eq__

__ge__(self, other)
(Greater-than-or-equals operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> c = OrderedDict(((0, 3), (3, 2), (2, 1)))
>>> e = OrderedDict(d)
>>> c >= d
False
>>> d >= c
True
>>> d >= dict(c)
Traceback (most recent call last):
TypeError: Can only compare with other OrderedDicts
>>> e >= d
True
Overrides:
__builtin__.dict.__ge__

__getattr__(self, name)
(Qualification operator)

Implemented so that access to sequence raises a warning.

>>> d = OrderedDict()
>>> d.sequence
[]

__getitem__(self, key)
(Indexing operator)

Allows slicing. Returns an OrderedDict if you slice. >>> b = OrderedDict([(7, 0), (6, 1), (5, 2), (4, 3), (3, 4), (2, 5), (1, 6)]) >>> b[::-1] OrderedDict([(1, 6), (2, 5), (3, 4), (4, 3), (5, 2), (6, 1), (7, 0)]) >>> b[2:5] OrderedDict([(5, 2), (4, 3), (3, 4)]) >>> type(b[2:4]) <class '__main__.OrderedDict'>

Overrides:
__builtin__.dict.__getitem__

__gt__(self, other)
(Greater-than operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> c = OrderedDict(((0, 3), (3, 2), (2, 1)))
>>> d > c
True
>>> c > d
False
>>> d > dict(c)
Traceback (most recent call last):
TypeError: Can only compare with other OrderedDicts
Overrides:
__builtin__.dict.__gt__

__iter__(self)

>>> ii = OrderedDict(((1, 3), (3, 2), (2, 1))).iterkeys()
>>> ii.next()
1
>>> ii.next()
3
>>> ii.next()
2
>>> ii.next()
Traceback (most recent call last):
StopIteration
Overrides:
__builtin__.dict.iterkeys

__le__(self, other)
(Less-than-or-equals operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> c = OrderedDict(((0, 3), (3, 2), (2, 1)))
>>> e = OrderedDict(d)
>>> c <= d
True
>>> d <= c
False
>>> d <= dict(c)
Traceback (most recent call last):
TypeError: Can only compare with other OrderedDicts
>>> d <= e
True
Overrides:
__builtin__.dict.__le__

__lt__(self, other)
(Less-than operator)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> c = OrderedDict(((0, 3), (3, 2), (2, 1)))
>>> c < d
True
>>> d < c
False
>>> d < dict(c)
Traceback (most recent call last):
TypeError: Can only compare with other OrderedDicts
Overrides:
__builtin__.dict.__lt__

__ne__(self, other)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d != OrderedDict(d)
False
>>> d != OrderedDict(((1, 3), (2, 1), (3, 2)))
True
>>> d != OrderedDict(((1, 0), (3, 2), (2, 1)))
True
>>> d == OrderedDict(((0, 3), (3, 2), (2, 1)))
False
>>> d != dict(d)
True
>>> d != False
True
Overrides:
__builtin__.dict.__ne__

__repr__(self)
(Representation operator)

Used for __repr__ and __str__

>>> r1 = repr(OrderedDict((('a', 'b'), ('c', 'd'), ('e', 'f'))))
>>> r1
"OrderedDict([('a', 'b'), ('c', 'd'), ('e', 'f')])"
>>> r2 = repr(OrderedDict((('a', 'b'), ('e', 'f'), ('c', 'd'))))
>>> r2
"OrderedDict([('a', 'b'), ('e', 'f'), ('c', 'd')])"
>>> r1 == str(OrderedDict((('a', 'b'), ('c', 'd'), ('e', 'f'))))
True
>>> r2 == str(OrderedDict((('a', 'b'), ('e', 'f'), ('c', 'd'))))
True
Overrides:
__builtin__.dict.__repr__

__setattr__(self, name, value)

Implemented so that accesses to sequence raise a warning and are diverted to the new setkeys method.

Overrides:
__builtin__.object.__setattr__

__setitem__(self, key, val)
(Index assignment operator)

Allows slice assignment, so long as the slice is an OrderedDict >>> d = OrderedDict() >>> d['a'] = 'b' >>> d['b'] = 'a' >>> d[3] = 12 >>> d OrderedDict([('a', 'b'), ('b', 'a'), (3, 12)]) >>> d[:] = OrderedDict(((1, 2), (2, 3), (3, 4))) >>> d OrderedDict([(1, 2), (2, 3), (3, 4)]) >>> d[::2] = OrderedDict(((7, 8), (9, 10))) >>> d OrderedDict([(7, 8), (2, 3), (9, 10)]) >>> d = OrderedDict(((0, 1), (1, 2), (2, 3), (3, 4))) >>> d[1:3] = OrderedDict(((1, 2), (5, 6), (7, 8))) >>> d OrderedDict([(0, 1), (1, 2), (5, 6), (7, 8), (3, 4)]) >>> d = OrderedDict(((0, 1), (1, 2), (2, 3), (3, 4)), strict=True) >>> d[1:3] = OrderedDict(((1, 2), (5, 6), (7, 8))) >>> d OrderedDict([(0, 1), (1, 2), (5, 6), (7, 8), (3, 4)])

>>> a = OrderedDict(((0, 1), (1, 2), (2, 3)), strict=True)
>>> a[3] = 4
>>> a
OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a[::1] = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a
OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a[:2] = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4), (4, 5)])
Traceback (most recent call last):
ValueError: slice assignment must be from unique keys
>>> a = OrderedDict(((0, 1), (1, 2), (2, 3)))
>>> a[3] = 4
>>> a
OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a[::1] = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a
OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a[:2] = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a
OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a[::-1] = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> a
OrderedDict([(3, 4), (2, 3), (1, 2), (0, 1)])
>>> d = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> d[:1] = 3
Traceback (most recent call last):
TypeError: slice assignment requires an OrderedDict
>>> d = OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
>>> d[:1] = OrderedDict([(9, 8)])
>>> d
OrderedDict([(9, 8), (1, 2), (2, 3), (3, 4)])
Overrides:
__builtin__.dict.__setitem__

__str__(self)
(Informal representation operator)

Used for __repr__ and __str__

>>> r1 = repr(OrderedDict((('a', 'b'), ('c', 'd'), ('e', 'f'))))
>>> r1
"OrderedDict([('a', 'b'), ('c', 'd'), ('e', 'f')])"
>>> r2 = repr(OrderedDict((('a', 'b'), ('e', 'f'), ('c', 'd'))))
>>> r2
"OrderedDict([('a', 'b'), ('e', 'f'), ('c', 'd')])"
>>> r1 == str(OrderedDict((('a', 'b'), ('c', 'd'), ('e', 'f'))))
True
>>> r2 == str(OrderedDict((('a', 'b'), ('e', 'f'), ('c', 'd'))))
True
Overrides:
__builtin__.dict.__repr__

clear(self)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.clear()
>>> d
OrderedDict([])
Overrides:
__builtin__.dict.clear

copy(self)

>>> OrderedDict(((1, 3), (3, 2), (2, 1))).copy()
OrderedDict([(1, 3), (3, 2), (2, 1)])
Overrides:
__builtin__.dict.copy

index(self, key)

Return the position of the specified key in the OrderedDict.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.index(3)
1
>>> d.index(4)
Traceback (most recent call last):
ValueError: list.index(x): x not in list

insert(self, index, key, value)

Takes index, key, and value as arguments.

Sets key to value, so that key is at position index in the OrderedDict.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.insert(0, 4, 0)
>>> d
OrderedDict([(4, 0), (1, 3), (3, 2), (2, 1)])
>>> d.insert(0, 2, 1)
>>> d
OrderedDict([(2, 1), (4, 0), (1, 3), (3, 2)])
>>> d.insert(8, 8, 1)
>>> d
OrderedDict([(2, 1), (4, 0), (1, 3), (3, 2), (8, 1)])

items(self)

items returns a list of tuples representing all the (key, value) pairs in the dictionary.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.items()
[(1, 3), (3, 2), (2, 1)]
>>> d.clear()
>>> d.items()
[]
Overrides:
__builtin__.dict.items

iteritems(self)

>>> ii = OrderedDict(((1, 3), (3, 2), (2, 1))).iteritems()
>>> ii.next()
(1, 3)
>>> ii.next()
(3, 2)
>>> ii.next()
(2, 1)
>>> ii.next()
Traceback (most recent call last):
StopIteration
Overrides:
__builtin__.dict.iteritems

iterkeys(self)

>>> ii = OrderedDict(((1, 3), (3, 2), (2, 1))).iterkeys()
>>> ii.next()
1
>>> ii.next()
3
>>> ii.next()
2
>>> ii.next()
Traceback (most recent call last):
StopIteration
Overrides:
__builtin__.dict.iterkeys

itervalues(self)

>>> iv = OrderedDict(((1, 3), (3, 2), (2, 1))).itervalues()
>>> iv.next()
3
>>> iv.next()
2
>>> iv.next()
1
>>> iv.next()
Traceback (most recent call last):
StopIteration
Overrides:
__builtin__.dict.itervalues

keys(self)

Return a list of keys in the OrderedDict.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.keys()
[1, 3, 2]
Overrides:
__builtin__.dict.keys

pop(self, key, *args)

No dict.pop in Python 2.2, gotta reimplement it

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.pop(3)
2
>>> d
OrderedDict([(1, 3), (2, 1)])
>>> d.pop(4)
Traceback (most recent call last):
KeyError: 4
>>> d.pop(4, 0)
0
>>> d.pop(4, 0, 1)
Traceback (most recent call last):
TypeError: pop expected at most 2 arguments, got 3
Overrides:
__builtin__.dict.pop

popitem(self, i=-1)

Delete and return an item specified by index, not a random one as in dict. The index is -1 by default (the last item).

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.popitem()
(2, 1)
>>> d
OrderedDict([(1, 3), (3, 2)])
>>> d.popitem(0)
(1, 3)
>>> OrderedDict().popitem()
Traceback (most recent call last):
KeyError: 'popitem(): dictionary is empty'
>>> d.popitem(2)
Traceback (most recent call last):
IndexError: popitem(): index 2 not valid
Overrides:
__builtin__.dict.popitem

rename(self, old_key, new_key)

Rename the key for a given value, without modifying sequence order.

For the case where new_key already exists this raise an exception, since if new_key exists, it is ambiguous as to what happens to the associated values, and the position of new_key in the sequence.

>>> od = OrderedDict()
>>> od['a'] = 1
>>> od['b'] = 2
>>> od.items()
[('a', 1), ('b', 2)]
>>> od.rename('b', 'c')
>>> od.items()
[('a', 1), ('c', 2)]
>>> od.rename('c', 'a')
Traceback (most recent call last):
ValueError: New key already exists: 'a'
>>> od.rename('d', 'b')
Traceback (most recent call last):
KeyError: 'd'

reverse(self)

Reverse the order of the OrderedDict.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.reverse()
>>> d
OrderedDict([(2, 1), (3, 2), (1, 3)])

setdefault(self, key, defval=None)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.setdefault(1)
3
>>> d.setdefault(4) is None
True
>>> d
OrderedDict([(1, 3), (3, 2), (2, 1), (4, None)])
>>> d.setdefault(5, 0)
0
>>> d
OrderedDict([(1, 3), (3, 2), (2, 1), (4, None), (5, 0)])
Overrides:
__builtin__.dict.setdefault

setitems(self, items)

This method allows you to set the items in the dict.

It takes a list of tuples - of the same sort returned by the items method.

>>> d = OrderedDict()
>>> d.setitems(((3, 1), (2, 3), (1, 2)))
>>> d
OrderedDict([(3, 1), (2, 3), (1, 2)])

setkeys(self, keys)

setkeys all ows you to pass in a new list of keys which will replace the current set. This must contain the same set of keys, but need not be in the same order.

If you pass in new keys that don't match, a KeyError will be raised.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.keys()
[1, 3, 2]
>>> d.setkeys((1, 2, 3))
>>> d
OrderedDict([(1, 3), (2, 1), (3, 2)])
>>> d.setkeys(['a', 'b', 'c'])
Traceback (most recent call last):
KeyError: 'Keylist is not the same as current keylist.'

setvalues(self, values)

You can pass in a list of values, which will replace the current list. The value list must be the same len as the OrderedDict.

(Or a ValueError is raised.)

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.setvalues((1, 2, 3))
>>> d
OrderedDict([(1, 1), (3, 2), (2, 3)])
>>> d.setvalues([6])
Traceback (most recent call last):
ValueError: Value list is not the same length as the OrderedDict.

sort(self, *args, **kwargs)

Sort the key order in the OrderedDict.

This method takes the same arguments as the list.sort method on your version of Python.

>>> d = OrderedDict(((4, 1), (2, 2), (3, 3), (1, 4)))
>>> d.sort()
>>> d
OrderedDict([(1, 4), (2, 2), (3, 3), (4, 1)])

update(self, from_od)

Update from another OrderedDict or sequence of (key, value) pairs

>>> d = OrderedDict(((1, 0), (0, 1)))
>>> d.update(OrderedDict(((1, 3), (3, 2), (2, 1))))
>>> d
OrderedDict([(1, 3), (0, 1), (3, 2), (2, 1)])
>>> d.update({4: 4})
Traceback (most recent call last):
TypeError: undefined order, cannot get items from dict
>>> d.update((4, 4))
Traceback (most recent call last):
TypeError: cannot convert dictionary update sequence element "4" to a 2-item sequence
Overrides:
__builtin__.dict.update

values(self, values=None)

Return a list of all the values in the OrderedDict.

Optionally you can pass in a list of values, which will replace the current list. The value list must be the same len as the OrderedDict.

>>> d = OrderedDict(((1, 3), (3, 2), (2, 1)))
>>> d.values()
[3, 2, 1]
Overrides:
__builtin__.dict.values

Generated by Epydoc 2.1 on Tue Apr 15 17:16:46 2008 http://epydoc.sf.net