From 58b1c69b6a40749f7dcc03f6489e5486e50f7ea2 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 23 Oct 2011 15:13:34 -0400 Subject: [PATCH] Explain custom auth handlers --- docs/user/advanced.rst | 33 +++++++++++++++++++++++++++++++++ requests/sessions.py | 2 +- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 5c17898..90d1143 100644 --- 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')) + + Verbose Logging --------------- diff --git a/requests/sessions.py b/requests/sessions.py index 9c7f32c..c5cd501 100644 --- 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. -- 2.34.1