diff --git a/django/http/request.py b/django/http/request.py index ecad639c82..1306dd3227 100644 --- a/django/http/request.py +++ b/django/http/request.py @@ -288,12 +288,19 @@ class HttpRequest(object): 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 diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 939f39a1a3..0ffcec09e7 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -339,22 +339,37 @@ QueryDict objects .. 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, @@ -367,8 +382,8 @@ a subclass of dictionary. Exceptions are outlined here: 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) @@ -391,8 +406,7 @@ a subclass of dictionary. Exceptions are outlined here: 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'] @@ -437,8 +451,7 @@ In addition, ``QueryDict`` has the following methods: .. 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)