--- a/script/lib/tweetstream/README	Tue Jan 18 18:25:18 2011 +0100
+++ b/script/lib/tweetstream/README	Fri Jul 01 10:15:32 2011 +0200
@@ -7,19 +7,19 @@
 Introduction
 ------------
 
-tweetstream provides a class, TweetStream, that can be used to get
-tweets from Twitter's streaming API. An instance of the class can be used as
-an iterator. In addition to fetching tweets, the object keeps track of
-the number of tweets collected and the rate at which tweets are received.
+tweetstream provides two classes, SampleStream and FollowStream, that can be
+used to get tweets from Twitter's streaming API. An instance of one of the
+classes can be used as an iterator. In addition to fetching tweets, the 
+object keeps track of the number of tweets collected and the rate at which
+tweets are received.
 
-Subclasses are available for accessing the "track" and "follow" streams
-as well.
-
-There's also a ReconnectingTweetStream class that handles automatic
-reconnecting.
+SampleStream delivers a sample of all tweets. FilterStream delivers
+tweets that match one or more criteria. Note that it's not possible
+to get all tweets without access to the "firehose" stream, which
+is not currently avaliable to the public.
 
 Twitter's documentation about the streaming API can be found here:
-http://apiwiki.twitter.com/Streaming-API-Documentation .
+http://dev.twitter.com/pages/streaming_api_methods .
 
 **Note** that the API is blocking. If for some reason data is not immediatly
 available, calls will block until enough data is available to yield a tweet.
@@ -27,9 +27,9 @@
 Examples
 --------
 
-Printing all incomming tweets:
+Printing incoming tweets:
 
->>> stream = tweetstream.TweetStream("username", "password")
+>>> stream = tweetstream.SampleStream("username", "password")
 >>> for tweet in stream:
 ...     print tweet
 
@@ -37,7 +37,7 @@
 The stream object can also be used as a context, as in this example that
 prints the author for each tweet as well as the tweet count and rate:
 
->>> with tweetstream.TweetStream("username", "password") as stream
+>>> with tweetstream.SampleStream("username", "password") as stream
 ...     for tweet in stream:
 ...         print "Got tweet from %-16s\t( tweet %d, rate %.1f tweets/sec)" % (
 ...                 tweet["user"]["screen_name"], stream.count, stream.rate )
@@ -53,36 +53,35 @@
 ... except tweetstream.ConnectionError, e:
 ...     print "Disconnected from twitter. Reason:", e.reason
 
-To get tweets that relate to specific terms, use the TrackStream:
+To get tweets that match specific criteria, use the FilterStream. FilterStreams
+take three keyword arguments: "locations", "follow" and "track".
+
+Locations are a list of bounding boxes in which geotagged tweets should originate.
+The argument should be an iterable of longitude/latitude pairs.
+
+Track specifies keywords to track. The argument should be an iterable of
+strings.
+
+Follow returns statuses that reference given users. Argument should be an iterable
+of twitter user IDs. The IDs are userid ints, not the screen names. 
 
 >>> words = ["opera", "firefox", "safari"]
->>> with tweetstream.TrackStream("username", "password", words) as stream
+>>> people = [123,124,125]
+>>> locations = ["-122.75,36.8", "-121.75,37.8"]
+>>> with tweetstream.FilterStream("username", "password", track=words,
+...                               follow=people, locations=locations) as stream
 ...     for tweet in stream:
 ...         print "Got interesting tweet:", tweet
 
-To get only tweets from a set of users, use the FollowStream. The following
-would get tweets for user 1, 42 and 8675309
 
->>> users = [1, 42, 8675309]
->>> with tweetstream.FollowStream("username", "password", users) as stream
-...     for tweet in stream:
-...         print "Got  tweet from:", tweet["user"]["screen_name"]
-
-
-Simple tweet fetcher that sends tweets to an AMQP message server using carrot:
+Deprecated classes
+------------------
 
->>> from carrot.messaging import Publisher
->>> from carrot.connection import AMQPConnection
->>> from tweetstream import TweetStream
->>> amqpconn = AMQPConnection(hostname="localhost", port=5672,
-...                           userid="test", password="test",
-...                           vhost="test")
->>> publisher = Publisher(connection=amqpconn,
-...                       exchange="tweets", routing_key="stream")
->>> with TweetStream("username", "password") as stream:
-...    for tweet in stream:
-...        publisher.send(tweet)
->>> publisher.close()
+tweetstream used to contain the classes TweetStream, FollowStream, TrackStream
+LocationStream and ReconnectingTweetStream. These were deprecated when twitter
+changed its API end points. The same functionality is now available in
+SampleStream and FilterStream. The deprecated methods will emit a warning when
+used, but will remain functional for a while longer.
 
 
 Changelog
@@ -98,6 +97,12 @@
 requests, please report them in the project site issue tracker. Patches are
 also very welcome.
 
+Contributors
+------------
+
+- Rune Halvorsen
+- Christopher Schierkolk
+
 License
 -------