From e8e16abe6a797789427a79cd66175ae70f392a08 Mon Sep 17 00:00:00 2001
From: Duncan Parkes <duncan@mysociety.org>
Date: Wed, 11 Jun 2014 21:41:25 +0100
Subject: [PATCH] [1.7.x] Improved documentation for QueryDict.
Backport of 7f4e2ef1e9 from master
---
django/http/request.py | 13 ++++++++---
docs/ref/request-response.txt | 43 +++++++++++++++++++++++------------
2 files changed, 38 insertions(+), 18 deletions(-)
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)