diff options
| -rw-r--r-- | CHANGES.txt | 3 | ||||
| -rw-r--r-- | TODO.txt | 2 | ||||
| -rw-r--r-- | docs/api/interfaces.rst | 4 | ||||
| -rw-r--r-- | docs/api/request.rst | 6 | ||||
| -rw-r--r-- | docs/glossary.rst | 8 | ||||
| -rw-r--r-- | docs/narr/webob.rst | 58 | ||||
| -rw-r--r-- | pyramid/interfaces.py | 37 |
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 -------- @@ -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 |