From: Mike Helmick <mikeh@ydekproductions.com>
Date: Thu, 11 Apr 2013 03:49:27 +0000 (-0300)
Subject: Fix Advanced docs Twitter Streaming example
X-Git-Tag: v1.2.1~16^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=ed0242ae3a6f30202983aef6938bebadf655ef67;p=services%2Fpython-requests.git

Fix Advanced docs Twitter Streaming example

Twitter API v1.1 Streaming now requires OAuth Authentication rather than XAuth.
I believe v1 is being blacked out sometime at the beginning of May.
---

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 21bfa7b..79c9d41 100644
--- a/docs/user/advanced.rst
+++ b/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
diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst
index a3b5b56..d25f373 100644
--- a/docs/user/authentication.rst
+++ b/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