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

Chris McDonough

2011-05-13 2a1c3f740dfe3bb5f899cc4ccb2cf15461c5f950

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

 CHANGES.txt

@@ -29,6 +29,9 @@
  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
--------


 TODO.txt

@@ -4,8 +4,6 @@
Should-Have
-----------

- MultiDict documentation.

- Speed up startup time (defer _bootstrap and registerCommonDirectives()
  until needed by ZCML, as well as unfound speedups).


 docs/api/interfaces.rst

@@ -54,3 +54,7 @@
  .. autointerface:: IViewMapper
     :members:

  .. autointerface:: IMultiDict
     :members:



 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`.


 docs/glossary.rst

@@ -630,10 +630,10 @@
      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

 docs/narr/webob.rst

@@ -208,6 +208,38 @@
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 @@
attributes like ``content_type``, ``charset``, etc. on these exception
objects.

.. index::
   single: multidict (WebOb)

More Details
++++++++++++

@@ -381,27 +410,4 @@
:mod:`pyramid.response` documentation.  More details about exception responses
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.


 pyramid/interfaces.py

@@ -190,6 +190,43 @@
        ``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