Fixed #9886 -- Added a file-like interface to HttpRequest. Thanks to Ivan Sagalaev for the suggestion and patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14394 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 29 insertions, 2 deletions

diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 0cecebf5ad..5a317aee06 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -189,8 +189,14 @@ All attributes except ``session`` should be considered read-only.
 
 .. attribute:: HttpRequest.raw_post_data
 
-    The raw HTTP POST data. This is only useful for advanced processing. Use
-    ``POST`` instead.
+    The raw HTTP POST data as a byte string. This is useful for processing
+    data in different formats than of conventional HTML forms: binary images,
+    XML payload etc. For processing form data use ``HttpRequest.POST``.
+
+    .. versionadded:: 1.3
+
+    You can also read from an HttpRequest using file-like interface. See
+    :meth:`HttpRequest.read()`.
 
 .. attribute:: HttpRequest.urlconf
 
@@ -249,6 +255,27 @@ Methods
    If you write your own XMLHttpRequest call (on the browser side), you'll
    have to set this header manually if you want ``is_ajax()`` to work.
 
+.. method:: HttpRequest.read(size=None)
+.. method:: HttpRequest.readline()
+.. method:: HttpRequest.readlines()
+.. method:: HttpRequest.xreadlines()
+.. method:: HttpRequest.__iter__()
+
+    .. versionadded:: 1.3
+
+    Methods implementing a file-like interface for reading from an
+    HttpRequest instance. This makes it possible to consume an incoming
+    request in a streaming fashion. A common use-case would be to process a
+    big XML payload with iterative parser without constructing a whole
+    XML tree in memory.
+
+    Given this standard interface, an HttpRequest instance can be
+    passed directly to an XML parser such as ElementTree::
+
+        import xml.etree.ElementTree as ET
+        for element in ET.iterparse(request):
+            process(element)
+
 
 QueryDict objects
 -----------------