Explain custom auth handlers

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 5c17898e3cec8c74859ef37f1cdf03d0786c9ba8..90d11433872e3a5a9e6c554b2ab8141efbb650ae 100644 (file)
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -157,6 +157,39 @@ And give it a try::
     }
 
 
+Custom Authentication
+---------------------
+
+Requests allows you to use specify your own authentication mechanism.
+
+When you pass our authentication tuple to a request method, the first
+string is the type of authentication. 'basic' is inferred if none is
+provided.
+
+You can pass in a callable object instead of a string for the first item
+in the tuple, and it will be used in place of the built in authentication
+callbacks.
+
+Let's pretend that we have a web service that will only respond if the
+``X-Pizza`` header is set to a password value. Unlikely, but just go with it.
+
+We simply need to define a callback function that will be used to update the
+Request object, right before it is dispatched.
+
+::
+
+    def pizza_auth(r, username):
+        """Attaches HTTP Pizza Authentication to the given Request object.
+        """
+        r.headers['X-Pizza'] = username
+
+        return r
+
+Then, we can make a request using our Pizza Auth::
+
+    >>> requests.get('http://pizzabin.org/admin', auth=(pizza_auth, 'kenneth'))
+    <Response [200]>
+
 
 Verbose Logging
 ---------------

diff --git a/requests/sessions.py b/requests/sessions.py
index 9c7f32c7236fe2a30a3e78eae77ea7bd87db5211..c5cd50153ea1a208002248e7738e308ebde2b853 100644 (file)
--- a/requests/sessions.py
+++ b/requests/sessions.py
@@ -112,7 +112,7 @@ class Session(object):
         :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
         :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
         :param files: (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
-        :param auth: (optional) AuthObject to enable Basic HTTP Auth.
+        :param auth: (optional) Auth typle to enable Basic/Digest/Custom HTTP Auth.
         :param timeout: (optional) Float describing the timeout of the request.
         :param allow_redirects: (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
         :param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.