README.md in twitter-4.0.0 vs README.md in twitter-4.1.0

- old
+ new

@@ -5,11 +5,11 @@ [travis]: http://travis-ci.org/sferik/twitter [gemnasium]: https://gemnasium.com/sferik/twitter [codeclimate]: https://codeclimate.com/github/sferik/twitter -#### A Ruby interface to the Twitter API. +A Ruby interface to the Twitter API. ## Installation ```sh gem install twitter ``` @@ -61,11 +61,11 @@ [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 remove of the [`GET +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 @@ -92,11 +92,11 @@ MAX_ATTEMPTS = 3 num_attempts = 0 begin num_attempts += 1 retweets = Twitter.retweeted_by_user("sferik") -rescue Twitter::Error::RateLimited => error +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 @@ -134,21 +134,22 @@ `search.twitter.com` endpoint, so `search_endpoint` configuration has also been removed. ### Errors -It's worth mentioning two new error classes: +It's worth mentioning new error classes: * `Twitter::Error::GatewayTimeout` -* `Twitter::Error::RateLimited` +* `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::RateLimited` for all rate limit errors. The -`Twitter::Error::EnhanceYourCalm` class has been aliased to -`Twitter::Error::RateLimited`. +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 @@ -162,13 +163,30 @@ [default]: https://github.com/sferik/twitter/blob/master/lib/twitter/identity_map.rb [custom]: https://github.com/sferik/twitter/blob/master/etc/sqlite_identity_map.rb ## Configuration -Applications that make requests on behalf of one Twitter user at a time can -pass global configuration options as a block to the `Twitter.configure` method. +Twitter API v1.1 requires you to authenticate via OAuth, so you'll need a +registered Twitter application. To register a new application, sign-in using +your Twitter account and the fill out the form at +http://dev.twitter.com/apps/new. If you've previously registered a Twitter +application, it will be listed at http://dev.twitter.com/apps. Once you've +registered an application, make sure to set the correct access level, otherwise +you may see the error: + 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 + +Applications that make requests on behalf of a single Twitter user can pass +global configuration options as a block to the `Twitter.configure` method. + ```ruby Twitter.configure do |config| config.consumer_key = YOUR_CONSUMER_KEY config.consumer_secret = YOUR_CONSUMER_SECRET config.oauth_token = YOUR_OAUTH_TOKEN @@ -189,56 +207,55 @@ ```ruby Twitter.update("I'm tweeting with @gem!") ``` -### Threadsafe Configuration +### Thread Safety Applications that make requests on behalf of multiple Twitter users should -avoid using global configuration. Instead, instantiate a `Twitter::Client` for -each user, passing in the user's token/secret pair as a `Hash`. +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/initiliazers/twitter.rb`.) -You can still specify the `consumer_key` and `consumer_secret` globally. (In a -Rails application, this could go in `config/initiliazers/twitter.rb`.) - ```ruby Twitter.configure do |config| config.consumer_key = YOUR_CONSUMER_KEY config.consumer_secret = YOUR_CONSUMER_SECRET end ``` -Then, for each user's token/secret pair, instantiate a `Twitter::Client`: +Then, for each user's access token/secret pair, instantiate a +`Twitter::Client`: ```ruby -@erik = Twitter::Client.new( - :oauth_token => "Erik's OAuth token", - :oauth_token_secret => "Erik's OAuth secret" +@client_erik = Twitter::Client.new( + :oauth_token => "Erik's access token", + :oauth_token_secret => "Erik's access secret" ) -@john = Twitter::Client.new( - :oauth_token => "John's OAuth token", - :oauth_token_secret => "John's OAuth secret" +@client_john = Twitter::Client.new( + :oauth_token => "John's access token", + :oauth_token_secret => "John's access secret" ) ``` -You can now make threadsafe requests as the authenticated user like so: +You can now make threadsafe requests as the authenticated user: ```ruby -@erik.update("Tweeting as Erik!") -@john.update("Tweeting as John!") +Thread.new{@client_erik.update("Tweeting as Erik!")} +Thread.new{@client_john.update("Tweeting as John!")} ``` Or, if you prefer, you can specify all configuration options when instantiating a `Twitter::Client`: ```ruby @client = Twitter::Client.new( - :consumer_key => "a consumer key", - :consumer_secret => "a consumer secret", - :oauth_token => "a user's OAuth token", - :oauth_token_secret => "a user's OAuth secret" + :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" ) ``` This may be useful if you're using multiple consumer key/secret pairs. @@ -261,68 +278,81 @@ end ) ``` ## Usage Examples -###### Return a user's location +All examples require an authenticated Twitter client. See the section on <a +href="#configuration">configuration</a> above. + +**Tweet (as the authenticated user)** + ```ruby -Twitter.user("sferik").location +Twitter.update("I'm tweeting with @gem!") ``` -###### Return a user's most recent Tweet +**Follow a user (by screen name or user ID)** + ```ruby -Twitter.user_timeline("sferik").first.text +Twitter.follow("gem") +Twitter.follow(213747670) ``` -###### Return the text of a Tweet +**Fetch a user (by screen name or user ID)** + ```ruby -Twitter.status(27558893223).text +Twitter.user("gem") +Twitter.user(213747670) ``` -###### Find the 3 most recent marriage proposals to @justinbieber +**Fetch the timeline of Tweets by a user** + ```ruby -Twitter.search("to:justinbieber marry me", :count => 3, :result_type => "recent").results.map do |status| - "#{status.from_user}: #{status.text}" -end +Twitter.user_timeline("gem") +Twitter.user_timeline(213747670) ``` -###### Find a Japanese-language Tweet tagged #ruby (excluding retweets) +**Fetch the timeline of Tweets from the authenticated user's home page** + ```ruby -Twitter.search("#ruby -rt", :lang => "ja", :count => 1).results.first.text +Twitter.home_timeline ``` -###### Update your status +**Fetch the timeline of Tweets mentioning the authenticated user** + ```ruby -Twitter.update("I'm tweeting with @gem!") +Twitter.mentions_timeline ``` -###### Read the most recent Tweet in your timeline +**Fetch a particular Tweet by ID** + ```ruby -Twitter.home_timeline.first.text +Twitter.status(27558893223) +``` +**Find the 3 most recent marriage proposals to @justinbieber** -For more usage examples, please see the full [documentation][]. +```ruby +Twitter.search("to:justinbieber marry me", :count => 3, :result_type => "recent").results.map do |status| + "#{status.from_user}: #{status.text}" +end ``` +**Find a Japanese-language Tweet tagged #ruby (excluding retweets)** +```ruby +Twitter.search("#ruby -rt", :lang => "ja", :count => 1).results.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 -## 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. +## Statistics -[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 - -## Stats - 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 over 2.5:1 * The spec suite contains over 600 examples and runs in under 2 seconds @@ -337,60 +367,10 @@ * Previous versions of this gem have been [downloaded over half a million times][stats] [stats]: https://rubygems.org/gems/twitter -## Contributing -In the spirit of [free software][free-sw], **everyone** is encouraged to help -improve this project. - -[free-sw]: http://www.fsf.org/licensing/essays/free-sw.html - -Here are some ways *you* can contribute: - -* by using alpha, beta, and prerelease versions -* by reporting bugs -* by suggesting new features -* by writing or editing documentation -* by writing specifications -* by writing code (**no patch is too small**: fix typos, add comments, clean up - inconsistent whitespace) -* by refactoring code -* by fixing [issues][] -* by reviewing patches - -[issues]: https://github.com/sferik/twitter/issues - -## Submitting an Issue -We use the [GitHub issue tracker][issues] to track bugs and features. Before -submitting a bug report or feature request, check to make sure it hasn't -already been submitted. When submitting a bug report, please include a [Gist][] -that includes a stack trace and any details that may be necessary to reproduce -the bug, including your gem version, Ruby version, and operating system. -Ideally, a bug report should include a pull request with failing specs. - -[gist]: https://gist.github.com/ - -## Submitting a Pull Request -1. [Fork the repository.][fork] -2. [Create a topic branch.][branch] -3. Add specs for your unimplemented feature or bug fix. -4. Run `bundle exec rake spec`. If your specs pass, return to step 3. -5. Implement your feature or bug fix. -6. Run `bundle exec rake spec`. If your specs fail, return to step 5. -7. Run `open coverage/index.html`. If your changes are not completely covered - by your tests, return to step 3. -8. Add documentation for your feature or bug fix. -9. Run `bundle exec rake yard`. If your changes are not 100% documented, go - back to step 8. -10. Add, commit, and push your changes. -11. [Submit a pull request.][pr] - -[fork]: http://help.github.com/fork-a-repo/ -[branch]: http://learn.github.com/p/branching.html -[pr]: http://help.github.com/send-pull-requests/ - ## Supported Ruby Versions This library aims to support and is [tested against][travis] the following Ruby version: * Ruby 1.8.7 @@ -405,9 +385,24 @@ volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be personally responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped. + +## 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-2012 John Nunemaker, Wynn Netherland, Erik Michaels-Ober, Steve Richert. See [LICENSE][] for details.