Add section header

README.rst

@@ -22,7 +22,9 @@ Usage
   preshared_secret = b'monorail_cat'
   url = 'http://example.com/path'
 
-  auth = HTTPSignatureAuth(key=preshared_secret, key_id=preshared_key_id, signature_algorithm=algorithms.HMAC_SHA256)
+  auth = HTTPSignatureAuth(key=preshared_secret,
+                           key_id=preshared_key_id,
+                           signature_algorithm=algorithms.HMAC_SHA256)
   requests.get(url, auth=auth)
 
 By default, only the ``Date`` header and the ``@method``, ``@authority``, and ``@target-uri`` derived component
@@ -31,7 +33,11 @@ requests with bodies (such as POST), the ``Content-Digest`` header is set to the
 format described in the
 `IETF Digest Fields draft RFC <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers>`_ and signed.
 To add other headers to the signature, pass an array of header names in the ``covered_component_ids`` keyword argument.
+See the `API documentation <https://pyauth.github.io/requests-http-signature/#id1>`_ for the full list of options and
+details.
 
+Verifying messages
+~~~~~~~~~~~~~~~~~~
 In addition to signing messages in the client, the class method ``HTTPSignatureAuth.verify()`` can be used to verify
 incoming requests:
 
@@ -42,7 +48,11 @@ incoming requests:
           assert key_id == 'squirrel'
           return 'monorail_cat'
 
-  HTTPSignatureAuth.verify(request, signature_algorithm=algorithms.HMAC_SHA256, key_resolver=key_resolver)
+  request = requests.Request(...)  # Reconstruct the incoming request using the Requests API
+  request = request.prepare()
+  HTTPSignatureAuth.verify(request,
+                           signature_algorithm=algorithms.HMAC_SHA256,
+                           key_resolver=key_resolver)
 
 .. admonition:: See what is signed
 
@@ -72,7 +82,9 @@ constructor as bytes in the PEM format, or configure the key resolver as follows
 .. code-block:: python
 
   with open('key.pem', 'rb') as fh:
-      auth = HTTPSignatureAuth(algorithm=algorithms.RSA_V1_5_SHA256, key=fh.read(), key_id=preshared_key_id)
+      auth = HTTPSignatureAuth(algorithm=algorithms.RSA_V1_5_SHA256,
+                               key=fh.read(),
+                               key_id=preshared_key_id)
   requests.get(url, auth=auth)
 
   class MyKeyResolver:
@@ -82,7 +94,9 @@ constructor as bytes in the PEM format, or configure the key resolver as follows
       def resolve_private_key(self, key_id: str):
           return private_key_pem_bytes[key_id]
 
-  auth = HTTPSignatureAuth(algorithm=algorithms.RSA_V1_5_SHA256, key=fh.read(), key_resolver=MyKeyResolver())
+  auth = HTTPSignatureAuth(algorithm=algorithms.RSA_V1_5_SHA256,
+                           key=fh.read(),
+                           key_resolver=MyKeyResolver())
   requests.get(url, auth=auth)
 
 Digest algorithms

requests_http_signature/__init__.py

@@ -148,7 +148,7 @@ class HTTPSignatureAuth(requests.auth.AuthBase):
         return request
 
     @classmethod
-    def verify(cls, request, *,
+    def verify(cls, request: requests.PreparedRequest, *,
                require_components: List[str] = ("@method", "@authority", "@target-uri"),
                signature_algorithm: HTTPSignatureAlgorithm,
                key_resolver: HTTPSignatureKeyResolver):
@@ -166,7 +166,14 @@ class HTTPSignatureAuth(requests.auth.AuthBase):
          You can ensure that the information signed is what you expect to be signed by only trusting the *VerifyResult*
          tuple returned by ``verify()``.
 
-        :param request: The HTTP request to verify.
+        :param request:
+            The HTTP request to verify. You can reconstruct an incoming request using the
+            `Requests API <https://docs.python-requests.org/en/latest/api/#requests.Request>`_ as follows::
+
+              request = requests.Request(...)
+              request = request.prepare()
+              HTTPSignatureAuth.verify(request, ...)
+
         :param require_components:
             A list of lowercased header names or derived component IDs ("@method", "@target-uri", "@authority",
             "@scheme", "@request-target", "@path", "@query", "@query-params", "@status", or "@request-response" as