[1.7.x] Improved documentation for QueryDict.

class QueryDict(MultiValueDict):

    """

    A specialized MultiValueDict that takes a query string when initialized.

    This is immutable unless you create a copy of it.

    A specialized MultiValueDict which represents a query string.

    Values retrieved from this class are converted from the given encoding

    A QueryDict can be used to represent GET or POST data. It subclasses

    MultiValueDict since keys in such data can be repeated, for instance

    in the data from a form with a <select multiple> field.

    By default QueryDicts are immutable, though the copy() method

    will always return a mutable copy.

    Both keys and values set on this class are converted from the given encoding

    (DEFAULT_CHARSET by default) to unicode.

    """

    # These are both reset in __init__, but is specified here at the class

    # level so that unpickling will have valid values

    _mutable = True

.. class:: QueryDict

In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances

of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like

class customized to deal with multiple values for the same key. This is

necessary because some HTML form elements, notably

``<select multiple="multiple">``, pass multiple values for the same key.

In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are

instances of ``django.http.QueryDict``, a dictionary-like class customized to

deal with multiple values for the same key. This is necessary because some HTML

form elements, notably ``<select multiple>``, pass multiple values for the same

key.

``QueryDict`` instances are immutable, unless you create a ``copy()`` of them.

That means you can't change attributes of ``request.POST`` and ``request.GET``

directly.

The ``QueryDict``\ s at ``request.POST`` and ``request.GET`` will be immutable

when accessed in a normal request/response cycle. To get a mutable version you

need to use ``.copy()``.

Methods

-------

:class:`QueryDict` implements all the standard dictionary methods, because it's

:class:`QueryDict` implements all the standard dictionary methods because it's

a subclass of dictionary. Exceptions are outlined here:

.. method:: QueryDict.__init__(query_string, mutable=False, encoding=None)

   Instantiates a ``QueryDict`` object based on ``query_string``.

          >>> QueryDict('a=1&a=2&c=3')

          <QueryDict: {u'a': [u'1', u'2'], u'b': [u'1']}>

   Most ``QueryDict``\ s you encounter, and in particular those at

   ``request.POST`` and ``request.GET``, will be immutable. If you are

   instantiating one yourself, you can make it mutable by passing

   ``mutable=True`` to its ``__init__()``.

   Strings for setting both keys and values will be converted from ``encoding``

   to unicode. If encoding is not set, it defaults to :setting:`DEFAULT_CHARSET`.

.. method:: QueryDict.__getitem__(key)

    Returns the value for the given key. If the key has more than one value,

    Sets the given key to ``[value]`` (a Python list whose single element is

    ``value``). Note that this, as other dictionary functions that have side

    effects, can only be called on a mutable ``QueryDict`` (one that was created

    via ``copy()``).

    effects, can only be called on a mutable ``QueryDict`` (such as one that

    was created via ``copy()``).

.. method:: QueryDict.__contains__(key)

    dictionary ``update()`` method, except it *appends* to the current

    dictionary items rather than replacing them. For example::

          >>> q = QueryDict('a=1')

          >>> q = q.copy() # to make it mutable

          >>> q = QueryDict('a=1', mutable=True)

          >>> q.update({'a': '2'})

          >>> q.getlist('a')

          [u'1', u'2']

.. method:: QueryDict.copy()

    Returns a copy of the object, using ``copy.deepcopy()`` from the Python

    standard library. The copy will be mutable -- that is, you can change its

    values.

    standard library. This copy will be mutable even if the original was not.

.. method:: QueryDict.getlist(key, default)