HTTP Digest authentication support

.github/workflows/ci.yaml

@@ -16,7 +16,7 @@ jobs:
 
     - uses: actions/setup-python@v5
       with:
-        python-version: '3.11'
+        python-version: '3.12'
 
     - uses: actions/cache@v4
       with:
@@ -42,7 +42,7 @@ jobs:
 
     - uses: actions/setup-python@v5
       with:
-        python-version: "3.11"
+        python-version: "3.12"
 
     - uses: actions/cache@v4
       with:

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,27 @@ 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
+caching HTTP digest credentials — after authorizing any URL/method pair,
+the library will use the initially received HTTP digest credentials on that endpoint
+for subsequent requests, and will not perform any redundant requests to obtain the
+credentials.
+
+: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      |
 +----------------------------------+----------+----------+