Clean up documentation and README

[z_archive/twitter.git] / twitter / stream.py

diff --git a/twitter/stream.py b/twitter/stream.py
index 6a7753a77733a1b2672ef2c638df3f434523a5d4..5384d5b865df3f70947a232261aac46815ee6b1c 100644 (file)
--- a/twitter/stream.py
+++ b/twitter/stream.py
@@ -221,7 +221,37 @@ class TwitterStream(TwitterCall):
         iterator = twitter_stream.statuses.sample()
 
         for tweet in iterator:
-            ...do something with this tweet...
+            # ...do something with this tweet...
+
+    Per default the ``TwitterStream`` object uses
+    [public streams](https://dev.twitter.com/docs/streaming-apis/streams/public).
+    If you want to use one of the other
+    [streaming APIs](https://dev.twitter.com/docs/streaming-apis), specify the URL
+    manually:
+
+    - [Public streams](https://dev.twitter.com/docs/streaming-apis/streams/public): stream.twitter.com
+    - [User streams](https://dev.twitter.com/docs/streaming-apis/streams/user): userstream.twitter.com
+    - [Site streams](https://dev.twitter.com/docs/streaming-apis/streams/site): sitestream.twitter.com
+
+    Note that you require the proper
+    [permissions](https://dev.twitter.com/docs/application-permission-model) to
+    access these streams. E.g. for direct messages your
+    [application](https://dev.twitter.com/apps) needs the "Read, Write & Direct
+    Messages" permission.
+
+    The following example demonstrates how to retrieve all new direct messages
+    from the user stream::
+
+        auth = OAuth(
+            consumer_key='[your consumer key]',
+            consumer_secret='[your consumer secret]',
+            token='[your token]',
+            token_secret='[your token secret]'
+        )
+        twitter_userstream = TwitterStream(auth=auth, domain='userstream.twitter.com')
+        for msg in twitter_userstream.user():
+            if 'direct_message' in msg:
+                print msg['direct_message']['text']
 
     The iterator will yield until the TCP connection breaks. When the
     connection breaks, the iterator yields `{'hangup': True}`, and