Added json_content and etree_content, more docs and comments.

diff --git a/requests/hooks/response.py b/requests/hooks/response.py
index e9ce39b307fc44596bf35cf5ea34ee7db6bd6c1b..beec248bd5f53c62a4f1116475c051d38a572dee 100644 (file)
--- a/requests/hooks/response.py
+++ b/requests/hooks/response.py
@@ -4,41 +4,82 @@ request.hooks.response
 
 This module provide a collection of response hooks.
 """
-from functools import wraps
 import zlib
+import bz2
 from cgi import parse_header
 
+try:
+    import json
+except ImportError:
+    try:
+        import simplejson as json
+    except ImportError:
+        json = False
+try:
+    from lxml import etree
+except ImportError:
+    try:
+        import xml.etree.cElementTree as etree
+    except ImportError:
+        try:
+            import xml.etree.ElementTree as etree
+        except ImportError:
+            try:
+                import cElementTree as etree
+            except ImportError:
+                try:
+                    import elementtree.ElementTree as etree
+                except ImportError:
+                    etree = False
+
 #: Dictionary of content decoders.
-decoders = {
+content_decoders = {
     # No decoding applied.
-    'identity': lambda r: r.content,
+    'identity': lambda content: content,
     # Decode Response file object compressed with deflate.
-    'deflate': lambda r: zlib.decompress(r.content),
+    'deflate': lambda content: zlib.decompress(content),
     # Decode Response file object compressed with gzip.
-    'gzip': lambda r: zlib.decompress(r.content, 16+zlib.MAX_WBITS),
+    'gzip': lambda content: zlib.decompress(content, 16+zlib.MAX_WBITS),
+    # Decode Response file object compressed with bz2.
+    # Not a standard Content-Encoding value, but..
+    'bzip2': lambda content: bz2.decompress(content),
 }
 
 # Decode Response file object compressed with compress.
-decoders['compress'] = decoders['deflate']
+content_decoders['compress'] = content_decoders['deflate']
 
-try:
-    import bz2
-except ImportError:
-    pass
-else:
-    # Decode Response file object compressed with bz2.
-    decoders['bzip2'] = lambda r: bz2.decompress(r.content)
-
-def unicode_response(r):
-    """Encode response file object in unicode."""
-    content_type, params = parse_header(r.headers.get('content-type'))
+def decode_unicode(r):
+    """Encode a :py:class:`requests.models.Response` file object in unicode."""
+    content_type, params = parse_header(r.headers['content-type'])
     charset = params.get('charset', '').strip("'\"")
     r._content = unicode(r.content, charset) if charset else unicode(r.content)
     return r
 
-def decode_response(r):
-    """Decode compressed response content using Contetn-Encoding header."""
-    encoding = r.headers.get('content-encoding')
-    r._content = decoders.get(encoding)(r)
+def decode_encoding(r):
+    """
+        Decode a :py:class:`requests.models.Response` content using
+        Contetn-Encoding header.
+    """
+    # Apply decoding only if the header is set.
+    encoding = r.headers['content-encoding']
+    if encoding:
+        r._content = content_decoders[encoding](r.content)
     return r
 
+if json:
+    def json_content(r):
+        """
+            Turns :py:class:`requests.models.Response` content into a dumped
+            JSON structure.
+        """
+        r._content = json.dumps(r.content)
+        return r
+
+if etree:
+    def etree_content(r):
+        """
+            Turns :py:class:`requests.models.Response` content into an
+            ElementTree structure.
+        """
+        r._content = etree.fromstring(r.content)
+        return r