1# omdict API 2 3### Nomenclature 4 5Many of omdict's methods contain the word __list__ or __all__. __list__ in a method\ 6name indicates that method interacts with a list of values instead of a\ 7single value. __all__ in a method name indicates that method interacts with\ 8the ordered list of all items, including multiple items with the same key. 9 10Here's an example illustrating __getlist(key, default=[])__, a __list__ method, and\ 11__allitems()__, an __all__ method. 12 13```python 14>>> from orderedmultidict import omdict 15>>> omd = omdict([(1,1), (2,2), (1,11)]) 16>>> omd.items() 17[(1, 1), (2, 2)] 18>>> omd.allitems() 19[(1, 1), (2, 2), (1, 11)] 20>>> omd.get(1) 211 22>>> omd.getlist(1) 23[1, 11] 24``` 25 26So __list__ denotes a list of values, and __all__ denotes all items. 27 28Simple. 29 30 31### Method parity with dict 32 33All [dict](http://docs.python.org/library/stdtypes.html#dict) methods behave identically on omdict objects (__pop()__,\ 34__setdefault()__, __clear()__, etc) 35 36 37### Initialization and Updates 38 39omdict objects can be initialized from a dictionary or a list of key:value\ 40items. 41 42```python 43>>> omd = omdict() 44>>> omd.allitems() 45[] 46>>> omd = omdict({1:1, 2:2, 3:3}) 47>>> omd.allitems() 48[(1, 1), (2, 2), (3, 3)] 49>>> omd = omdict([(1,1), (2,2), (3,3), (1,1)]) 50>>> omd.allitems() 51[(1, 1), (2, 2), (3, 3), (1, 1)] 52``` 53 54__load(mapping)__ can be used at any time to reinitialize an omdict. 55 56```python 57>>> omd.load({4:4, 5:5}) 58>>> omd.allitems() 59[(4, 4), (5, 5)] 60>>> omd = omdict([(1,1), (2,2), (3,3)]) 61>>> omd.allitems() 62[(1, 1), (2, 2), (3, 3)] 63>>> omd.load([(6,6), (6,6)]) 64>>> omd.allitems() 65[(6, 6), (6, 6)] 66``` 67 68__update([mapping])__ updates the dictionary with items from __mapping__, one\ 69item per key like [dict.update([mapping])](http://docs.python.org/library/stdtypes.html#dict.update). __updateall([mapping])__ updates\ 70the dictionary with all items from __mapping__. Key order is preserved -\ 71existing keys are updated with values from __mapping__ before any new\ 72items are added. 73 74```python 75>>> omd = omdict() 76>>> omd.update([(1,1), (2,2), (1,11), (2,22)]) 77>>> omd.items() 78[(1, 11), (2, 22)] 79>>> omd.allitems() 80[(1, 11), (2, 22)] 81>>> omd.updateall([(2,'replaced'), (1,'replaced'), (2,'added'), (1,'added')]) 82>>> omd.allitems() 83[(1, 'replaced'), (2, 'replaced'), (2, 'added'), (1, 'added')] 84``` 85 86 87### Getters, Setters, and Adders 88 89__omd[key]__ behaves identically to [dict[key]](http://docs.python.org/library/stdtypes.html#dict). If __key__ has multiple values, only\ 90its first value is returned. 91 92```python 93>>> omd = omdict([(1,1), (1,'not me')]) 94>>> omd[1] 951 96``` 97 98__omd[key] = value__ behaves identically to [dict[key] = 99value](http://docs.python.org/library/stdtypes.html#dict). If __key__ has\ 100multiple values, they will all be deleted and replaced with __value__. 101 102```python 103>>> omd = omdict([(1,'deleted'), (1,'deleted')]) 104>>> omd[1] = 1 105>>> omd[1] 1061 107``` 108 109__del omd[key]__ behaves identically to [del 110dict[key]](http://docs.python.org/library/stdtypes.html#dict). If __key__ has multiple\ 111values, all of them will be deleted. 112 113```python 114>>> omd = omdict([(1,1), (1,11)]) 115>>> del omd[1] 116>>> omd.allitems() 117[] 118``` 119 120__get(key, default=None)__ behaves identically to\ 121[dict.get(key, 122default=None)](http://docs.python.org/library/stdtypes.html#dict.get). If __key__ has multiple values, only its first value\ 123is returned. 124 125```python 126>>> omd = omdict([(1,1), (1,2)]) 127>>> omd.get(1) 1281 129>>> omd.get(404, 'sup') 130'sup' 131``` 132 133__getlist(key, default=[])__ is like __get(key, default=None)__ except it returns the\ 134list of values assocaited with __key__. 135 136```python 137>>> omd = omdict([(1,1), (1,11), (2,2)]) 138>>> omd.getlist(1) 139[1, 11] 140>>> omd.getlist(2) 141[2] 142>>> omd.getlist(404, 'sup') 143'sup' 144``` 145 146__set(key, value=None)__ sets __key__'s value to __value__. Identical in function to\ 147`omd[key] = value`. Returns the omdict object for method chaining. 148 149```python 150>>> omd = omdict([(1,1), (1,11), (1,111)]) 151>>> omd.set(1, 1) 152>>> omd.getlist(1) 153[1] 154>>> omd.set(1, 11).set(2, 2) 155>>> omd.allitems() 156[(1, 11), (2, 2)] 157``` 158 159__setlist(key, values=[])__ sets __key__'s list of values to __values__. Returns the\ 160omdict object for method chaining. 161 162```python 163>>> omd = omdict([(1,1), (2,2)]) 164>>> omd.setlist(1, ['replaced', 'appended']) 165>>> omd.allitems() 166[(1, 'replaced'), (2, 2), (1, 'appended')] 167>>> omd.setlist(1, ['onlyme']) 168>>> omd.allitems() 169[(1, 'onlyme'), (2, 2)] 170``` 171 172__setdefault(key, default=None)__ behaves identically to\ 173[dict.setdefault(key, 174default=None)](http://docs.python.org/library/stdtypes.html#dict.setdefault). 175 176```python 177>>> omd = omdict([(1,1)]) 178>>> omd.setdefault(1) 1791 180>>> omd.setdefault(2, None) 181>>> omd.allitems() 182[(1, 1), (2, None)] 183``` 184 185__setdefaultlist(key, defaultlist=[None])__ is like\ 186__setdefault(key, default=None)__ except a list of values for __key__ is adopted. If\ 187__defaultlist__ isn't provided, __key__'s value becomes None. 188 189```python 190>>> omd = omdict([(1,1)]) 191>>> omd.setdefaultlist(1) 192[1] 193>>> omd.setdefaultlist(2, [2, 22]) 194[2, 22] 195>>> omd.allitems() 196[(1, 1), (2, 2), (2, 22)] 197>>> omd.setdefaultlist(3) 198[None] 199>>> print omd[3] 200None 201``` 202 203__add(key, value=None)__ adds __value__ to the list of values for __key__. Returns\ 204the omdict object for method chaining. 205 206```python 207>>> omd = omdict() 208>>> omd.add(1, 1) 209>>> omd.allitems() 210[(1, 1)] 211>>> omd.add(1, 11).add(2, 2) 212>>> omd.allitems() 213[(1, 1), (1, 11), (2, 2)] 214``` 215 216__addlist(key, valuelist=[])__ adds the values in __valuelist__ to the list of values\ 217for __key__. Returns the omdict object for method chaining. 218 219```python 220>>> omd = omdict([(1,1)]) 221>>> omd.addlist(1, [11, 111]) 222>>> omd.allitems() 223[(1, 1), (1, 11), (1, 111)] 224>>> omd.addlist(2, [2]).addlist(3, [3, 33]) 225>>> omd.allitems() 226[(1, 1), (1, 11), (1, 111), (2, 2), (3, 3), (3, 33)] 227``` 228 229 230### Groups and Group Iteration 231 232__items([key])__ behaves identically to [dict.items()](http://docs.python.org/library/stdtypes.html#dict.items) except an optional __key__\ 233parameter has been added. If __key__ is provided, only items with key __key__\ 234are returned. __iteritems([key])__ returns an iterator over `items(key)`. KeyError\ 235is raised if __key__ is provided but not in the dictionary. 236 237```python 238>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 239>>> omd.items() 240[(1, 1), (2, 2), (3, 3)] 241>>> omd.items(1) 242[(1, 1), (1, 11), (1, 111)] 243``` 244 245__keys()__ behaves identically to [dict.keys()](http://docs.python.org/library/stdtypes.html#dict.keys). __iterkeys()__ returns an iterator\ 246over keys(). 247 248__values([key])__ behaves identically to [dict.values()](http://docs.python.org/library/stdtypes.html#dict.values) except an optional __key__\ 249parameter has been added. If __key__ is provided, only the values for __key__ are\ 250returned. __itervalues([key])__ returns an iterator over `values(key)`. KeyError\ 251is raised if __key__ is provided but not in the dictionary. 252 253```python 254>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 255>>> omd.values() 256[1, 2, 3] 257>>> omd.values(1) 258[1, 11, 111] 259``` 260 261__lists()__ returns a list comprised of the lists of values associated with each\ 262dictionary key. __iterlists()__ returns an iterator over __lists()__. 263 264```python 265>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 266>>> omd.lists() 267[[1, 11, 111], [2], [3]] 268``` 269 270__listitems()__ returns a list of key:valuelist items. __iterlistitems()__ returns an\ 271iterator over __listitems()__. 272 273```python 274>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3), (2,22)]) 275>>> omd.listitems() 276[(1, [1, 11, 111]), (2, [2, 22]), (3, [3])] 277``` 278 279__allitems([key])__ returns a list of every item in the dictionary, including\ 280multiple items with the same key. If __key__ is provided and in the dictionary,\ 281only items with key __key__ are returned . KeyError is raised if __key__ is\ 282provided and not in the dictionary. __iterallitems([key])__ returns an iterator\ 283over __allitems(key)__. 284 285```python 286>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 287>>> omd.allitems() 288[(1, 1), (1, 11), (1, 111), (2, 2), (3, 3)] 289``` 290 291__allkeys()__ returns a list of the keys of every item in the dictionary.\ 292__iterallkeys()__ returns an iterator over __allkeys()__. 293 294```python 295>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 296>>> omd.allkeys() 297[1, 1, 1, 2, 3] 298``` 299 300__allvalues()__ returns a list of the values of every item in the dictionary.\ 301__iterallvalues()__ returns an iterator over __allvalues()__. 302 303```python 304>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 305>>> omd.allvalues() 306[1, 11, 111, 2, 3] 307``` 308 309 310### Pops 311 312__pop(key[, default])__ behaves identically to [dict.pop(key[, 313default])](http://docs.python.org/library/stdtypes.html#dict.pop). If __key__\ 314has multiple values, the first value is returned but all items with key __key__\ 315are popped. KeyError is raised if __default__ isn't provided and __key__ isn't in\ 316the dictionary. 317 318```python 319>>> omd = omdict([(1,1), (2,2), (1,11)]) 320>>> omd.pop(1) 3211 322>>> omd.allitems() 323[(2, 2)] 324``` 325 326__poplist(key[, default])__ is like `pop(key[, default])` except it returns the list of\ 327values for __key__. KeyError is raised if __default__ isn't provided and __key__ isn't in\ 328the dictionary. 329 330```python 331>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 332>>> omd.poplist(1) 333[1, 11, 111] 334>>> omd.allitems() 335[(2, 2), (3, 3)] 336>>> omd.poplist(2) 337[2] 338>>> omd.allitems() 339[(3, 3)] 340>>> omd.poplist('nonexistent key', 'sup') 341'sup' 342``` 343 344__popvalue(key[, value, default], last=True)__ pops a value for __key__. 345 346If __value__ is not provided, the first or last value for __key__ is popped and\ 347returned. 348 349If __value__ is provided, the first or last (__key__,__value__) item is popped and __value__\ 350is returned. 351 352If __key__ no longer has any values after a __popvalue()__ call, __key__ is removed\ 353from the dictionary. __default__ is returned if provided and __key__ isn't in the\ 354dictionary. KeyError is raised if __default__ isn't provided and __key__ isn't in the\ 355dictionary. ValueError is raised if __value__ is provided but isn't a value for\ 356__key__. 357 358```python 359>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3), (2,22)]) 360>>> omd.popvalue(1) 361111 362>>> omd.allitems() 363[(1, 1), (1, 11), (2, 2), (3, 3), (2, 22)] 364>>> omd.popvalue(1, last=False) 3651 366>>> omd.allitems() 367[(1, 11), (2, 2), (3, 3), (2, 22)] 368>>> omd.popvalue(2, 2) 3692 370>>> omd.allitems() 371[(1, 11), (3, 3), (2, 22)] 372>>> omd.popvalue(1, 11) 37311 374>>> omd.allitems() 375[(3, 3), (2, 22)] 376>>> omd.popvalue('not a key', default='sup') 377'sup' 378``` 379 380__popitem(fromall=False, last=True)__ pops and returns a key:value item. 381 382If __fromall__ is False, `items()[0]` is popped if __last__ is False or `items()[-1]` is\ 383popped if __last__ is True. All remaining items with the same key are\ 384removed. 385 386If __fromall__ is True, `allitems()[0]` is popped if __last__ is False or `allitems()[-1]` is\ 387popped if __last__ is True. No other remaining items are removed, even if\ 388they have the same key. 389 390```python 391>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 392>>> omd.popitem() 393(3, 3) 394>>> omd.popitem(fromall=False, last=False) 395(1, 1) 396>>> omd.popitem(fromall=False, last=False) 397(2, 2) 398>>> omd.allitems() 399[] 400 401>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 402>>> omd.popitem(fromall=True, last=False) 403(1, 1) 404>>> omd.popitem(fromall=True, last=False) 405(1, 11) 406>>> omd.popitem(fromall=True, last=True) 407(3, 3) 408>>> omd.popitem(fromall=True, last=False) 409(1, 111) 410``` 411 412__poplistitem([key], last=True)__ pops and returns a key:valuelist item\ 413comprised of a key and that key's list of values. If __last__ is False, a\ 414key:valuelist item comprised of `keys()[0]` and its list of values is popped\ 415and returned. If __last__ is True, a key:valuelist item comprised of `keys()[-1]`\ 416and its list of values is popped and returned. KeyError is raised if the\ 417dictionary is empty or if __key__ is provided and not in the dictionary. 418 419```python 420>>> omd = omdict([(1,1), (1,11), (1,111), (2,2), (3,3)]) 421>>> omd.poplistitem(last=True) 422(3, [3]) 423>>> omd.poplistitem(last=False) 424(1, [1, 11, 111]) 425``` 426 427 428### Miscellaneous 429 430__copy()__ returns a shallow copy of the dictionary. 431 432```python 433>>> omd = omdict([(1,1), (1,11), (2,2), (3,3)]) 434>>> copy = omd.copy() 435>>> omd == copy 436True 437>>> isinstance(copy, omdict) 438True 439``` 440 441__clear()__ clears all items. 442 443```python 444>>> omd = omdict([(1,1), (1,11), (2,2), (3,3)]) 445>>> omd.clear() 446>>> omd.allitems() 447[] 448``` 449 450__len(omd)__ returns the number of keys in the dictionary, identical to\ 451[len(dict)](http://docs.python.org/library/stdtypes.html#dict). 452 453```python 454>>> omd = omdict([(1, 1), (2, 2), (1, 11)]) 455>>> len(omd) 4562 457``` 458 459__size()__ returns the total number of items in the dictionary. 460 461```python 462>>> omd = omdict([(1, 1), (1, 11), (2, 2), (1, 111)]) 463>>> omd.size() 4644 465``` 466 467__reverse()__ reverses the order of all items in the dictionary and returns the\ 468omdict object for method chaining. 469 470```python 471>>> omd = omdict([(1, 1), (2, 2), (3, 3)]) 472>>> omd.allitems() 473[(1, 1), (2, 2), (3, 3)] 474>>> omd.reverse() 475>>> omd.allitems() 476[(3, 3), (2, 2), (1, 1)] 477``` 478 479__fromkeys(keys[, value])__ behaves identically to [dict.fromkeys(key[, 480value])](http://docs.python.org/library/stdtypes.html#dict.fromkeys). 481 482__has_key(key)__ behaves identically to [dict.has_key(key)](http://docs.python.org/library/stdtypes.html#dict.has_key), but use\ 483`key in omd` instead of `omd.has_key(key)` where possible. 484