Merge pull request #1009 from Lukasa/master

Auth documentation.

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

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'))
+    <Response [200]>
+
+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'))
+    <Response [200]>
+
+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'))
+    <Response [200]>
+
+
+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
+

docs/user/quickstart.rst

@@ -337,80 +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'))
-    <Response [200]>
-
-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'))
-    <Response [200]>
-
-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'))
-    <Response [200]>
-
-
-OAuth Authentication
---------------------
-
-Requests features robust, built-in OAuth support!
-
-OAuth takes many forms, so let's take a look at a few different forms::
-
-    import requests
-    from requests.auth import OAuth1
-
-    url = u'https://api.twitter.com/1/account/settings.json'
-
-    client_key = u'...'
-    client_secret = u'...'
-    resource_owner_key = u'...'
-    resource_owner_secret = u'...'
-
-
-Query signing::
-
-    queryoauth = OAuth1(client_key, client_secret,
-                        resource_owner_key, resource_owner_secret,
-                        signature_type='query')
-    r = requests.get(url, auth=queryoauth)
-
-Header signing::
-
-    headeroauth = OAuth1(client_key, client_secret,
-                         resource_owner_key, resource_owner_secret,
-                         signature_type='auth_header')
-    r = requests.get(url, auth=headeroauth)
-
-Body signing::
-
-    bodyoauth = OAuth1(client_key, client_secret,
-                       resource_owner_key, resource_owner_secret,
-                       signature_type='body')
-
-    r = requests.post(url, auth=bodyoauth)
-
-
 Redirection and History
 -----------------------