twitter 4.8.1 → 5.0.0.rc.1

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+5.0.0
+-----
+* [Remove `Twitter::API::Undocumented#status_activity` and `#statuses_activity`](https://github.com/sferik/twitter/commit/7f970810af251b2fe80c38b30c54485c55bd2034)
+* [Remove `Twitter::Tweet#favoriters`, `#repliers`, `#repliers_count`, and `#retweeters`](https://github.com/sferik/twitter/commit/77cc963381a68e8299ef6c6b7a306b440666d792)
+* [Remove identity map](https://github.com/sferik/twitter/commit/ec7c2df78a200e2b0b1cd3a40983c6ce9dee552d)
+* [Remove `Twitter::Cursor#all`](https://github.com/sferik/twitter/commit/72be4148b973153c6d3044c406b768ad832555ff)
+* [Remove `Twitter::Cursor#collection`](https://github.com/sferik/twitter/commit/9ae4621610ba6c26950e6b77f950f698cdfc8dac)
+* [Remove `Twitter#from_user`](https://github.com/sferik/twitter/commit/d2ae9f1cc1f5224bcdff06cda65fabdf9e7fbcb3)
+* [Remove `ClientError`, `ServerError`, and `ParserError`](https://github.com/sferik/twitter/commit/72843948d8a6f66345adc254fa91cf1097592b22)
+* [Remove global configuration](https://github.com/sferik/twitter/commit/239c5a8462fabb8c8ef9ec6a4cdded34561d572d)
+* [Replace `multi_json` with `json`](https://github.com/sferik/twitter/commit/e5fc292fee078567664acf6be4ed31a8ad077780)
+* [Rename `oauth_token` to `access_token`](https://github.com/sferik/twitter/commit/d360f8015c487c4599460abd0dd0bc7e59a522a3)
+* [Move `Twitter::Arguments` out of `REST::API` namespace](https://github.com/sferik/twitter/commit/8faa15309d906dd46fccc1b914ea4aa7a5da7c2d)
+* [Move `Twitter::Client` into `REST` namespace](https://github.com/sferik/twitter/commit/5b8c3fd243227888fc0886b0bf864ecd3a018f99)
+* [Add `Twitter::Streaming::Client`](https://github.com/sferik/twitter/commit/23afe90aa494229a4389c3e51f753102b34fc551)
+* [Add `Twitter::Error::AlreadyPosted`](https://github.com/sferik/twitter/commit/e11d2a27dd0dfbbe16c812a81b9c2ab2852a7790)
+* [Add `#url` methods to `Twitter::List`, `Twitter::Tweet`, and `Twitter::User`](https://github.com/sferik/twitter/commit/a89ec0f4e81097cc303b6c204e0375eb57ffd614)
+* [Add `Twitter::Place#contained_within` and `#contained_within?`](https://github.com/sferik/twitter/commit/23cc247bd20001ecbafa544bfb4546bdfc630429)
+* [Add `Twitter::GeoResults`](https://github.com/sferik/twitter/commit/be1a0a1425a6700267aae0f94a8835bff24dad56)
+* [Add `NullObject`](https://github.com/sferik/twitter/commit/17880f491726cee77c1cbcf914887e95d5e6ae7e)
+* [Add predicate methods for any possible `NullObject`](https://github.com/sferik/twitter/commit/eac5522edededacfc2a22d6f6879da43b8136d41)
+* [Always return `URI` instead of `String`](https://github.com/sferik/twitter/commit/341f68d1a46667a820754d30ffa6ec2f50034afc)
+* [Allow `URI` as argument](https://github.com/sferik/twitter/commit/c207567e674f108e4074e12c9e7343fb74e8a97c)
+* [Allow `String` in addition to `URI` objects](https://github.com/sferik/twitter/commit/89a46fbd3560109da87d5f87262dcf6bd2a336c6)
+* [Collection caching](https://github.com/sferik/twitter/commit/d484d7d7d7a0956f9b4fa6791a911ed7c9522cba)
+* [Memoize result within `Twitter::Base#new_or_null_object`](https://github.com/sferik/twitter/commit/45dd18a9feadbb56a60cea76424dd466d3e80c5e)
+* [Implement `Twitter::Cursor#each` without making an extra HTTP request](https://github.com/sferik/twitter/commit/8eeff57f5c6d6ca0a6f1ff5ebc31e652a71fc150)
+* [Make `Twitter::SearchResults` enumerable](https://github.com/sferik/twitter/commit/d5ce8537164912e79dffc5a054ecd9ae6ecb8075)
+* [Fix `Twitter::SearchResults#rpp` return value](https://github.com/sferik/twitter/commit/28d73200490ac2755c3e68d8d273fbc64a8d7066)
+
 4.8.1
 -----
 * [Ignore case of profile image extension](https://github.com/sferik/twitter/commit/73760610e959ae868de23de3da661d237fbcb106)

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2013 John Nunemaker, Wynn Netherland, Erik Michaels-Ober, Steve Richert
+Copyright (c) 2006-2013 Erik Michaels-Ober, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -29,32 +29,6 @@ Then, install the gem with the high security trust policy:
 
     gem install twitter -P HighSecurity
 
-## Quick Start Guide
-So you want to get up and tweeting as fast as possible?
-
-First, [register your application with Twitter][register].
-
-Then, copy and paste in your OAuth data.
-
-```ruby
-Twitter.configure do |config|
-  config.consumer_key = YOUR_CONSUMER_KEY
-  config.consumer_secret = YOUR_CONSUMER_SECRET
-  config.oauth_token = YOUR_OAUTH_TOKEN
-  config.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
-end
-```
-
-That's it! You're ready to Tweet:
-```ruby
-Twitter.update("I'm tweeting with @gem!")
-```
-
-For more examples of how to use the gem, read the [documentation][] or see [Usage Examples][] below.
-
-[register]: https://dev.twitter.com/apps/new
-[Usage Examples]: #usage-examples
-
 ## CLI
 
 Looking for the Twitter command-line interface? It was [removed][] from this
@@ -85,107 +59,411 @@ wiki][apps]!
 
 [apps]: https://github.com/sferik/twitter/wiki/apps
 
-## Configuration
-Twitter API v1.1 requires you to authenticate via OAuth, so you'll need to
-[register your application with Twitter][register]. Once you've registered an
-application, make sure to set the correct access level, otherwise you may see
-the error:
+## What's New in Version 5?
+### Configuration
+Global configuration has been removed, as it was not threadsafe. Instead, you
+can configure a `Twitter::REST::Client` by passing it a block when it's
+initialized.
 
-    Read-only application cannot POST
+```ruby
+client = Twitter::REST::Client.new do |config|
+  config.consumer_key        = "YOUR_CONSUMER_KEY"
+  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
+  config.access_token        = "YOUR_ACCESS_TOKEN"
+  config.access_token_secret = "YOUR_ACCESS_SECRET"
+end
+```
 
-Your new application will be assigned a consumer key/secret pair and you will
-be assigned an OAuth access token/secret pair for that application. You'll need
-to configure these values before you make a request or else you'll get the
-error:
+Alternately, you can configure a `Twitter::REST::Client` piecemeal, after it
+has been initialized, if that better suits your application:
 
-    Bad Authentication data
+```ruby
+client = Twitter::REST::Client.new
+client.consumer_key        = "YOUR_CONSUMER_KEY"
+client.consumer_secret     = "YOUR_CONSUMER_SECRET"
+client.access_token        = "YOUR_ACCESS_TOKEN"
+client.access_token_secret = "YOUR_ACCESS_SECRET"
+```
+
+Note: `oauth_token` has been renamed to `access_token` and `oauth_token_secret`
+is now `access_token_secret` to conform to the terminology used in Twitter's
+developer documentation.
+
+### Streaming (Experimental)
+This library now offers support for the [Twitter Streaming API][streaming]. We
+previously recommended using [TweetStream][] for this, however [TweetStream
+does not work on Ruby 2.0.0][bug].
 
-Applications that make requests on behalf of a single Twitter user can pass
-global configuration options as a block to the `Twitter.configure` method.
+[streaming]: https://dev.twitter.com/docs/streaming-apis
+[tweetstream]: http://rubygems.org/gems/tweetstream
+[bug]: https://github.com/tweetstream/tweetstream/issues/117
+
+Unlike the rest of this library, this feature is not well tested and not
+recommended for production applications. That said, if you need to do Twitter
+streaming on Ruby 2.0.0, this is probably your best option. I've decided to
+ship it as an experimental feature and make it more robust over time. Patches
+in this area are particularly welcome.
+
+Hopefully, by the time version 6 is released, this gem can fully replace
+[TweetStream][], [em-twitter][], [twitterstream][], and [twitter-stream].
+Special thanks to [Steve Agalloco][spagalloco], [Tim Carey-Smith][halorgium],
+and [Tony Arcieri][tarcieri] for helping to develop this feature.
+
+[em-twitter]: http://rubygems.org/gems/em-twitter
+[twitterstream]: http://rubygems.org/gems/twitterstream
+[twitter-stream]: http://rubygems.org/gems/twitter-stream
+[spagalloco]: https://github.com/spagalloco
+[halorgium]: https://github.com/halorgium
+[tarcieri]: https://github.com/tarcieri
+
+**Configuration works just like `Twitter::REST::Client`**
 
 ```ruby
-Twitter.configure do |config|
-  config.consumer_key = YOUR_CONSUMER_KEY
-  config.consumer_secret = YOUR_CONSUMER_SECRET
-  config.oauth_token = YOUR_OAUTH_TOKEN
-  config.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
+client = Twitter::Streaming::Client.new do
+  config.consumer_key        = "YOUR_CONSUMER_KEY"
+  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
+  config.access_token        = "YOUR_ACCESS_TOKEN"
+  config.access_token_secret = "YOUR_ACCESS_SECRET"
 end
 ```
 
-Alternately, you can set the following environment variables:
+**Stream mentions of coffee or tea**
 
-    TWITTER_CONSUMER_KEY
-    TWITTER_CONSUMER_SECRET
-    TWITTER_OAUTH_TOKEN
-    TWITTER_OAUTH_TOKEN_SECRET
+```ruby
+topics = ["coffee", "tea"]
+client.filter(:track => topics.join(",")) do |tweet|
+  puts tweet.text
+end
+```
 
-After configuration, requests can be made like so:
+**Stream a random sample of all tweets**
 
 ```ruby
-Twitter.update("I'm tweeting with @gem!")
+client.sample do |tweet|
+  puts tweet.text
+end
 ```
 
-#### Thread Safety
-Applications that make requests on behalf of multiple Twitter users should
-avoid using global configuration. In this case, you may still specify the
-`consumer_key` and `consumer_secret` globally. (In a Rails application, this
-could go in `config/initializers/twitter.rb`.)
+**Stream tweets for the authenticated user**
 
 ```ruby
-Twitter.configure do |config|
-  config.consumer_key = YOUR_CONSUMER_KEY
-  config.consumer_secret = YOUR_CONSUMER_SECRET
+client.user do |tweet|
+  puts tweet.text
 end
 ```
 
-Then, for each user's access token/secret pair, instantiate a
-`Twitter::Client`:
+Currently, this library will only stream tweets. The goal is to eventually
+handle all [streaming message types][messages]. Patches that add support for a
+new message type would be appreciated.
+
+[messages]: https://dev.twitter.com/docs/streaming-apis/messages
+
+### Cursors
+The `Twitter::Cursor` class has been completely redesigned with a focus on
+simplicity and performance.
+
+[cursors]: https://dev.twitter.com/docs/misc/cursoring
+
+<table>
+  <thead>
+    <tr>
+      <th>Notes</th>
+      <th colspan="2">Version 4</th>
+      <th colspan="2">Version 5</th>
+    </th>
+    <tr>
+      <th></th>
+      <th>Code</th>
+      <th>HTTP GETs</th>
+      <th>Code</th>
+      <th>HTTP GETs</th>
+    </th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        Are you at the start of the cursor?
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.first</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.first?</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Return your most recent follower.
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.users.first</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.first</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Return an array of all your friends.
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.all</code></pre>
+      </td>
+      <td>
+        <em>Θ(n+1)</em>
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.to_a</code></pre>
+      </td>
+      <td>
+        <em>Θ(n)</em>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Collect your 20 most recent friends.
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.take(20)</code></pre>
+      </td>
+      <td>
+        <em>Θ(n+1)</em>
+      </td>
+      <td>
+        <pre><code lang="ruby">client.friends.take(20)</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Collect your 20 most recent friends (twice).
+      </td>
+      <td>
+        <pre><code lang="ruby">friends = client.friends
+2.times.collect do
+  friends.take(20)
+end</code></pre>
+      </td>
+      <td>
+        <em>Θ(2n+2)</em>
+      </td>
+      <td>
+        <pre><code lang="ruby">friends = client.friends
+2.times.collect do
+  friends.take(20)
+end</code></pre>
+      </td>
+      <td>
+        <em>Θ(1)</em>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+In the examples above, *n* varies with the number of people the authenticated
+user follows on Twitter. This resource returns up to 20 friends per HTTP GET,
+so if the authenticated user follows 200 people, calling
+`client.friends.take(20)` would make 11 HTTP requests in version 4. In version
+5, it makes just 1 HTTP request. Keep in mind, eliminating a single HTTP
+request to the Twitter API will reduce the latency of your application by
+[about 500 ms][status].
+
+[status]: https://dev.twitter.com/status
+
+The last example might seem contrived ("Why would I call
+`client.friends.take(20)` twice?") but it applies to any
+[`Enumerable`][enumerable] method you might call on a cursor, including:
+`#all?`, `#collect`, `#count`, `#each`, `#inject`, `#max`, `#min`, `#reject`,
+`#reverse_each`, `#select`, `#sort`, `#sort_by`, and `#to_a`. In version 4,
+each time you called one of those methods, it would perform *n+1* HTTP
+requests. In version 5, it only performs those HTTP requests the first time any
+one of those methods is called. Each subsequent call fetches data from a
+[cache][].
+
+[enumerable]: http://ruby-doc.org/core-2.0/Enumerable.html
+[cache]: https://github.com/sferik/twitter/commit/7d8b2727af9400643ac397207185fd54e3f6387b
+
+The performance improvements are actually even **better** than the table above
+indicates. In version 5, calling `Twitter::Cursor#each` (or any
+[`Enumerable`][enumerable] method) starts yielding results immediately and
+continues yielding as each response comes back from the server. In version 4,
+`#each` made a series of requests and waited for the last one to complete
+before yielding any data.
+
+Here is a list of the interface changes to `Twitter::Cursor`:
+
+* `#all` has been replaced by `#to_a`.
+* `#last` has been replaced by `#last?`.
+* `#first` has been replaced by `#first?`.
+* `#first` now returns the first element in the collection, as prescribed by `Enumerable`.
+* `#collection` and its aliases have been removed.
+
+### Search Results
+The `Twitter::SearchResults` class has also been redesigned to have an
+[`Enumerable`][enumerable] interface. The `#statuses` method and its aliases
+(`#collection` and `#results`) have been replaced by `#to_a`. Additionally,
+this class no longer inherits from `Twitter::Base`. As a result, the `#[]`
+method has been removed.
+
+### Trend Results
+The `#trends` method now returns an [`Enumerable`][enumerable]
+`Twitter::TrendResults` object instead of an array. This object provides
+methods to determinte the recency of the trend (`#as_of`), when the trend
+started (`#created_at`), and the location of the trend (`#location`). This data
+was previously unavailable.
+
+### Geo Results
+Similarly, the `#reverse_geocode`, `#geo_search`, and `#similar_places` methods
+now return an [`Enumerable`][enumerable] `Twitter::GeoResults` object instead
+of an array. This object provides access to the token to create a new place
+(`#token`), which was previously unavailable.
+
+### Tweets
+The `Twitter::Tweet` object has been cleaned up. The following methods have been
+removed:
+
+* `#from_user`
+* `#from_user_id`
+* `#from_user_name`
+* `#to_user`
+* `#to_user_id`
+* `#to_user_name`
+* `#profile_image_url`
+* `#profile_image_url_https`
+
+These attributes can be accessed on the `Twitter::User` object, returned
+through the `#user` method.
+
+### Users
+The `Twitter::User` object has also been cleaned up. The following aliases have
+been removed:
+
+* `#favorite_count` (use `#favorites_count`)
+* `#favoriters_count` (use `#favorites_count`)
+* `#favourite_count` (use `#favourites_count`)
+* `#favouriters_count` (use `#favourites_count`)
+* `#follower_count` (use `#followers_count`)
+* `#friend_count` (use `#friends_count`)
+* `#status_count` (use `#statuses_count`)
+* `#tweet_count` (use `#tweets_count`)
+* `#update_count` (use `#tweets_count`)
+* `#updates_count` (use `#tweets_count`)
+* `#translator` (use `#translator?`)
+
+### Errors
+The `Twitter::Error::ClientError` and `Twitter::Error::ServerError` class
+hierarchy has been removed. All errors now inherit directly from
+`Twitter::Error`.
+
+### Null Objects
+In version 4, methods you would expect to return a `Twitter` object would
+return `nil` if that object was missing. This may have resulted in a
+`NoMethodError`. To prevent such errors, you may have introduced checks for the
+truthiness of the response, for example:
 
 ```ruby
-erik = Twitter::Client.new(
-  :oauth_token => "Erik's access token",
-  :oauth_token_secret => "Erik's access secret"
-)
+status = client.status(55709764298092545)
+if status.place
+  # Do something with the Twitter::Place object
+elsif status.geo
+  # Do something with the Twitter::Geo object
+end
+```
+In version 5, all such methods will return a `Twitter::NullObject` instead of
+`nil`. This should prevent `NoMethodError` but may result in unexpected
+behavior if you have truthiness checks in place, since everything is truthy in
+Ruby except `false` and `nil`. For these cases, there are now predicate
+methods:
 
-john = Twitter::Client.new(
-  :oauth_token => "John's access token",
-  :oauth_token_secret => "John's access secret"
-)
+```ruby
+status = client.status(55709764298092545)
+if status.place?
+  # Do something with the Twitter::Place object
+elsif status.geo?
+  # Do something with the Twitter::Geo object
+end
 ```
 
-You can now make threadsafe requests as the authenticated user:
+### URI Methods
+The `Twitter::List`, `Twitter::Tweet`, and `Twitter::User` objects all have a
+`#uri` method, which returns an HTTPS URI to twitter.com. This clobbers the
+`Twitter::List#uri` method, which previously returned the list URI's path (not
+a URI).
+
+These methods are aliased to `#url` for users who prefer that nomenclature.
+`Twitter::User` previously had a `#url` method, which returned the user's
+website. This URI is now available via the `#website` method.
+
+All `#uri` methods now return `URI` objects instead of strings. To convert a
+`URI` object to a string, call `#to_s` on it.
+
+## Configuration
+Twitter API v1.1 requires you to authenticate via OAuth, so you'll need to
+[register your application with Twitter][register]. Once you've registered an
+application, make sure to set the correct access level, otherwise you may see
+the error:
+
+[register]: https://dev.twitter.com/apps
+
+    Read-only application cannot POST
+
+Your new application will be assigned a consumer key/secret pair and you will
+be assigned an OAuth access token/secret pair for that application. You'll need
+to configure these values before you make a request or else you'll get the
+error:
+
+    Bad Authentication data
+
+You can pass configuration options as a block to `Twitter::REST::Client.new`.
 
 ```ruby
-Thread.new{erik.update("Tweeting as Erik!")}
-Thread.new{john.update("Tweeting as John!")}
+client = Twitter::REST::Client.new do |config|
+  config.consumer_key = YOUR_APP_CONSUMER_KEY
+  config.consumer_secret = YOUR_APP_CONSUMER_SECRET
+  config.access_token = A_USER_ACCESS_TOKEN
+  config.access_token_secret = A_USER_ACCESS_SECRET
+end
 ```
 
-Or, if you prefer, you can specify all configuration options when instantiating
-a `Twitter::Client`:
+Alternately, you can set the following environment variables:
+
+    TWITTER_CONSUMER_KEY
+    TWITTER_CONSUMER_SECRET
+    TWITTER_ACCESS_TOKEN
+    TWITTER_ACCESS_TOKEN_SECRET
+
+After configuration, requests can be made like so:
 
 ```ruby
-client = Twitter::Client.new(
-  :consumer_key => "an application's consumer key",
-  :consumer_secret => "an application's consumer secret",
-  :oauth_token => "a user's access token",
-  :oauth_token_secret => "a user's access secret"
-)
+client.update("I'm tweeting with @gem!")
 ```
 
-This may be useful if you're using multiple consumer key/secret pairs.
-
-#### Middleware
+### Middleware
 The Faraday middleware stack is fully configurable and is exposed as a
 `Faraday::Builder` object. You can modify the default middleware in-place:
 
 ```ruby
-Twitter.middleware.insert_after Twitter::Response::RaiseError, CustomMiddleware
+client.middleware.insert_after Twitter::Response::RaiseError, CustomMiddleware
 ```
 
 A custom adapter may be set as part of a custom middleware stack:
 
 ```ruby
-Twitter.middleware = Faraday::Builder.new(
+client.middleware = Faraday::Builder.new(
   &Proc.new do |builder|
     # Specify a middleware stack here
     builder.adapter :some_other_adapter
@@ -195,114 +473,81 @@ Twitter.middleware = Faraday::Builder.new(
 
 ## Usage Examples
 All examples require an authenticated Twitter client. See the section on <a
-href="#configuration">configuration</a> above.
+href="#configuration">configuration</a>.
 
 **Tweet (as the authenticated user)**
 
 ```ruby
-Twitter.update("I'm tweeting with @gem!")
+client.update("I'm tweeting with @gem!")
 ```
 **Follow a user (by screen name or user ID)**
 
 ```ruby
-Twitter.follow("gem")
-Twitter.follow(213747670)
+client.follow("gem")
+client.follow(213747670)
 ```
 **Fetch a user (by screen name or user ID)**
 
 ```ruby
-Twitter.user("gem")
-Twitter.user(213747670)
+client.user("gem")
+client.user(213747670)
 ```
 **Fetch a cursored list of followers with profile details (by screen name or user ID, or by implict authenticated user)**
 
 ```ruby
-Twitter.followers("gem")
-Twitter.followers(213747670)
-Twitter.followers
+client.followers("gem")
+client.followers(213747670)
+client.followers
 ```
 **Fetch a cursored list of friends with profile details (by screen name or user ID, or by implict authenticated user)**
 
 ```ruby
-Twitter.friends("gem")
-Twitter.friends(213747670)
-Twitter.friends
+client.friends("gem")
+client.friends(213747670)
+client.friends
 ```
 
 **Fetch a collection of user_ids that the currently authenticated user does not want to receive retweets from**
 
 ```ruby
-Twitter.no_retweet_ids
+client.no_retweet_ids
 ````
 
 **Fetch the timeline of Tweets by a user**
 
 ```ruby
-Twitter.user_timeline("gem")
-Twitter.user_timeline(213747670)
+client.user_timeline("gem")
+client.user_timeline(213747670)
 ```
 **Fetch the timeline of Tweets from the authenticated user's home page**
 
 ```ruby
-Twitter.home_timeline
+client.home_timeline
 ```
 **Fetch the timeline of Tweets mentioning the authenticated user**
 
 ```ruby
-Twitter.mentions_timeline
+client.mentions_timeline
 ```
 **Fetch a particular Tweet by ID**
 
 ```ruby
-Twitter.status(27558893223)
+client.status(27558893223)
 ```
-**Find the 3 most recent marriage proposals to @justinbieber**
+**Collect the 3 most recent marriage proposals to @justinbieber**
 
 ```ruby
-Twitter.search("to:justinbieber marry me", :count => 3, :result_type => "recent").results.map do |status|
-  "#{status.from_user}: #{status.text}"
+client.search("to:justinbieber marry me", :count => 3, :result_type => "recent").collect do |tweet|
+  "#{tweet.user.screen_name}: #{tweet.text}"
 end
 ```
 **Find a Japanese-language Tweet tagged #ruby (excluding retweets)**
 
 ```ruby
-Twitter.search("#ruby -rt", :lang => "ja", :count => 1).results.first.text
+client.search("#ruby -rt", :lang => "ja").first.text
 ```
 For more usage examples, please see the full [documentation][].
 
-## Streaming
-To access the Twitter Streaming API, we recommend [TweetStream][].
-
-[tweetstream]: https://github.com/intridea/tweetstream
-
-## Performance
-You can improve performance by loading a faster JSON parsing library. By
-default, JSON will be parsed with [okjson][]. For faster JSON parsing, we
-recommend [Oj][].
-
-[okjson]: https://github.com/ddollar/okjson
-[oj]: https://rubygems.org/gems/oj
-
-## Statistics
-Here are some fun facts about this library:
-
-* It is implemented in just 2,000 lines of Ruby code
-* With over 5,000 lines of specs, the spec-to-code ratio is about 2.5:1
-* The spec suite contains over 750 examples and runs in about 5 seconds
-* It has 100% C0 code coverage (the tests execute every line of
-  source code at least once)
-* It is comprehensive: you can request all documented Twitter REST API
-  resources (over 100 resources)
-* This gem works on every major Ruby implementation, including JRuby and
-  Rubinius
-* The first version was released on November 26, 2006
-* This gem has just three runtime dependencies: `faraday`, `multi_json`, and
-  `simple_oauth`
-* Previous versions of this gem have been [downloaded over half a million
-  times][stats]
-
-[stats]: https://rubygems.org/gems/twitter
-
 ## Supported Ruby Versions
 This library aims to support and is [tested against][travis] the following Ruby
 implementations:
@@ -340,133 +585,8 @@ Constraint][pvc] with two digits of precision. For example:
 [semver]: http://semver.org/
 [pvc]: http://docs.rubygems.org/read/chapter/16#page74
 
-## What's new in version 4?
-#### Twitter API v1.1
-Version 4 of this library targets Twitter API v1.1. To understand the
-implications of this change, please read the following announcements from
-Twitter:
-
-* [Changes coming in Version 1.1 of the Twitter API][coming]
-* [Current status: API v1.1][status]
-* [Overview: Version 1.1 of the Twitter API][overview]
-
-[coming]: https://dev.twitter.com/blog/changes-coming-to-twitter-api
-[status]: https://dev.twitter.com/blog/current-status-api-v1.1
-[overview]: https://dev.twitter.com/docs/api/1.1/overview
-
-Despite the removal of certain underlying functionality in Twitter API v1.1,
-this library aims to preserve backward-compatibility wherever possible. For
-example, despite the removal of the [`GET
-statuses/retweeted_by_user`][retweeted_by_user] resource, the
-`Twitter::API#retweeted_by_user` method continues to exist, implemented by
-making multiple requests to the [`GET statuses/user_timeline`][user_timeline]
-resource. As a result, there is no longer a one-to-one correlation between
-method calls and Twitter API requests. In fact, it's possible for a single
-method call to exceed the Twitter API rate limit for a resource. If you think
-this might cause a problem for your application, feel free to [join the
-discussion][discussion].
-
-[retweeted_by_user]: https://dev.twitter.com/docs/api/1/get/statuses/retweeted_by_user
-[user_timeline]: https://dev.twitter.com/docs/api/1.1/get/statuses/user_timeline
-[discussion]: https://dev.twitter.com/discussions/10644
-
-#### Rate Limiting
-Another consequence of Twitter API v1.1 is that the
-`Twitter::Client#rate_limit` method has been removed, since the concept of a
-client-wide rate limit no longer exists. Rate limits are now applied on a
-per-resource level, however, since there is no longer a one-to-one mapping
-between methods and Twitter API resources, it's not entirely obvious how rate
-limit information should be exposed. I've decided to go back to the pre-3.0.0
-behavior of including rate limit information on `Twitter::Error` objects.
-Here's an example of how to handle rate limits:
-
-```ruby
-MAX_ATTEMPTS = 3
-num_attempts = 0
-begin
-  num_attempts += 1
-  retweets = Twitter.retweeted_by_user("sferik")
-rescue Twitter::Error::TooManyRequests => error
-  if num_attempts <= MAX_ATTEMPTS
-    # NOTE: Your process could go to sleep for up to 15 minutes but if you
-    # retry any sooner, it will almost certainly fail with the same exception.
-    sleep error.rate_limit.reset_in
-    retry
-  else
-    raise
-  end
-end
-```
-#### Methods Missing
-As a consequence of moving to Twitter API v1.1, the following methods from
-version 3 are no longer available in version 4:
-
-* `Twitter::API#accept`
-* `Twitter::API#deny`
-* `Twitter::API#disable_notifications`
-* `Twitter::API#enable_notifications`
-* `Twitter::API#end_session`
-* `Twitter::API#rate_limit_status`
-* `Twitter::API#rate_limited?`
-* `Twitter::API#recommendations`
-* `Twitter::API#related_results`
-* `Twitter::API#retweeted_to_user`
-* `Twitter::API#trends_daily`
-* `Twitter::API#trends_weekly`
-* `Twitter::Client#rate_limit`
-* `Twitter::RateLimit#class`
-
-#### Custom Endpoints
-The `Twitter::API#update_with_media` method no longer uses the custom
-`upload.twitter.com` endpoint, so `media_endpoint` configuration has been
-removed. Likewise, the `Twitter::API#search` method no longer uses the custom
-`search.twitter.com` endpoint, so `search_endpoint` configuration has also been
-removed.
-
-#### Errors
-It's worth mentioning new error classes:
-
-* `Twitter::Error::GatewayTimeout`
-* `Twitter::Error::TooManyRequests`
-* `Twitter::Error::UnprocessableEntity`
-
-In previous versions of this library, rate limit errors were indicated by
-raising either `Twitter::Error::BadRequest` or
-`Twitter::Error::EnhanceYourCalm` (for the Search API). As of version 4, the
-library will raise `Twitter::Error::TooManyRequests` for all rate limit errors.
-The `Twitter::Error::EnhanceYourCalm` class has been aliased to
-`Twitter::Error::TooManyRequests`.
-
-#### Identity Map
-In version 4, the identity map is [disabled by default][disabled]. If you want
-to enable this feature, you can use the [default identity map][default] or
-[write a custom identity map][custom].
-
-```ruby
-Twitter.identity_map = Twitter::IdentityMap
-```
-
-[disabled]: https://github.com/sferik/twitter/commit/c6c5960bea998abdc3e82cbb8dd68766a2df52e1
-[default]: lib/twitter/identity_map.rb
-[custom]: etc/sqlite_identity_map.rb
-
-## Additional Notes
-This will be the last major version of this library to support Ruby 1.8.
-Requiring Ruby 1.9 will allow us to [remove][class_variable_get]
-[various][each_with_object] [hacks][singleton_class] put in place to maintain
-Ruby 1.8 compatibility. [The first stable version of Ruby 1.9 was released on
-August 19, 2010.][ruby192] If you haven't found the opportunity to upgrade your
-Ruby interpreter since then, let this be your nudge. Once version 5 of this
-library is released, all previous versions will cease to be supported, even if
-critical security vulnerabilities are discovered.
-
-[class_variable_get]: https://github.com/sferik/twitter/commit/88c5a0513d1b58a1d4ae1a1e3deeb012c9d19547
-[each_with_object]: https://github.com/sferik/twitter/commit/6052252a07baf7aefe0f100bba0abd2cbb7139bb
-[singleton_class]: https://github.com/sferik/twitter/commit/2ed9db21c87d1218b15373e42a36ad536b07dcbb
-[ruby192]: http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/367983
-
 ## Copyright
-Copyright (c) 2006-2013 John Nunemaker, Wynn Netherland, Erik Michaels-Ober, Steve Richert.
+Copyright (c) 2006-2013 Erik Michaels-Ober, John Nunemaker, Wynn Netherland, Steve Richert, Steve Agalloco.
 See [LICENSE][] for details.
 
 [license]: LICENSE.md