X-Git-Url: https://jfr.im/git/z_archive/twitter.git/blobdiff_plain/8df7be82b941c4b1c83bbfe9ed06a4026f3c08e2..a6a7f7632ec022aceebb4a23fadcdc698029f581:/twitter/oauth.py

diff --git a/twitter/oauth.py b/twitter/oauth.py
index d2df7c1..9ee4fd0 100644
--- a/twitter/oauth.py
+++ b/twitter/oauth.py
@@ -1,6 +1,43 @@
-from __future__ import print_function
+"""
+Visit the Twitter developer page and create a new application:
+
+    https://dev.twitter.com/apps/new
+
+This will get you a CONSUMER_KEY and CONSUMER_SECRET.
+
+When users run your application they have to authenticate your app
+with their Twitter account. A few HTTP calls to twitter are required
+to do this. Please see the twitter.oauth_dance module to see how this
+is done. If you are making a command-line app, you can use the
+oauth_dance() function directly.
+
+Performing the "oauth dance" gets you an ouath token and oauth secret
+that authenticate the user with Twitter. You should save these for
+later so that the user doesn't have to do the oauth dance again.
+
+read_token_file and write_token_file are utility methods to read and
+write OAuth token and secret key values. The values are stored as
+strings in the file. Not terribly exciting.
+
+Finally, you can use the OAuth authenticator to connect to Twitter. In
+code it all goes like this::
 
-from twitter.auth import Auth
+    MY_TWITTER_CREDS = os.path.expanduser('~/.my_app_credentials')
+    if not os.path.exists(MY_TWITTER_CREDS):
+        oauth_dance("My App Name", CONSUMER_KEY, CONSUMER_SECRET,
+                    MY_TWITTER_CREDS)
+
+    oauth_token, oauth_secret = read_token_file(MY_TWITTER_CREDS)
+
+    twitter = Twitter(auth=OAuth(
+        oauth_token, oauth_token_secret, CONSUMER_KEY, CONSUMER_SECRET))
+
+    # Now work with Twitter
+    twitter.statuses.update('Hello, world!')
+
+"""
+
+from __future__ import print_function
 
 from time import time
 from random import getrandbits
@@ -18,6 +55,7 @@ import hashlib
 import hmac
 import base64
 
+from .auth import Auth
 
 
 def write_token_file(filename, oauth_token, oauth_token_secret):