Improve documentation.

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

diff --git a/twitter/stream.py b/twitter/stream.py
index 68ec018ff934d2f112b1004a860590efc594d7cc..295e49062ea6187747a502efb395cc75240bc3ad 100644 (file)
--- a/twitter/stream.py
+++ b/twitter/stream.py
@@ -1,6 +1,7 @@
 try:
     import urllib.request as urllib_request
     import urllib.error as urllib_error
+    import io
 except ImportError:
     import urllib2 as urllib_request
     import urllib2 as urllib_error
@@ -13,15 +14,15 @@ class TwitterJSONIter(object):
     def __init__(self, handle, uri, arg_data):
         self.decoder = json.JSONDecoder()
         self.handle = handle
-        self.buf = ""
+        self.buf = b""
 
     def __iter__(self):
         while True:
-            # This might need better py3 IO
             self.buf += self.handle.read(1024)
             try:
-                res, ptr = self.decoder.raw_decode(self.buf)
-                self.buf = self.buf[ptr + 2:] # +2 is for \r\n
+                utf8_buf = self.buf.decode('utf8').lstrip()
+                res, ptr = self.decoder.raw_decode(utf8_buf)
+                self.buf = utf8_buf[ptr:].encode('utf8')
                 yield wrap_response(res, self.handle.headers)
             except ValueError as e:
                 continue
@@ -34,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'):