HTTP Digest authentication support

docs/examples/digest_auth.py

@@ -0,0 +1,16 @@
+from twisted.internet.task import react
+from _utils import print_response
+
+import treq
+from treq.auth import HTTPDigestAuth
+
+
+def main(reactor, *args):
+    d = treq.get(
+        'http://httpbin.org/digest-auth/auth/treq/treq',
+        auth=HTTPDigestAuth('treq', 'treq')
+    )
+    d.addCallback(print_response)
+    return d
+
+react(main, [])

docs/howto.rst

@@ -92,6 +92,26 @@ The ``auth`` argument should be a tuple of the form ``('username', 'password')``
 
 Full example: :download:`basic_auth.py <examples/basic_auth.py>`
 
+HTTP Digest authentication is supported by passing an instance of
+:py:class:`treq.auth.HTTPDigestAuth` to any of the request functions by using the `auth` keyword argument.
+We support only "auth" QoP as defined at `RFC 2617`_
+or simple `RFC 2069`_ without QoP at the moment. Treq takes care of
+HTTP digest credentials caching - after authorization on any URL/method pair,
+the library will use the first time received HTTP digest credentials on that endpoint
+for further requests, and will not perform any redundant requests for obtaining the creds.
+
+:py:class:`treq.auth.HTTPDigestAuth` class accepts ``username`` and ``password``
+as constructor arguments.
+
+.. literalinclude:: examples/digest_auth.py
+    :linenos:
+    :lines: 5-14
+
+Full example: :download:`digest_auth.py <examples/digest_auth.py>`
+
+.. _RFC 2617: http://www.ietf.org/rfc/rfc2617.txt
+.. _RFC 2069: http://www.ietf.org/rfc/rfc2069.txt
+
 Redirects
 ---------
 

docs/index.rst

@@ -71,7 +71,7 @@ Here is a list of `requests`_ features and their status in treq.
 +----------------------------------+----------+----------+
 | Basic Authentication             | yes      | yes      |
 +----------------------------------+----------+----------+
-| Digest Authentication            | yes      | no       |
+| Digest Authentication            | yes      | yes      |
 +----------------------------------+----------+----------+
 | Elegant Key/Value Cookies        | yes      | yes      |
 +----------------------------------+----------+----------+