From: Mike Verdone <redacted>
Date: Tue, 29 Mar 2011 20:08:44 +0000 (+0200)
Subject: Improve documentation.
X-Git-Tag: twitter-1.6^0
X-Git-Url: https://jfr.im/git/z_archive/twitter.git/commitdiff_plain/249508919a85673ed16c9661815697aada5462b5

Improve documentation.
---

diff --git a/twitter/__init__.py b/twitter/__init__.py
index 8f31181..d48fd9b 100644
--- a/twitter/__init__.py
+++ b/twitter/__init__.py
@@ -1,15 +1,55 @@
 """
 The minimalist yet fully featured Twitter API and Python toolset.
 
-The Twitter class is the key to building your own Twitter-enabled
-applications. Get help on it like this::
-
-    help(twitter.Twitter)
-
+The Twitter and TwitterStream classes are the key to building your own
+Twitter-enabled applications.
 
 """
 
 from .api import Twitter, TwitterError, TwitterHTTPError, TwitterResponse
-from .auth import NoAuth
+from .auth import NoAuth, UserPassAuth
 from .oauth import OAuth, read_token_file, write_token_file
 from .stream import TwitterStream
+
+
+# Who needs Sphinx? Not me!
+
+__doc__ += """
+The Twitter class
+=================
+"""
+__doc__ += Twitter.__doc__
+
+__doc__ += """
+The TwitterStream class
+=======================
+"""
+__doc__ += TwitterStream.__doc__
+
+
+__doc__ += """
+Twitter Response Objects
+========================
+"""
+__doc__ += TwitterResponse.__doc__
+
+
+__doc__ += """
+Authentication Objects
+======================
+
+You can authenticate with Twitter in three ways: NoAuth, OAuth, or
+UserPassAuth. Get help() on these classes to learn how to use them.
+
+
+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.
+"""
+
+__all__ = ["Twitter", "TwitterStream", "TwitterResponse", "TwitterError",
+           "TwitterHTTPError", "NoAuth", "OAuth", "UserPassAuth",
+           "read_token_file", "write_token_file"]
diff --git a/twitter/stream.py b/twitter/stream.py
index 2c60918..295e490 100644
--- a/twitter/stream.py
+++ b/twitter/stream.py
@@ -35,6 +35,21 @@ class TwitterStreamCall(TwitterCall):
         return iter(TwitterJSONIter(handle, uri, arg_data))
 
 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::
+
+        twitter_stream = TwitterStream(auth=UserPassAuth('joe', 'joespassword'))
+        iterator = twitter_stream.statuses.sample()
+
+        for tweet in iterator:
+            ...do something with this tweet...
+
+    The iterator will yield tweets forever and ever (until the stream
+    breaks at which point it raises a TwitterHTTPError.)
+    """
     def __init__(
         self, domain="stream.twitter.com", secure=False, auth=None,
         api_version='1'):