Merge pull request #1305 from michaelhelmick/patch-1

Fix Advanced docs Twitter Streaming example

docs/user/advanced.rst

@@ -278,9 +278,17 @@ To use the Twitter Streaming API to track the keyword "requests"::
 
     import requests
     import json
+    from requests_oauthlib import OAuth1
 
-    r = requests.post('https://stream.twitter.com/1/statuses/filter.json',
-        data={'track': 'requests'}, auth=('username', 'password'), stream=True)
+    app_key = 'YOUR_APP_KEY'
+    app_secret = 'YOUR_APP_SECRET'
+    oauth_token = 'USER_OAUTH_TOKEN'
+    oauth_token_secret = 'USER_OAUTH_TOKEN_SECRET'
+
+    auth = OAuth1(app_key, app_secret, oauth_token, oauth_token_secret)
+
+    r = requests.post('https://stream.twitter.com/1.1/statuses/filter.json',
+                      data={'track': 'requests'}, auth=auth, stream=True)
 
     for line in r.iter_lines():
         if line: # filter out keep-alive new lines

docs/user/authentication.rst

@@ -44,6 +44,25 @@ and Requests supports this out of the box as well::
     <Response [200]>
 
 
+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::
+
+    >>> import request
+    >>> from requests_oauthlib import OAuth1
+
+    >>> url = 'https://api.twitter.com/1.1/account/verify_credentials.json'
+    >>> auth = OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET',
+                      'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')
+
+    >>> requests.get(url, auth=auth)
+    <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
+
+
 Other Authentication
 --------------------
 
@@ -53,7 +72,6 @@ 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_
 
@@ -77,7 +95,8 @@ 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
+.. _OAuth: http://oauth.net/
+.. _requests_oauthlib: 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