Merge pull request #1477 from dpursehouse/other-auth-basic-example

Add a simple example of custom authentication in the documentation

docs/user/authentication.rst

@@ -58,7 +58,8 @@ and Requests supports this out of the box as well::
 OAuth 1 Authentication
 ----------------------
 
-A common form of authentication for several web APIs is OAuth. The ``requests-oauthlib`` library allows Requests users to easily make OAuth authenticated requests::
+A common form of authentication for several web APIs is OAuth. The ``requests-oauthlib``
+library allows Requests users to easily make OAuth authenticated requests::
 
     >>> import requests
     >>> from requests_oauthlib import OAuth1
@@ -71,7 +72,8 @@ A common form of authentication for several web APIs is OAuth. The ``requests-oa
     <Response [200]>
 
 For more information on how to OAuth flow works, please see the official `OAuth`_ website.
-For examples and documentation on requests-oauthlib, please see the `requests_oauthlib`_ repository on GitHub
+For examples and documentation on requests-oauthlib, please see the `requests_oauthlib`_
+repository on GitHub
 
 
 Other Authentication
@@ -98,12 +100,24 @@ 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,
+``__call__()`` method::
+
+    >>> import requests
+    >>> class MyAuth(requests.auth.AuthBase):
+    ...     def __call__(self, r):
+    ...         # Implement my authentication
+    ...         return r
+    ...
+    >>> url = 'http://httpbin.org/get'
+    >>> requests.get(url, auth=MyAuth())
+    <Response [200]>
+
+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
+Further examples can be found under the `Requests organization`_ and in the
 ``auth.py`` file.
 
 .. _OAuth: http://oauth.net/