- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as

  interface API documentation.

7 files changed, 86 insertions, 32 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 7c3b20c33..0182bdce0 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -29,6 +29,9 @@ Documentation
   chapter in the narrative documentation section entitled "Adding a Custom
   Setting".
 
+- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as
+  interface API documentation.
+
 Features
 --------
 
diff --git a/TODO.txt b/TODO.txt
index c7db73e56..1429bd80c 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -4,8 +4,6 @@ Pyramid TODOs
 Should-Have
 -----------
 
-- MultiDict documentation.
-
 - Speed up startup time (defer _bootstrap and registerCommonDirectives()
   until needed by ZCML, as well as unfound speedups).
 
diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index 54afdc830..ac282fbcc 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -54,3 +54,7 @@ Other Interfaces
   .. autointerface:: IViewMapper
      :members:
 
+  .. autointerface:: IMultiDict
+     :members:
+
+
diff --git a/docs/api/request.rst b/docs/api/request.rst
index 639d0fcd8..8cb424658 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -177,3 +177,9 @@
       (such as the status code, a header, the content type, etc) see,
       :ref:`response_prefixed_attrs`.
 
+.. note::
+
+   For information about the API of a :term:`multidict` structure (such as
+   that used as ``request.GET``, ``request.POST``, and ``request.params``),
+   see :class:`pyramid.interfaces.IMultiDict`.
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 97fc68707..13de8c41a 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -630,10 +630,10 @@ Glossary
       more information.
 
    multidict
-     An ordered dictionary that can have multiple values for each
-     key. Adds the methods ``getall``, ``getone``, ``mixed``, and
-     ``add`` to the normal dictionary interface.  See
-     http://pythonpaste.org/webob/class-webob.multidict.MultiDict.html
+     An ordered dictionary that can have multiple values for each key. Adds
+     the methods ``getall``, ``getone``, ``mixed``, ``add`` and
+     ``dict_of_lists`` to the normal dictionary interface.  See
+     :ref:`multidict_narr` and :class:`pyramid.interfaces.IMultiDict`.
 
    PyPI
      `The Python Package Index <http://pypi.python.org/pypi>`_, a
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 26a40a59b..072ca1c74 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -208,6 +208,38 @@ If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and
 corresponding ``req.str_*`` (e.g., ``req.str_POST``) that is always
 a ``str``, and never unicode.
 
+.. index::
+   single: multidict (WebOb)
+
+.. _multidict_narr:
+
+Multidict
++++++++++
+
+Several attributes of a WebOb request are "multidict"; structures (such as
+``request.GET``, ``request.POST``, and ``request.params``).  A multidict 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 sometimes returning a list, is the 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.
+
+API documentation for a multidict exists as
+:class:`pyramid.interfaces.IMultiDict`.
+
 More Details
 ++++++++++++
 
@@ -371,9 +403,6 @@ The exceptions are still WSGI applications, but you cannot set
 attributes like ``content_type``, ``charset``, etc. on these exception
 objects.
 
-.. index::
-   single: multidict (WebOb)
-
 More Details
 ++++++++++++
 
@@ -382,26 +411,3 @@ More details about the response object API are available in the
 are in the :mod:`pyramid.httpexceptions` API documentation.  The `WebOb
 documentation <http://pythonpaste.org/webob>`_ is also useful.
 
-Multidict
-~~~~~~~~~
-
-Several parts of WebOb use a "multidict"; this 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 sometimes returning a list, is the 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.
-
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index dbea91c99..617133052 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -190,6 +190,43 @@ class IAuthorizationPolicy(Interface):
         ``pyramid.security.principals_allowed_by_permission`` API is
         used."""
 
+class IMultiDict(Interface): # docs-only interface
+    """
+    An ordered dictionary that can have multiple values for each key. A
+    multidict adds the methods ``getall``, ``getone``, ``mixed``, ``extend``
+    ``add``, and ``dict_of_lists`` to the normal dictionary interface.  A
+    multidict data structure is used as ``request.POST``, ``request.GET``,
+    and ``request.params`` within an :app:`Pyramid` application.
+    """
+
+    def add(key, value):
+        """ Add the key and value, not overwriting any previous value. """
+
+    def dict_of_lists():
+        """
+        Returns a dictionary where each key is associated with a list of
+        values.
+        """
+
+    def extend(other=None, **kwargs):
+        """ Add a set of keys and values, not overwriting any previous
+        values.  The ``other`` structure may be a list of two-tuples or a
+        dictionary.  If ``**kwargs`` is passed, its value *will* overwrite
+        existing values."""
+
+    def getall(key):
+        """ Return a list of all values matching the key (may be an empty
+        list) """
+
+    def getone(key):
+        """ Get one value matching the key, raising a KeyError if multiple
+        values were found. """
+
+    def 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. """
 
 # internal interfaces