|
1 .. -*- restructuredtext -*- |
|
2 |
|
3 ########################################## |
|
4 tweetstream - Simple twitter streaming API |
|
5 ########################################## |
|
6 |
|
7 Introduction |
|
8 ------------ |
|
9 |
|
10 tweetstream provides a class, TweetStream, that can be used to get |
|
11 tweets from Twitter's streaming API. An instance of the class can be used as |
|
12 an iterator. In addition to fetching tweets, the object keeps track of |
|
13 the number of tweets collected and the rate at which tweets are received. |
|
14 |
|
15 Subclasses are available for accessing the "track" and "follow" streams |
|
16 as well. |
|
17 |
|
18 There's also a ReconnectingTweetStream class that handles automatic |
|
19 reconnecting. |
|
20 |
|
21 Twitter's documentation about the streaming API can be found here: |
|
22 http://apiwiki.twitter.com/Streaming-API-Documentation . |
|
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 all incomming tweets: |
|
31 |
|
32 >>> stream = tweetstream.TweetStream("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.TweetStream("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 relate to specific terms, use the TrackStream: |
|
57 |
|
58 >>> words = ["opera", "firefox", "safari"] |
|
59 >>> with tweetstream.TrackStream("username", "password", words) as stream |
|
60 ... for tweet in stream: |
|
61 ... print "Got interesting tweet:", tweet |
|
62 |
|
63 To get only tweets from a set of users, use the FollowStream. The following |
|
64 would get tweets for user 1, 42 and 8675309 |
|
65 |
|
66 >>> users = [1, 42, 8675309] |
|
67 >>> with tweetstream.FollowStream("username", "password", users) as stream |
|
68 ... for tweet in stream: |
|
69 ... print "Got tweet from:", tweet["user"]["screen_name"] |
|
70 |
|
71 |
|
72 Simple tweet fetcher that sends tweets to an AMQP message server using carrot: |
|
73 |
|
74 >>> from carrot.messaging import Publisher |
|
75 >>> from carrot.connection import AMQPConnection |
|
76 >>> from tweetstream import TweetStream |
|
77 >>> amqpconn = AMQPConnection(hostname="localhost", port=5672, |
|
78 ... userid="test", password="test", |
|
79 ... vhost="test") |
|
80 >>> publisher = Publisher(connection=amqpconn, |
|
81 ... exchange="tweets", routing_key="stream") |
|
82 >>> with TweetStream("username", "password") as stream: |
|
83 ... for tweet in stream: |
|
84 ... publisher.send(tweet) |
|
85 >>> publisher.close() |
|
86 |
|
87 |
|
88 Changelog |
|
89 --------- |
|
90 |
|
91 See the CHANGELOG file |
|
92 |
|
93 Contact |
|
94 ------- |
|
95 |
|
96 The author is Rune Halvorsen <runefh@gmail.com>. The project resides at |
|
97 http://bitbucket.org/runeh/tweetstream . If you find bugs, or have feature |
|
98 requests, please report them in the project site issue tracker. Patches are |
|
99 also very welcome. |
|
100 |
|
101 License |
|
102 ------- |
|
103 |
|
104 This software is licensed under the ``New BSD License``. See the ``LICENCE`` |
|
105 file in the top distribution directory for the full license text. |