From 2a1c3f740dfe3bb5f899cc4ccb2cf15461c5f950 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 13 May 2011 02:28:05 -0400 Subject: - Added documentation for a "multidict" (e.g. the API of ``request.POST``) as interface API documentation. --- docs/api/interfaces.rst | 4 ++++ docs/api/request.rst | 6 +++++ docs/glossary.rst | 8 +++---- docs/narr/webob.rst | 58 +++++++++++++++++++++++++++---------------------- 4 files changed, 46 insertions(+), 30 deletions(-) (limited to 'docs') 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 `_, 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 `_ 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. - -- cgit v1.2.3