jcrossley-twitter-search 0.5.8

data/CHANGELOG.textile

@@ -0,0 +1,32 @@
+h2. 0.5.8 (June 30, 2009)
+
+* subclass Tweets and Trends from Array. (Dan Croak)
+* change test suite to use cURL'd JSON fixtures & Fakeweb for just HTTP calls
+for more surgical tests. (Dan Croak)
+
+h2. 0.5.7 (June 30, 2009)
+
+* improved Fakeweb usage. (Matt Jankowski)
+* account for possible 403 response, plus user-friendly message. (Matt Jankowski)
+
+h2. 0.5.6 (June 6, 2009)
+
+* When Twitter returns a 404, raise a TwitterSearch::SearchServerError instead
+of a JSON parse error. (Luke Francl)
+
+h2. 0.5.5 (May 18, 2009)
+
+* raise error when query contains :near or :within:. (Dan Croak)
+
+h2. 0.5.4 (May 16, 2009)
+
+* Fixed bug in Twitter trends. (Dan Croak)
+* Refactored test suite. Now organized by function, uses redgreen, began moving toward using JSON instead of YAML for fixtures. (Dan Croak)
+* Exposed Shoulda Macros to apps that want to use them. (Dan Croak)
+
+h2. 0.5.3 (May 15, 2009)
+
+* Added Twitter trends. (Matt Sanford)
+* Added overdue attribution for Luke Francl, Matt Sanford, Alejandro Crosa, Danny Burkes, Don Brown, & HotFusionMan.
+* Added CHANGELOG. (Dan Croak)
+

data/README.markdown

@@ -0,0 +1,112 @@
+# A Twitter Search client for Ruby.
+
+Access the Twitter Search API from your Ruby code.
+
+## Usage
+
+Install the gem.
+
+    sudo gem install dancroak-twitter-search -s http://gems.github.com
+
+Require the gem.
+
+    require 'twitter_search'
+
+Set up a TwitterSearch::Client. Name your client (a.k.a. 'user agent') to something meaningful, such as your app's name. This helps Twitter Search answer any questions about your use of the API.
+
+    client = TwitterSearch::Client.new('thunderthimble')
+
+### Search
+
+Request tweets by calling the query method of your client. It takes either a String or a Hash of arguments.
+
+    tweets = client.query('twitter search')
+
+The String form uses the default Twitter Search behavior, which in this example finds tweets containing both "twitter" and "search". It is identical to the more verbose, explicit version:
+
+    tweets = client.query(:q => 'twitter search')
+
+Use the Twitter Search API's query operators with the :q key to access a variety of behavior.
+
+### Trends
+
+Request the current trending topics by calling the trends method of your client. It takes an optional Hash of arguments.
+
+    trends = client.trends
+
+The only supported option currently is exclude_hashtags to return trends that are not hashtags only.
+
+    trends = client.trends(:exclude_hashtags => true)
+
+## Search Operators
+
+The following operator examples find tweets...
+
+* <a href="http://search.twitter.com/search?q=twitter+search">:q => 'twitter search'</a> - containing both "twitter" and "search". This is the default operator. 
+* <a href="http://search.twitter.com/search?q=%22happy+hour%22">:q => '<b>"</b>happy hour<b>"</b>'</a> - containing the exact phrase "happy hour".
+* <a href="http://search.twitter.com/search?q=obama+OR+hillary">:q => 'obama <b>OR</b> hillary'</a> - containing either "obama" or "hillary" (or both).
+* <a href="http://search.twitter.com/search?q=beer+-root">:q => 'beer <b>-</b>root'</a> - containing "beer" but not "root".
+* <a href="http://search.twitter.com/search?q=%23haiku">:q => '<b>#</b>haiku</a>' - containing the hashtag "haiku".
+* <a href="http://search.twitter.com/search?q=from%3Aalexiskold">:q => '<b>from:</b>alexiskold'</a> - sent from person "alexiskold".
+* <a href="http://search.twitter.com/search?q=to%3Atechcrunch">:q => '<b>to:</b>techcrunch</a>' - sent to person "techcrunch".
+* <a href="http://search.twitter.com/search?q=%40mashable">:q => '<b>@</b>mashable</a>' - referencing person "mashable".
+* <a href="http://search.twitter.com/search?q=superhero+since%3A2008-05-01">:q => 'superhero <b>since:</b>2008-05-01'</a> - containing "superhero" and sent since date "2008-05-01" (year-month-day).
+* <a href="http://search.twitter.com/search?q=ftw+until%3A2008-05-03">:q => 'ftw <b>until:</b>2008-05-03'</a> - containing "ftw" and sent up to date "2008-05-03".
+* <a href="http://search.twitter.com/search?q=movie+-scary+%3A%29">:q => 'movie -scary <b>:)</b>'</a> - containing "movie", but not "scary", and with a positive attitude.
+* <a href="http://search.twitter.com/search?q=flight+%3A%28">:q => 'flight <b>:(</b>'</a> - containing "flight" and with a negative attitude.
+* <a href="http://search.twitter.com/search?q=traffic+%3F">:q => 'traffic <b>?</b>'</a> - containing "traffic" and asking a question.
+* <a href="http://search.twitter.com/search?q=hilarious+filter%3Alinks">:q => 'hilarious <b>filter:links</b>'</a> - containing "hilarious" and linking to URLs.
+
+### Foreign Languages
+
+The Twitter Search API supports foreign languages, accessible via the :lang key. Use the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) codes as the value:
+
+    tweets = client.query(:q => 'programmé', :lang => 'fr')
+
+### Pagination
+
+Alter the number of Tweets returned per page with the :rpp key. Stick with 10, 15, 20, 25, 30, or 50.
+
+    tweets = client.query(:q => 'Boston Celtics', :rpp => '30')
+
+## Gotchas
+
+* Searches are case-insenstive.
+* The "near" operator available in the Twitter Search web interface is not available via the API. You must geocode before making your Twitter Search API call, and use the :geocode key in your request using the pattern lat,lngmi or lat,lngkm:
+
+    tweets = client.query(:q => 'Pearl Jam', :geocode => '43.4411,-70.9846mi')
+
+* Searching for a positive attitude :) returns tweets containing the text :), =), :D, and :-)
+
+## Contributing
+
+Get the source and clone it.
+
+The test suite uses JSON fixtures which were created from cURL. Usage example:
+
+    query   = { :q => 'rails training' }
+    fake_query(query, 'rails_training.json')
+    @tweets = TwitterSearch::Client.new.query(query)
+
+Then you assert any necessary expectations on @tweets.
+
+To create your own JSON fixtures, first get the CGI escaped querystring in irb:
+
+    require 'lib/twitter_search'
+    TwitterSearch::Client.new.sanitize_query({ :q => 'rails training' })
+
+Then take the output and append it to a simple cURL, sending the output into your new file:
+
+    curl -i 'http://search.twitter.com/search.json?q=rails+training' > test/json/rails_training.json
+
+## Contributors
+
+Dustin Sallings, Dan Croak, Luke Francl, Matt Jankowski, Matt Sanford, Alejandro Crosa, Danny Burkes, Don Brown, & HotFusionMan.
+
+## Resources
+
+* [Official Twitter Search API](http://apiwiki.twitter.com/Twitter-API-Documentation)
+
+## License
+
+MIT License, same terms as Ruby.

data/Rakefile

@@ -0,0 +1,71 @@
+require 'rake'
+require 'rake/testtask'
+require 'rubygems'
+
+test_files_pattern = 'test/*_test.rb'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = test_files_pattern
+  t.verbose = false
+end
+
+desc "Run the test suite"
+task :default => :test
+
+gem_spec = Gem::Specification.new do |gem_spec|
+  gem_spec.name        = "jcrossley-twitter-search"
+  gem_spec.version     = "0.5.8"
+  gem_spec.summary     = "Ruby client for Twitter Search. Includes trends."
+  gem_spec.email       = "dcroak@thoughtbot.com"
+  gem_spec.homepage    = "http://github.com/jcrossley/twitter-search"
+  gem_spec.description = "Ruby client for Twitter Search."
+  gem_spec.authors     = ["Dustin Sallings", "Dan Croak", "Luke Francl", "Matt Jankowski", "Matt Sanford", "Alejandro Crosa", "Danny Burkes", "Don Brown", "HotFusionMan"]
+  gem_spec.files       = FileList["[A-Z]*", "{lib,shoulda_macros}/**/*"]
+  gem_spec.add_dependency('json', '>= 1.1.2')
+end
+
+desc "Generate a gemspec file"
+task :gemspec do
+  File.open("#{gem_spec.name}.gemspec", 'w') do |f|
+    f.write gem_spec.to_yaml
+  end
+end
+
+require File.expand_path('lib/twitter_search', File.dirname(__FILE__))
+require 'rubygems'
+require 'yaml'
+
+namespace :yaml do
+  desc "Write Twitter Search results to yaml file so API is not hit every test."
+  task :write do
+    write_yaml :tweets => 'Obama',                                     :file => 'obama'
+    write_yaml :tweets => 'twitter search',                            :file => 'twitter_search'
+    write_yaml :tweets => {:q => 'twitter search'},                    :file => 'twitter_search_and'
+    write_yaml :tweets => {:q => '"happy hour"'},                      :file => 'happy_hour_exact'  
+    write_yaml :tweets => {:q => 'obama OR hillary'},                  :file => 'obama_or_hillary'
+    write_yaml :tweets => {:q => 'beer -root'},                        :file => 'beer_minus_root'
+    write_yaml :tweets => {:q => '#haiku'},                            :file => 'hashtag_haiku'
+    write_yaml :tweets => {:q => 'from:alexiskold'},                   :file => 'from_alexiskold'
+    write_yaml :tweets => {:q => 'to:techcrunch'},                     :file => 'to_techcrunch'
+    write_yaml :tweets => {:q => '@mashable'},                         :file => 'reference_mashable'
+    write_yaml :tweets => {:q => '"happy hour" near:"san francisco"'}, :file => 'happy_hour_near_sf'
+    write_yaml :tweets => {:q => 'near:NYC within:15mi'},              :file => 'within_15mi_nyc'
+    write_yaml :tweets => {:q => 'superhero since:2008-05-01'},        :file => 'superhero_since'
+    write_yaml :tweets => {:q => 'ftw until:2008-05-03'},              :file => 'ftw_until'
+    write_yaml :tweets => {:q => 'movie -scary :)'},                   :file => 'movie_positive_tude'
+    write_yaml :tweets => {:q => 'flight :('},                         :file => 'flight_negative_tude'
+    write_yaml :tweets => {:q => 'traffic ?'},                         :file => 'traffic_question'
+    write_yaml :tweets => {:q => 'hilarious filter:links'},            :file => 'hilarious_links'
+    write_yaml :tweets => {:q => 'congratulations', :lang => 'en'},    :file => 'english'
+    write_yaml :tweets => {:q => 'با', :lang => 'ar'},                 :file => 'arabic'
+    write_yaml :tweets => {:q => 'Boston Celtics', :rpp => '30'},      :file => 'results_per_page'
+  end
+end
+
+def write_yaml(opts = {})
+  @client = TwitterSearch::Client.new 'twitter-search'
+  tweets  = @client.query(opts[:tweets])
+  File.open(File.join(File.dirname(__FILE__), 'test', 'yaml', "#{opts[:file]}.yaml"), 'w+') do |file|
+    file.puts tweets.to_yaml
+  end
+end

data/TODO.markdown

@@ -0,0 +1,7 @@
+Add tests for:
+
+* since_id: returns tweets with status ids greater than the given id.
+* geocode: returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile.
+* show_user: when "true", adds "<user>:" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is "false".
+* callback: if supplied, the response will use the JSONP format with a callback of the given name. E.g., http://search.twitter.com/search.json?callback=foo&q=twitter
+

data/lib/trends.rb

@@ -0,0 +1,24 @@
+module TwitterSearch
+  class Trend
+    VARS = [:query, :name]
+    attr_reader *VARS
+    attr_reader :exclude_hashtags
+
+    def initialize(opts)
+      @exclude_hashtags = !!opts['exclude_hashtags']
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+  end
+
+  class Trends < Array
+    VARS = [:date]
+    attr_reader *VARS
+
+    def initialize(opts)
+      trends = opts('trends').delete
+      trends = trends.values.first.collect { |each| Trend.new(each) }
+      super(trends)
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+  end
+end

data/lib/tweets.rb

@@ -0,0 +1,43 @@
+module TwitterSearch
+  class Tweet
+    VARS = [:text, :from_user, :to_user, :to_user_id, :id, :iso_language_code, :from_user_id, :created_at, :profile_image_url, :source, :geo ]
+    attr_reader *VARS
+    attr_reader :language
+
+    def initialize(opts)
+      @language = opts['iso_language_code']                   
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+
+ 	
+    def eql?(other)
+      self.hash == other.hash
+    end
+
+    def hash
+      @id
+    end
+
+  end
+
+  class Tweets < Array
+    VARS = [:since_id, :max_id, :results_per_page, :page, :query, :next_page]
+    attr_reader *VARS
+
+    def initialize(opts)
+      results = opts.delete('results') || []
+      results.collect! { |each| Tweet.new(each) }
+      super(results)
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+
+    def has_next_page?
+      ! @next_page.nil?
+    end
+
+    def get_next_page
+      client = Client.new
+      return client.query( CGI.parse( @next_page[1..-1] ) )
+    end
+  end
+end

data/lib/twitter_search.rb

@@ -0,0 +1,114 @@
+require 'rubygems'
+require 'net/http'
+require 'json'
+require 'cgi'
+
+require File.join(File.dirname(__FILE__), 'tweets')
+require File.join(File.dirname(__FILE__), 'trends')
+
+module TwitterSearch
+  class SearchOperatorError < ArgumentError
+  end
+  class SearchServerError < RuntimeError
+  end
+  class RateLimitError < SearchServerError
+    attr_reader :retry_after
+    def initialize(retry_after)
+      super "Twitter has rate limited your IP address; wait #{retry_after} seconds before retry."
+      @retry_after = retry_after.to_i
+    end
+  end
+
+  class Client
+    TWITTER_SEARCH_API_URL = 'http://search.twitter.com/search.json'
+    TWITTER_TRENDS_API_URL = 'http://search.twitter.com/trends/current.json'
+    DEFAULT_TIMEOUT = 5
+
+    attr_accessor :agent
+    attr_accessor :timeout
+
+    def initialize(agent = 'twitter-search', timeout = DEFAULT_TIMEOUT)
+      @agent   = agent
+      @timeout = timeout
+    end
+
+    def headers
+      { "Content-Type" => 'application/json',
+        "User-Agent"   => @agent }
+    end
+
+    def query(opts = {})
+      url       = URI.parse(TWITTER_SEARCH_API_URL)
+      url.query = sanitize_query(opts)
+
+      ensure_no_location_operators(url.query)
+
+      req  = Net::HTTP::Get.new(url.path)
+      http = Net::HTTP.new(url.host, url.port)
+      http.read_timeout = timeout
+
+      res = http.start { |http|
+        http.get("#{url.path}?#{url.query}", headers)
+      }
+
+      if res.code == '404'
+        raise TwitterSearch::SearchServerError,
+              "Twitter responded with a 404 for your query."
+      end
+
+      if res.code == '420'
+        raise TwitterSearch::RateLimitError.new(res['retry-after'])
+      end
+
+      json        = res.body
+      parsed_json = JSON.parse(json)
+
+      if parsed_json['error']
+        raise TwitterSearch::SearchServerError,
+              "Twitter responded with an error body: #{parsed_json['error']}"
+      end
+
+      Tweets.new parsed_json
+    end
+
+    def trends(opts = {})
+      url = URI.parse(TWITTER_TRENDS_API_URL)
+      if opts['exclude_hashtags']
+        url.query = sanitize_query_hash({ :exclude_hashtags => opts['exclude_hashtags'] })
+      end
+
+      req  = Net::HTTP::Get.new(url.path)
+      http = Net::HTTP.new(url.host, url.port)
+      http.read_timeout = timeout
+
+      json = http.start { |http|
+        http.get("#{url.path}?#{url.query}", headers)
+      }.body
+
+      Trends.new JSON.parse(json)
+    end
+
+    def sanitize_query(opts)
+      if opts.is_a? String
+        "q=#{CGI.escape(opts)}"
+      elsif opts.is_a? Hash
+        "#{sanitize_query_hash(opts)}"
+      end
+    end
+
+    def sanitize_query_hash(query_hash)
+      query_hash.collect { |key, value|
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      }.join('&')
+    end
+
+    def ensure_no_location_operators(query_string)
+      if query_string.include?("near%3A") ||
+         query_string.include?("within%3A")
+        raise TwitterSearch::SearchOperatorError,
+          "near: and within: are available from the Twitter Search web interface, but not the API. The API requires the geocode parameter. See dancroak/twitter-search README."
+      end
+    end
+
+  end
+end

data/shoulda_macros/twitter_search.rb

@@ -0,0 +1,36 @@
+module TwitterSearch
+  module Shoulda
+    def should_have_default_search_behaviors
+      should_find_tweets
+      should_have_text_for_all_tweets
+      should_return_page 1
+      should_return_tweets_in_sets_of 15
+    end
+
+    def should_find_tweets
+      should 'find tweets' do
+        assert @tweets.any?
+      end
+    end
+
+    def should_have_text_for_all_tweets
+      should 'have text for all tweets' do
+        assert @tweets.all? { |tweet| tweet.text.size > 0 }
+      end
+    end
+
+    def should_return_page(number)
+      should "return page #{number}" do
+        assert_equal number, @tweets.page
+      end
+    end
+
+    def should_return_tweets_in_sets_of(number)
+      should "return tweets in sets of #{number}" do
+        assert_equal number, @tweets.results_per_page
+      end
+    end
+  end
+end
+
+Test::Unit::TestCase.extend(TwitterSearch::Shoulda)

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: jcrossley-twitter-search
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  - 8
+  version: 0.5.8
+platform: ruby
+authors: 
+- Dustin Sallings
+- Dan Croak
+- Luke Francl
+- Matt Jankowski
+- Matt Sanford
+- Alejandro Crosa
+- Danny Burkes
+- Don Brown
+- HotFusionMan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-12 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 2
+        version: 1.1.2
+  type: :runtime
+  version_requirements: *id001
+description: Ruby client for Twitter Search.
+email: dcroak@thoughtbot.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- README.markdown
+- TODO.markdown
+- CHANGELOG.textile
+- lib/tweets.rb
+- lib/twitter_search.rb
+- lib/trends.rb
+- shoulda_macros/twitter_search.rb
+has_rdoc: true
+homepage: http://github.com/jcrossley/twitter-search
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Ruby client for Twitter Search. Includes trends.
+test_files: []
+