Improve documentation wrt OAuth.

diff --git a/twitter/__init__.py b/twitter/__init__.py
index d48fd9bfc394c1c71da03d7d592153217144a5a3..ec19917bd8e2fd754bfa580b5a8d58b3ce5091ce 100644 (file)
--- a/twitter/__init__.py
+++ b/twitter/__init__.py
@@ -6,11 +6,14 @@ Twitter-enabled applications.
 
 """
 
+from textwrap import dedent
+
 from .api import Twitter, TwitterError, TwitterHTTPError, TwitterResponse
 from .auth import NoAuth, UserPassAuth
-from .oauth import OAuth, read_token_file, write_token_file
+from .oauth import (OAuth, read_token_file, write_token_file,
+                    __doc__ as oauth_doc)
 from .stream import TwitterStream
-
+from .oauth_dance import oauth_dance
 
 # Who needs Sphinx? Not me!
 
@@ -18,38 +21,38 @@ __doc__ += """
 The Twitter class
 =================
 """
-__doc__ += Twitter.__doc__
+__doc__ += dedent(Twitter.__doc__)
 
 __doc__ += """
 The TwitterStream class
 =======================
 """
-__doc__ += TwitterStream.__doc__
+__doc__ += dedent(TwitterStream.__doc__)
 
 
 __doc__ += """
 Twitter Response Objects
 ========================
 """
-__doc__ += TwitterResponse.__doc__
+__doc__ += dedent(TwitterResponse.__doc__)
 
 
 __doc__ += """
-Authentication Objects
-======================
+Authentication
+==============
 
 You can authenticate with Twitter in three ways: NoAuth, OAuth, or
 UserPassAuth. Get help() on these classes to learn how to use them.
 
+OAuth is probably the most useful.
 
-Other things
-============
 
-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.
+Working with OAuth
+==================
 """
 
+__doc__ += dedent(oauth_doc)
+
 __all__ = ["Twitter", "TwitterStream", "TwitterResponse", "TwitterError",
            "TwitterHTTPError", "NoAuth", "OAuth", "UserPassAuth",
-           "read_token_file", "write_token_file"]
+           "read_token_file", "write_token_file", "oauth_dance"]

diff --git a/twitter/oauth.py b/twitter/oauth.py
index d2df7c121840ec20f02b8e08353db224c79636c4..9ee4fd06ce52879d802a506da8d2084c3c7820a7 100644 (file)
--- 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):

diff --git a/twitter/oauth_dance.py b/twitter/oauth_dance.py
index a013c422f66992642fbb2fdcac52d58a31160fd8..17dbae6f44fce9981a6c7f768d53ceff8a23dc29 100644 (file)
--- a/twitter/oauth_dance.py
+++ b/twitter/oauth_dance.py
@@ -21,7 +21,7 @@ def oauth_dance(app_name, consumer_key, consumer_secret, token_filename=None):
 
     Provide the name of your app in `app_name`, your consumer_key, and
     consumer_secret. This function will open a web browser to let the
-    user Allow your app to access their Twitter account. PIN
+    user allow your app to access their Twitter account. PIN
     authentication is used.
 
     If a token_filename is given, the oauth tokens will be written to

diff --git a/twitter/stream.py b/twitter/stream.py
index ef82a3672199c3726797cb480487c31aaa33c9a8..e60157c43a57b03cb9a773af026d7fdf1fabe4a7 100644 (file)
--- a/twitter/stream.py
+++ b/twitter/stream.py
@@ -60,10 +60,11 @@ class TwitterStreamCallNonBlocking(TwitterCall):
 
 class TwitterStream(TwitterStreamCall):
     """
-    Interface to the Twitter Stream API (stream.twitter.com). This can
-    be used pretty much the same as the Twitter class except the
-    result of calling a method will be an iterator that yields objects
-    decoded from the stream. For example::
+    The TwitterStream object is an interface to the Twitter Stream API
+    (stream.twitter.com). This can be used pretty much the same as the
+    Twitter class except the result of calling a method will be an
+    iterator that yields objects decoded from the stream. For
+    example::
 
         twitter_stream = TwitterStream(auth=UserPassAuth('joe', 'joespassword'))
         iterator = twitter_stream.statuses.sample()