From: Cory Benfield Date: Mon, 17 Dec 2012 19:25:21 +0000 (+0000) Subject: Split authentication out into a separate file. X-Git-Tag: v1.0.3~5^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a7c5d5e8ac7b4fac71352ef359a5af6b812a9a4c;p=services%2Fpython-requests.git Split authentication out into a separate file. --- diff --git a/docs/index.rst b/docs/index.rst index 64929d1..cd0a0f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,6 +90,7 @@ instructions for getting the most out of Requests. user/install user/quickstart user/advanced + user/authentication Community Guide diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst new file mode 100644 index 0000000..a3b5b56 --- /dev/null +++ b/docs/user/authentication.rst @@ -0,0 +1,84 @@ +.. _authentication: + +Authentication +============== + +This document discusses using various kinds of authentication with Requests. + +Many web services require authentication, and there are many different types. +Below, we outline various forms of authentication available in Requests, from +the simple to the complex. + + +Basic Authentication +-------------------- + +Many web services that require authentication accept HTTP Basic Auth. This is +the simplest kind, and Requests supports it straight out of the box. + +Making requests with HTTP Basic Auth is very simple:: + + >>> from requests.auth import HTTPBasicAuth + >>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass')) + + +In fact, HTTP Basic Auth is so common that Requests provides a handy shorthand +for using it:: + + >>> requests.get('https://api.github.com/user', auth=('user', 'pass')) + + +Providing the credentials in a tuple like this is exactly the same as the +``HTTPBasicAuth`` example above. + + +Digest Authentication +--------------------- + +Another very popular form of HTTP Authentication is Digest Authentication, +and Requests supports this out of the box as well:: + + >>> from requests.auth import HTTPDigestAuth + >>> url = 'http://httpbin.org/digest-auth/auth/user/pass' + >>> requests.get(url, auth=HTTPDigestAuth('user', 'pass')) + + + +Other Authentication +-------------------- + +Requests is designed to allow other forms of authentication to be easily and +quickly plugged in. Members of the open-source community frequently write +authentication handlers for more complicated or less commonly-used forms of +authentication. Some of the best have been brought together under the +`Requests organization`_, including: + +- OAuth_ +- Kerberos_ +- NTLM_ + +If you want to use any of these forms of authentication, go straight to their +Github page and follow the instructions. + + +New Forms of Authentication +--------------------------- + +If you can't find a good implementation of the form of authentication you +want, you can implement it yourself. Requests makes it easy to add your own +forms of authentication. + +To do so, subclass :class:`requests.auth.AuthBase` and implement the +``__call__()`` method. When an authentication handler is attached to a request, +it is called during request setup. The ``__call__`` method must therefore do +whatever is required to make the authentication work. Some forms of +authentication will additionally add hooks to provide further functionality. + +Examples can be found under the `Requests organization`_ and in the +``auth.py`` file. + +.. _OAuth: https://github.com/requests/requests-oauthlib +.. _Kerberos: https://github.com/requests/requests-kerberos +.. _NTLM: https://github.com/requests/requests-ntlm +.. _Requests organization: https://github.com/requests + diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 5f6e6a2..1731b29 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -337,62 +337,6 @@ parameter:: '{"cookies": {"cookies_are": "working"}}' -Basic Authentication --------------------- - -Many web services require authentication. There are many different types of -authentication, but the most common is HTTP Basic Auth. - -Making requests with Basic Auth is extremely simple:: - - >>> from requests.auth import HTTPBasicAuth - >>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass')) - - -Due to the prevalence of HTTP Basic Auth, requests provides a shorthand for -this authentication method:: - - >>> requests.get('https://api.github.com/user', auth=('user', 'pass')) - - -Providing the credentials as a tuple in this fashion is functionally equivalent -to the ``HTTPBasicAuth`` example above. - - -Digest Authentication ---------------------- - -Another popular form of web service protection is Digest Authentication:: - - >>> from requests.auth import HTTPDigestAuth - >>> url = 'http://httpbin.org/digest-auth/auth/user/pass' - >>> requests.get(url, auth=HTTPDigestAuth('user', 'pass')) - - - -Other Authentication --------------------- - -Requests is designed to allow other forms of authentication to be easily and -quickly plugged in. Members of the open-source community frequently write -authentication handlers for more complicated or less commonly-used forms of -authentication. Some of the best have been brought together under a single -`organization on Github`_, including: - -- OAuth_ -- Kerberos_ -- NTLM_ - -If you want to use any of these forms of authentication, go straight to their -Github page and follow the instructions. If you can't find the one you want, -why not write one and submit it? - -.. _OAuth: https://github.com/requests/requests-oauthlib -.. _Kerberos: https://github.com/requests/requests-kerberos -.. _NTLM: https://github.com/requests/requests-ntlm -.. _organization on Github: https://github.com/requests - - Redirection and History -----------------------