added timeout option to TwitterStream

[z_archive/twitter.git] / README

diff --git a/README b/README
index 0d92a87365c091f0b0e39c2ee649cbce474682cc..8e3a5346109e5e4953df8eda4cb385f6d889abc5 100644 (file)
--- a/README
+++ b/README
@@ -191,6 +191,38 @@ The `block` parameter controls if the stream is blocking. Default
 is blocking (True). When set to False, the iterator will
 occasionally yield None when there is no available message.
 
+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 retreive all new direct messages
+from the user stream:
+
+```python
+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']
+```
+
 Twitter Response Objects
 ------------------------