1 .. -*- restructuredtext -*-

     2 

     3 ##########################################

     4 tweetstream - Simple twitter streaming API

     5 ##########################################

     6 

     7 Introduction

     8 ------------

     9 

    10 tweetstream provides two classes, SampleStream and FollowStream, that can be

    11 used to get tweets from Twitter's streaming API. An instance of one of the

    12 classes can be used as an iterator. In addition to fetching tweets, the 

    13 object keeps track of the number of tweets collected and the rate at which

    14 tweets are received.

    15 

    16 SampleStream delivers a sample of all tweets. FilterStream delivers

    17 tweets that match one or more criteria. Note that it's not possible

    18 to get all tweets without access to the "firehose" stream, which

    19 is not currently avaliable to the public.

    20 

    21 Twitter's documentation about the streaming API can be found here:

    22 http://dev.twitter.com/pages/streaming_api_methods .

    23 

    24 **Note** that the API is blocking. If for some reason data is not immediatly

    25 available, calls will block until enough data is available to yield a tweet.

    26 

    27 Examples

    28 --------

    29 

    30 Printing incoming tweets:

    31 

    32 >>> stream = tweetstream.SampleStream("username", "password")

    33 >>> for tweet in stream:

    34 ...     print tweet

    35 

    36 

    37 The stream object can also be used as a context, as in this example that

    38 prints the author for each tweet as well as the tweet count and rate:

    39 

    40 >>> with tweetstream.SampleStream("username", "password") as stream

    41 ...     for tweet in stream:

    42 ...         print "Got tweet from %-16s\t( tweet %d, rate %.1f tweets/sec)" % (

    43 ...                 tweet["user"]["screen_name"], stream.count, stream.rate )

    44 

    45 

    46 Stream objects can raise ConnectionError or AuthenticationError exceptions:

    47 

    48 >>> try:

    49 ...     with tweetstream.TweetStream("username", "password") as stream

    50 ...         for tweet in stream:

    51 ...             print "Got tweet from %-16s\t( tweet %d, rate %.1f tweets/sec)" % (

    52 ...                     tweet["user"]["screen_name"], stream.count, stream.rate )

    53 ... except tweetstream.ConnectionError, e:

    54 ...     print "Disconnected from twitter. Reason:", e.reason

    55 

    56 To get tweets that match specific criteria, use the FilterStream. FilterStreams

    57 take three keyword arguments: "locations", "follow" and "track".

    58 

    59 Locations are a list of bounding boxes in which geotagged tweets should originate.

    60 The argument should be an iterable of longitude/latitude pairs.

    61 

    62 Track specifies keywords to track. The argument should be an iterable of

    63 strings.

    64 

    65 Follow returns statuses that reference given users. Argument should be an iterable

    66 of twitter user IDs. The IDs are userid ints, not the screen names. 

    67 

    68 >>> words = ["opera", "firefox", "safari"]

    69 >>> people = [123,124,125]

    70 >>> locations = ["-122.75,36.8", "-121.75,37.8"]

    71 >>> with tweetstream.FilterStream("username", "password", track=words,

    72 ...                               follow=people, locations=locations) as stream

    73 ...     for tweet in stream:

    74 ...         print "Got interesting tweet:", tweet

    75 

    76 

    77 Deprecated classes

    78 ------------------

    79 

    80 tweetstream used to contain the classes TweetStream, FollowStream, TrackStream

    81 LocationStream and ReconnectingTweetStream. These were deprecated when twitter

    82 changed its API end points. The same functionality is now available in

    83 SampleStream and FilterStream. The deprecated methods will emit a warning when

    84 used, but will remain functional for a while longer.

    85 

    86 

    87 Changelog

    88 ---------

    89 

    90 See the CHANGELOG file

    91 

    92 Contact

    93 -------

    94 

    95 The author is Rune Halvorsen <runefh@gmail.com>. The project resides at

    96 http://bitbucket.org/runeh/tweetstream . If you find bugs, or have feature

    97 requests, please report them in the project site issue tracker. Patches are

    98 also very welcome.

    99 

   100 Contributors

   101 ------------

   102 

   103 - Rune Halvorsen

   104 - Christopher Schierkolk

   105 

   106 License

   107 -------

   108 

   109 This software is licensed under the ``New BSD License``. See the ``LICENCE``

   110 file in the top distribution directory for the full license text.