# `webob.multidict` -- multi-value dictionary object

## multidict

Several parts of WebOb use a "multidict", which is a dictionary where a key can have multiple values. The quintessential example is a query string like `?pref=red&pref=blue`. The `pref` variable has two values, `red` and `blue`.

In a multidict, when you do `request.GET['pref']`, you'll get back only `'blue'` (the last value of `pref`). Sometimes returning a string and other times returning a list is a cause of frequent exceptions. If you want all the values back, use `request.GET.getall('pref')`. If you want to be sure there is one and only one value, use `request.GET.getone('pref')`, which will raise an exception if there is zero or more than one value for `pref`.

When you use operations like `request.GET.items()`, you'll get back something like `[('pref', 'red'), ('pref', 'blue')]`. All the key/value pairs will show up. Similarly `request.GET.keys()` returns `['pref', 'pref']`. Multidict is a view on a list of tuples; all the keys are ordered, and all the values are ordered.

Gives a multi-value dictionary object (MultiDict) plus several wrappers

class webob.multidict.MultiDict(*args, **kw)

  An ordered dictionary that can have multiple values for each key. Adds the methods getall, getone, mixed and extend and add to the normal dictionary interface.

  classmethod view_list(lst)

    Create a dict that is a view on the given list

  classmethod from_fieldstorage(fs)

    Create a dict from a cgi.FieldStorage instance

  add(key, value)

    Add the key and value, not overwriting any previous value.

  getall(key)

    Return a list of all values matching the key (may be an empty list)

  getone(key)

    Get one value matching the key, raising a KeyError if multiple values were found.

  mixed()

    Returns a dictionary where the values are either single values, or a list of values when a key/value appears more than once in this dictionary. This is similar to the kind of dictionary often used to represent the variables in a web request.

  dict_of_lists()

    Returns a dictionary where each key is associated with a list of values.

  clear() → None. Remove all items from D.
  setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  pop(k[, d]) → v, remove specified key and return the corresponding

    value. If key is not found, d is returned if given, otherwise KeyError is raised.

  popitem() → (k, v), remove and return some (key, value) pair

    as a 2-tuple; but raise KeyError if D is empty.

  update([E, ]**F) → None. Update D from mapping/iterable E and F.
    If E present and has a .keys() method, does:

      for k in E.keys(): D[k] = E[k]

    If E present and lacks .keys() method, does:

      for (k, v) in E: D[k] = v

    In either case, this is followed by:

      for k, v in F.items(): D[k] = v

  keys() → a set-like object providing a view on D's keys
  items() → a set-like object providing a view on D's items
  values() → an object providing a view on D's values
  get(k[, d]) → D[k] if k in D, else d. d defaults to None.

class webob.multidict.NestedMultiDict(*dicts)

  Wraps several MultiDict objects, treating it as one large MultiDict

  add(*args, **kw)

    Add the key and value, not overwriting any previous value.

  clear() → None. Remove all items from D.
  setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  pop(k[, d]) → v, remove specified key and return the corresponding

    value. If key is not found, d is returned if given, otherwise KeyError is raised.

  popitem() → (k, v), remove and return some (key, value) pair

    as a 2-tuple; but raise KeyError if D is empty.

  update([E, ]**F) → None. Update D from mapping/iterable E and F.
    If E present and has a .keys() method, does:

      for k in E.keys(): D[k] = E[k]

    If E present and lacks .keys() method, does:

      for (k, v) in E: D[k] = v

    In either case, this is followed by:

      for k, v in F.items(): D[k] = v

  getall(key)

    Return a list of all values matching the key (may be an empty list)

  items() → a set-like object providing a view on D's items
  values() → an object providing a view on D's values
  keys() → a set-like object providing a view on D's keys

class webob.multidict.NoVars(reason=None)

  Represents no variables; used when no variables are applicable.

  This is read-only