Version 1.17.0

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

diff --git a/twitter/stream.py b/twitter/stream.py
index bc18f8e3fad0f0e8769cfc85b95991db86ea12f9..f7c9419bd406269c0414b210721b20d3c1744a68 100644 (file)
--- a/twitter/stream.py
+++ b/twitter/stream.py
@@ -1,5 +1,7 @@
-import sys
-PY_3_OR_HIGHER = sys.version_info >= (3, 0)
+# encoding: utf-8
+from __future__ import unicode_literals
+
+from .util import PY_3_OR_HIGHER
 
 if PY_3_OR_HIGHER:
     import urllib.request as urllib_request
@@ -81,7 +83,7 @@ class HttpChunkDecoder(object):
 class JsonDecoder(object):
 
     def __init__(self):
-        self.buf = u""
+        self.buf = ""
         self.raw_decode = json.JSONDecoder().raw_decode
 
     def decode(self, data):
@@ -218,7 +220,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