Document new multidicts

Author: asvetlov

docs/multidict.rst

@@ -13,20 +13,21 @@ Multidicts
 several *values* for the same *key*.
 
 :mod:`aiohttp.multidict` has four multidict classes:
-:class:`MultiDict`, :class:`MutableMultiDict`, :class:`CIMultiDict`
-and :class:`CIMutableMultiDict`.
+:class:`MultiDict`, :class:`MultiDictProxy`, :class:`CIMultiDict`
+and :class:`CIMultiDictProxy`.
 
+Immutable proxies (:class:`MultiDictProxy` and
+:class:`CIMultiDictProxy`) provide a dynamic view on the
+proxied multidict, the view reflects the multidict changes. They are
+implement :class:`~collections.abc.Mapping` interface.
 
-Immutable (:class:`MultiDict` and :class:`CIMultiDict`) classes
-doesn't allow to change *muldidict* content. They are implement
-:class:`~collections.abc.Mapping` interface.
-
-Mutable (:class:`MutableMultiDict` and :class:`CIMutableMultiDict`)
-ones implement :class:`~collections.abc.MutableMapping`.
+Regular mutable (:class:`MultiDict` and :class:`CIMultiDict`) clases
+implement :class:`~collections.abc.MutableMapping` and allow to change
+own content.
 
 
 *Case insensitive* (:class:`CIMultiDict` and
-:class:`CIMutableMultiDict`) ones assumes the *keys* are case
+:class:`CIMultiDictProxy`) ones assumes the *keys* are case
 insensitive, e.g.::
 
    >>> dct = CIMultiDict(a='val')
@@ -38,20 +39,20 @@ insensitive, e.g.::
 *Keys* should be a :class:`str`.
 
 
-MultiDict
----------
+MutableMultiDict
+----------------
 
-.. class:: MultiDict(**kwargs)
-           MultiDict(mapping, **kwargs)
-           MultiDict(iterable, **kwargs)
+.. class:: MutableMultiDict(**kwargs)
+           MutableMultiDict(mapping, **kwargs)
+           MutableMultiDict(iterable, **kwargs)
 
-   Create an immutable multidict instance.
+   Create a mutable multidict instance.
 
    Accepted parameters are the same as for :class:`dict`.
 
    If the same key produced several times it will be added, e.g.::
 
-      >>> d = MultiDict([('a', 1), ('b', 2), ('a', 3)])
+      >>> d = MultiDict[('a', 1), ('b', 2), ('a', 3)])
       >>> d
       <MultiDict {'a': 1, 'b': 2, 'a': 3}>
 
@@ -65,6 +66,18 @@ MultiDict
 
       Raises a :exc:`KeyError` if key is not in the multidict.
 
+   .. method:: d[key] = value
+
+      Set ``d[key]`` to *value*.
+
+      Replace all items where key is equal to *key* with single item
+      ``(key, value)``.
+
+   .. method:: del d[key]
+
+      Remove all items where key is equal to *key* from *d*.
+      Raises a :exc:`KeyError` if *key* is not in the map.
+
    .. method:: key in d
 
       Return ``True`` if d has a key *key*, else ``False``.
@@ -78,10 +91,30 @@ MultiDict
       Return an iterator over the keys of the dictionary.
       This is a shortcut for ``iter(d.keys())``.
 
+   .. method:: add(key, value)
+
+      Append ``(key, value)`` pair to the dictiaonary.
+
+   .. method:: clear()
+
+      Remove all items from the dictionary.
+
    .. method:: copy()
 
       Return a shallow copy of the dictionary.
 
+   .. method:: extend([other])
+
+      Extend the dictionary with the key/value pairs from *other*,
+      overwriting existing keys.
+      Return ``None``.
+
+      :meth:`extend` accepts either another dictionary object or an
+      iterable of key/value pairs (as tuples or other iterables of
+      length two). If keyword arguments are specified, the dictionary
+      is then extended with those key/value pairs:
+      ``d.extend(red=1, blue=2)``.
+
    .. method:: getone(key[, default])
 
       Return the **first** value for *key* if *key* is in the
@@ -129,6 +162,12 @@ MultiDict
       View contains all values if *getall* is ``True`` (default) or
       only first key occurrences otherwise.
 
+   .. method:: setdefault(key[, default])
+
+      If *key* is in the dictionary, return its the **first** value.
+      If not, insert *key* with a value of *default* and return *default*.
+      *default* defaults to ``None``.
+
 
 CIMultiDict
 -----------
@@ -138,7 +177,7 @@ CIMultiDict
            CIMultiDict(mapping, **kwargs)
            CIMultiDict(iterable, **kwargs)
 
-   Create an immutable case insensitive multidict instance.
+   Create a case insensitive multidict instance.
 
    The behavior is the same as of :class:`MultiDict` but key
    comparsions are case insensitive, e.g.::
@@ -150,53 +189,107 @@ CIMultiDict
       'val'
       >>> dct['a']
       'val'
+      >>> dct['b'] = 'new val'
+      >>> dct['B']
+      'new val'
 
+   The class is inherited from :class:`MultiDict`.
 
-MutableMultiDict
-----------------
 
-.. class:: MutableMultiDict(**kwargs)
-           MutableMultiDict(mapping, **kwargs)
-           MutableMultiDict(iterable, **kwargs)
+MultiDictProxy
+---------------
 
-    Create a mutable multidict instance.
+.. class:: MultiDictProxy(multidict)
 
-    The class inherited from :class:`MultiDict`.
+   Create an immutable multidict proxy.
 
-    .. method:: d[key] = value
+   It provides a dynamic view on
+   the multidict’s entries, which means that when the multidict changes,
+   the view reflects these changes.
 
-       Set ``d[key]`` to *value*.
+   Raises :exc:`TypeError` is *multidict* is not :class:`MultiDict` instance.
 
-       Replace all items where key is equal to *key* with single item
-       ``(key, value)``.
+   .. method:: len(d)
 
-   .. method:: del d[key]
+      Return number of items in multidict *d*.
 
-      Remove all items where key is equal to *key* from *d*.
-      Raises a :exc:`KeyError` if *key* is not in the map.
+   .. method:: d[key]
 
-   .. method:: add(key, value)
+      Return the **first** item of *d* with key *key*.
 
-      Append ``(key, value)`` pair to the dictiaonary.
+      Raises a :exc:`KeyError` if key is not in the multidict.
 
-   .. method:: clear()
+   .. method:: key in d
 
-      Remove all items from the dictionary.
+      Return ``True`` if d has a key *key*, else ``False``.
 
-   .. method:: extend([other])
+   .. method:: key not in d
 
-      Extend the dictionary with the key/value pairs from *other*,
-      overwriting existing keys.
-      Return ``None``.
+      Equivalent to ``not (key in d)``
 
-      :meth:`extend` accepts either another dictionary object or an
-      iterable of key/value pairs (as tuples or other iterables of
-      length two). If keyword arguments are specified, the dictionary
-      is then extended with those key/value pairs:
-      ``d.extend(red=1, blue=2)``.
+   .. method:: iter(d)
 
-   .. method:: setdefault(key[, default])
+      Return an iterator over the keys of the dictionary.
+      This is a shortcut for ``iter(d.keys())``.
 
-      If *key* is in the dictionary, return its the **first** value.
-      If not, insert *key* with a value of *default* and return *default*.
-      *default* defaults to ``None``.
+   .. method:: copy()
+
+      Return a shallow copy of the dictionary.
+
+   .. method:: getone(key[, default])
+
+      Return the **first** value for *key* if *key* is in the
+      dictionary, else *default*.
+
+      Raises :exc:`KeyError` if *default* is not given and *key* is not found.
+
+      ``d[key]`` is equivalent to ``d.getone(key)``.
+
+   .. method:: getall(key[, default])
+
+      Return a list of all values for *key* if *key* is in the
+      dictionary, else *default*.
+
+      Raises :exc:`KeyError` if *default* is not given and *key* is not found.
+
+   .. method:: get(key[, default])
+
+      Return the **first** value for *key* if *key* is in the
+      dictionary, else *default*.
+
+      If *default* is not given, it defaults to ``None``, so that this
+      method never raises a :exc:`KeyError`.
+
+      ``d.get(key)`` is equivalent to ``d.getone(key, None)``.
+
+   .. method:: keys(getall=True)
+
+      Return a new view of the dictionary's keys.
+
+      View contains all keys if *getall* is ``True`` (default) or
+      distinct set of ones otherwise.
+
+   .. method:: keys(getall=True)
+
+      Return a new view of the dictionary's items (``(key, value)`` pairs).
+
+      View contains all items if *getall* is ``True`` (default) or
+      only first key occurrences otherwise.
+
+   .. method:: values(getall=True)
+
+      Return a new view of the dictionary's values.
+
+      View contains all values if *getall* is ``True`` (default) or
+      only first key occurrences otherwise.
+
+CIMultiDictProxy
+----------------
+
+.. class:: CIMultiDictProxy(multidict)
+
+   Case insensitive version of :class:`MultiDictProxy`.
+
+   Raises :exc:`TypeError` is *multidict* is not :class:`CIMultiDict` instance.
+
+   The class is inherited from :class:`MultiDict`.