API.md

omdict API

Nomenclature

Many of omdict's methods contain the word list or all. list in a method
name indicates that method interacts with a list of values instead of a
single value. all in a method name indicates that method interacts with
the ordered list of all items, including multiple items with the same key.

Here's an example illustrating getlist(key, default=[]), a list method, and
allitems(), an all method.

>>> from orderedmultidict import omdict
>>> omd = omdict([(1,1), (2,2), (1,11)])
>>> omd.items()
[(1, 1), (2, 2)]
>>> omd.allitems()
[(1, 1), (2, 2), (1, 11)]
>>> omd.get(1)
1
>>> omd.getlist(1)
[1, 11]

So list denotes a list of values, and all denotes all items.

Simple.

Method parity with dict

All dict methods behave identically on omdict objects (pop(),
setdefault(), clear(), etc)

Initialization and Updates

omdict objects can be initialized from a dictionary or a list of key:value
items.

>>> omd = omdict()
>>> omd.allitems()
[]
>>> omd = omdict({1:1, 2:2, 3:3})
>>> omd.allitems()
[(1, 1), (2, 2), (3, 3)]
>>> omd = omdict([(1,1), (2,2), (3,3), (1,1)])
>>> omd.allitems()
[(1, 1), (2, 2), (3, 3), (1, 1)]

load(mapping) can be used at any time to reinitialize an omdict.

>>> omd.load({4:4, 5:5})
>>> omd.allitems()
[(4, 4), (5, 5)]
>>> omd = omdict([(1,1), (2,2), (3,3)])
>>> omd.allitems()
[(1, 1), (2, 2), (3, 3)]
>>> omd.load([(6,6), (6,6)])
>>> omd.allitems()
[(6, 6), (6, 6)]

update([mapping]) updates the dictionary with items from mapping, one
item per key like dict.update([mapping]). updateall([mapping]) updates
the dictionary with all items from mapping. Key order is preserved -
existing keys are updated with values from mapping before any new
items are added.

>>> omd = omdict()
>>> omd.update([(1,1), (2,2), (1,11), (2,22)])
>>> omd.items()
[(1, 11), (2, 22)]
>>> omd.allitems()
[(1, 11), (2, 22)]
>>> omd.updateall([(2,'replaced'), (1,'replaced'), (2,'added'), (1,'added')])
>>> omd.allitems()
[(1, 'replaced'), (2, 'replaced'), (2, 'added'), (1, 'added')]

Getters, Setters, and Adders

omd[key] behaves identically to dict[key]. If key has multiple values, only
its first value is returned.

>>> omd = omdict([(1,1), (1,'not me')])
>>> omd[1]
1

omd[key] = value behaves identically to dict[key] = value. If key has
multiple values, they will all be deleted and replaced with value.

>>> omd = omdict([(1,'deleted'), (1,'deleted')])
>>> omd[1] = 1
>>> omd[1]
1

del omd[key] behaves identically to del dict[key]. If key has multiple
values, all of them will be deleted.

>>> omd = omdict([(1,1), (1,11)])
>>> del omd[1]
>>> omd.allitems()
[]

get(key, default=None) behaves identically to
dict.get(key, default=None). If key has multiple values, only its first value
is returned.

>>> omd = omdict([(1,1), (1,2)])
>>> omd.get(1)
1
>>> omd.get(404, 'sup')
'sup'

getlist(key, default=[]) is like get(key, default=None) except it returns the
list of values assocaited with key.

>>> omd = omdict([(1,1), (1,11), (2,2)])
>>> omd.getlist(1)
[1, 11]
>>> omd.getlist(2)
[2]
>>> omd.getlist(404, 'sup')
'sup'

set(key, value=None) sets key's value to value. Identical in function to
omd[key] = value. Returns the omdict object for method chaining.

>>> omd = omdict([(1,1), (1,11), (1,111)])
>>> omd.set(1, 1)
>>> omd.getlist(1)
[1]
>>> omd.set(1, 11).set(2, 2)
>>> omd.allitems()
[(1, 11), (2, 2)]

setlist(key, values=[]) sets key's list of values to values. Returns the
omdict object for method chaining.

>>> omd = omdict([(1,1), (2,2)])
>>> omd.setlist(1, ['replaced', 'appended'])
>>> omd.allitems()
[(1, 'replaced'), (2, 2), (1, 'appended')]
>>> omd.setlist(1, ['onlyme'])
>>> omd.allitems()
[(1, 'onlyme'), (2, 2)]

setdefault(key, default=None) behaves identically to
dict.setdefault(key, default=None).

>>> omd = omdict([(1,1)])
>>> omd.setdefault(1)
1
>>> omd.setdefault(2, None)
>>> omd.allitems()
[(1, 1), (2, None)]

setdefaultlist(key, defaultlist=[None]) is like
setdefault(key, default=None) except a list of values for key is adopted. If
defaultlist isn't provided, key's value becomes None.

>>> omd = omdict([(1,1)])
>>> omd.setdefaultlist(1)
[1]
>>> omd.setdefaultlist(2, [2, 22])
[2, 22]
>>> omd.allitems()
[(1, 1), (2, 2), (2, 22)]
>>> omd.setdefaultlist(3)
[None]
>>> print omd[3]
None

add(key, value=None) adds value to the list of values for key. Returns
the omdict object for method chaining.

>>> omd = omdict()
>>> omd.add(1, 1)
>>> omd.allitems()
[(1, 1)]
>>> omd.add(1, 11).add(2, 2)
>>> omd.allitems()
[(1, 1), (1, 11), (2, 2)]

addlist(key, valuelist=[]) adds the values in valuelist to the list of values
for key. Returns the omdict object for method chaining.

>>> omd = omdict([(1,1)])
>>> omd.addlist(1, [11, 111])
>>> omd.allitems()
[(1, 1), (1, 11), (1, 111)]
>>> omd.addlist(2, [2]).addlist(3, [3, 33])
>>> omd.allitems()
[(1, 1), (1, 11), (1, 111), (2, 2), (3, 3), (3, 33)]

Groups and Group Iteration

items([key]) behaves identically to dict.items() except an optional key
parameter has been added. If key is provided, only items with key key
are returned. iteritems([key]) returns an iterator over items(key). KeyError
is raised if key is provided but not in the dictionary.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.items()
[(1, 1), (2, 2), (3, 3)]
>>> omd.items(1)
[(1, 1), (1, 11), (1, 111)]

keys() behaves identically to dict.keys(). iterkeys() returns an iterator
over keys().

values([key]) behaves identically to dict.values() except an optional key
parameter has been added. If key is provided, only the values for key are
returned. itervalues([key]) returns an iterator over values(key). KeyError
is raised if key is provided but not in the dictionary.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.values()
[1, 2, 3]
>>> omd.values(1)
[1, 11, 111]

lists() returns a list comprised of the lists of values associated with each
dictionary key. iterlists() returns an iterator over lists().

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.lists()
[[1, 11, 111], [2], [3]]

listitems() returns a list of key:valuelist items. iterlistitems() returns an
iterator over listitems().

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3), (2,22)])
>>> omd.listitems()
[(1, [1, 11, 111]), (2, [2, 22]), (3, [3])]

allitems([key]) returns a list of every item in the dictionary, including
multiple items with the same key. If key is provided and in the dictionary,
only items with key key are returned . KeyError is raised if key is
provided and not in the dictionary. iterallitems([key]) returns an iterator
over allitems(key).

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.allitems()
[(1, 1), (1, 11), (1, 111), (2, 2), (3, 3)]

allkeys() returns a list of the keys of every item in the dictionary.
iterallkeys() returns an iterator over allkeys().

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.allkeys()
[1, 1, 1, 2, 3]

allvalues() returns a list of the values of every item in the dictionary.
iterallvalues() returns an iterator over allvalues().

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.allvalues()
[1, 11, 111, 2, 3]

Pops

pop(key[, default]) behaves identically to dict.pop(key[, default]). If key
has multiple values, the first value is returned but all items with key key
are popped. KeyError is raised if default isn't provided and key isn't in
the dictionary.

>>> omd = omdict([(1,1), (2,2), (1,11)])
>>> omd.pop(1)
1
>>> omd.allitems()
[(2, 2)]

poplist(key[, default]) is like pop(key[, default]) except it returns the list of
values for key. KeyError is raised if default isn't provided and key isn't in
the dictionary.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.poplist(1)
[1, 11, 111]
>>> omd.allitems()
[(2, 2), (3, 3)]
>>> omd.poplist(2)
[2]
>>> omd.allitems()
[(3, 3)]
>>> omd.poplist('nonexistent key', 'sup')
'sup'

popvalue(key[, value, default], last=True) pops a value for key.

If value is not provided, the first or last value for key is popped and
returned.

If value is provided, the first or last (key,value) item is popped and value
is returned.

If key no longer has any values after a popvalue() call, key is removed
from the dictionary. default is returned if provided and key isn't in the
dictionary. KeyError is raised if default isn't provided and key isn't in the
dictionary. ValueError is raised if value is provided but isn't a value for
key.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3), (2,22)])
>>> omd.popvalue(1)
111
>>> omd.allitems()
[(1, 1), (1, 11), (2, 2), (3, 3), (2, 22)]
>>> omd.popvalue(1, last=False)
1
>>> omd.allitems()
[(1, 11), (2, 2), (3, 3), (2, 22)]
>>> omd.popvalue(2, 2)
2
>>> omd.allitems()
[(1, 11), (3, 3), (2, 22)]
>>> omd.popvalue(1, 11)
11
>>> omd.allitems()
[(3, 3), (2, 22)]
>>> omd.popvalue('not a key', default='sup')
'sup'

popitem(fromall=False, last=True) pops and returns a key:value item.

If fromall is False, items()[0] is popped if last is False or items()[-1] is
popped if last is True. All remaining items with the same key are
removed.

If fromall is True, allitems()[0] is popped if last is False or allitems()[-1] is
popped if last is True. No other remaining items are removed, even if
they have the same key.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.popitem()
(3, 3)
>>> omd.popitem(fromall=False, last=False)
(1, 1)
>>> omd.popitem(fromall=False, last=False)
(2, 2)
>>> omd.allitems()
[]

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.popitem(fromall=True, last=False)
(1, 1)
>>> omd.popitem(fromall=True, last=False)
(1, 11)
>>> omd.popitem(fromall=True, last=True)
(3, 3)
>>> omd.popitem(fromall=True, last=False)
(1, 111)

poplistitem([key], last=True) pops and returns a key:valuelist item
comprised of a key and that key's list of values. If last is False, a
key:valuelist item comprised of keys()[0] and its list of values is popped
and returned. If last is True, a key:valuelist item comprised of keys()[-1]
and its list of values is popped and returned. KeyError is raised if the
dictionary is empty or if key is provided and not in the dictionary.

>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)])
>>> omd.poplistitem(last=True)
(3, [3])
>>> omd.poplistitem(last=False)
(1, [1, 11, 111])

Miscellaneous

copy() returns a shallow copy of the dictionary.

>>> omd = omdict([(1,1), (1,11), (2,2), (3,3)])
>>> copy = omd.copy()
>>> omd == copy
True
>>> isinstance(copy, omdict)
True

clear() clears all items.

>>> omd = omdict([(1,1), (1,11), (2,2), (3,3)])
>>> omd.clear()
>>> omd.allitems()
[]

len(omd) returns the number of keys in the dictionary, identical to
len(dict).

>>> omd = omdict([(1, 1), (2, 2), (1, 11)])
>>> len(omd)
2

size() returns the total number of items in the dictionary.

>>> omd = omdict([(1, 1), (1, 11), (2, 2), (1, 111)])
>>> omd.size()
4

reverse() reverses the order of all items in the dictionary and returns the
omdict object for method chaining.

>>> omd = omdict([(1, 1), (2, 2), (3, 3)])
>>> omd.allitems()
[(1, 1), (2, 2), (3, 3)]
>>> omd.reverse()
>>> omd.allitems()
[(3, 3), (2, 2), (1, 1)]

fromkeys(keys[, value]) behaves identically to dict.fromkeys(key[, value]).

has_key(key) behaves identically to dict.has_key(key), but use
key in omd instead of omd.has_key(key) where possible.