werkzeug.datastructures.MultiDict

class documentation

class MultiDict(TypeConversionDict):

Known subclasses: werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.FileMultiDict, werkzeug.datastructures.ImmutableMultiDict, werkzeug.datastructures.OrderedMultiDict

View In Hierarchy

A MultiDict is a dictionary subclass customized to deal with multiple values for the same key which is for example used by the parsing functions in the wrappers. This is necessary because some HTML form elements pass multiple values for the same key.

MultiDict implements all standard dictionary methods. Internally, it saves all values for a key as a list, but the standard dict access methods will only return the first value for a key. If you want to gain access to the other values, too, you have to use the list methods as explained below.

Basic Usage:

>>> d = MultiDict([('a', 'b'), ('a', 'c')])
>>> d
MultiDict([('a', 'b'), ('a', 'c')])
>>> d['a']
'b'
>>> d.getlist('a')
['b', 'c']
>>> 'a' in d
True

It behaves like a normal dict thus all dict functions will only return the first value when multiple values for one key are found.

From Werkzeug 0.3 onwards, the KeyError raised by this class is also a subclass of the ~exceptions.BadRequest HTTP exception and will render a page for a 400 BAD REQUEST if caught in a catch-all for HTTP exceptions.

A MultiDict can be constructed from an iterable of (key, value) tuples, a dict, a MultiDict or from Werkzeug 0.2 onwards some keyword parameters.

Parameters
mapping	the initial value for the `MultiDict`. Either a regular dict, an iterable of `(key, value)` tuples or `None`.

Method	`__copy__`	Undocumented
Method	`__deepcopy__`	Undocumented
Method	`__getitem__`	Return the first data value for this key; raises KeyError if not found.
Method	`__getstate__`	Undocumented
Method	`__init__`	Undocumented
Method	`__iter__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__setitem__`	Like `add` but removes an existing key first.
Method	`__setstate__`	Undocumented
Method	`add`	Adds a new value for the key.
Method	`copy`	Return a shallow copy of this object.
Method	`deepcopy`	Return a deep copy of this object.
Method	`getlist`	No summary
Method	`items`	Return an iterator of `(key, value)` pairs.
Method	`lists`	Return a iterator of `(key, values)` pairs, where values is the list of all values associated with the key.
Method	`listvalues`	Return an iterator of all values associated with a key. Zipping `keys` and this is the same as calling `lists`:
Method	`pop`	Pop the first item for a list on the dict. Afterwards the key is removed from the dict, so additional values are discarded:
Method	`popitem`	Pop an item from the dict.
Method	`popitemlist`	Pop a `(key, list)` tuple from the dict.
Method	`poplist`	Pop the list for a key from the dict. If the key is not in the dict an empty list is returned.
Method	`setdefault`	Returns the value for the key if it is in the dict, otherwise it returns `default` and sets that value for `key`.
Method	`setlist`	Remove the old values for a key and add new ones. Note that the list you pass the values in will be shallow-copied before it is inserted in the dictionary.
Method	`setlistdefault`	No summary
Method	`to_dict`	Return the contents as regular dict. If `flat` is `True` the returned dict will only have the first item present, if `flat` is `False` all values will be returned as lists.
Method	`update`	update() extends rather than replaces existing key lists:
Method	`values`	Returns an iterator of the first value on every key's value list.

Inherited from TypeConversionDict:

Method get No summary

def __copy__(self):

overridden in werkzeug.datastructures.ImmutableMultiDict, werkzeug.datastructures.ImmutableOrderedMultiDict

Undocumented

def __deepcopy__(self, memo):

Undocumented

def __getitem__(self, key):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Return the first data value for this key; raises KeyError if not found.

Parameters
key	The key to be looked up.
Raises
`KeyError`	if the key does not exist.

def __getstate__(self):

overridden in werkzeug.datastructures.OrderedMultiDict

Undocumented

def __init__(self, mapping=None):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Undocumented

def __iter__(self):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Undocumented

def __repr__(self):

overridden in werkzeug.datastructures.CombinedMultiDict

Undocumented

def __setitem__(self, key, value):

overridden in werkzeug.datastructures.OrderedMultiDict

Like add but removes an existing key first.

Parameters
key	the key for the value.
value	the value to set.

def __setstate__(self, value):

overridden in werkzeug.datastructures.OrderedMultiDict

Undocumented

def add(self, key, value):

overridden in werkzeug.datastructures.OrderedMultiDict

Adds a new value for the key.

New in version 0.6.

Parameters
key	the key for the value.
value	the value to add.

def copy(self):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.ImmutableMultiDict, werkzeug.datastructures.ImmutableOrderedMultiDict

Return a shallow copy of this object.

def deepcopy(self, memo=None):

Return a deep copy of this object.

def getlist(self, key, type=None):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Return the list of items for a given key. If that key is not in the MultiDict, the return value will be an empty list. Just like get, getlist accepts a type parameter. All items will be converted with the callable defined there.

Parameters
key	The key to be looked up.
type	A callable that is used to cast the value in the `MultiDict`. If a `ValueError` is raised by this callable the value will be removed from the list.
Returns
a `list` of all the values for the key.

def items(self, multi=False):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Return an iterator of (key, value) pairs.

Parameters
multi	If set to `True` the iterator returned will have a pair for each value of each key. Otherwise it will only contain pairs for the first value of each key.

def lists(self):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Return a iterator of (key, values) pairs, where values is the list of all values associated with the key.

def listvalues(self):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Return an iterator of all values associated with a key. Zipping keys and this is the same as calling lists:

>>> d = MultiDict({"foo": [1, 2, 3]})
>>> zip(d.keys(), d.listvalues()) == d.lists()
True

def pop(self, key, default=_missing):

overridden in werkzeug.datastructures.OrderedMultiDict

Pop the first item for a list on the dict. Afterwards the key is removed from the dict, so additional values are discarded:

>>> d = MultiDict({"foo": [1, 2, 3]})
>>> d.pop("foo")
1
>>> "foo" in d
False

Parameters
key	the key to pop.
default	if provided the value to return if the key was not in the dictionary.

def popitem(self):

overridden in werkzeug.datastructures.OrderedMultiDict

Pop an item from the dict.

def popitemlist(self):

overridden in werkzeug.datastructures.OrderedMultiDict

Pop a (key, list) tuple from the dict.

def poplist(self, key):

overridden in werkzeug.datastructures.OrderedMultiDict

Pop the list for a key from the dict. If the key is not in the dict an empty list is returned.

Changed in version 0.5: If the key does no longer exist a list is returned instead of raising an error.

def setdefault(self, key, default=None):

Returns the value for the key if it is in the dict, otherwise it returns default and sets that value for key.

Parameters
key	The key to be looked up.
default	The default value to be returned if the key is not in the dict. If not further specified it's `None`.

def setlist(self, key, new_list):

overridden in werkzeug.datastructures.OrderedMultiDict

Remove the old values for a key and add new ones. Note that the list you pass the values in will be shallow-copied before it is inserted in the dictionary.

>>> d = MultiDict()
>>> d.setlist('foo', ['1', '2'])
>>> d['foo']
'1'
>>> d.getlist('foo')
['1', '2']

Parameters
key	The key for which the values are set.
new_list	An iterable with the new values for the key. Old values are removed first.

def setlistdefault(self, key, default_list=None):

overridden in werkzeug.datastructures.OrderedMultiDict

Like setdefault but sets multiple values. The list returned is not a copy, but the list that is actually used internally. This means that you can put new values into the dict by appending items to the list:

>>> d = MultiDict({"foo": 1})
>>> d.setlistdefault("foo").extend([2, 3])
>>> d.getlist("foo")
[1, 2, 3]

Parameters
key	The key to be looked up.
default_list	An iterable of default values. It is either copied (in case it was a list) or converted into a list before returned.
Returns
a `list`

def to_dict(self, flat=True):

overridden in werkzeug.datastructures.CombinedMultiDict

Return the contents as regular dict. If flat is True the returned dict will only have the first item present, if flat is False all values will be returned as lists.

Parameters
flat	If set to `False` the dict returned will have lists with all the values in it. Otherwise it will only contain the first value for each key.
Returns
a `dict`

def update(self, mapping):

overridden in werkzeug.datastructures.OrderedMultiDict

update() extends rather than replaces existing key lists:

>>> a = MultiDict({'x': 1})
>>> b = MultiDict({'x': 2, 'y': 3})
>>> a.update(b)
>>> a
MultiDict([('y', 3), ('x', 1), ('x', 2)])

If the value list for a key in other_dict is empty, no new values will be added to the dict and the key will not be created:

>>> x = {'empty_list': []}
>>> y = MultiDict()
>>> y.update(x)
>>> y
MultiDict([])

def values(self):

overridden in werkzeug.datastructures.CombinedMultiDict, werkzeug.datastructures.OrderedMultiDict

Returns an iterator of the first value on every key's value list.