topsy 0.2.0 → 0.2.1

data/.gitignore

@@ -23,3 +23,5 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+doc
+.yardoc

data/README.markdown

@@ -11,6 +11,9 @@ Topsy is hosted on Gemcutter, so:
     sudo gem install topsy
 
 ## Usage
+    >> Topsy.rate_limit
+    => <#Topsy::RateLimitInfo limit=10000 remaining=10000 reset=1262804400>
+
     >> Topsy.author_info('http://twitter.com/barackobama')
     => <#Topsy::Author description="44th President of the United States" influence_level=10 name="Barack Obama" nick="barackobama" topsy_author_url="http://topsy.com/twitter/barackobama" type="twitter" url="http://twitter.com/barackobama">
 

data/Rakefile

@@ -48,3 +48,11 @@ task :test => :check_dependencies
 
 task :default => :test
 
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/TODO

@@ -2,6 +2,4 @@
 
 Here is the TODO list for the topsy gem. 
 
-## Add tests for pagination of queries
-## Make windows for queries easier to understand (eg. :window => :day, or :window => :year, or :window => :month)
-
+Nothing!

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/changelog.markdown

@@ -1,5 +1,16 @@
 # Changelog
 
-# 0.1.0 January 1, 2010
+### 0.2.1 February, 14, 2010
 
-  * Initial version
+* Added site: option to search method
+
+    Topsy.search('riak', :site => 'thechangelog.com')
+
+### 0.2.0 January 6, 2010
+
+* Ernesto implemented biz objects for all return types, thanks!
+* Added rate_limit info
+
+### 0.1.0 January 1, 2010
+
+* Initial version

data/lib/topsy.rb

@@ -32,7 +32,7 @@ module Topsy
   # Returns profile information for an author (a twitter profile indexed by Topsy). The response contains the name, description (biography) and the influence level of the author
   #
   # @param [String] url URL string for the author.
-  # @return [Hashie::Mash]
+  # @return [Topsy::Author]
   def self.author_info(url)
     Topsy::Client.new.author_info(url)
   end
@@ -42,7 +42,7 @@ module Topsy
   #
   # @param [String] q the search query string
   # @param [Hash] options method options
-  # @option options [String] :window Time window for results. (default: 'a') Options: auto - automatically pick the most recent and relevant window. h last hour, d last day, w last week, m last month, a all time
+  # @option options [Symbol] :window Time window for results. (default: :auto) Options: :auto - automatically pick the most recent and relevant window. :hour last hour, :day last day, :week last week, :month last month, :all all time
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
   # @return [Topsy::Page]
@@ -58,9 +58,9 @@ module Topsy
   # @option options [String] :contains Query string to filter results
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.link_posts(url, options={})
-    Topsy::Client.new.link_posts(url, options={})
+    Topsy::Client.new.link_posts(url, options)
   end
   
   # Returns count of links posted by an author. This is the efficient, count-only version of /linkposts
@@ -70,7 +70,7 @@ module Topsy
   # @option options [String] :contains Query string to filter results
   # @return [Topsy::LinkpostCount]
   def self.link_post_count(url, options={})
-    response = Topsy::Client.new.link_post_count(url, options={})
+    response = Topsy::Client.new.link_post_count(url, options)
     Topsy::LinkpostCount.new(response)
   end
   
@@ -80,7 +80,7 @@ module Topsy
   # @param [Hash] options method options
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.profile_search(q, options={})
     Topsy::Client.new.profile_search(q, options)
   end
@@ -91,7 +91,7 @@ module Topsy
   # @param [Hash] options method options
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.related(url, options={})
     Topsy::Client.new.related(url, options)
   end
@@ -100,10 +100,10 @@ module Topsy
   #
   # @param [String] q the search query string
   # @param [Hash] options method options
-  # @option options [String] :window Time window for results. (default: 'a') Options: auto - automatically pick the most recent and relevant window. h last hour, d last day, w last week, m last month, a all time
+  # @option options [Symbol] :window Time window for results. (default: :auto) Options: :auto - automatically pick the most recent and relevant window. :hour last hour, :day last day, :week last week, :month last month, :all all time
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.search(q, options={})
     Topsy::Client.new.search(q, options)
   end
@@ -121,7 +121,7 @@ module Topsy
   # @param [String] url the url to look up
   # @param [Hash] options method options
   # @option options [String] :contains Query string to filter results
-  # @return [Hashie::Mash]
+  # @return [Topsy::Stats]
   def self.stats(url, options={})
     Topsy::Client.new.stats(url, options)
   end
@@ -132,7 +132,7 @@ module Topsy
   # @param [Hash] options method options
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.tags(url, options={})
     Topsy::Client.new.tags(url, options)
   end
@@ -145,7 +145,7 @@ module Topsy
   # @option options [Boolean] :infonly filters trackbacks to influential only (default 0)
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.trackbacks(url, options={})
     Topsy::Client.new.trackbacks(url, options)
   end
@@ -156,7 +156,7 @@ module Topsy
   # @param [Hash] options method options
   # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
   # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-  # @return [Hashie::Mash]
+  # @return [Topsy::Page]
   def self.trending(options={})
     Topsy::Client.new.trending(options)
   end
@@ -164,14 +164,14 @@ module Topsy
   # Returns info about a URL
   #
   # @param [String] url the url to look up
-  # @return [Hashie::Mash]
+  # @return [Topsy::UrlInfo]
   def self.url_info(url)
     Topsy::Client.new.url_info(url)
   end
   
   # Returns info about API rate limiting
   #
-  # @return [RateLimitInfo]
+  # @return [Topsy::RateLimitInfo]
   def self.credit
     Topsy::Client.new.credit
   end

data/lib/topsy/client.rb

@@ -3,10 +3,11 @@ module Topsy
     include HTTParty
     format :json
     base_uri "http://otter.topsy.com"
+    @@windows = {:all => 'a', :auto => 'auto', :week => 'w', :day => 'd', :month => 'm', :hour => 'h'}
     
     # Returns info about API rate limiting
     #
-    # @return [RateLimitInfo]
+    # @return [Topsy::RateLimitInfo]
     def credit
       handle_response(self.class.get("/credit.json"))
     end
@@ -24,11 +25,12 @@ module Topsy
     #
     # @param [String] q the search query string
     # @param [Hash] options method options
-    # @option options [String] :window Time window for results. (default: 'a') Options: auto - automatically pick the most recent and relevant window. h last hour, d last day, w last week, m last month, a all time
+    # @option options [Symbol] :window Time window for results. (default: :auto) Options: :auto - automatically pick the most recent and relevant window. :hour last hour, :day last day, :week last week, :month last month, :all all time
     # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
     # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
     # @return [Hashie::Mash]
     def author_search(q, options={})
+      options[:window] = @@windows[options[:window]] if options[:window]
       handle_response(self.class.get("/authorsearch.json", :query => {:q => q}.merge(options)))
     end
     
@@ -41,9 +43,7 @@ module Topsy
     # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
     # @return [Topsy::Page]
     def link_posts(url, options={})
-      query = {:url => url}
-      query.merge!(options)
-      linkposts = handle_response(self.class.get("/linkposts.json", :query => query))
+      linkposts = handle_response(self.class.get("/linkposts.json", :query => {:url => url}.merge(options)))
       Topsy::Page.new(linkposts,Topsy::Linkpost)
     end
     
@@ -58,7 +58,9 @@ module Topsy
       Topsy::LinkpostCount.new(count)
     end
     
-    # Returns list list of author profiles that match the query. The query is matched against the nick, name and biography information and the results are sorted by closeness of match and the influence of authors.
+    # Returns list list of author profiles that match the query. 
+    #   The query is matched against the nick, name and biography 
+    #   information and the results are sorted by closeness of match and the influence of authors.
     #
     # @param [String] q the search query string
     # @param [Hash] options method options
@@ -86,11 +88,19 @@ module Topsy
     #
     # @param [String] q the search query string
     # @param [Hash] options method options
-    # @option options [String] :window Time window for results. (default: 'a') Options: auto - automatically pick the most recent and relevant window. h last hour, d last day, w last week, m last month, a all time
+    # @option options [Symbol] :window Time window for results. (default: :auto) Options: :auto - automatically pick the most recent and relevant window. :hour last hour, :day last day, :week last week, :month last month, :all all time
     # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
     # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
+    # @option options [String] :site narrow results to a domain
     # @return [Topsy::Page]
     def search(q, options={})
+      if q.is_a?(Hash)
+        options = q
+        q = "site:#{options.delete(:site)}" if options[:site]
+      else
+        q += " site:#{options.delete(:site)}" if options[:site]
+      end
+      options[:window] = @@windows[options[:window]] if options[:window]
       results = handle_response(self.class.get("/search.json", :query => {:q => q}.merge(options)))
       Topsy::Page.new(results,Topsy::LinkSearchResult)
     end
@@ -151,7 +161,7 @@ module Topsy
     # @param [Hash] options method options
     # @option options [Integer] :page page number of the result set. (default: 1, max: 10)
     # @option options [Integer] :perpage limit number of results per page. (default: 10, max: 50)
-    # @return [Hashie::Mash]
+    # @return [Topsy::Page]
     def trending(options={})
       response = handle_response(self.class.get("/trending.json", :query => options))
       Topsy::Page.new(response,Topsy::Trend)

data/lib/topsy/linkpost.rb

@@ -1,15 +1,14 @@
-# This is the linkpost class for the topsy library. 
-# A Linkpost has the following attributes:
-#            "permalink_url" : "http://twitter.com/barackobama/status/3569838653",
-#            "target" : target instance
-#            "date" : "1251337427",
-#            "content" : "Highlights from the tribute to Sen. Kennedy's life and 
-#                accomplishments from last year's Democratic National Convention: http://bit.ly/TJcyr",
-#            "date_alpha" : "3 hours ago"
-# According to the official Topsy doc: http://code.google.com/p/otterapi/wiki/Resources?tm=6#/linkposts
-#
+
 module Topsy
-  
+  # This is the linkpost class for the topsy library. 
+  # A Linkpost has the following attributes:
+  #   "permalink_url" : "http://twitter.com/barackobama/status/3569838653",
+  #   "target" : target instance
+  #   "date" : "1251337427",
+  #   "content" : "Highlights from the tribute to Sen. Kennedy's life and 
+  #                accomplishments from last year's Democratic National Convention: http://bit.ly/TJcyr",
+  #   "date_alpha" : "3 hours ago"
+  # According to the official Topsy doc: http://code.google.com/p/otterapi/wiki/Resources?tm=6#/linkposts
   class Linkpost < Hashie::Dash
     property :permalink_url
     property :target

data/lib/topsy/page.rb

@@ -3,7 +3,9 @@
 #      "page" : 1,
 #      "total" : "1139",
 #      "perpage" : 15,
-#      "list" : Array of Author instances 
+#      "list" : Array of Author instances
+#      "window" : Optional symbol
+#      "topsy_trackback_url" : String, optional 
 #
 # According to the official Topsy doc: http://code.google.com/p/otterapi/wiki/Resources?tm=6#/authorsearch
 #
@@ -17,6 +19,8 @@ module Topsy
     property :window
     property :topsy_trackback_url
     
+    @@windows = {'a' => :all, 'auto' => :auto, 'w' => :week, 'd' => :day, 'm' => :month, 'h' => :hour}
+    
     def to_s
       "Topsy Page: #{page} of #{total}, #{list.size} authors"
     end
@@ -35,6 +39,13 @@ module Topsy
         self[:list] = value
       end
     end
+    
+    def window=(value)
+      if value
+        self[:window] = @@windows[value]  
+      end
+    end
+    
   end
  
 end

data/test/fixtures/authorsearch-page2.json

@@ -0,0 +1,115 @@
+{
+    "request": {
+        "response_type": "json",
+        "resource": "authorsearch",
+        "parameters": {
+            "q": "pengwynn"
+        },
+        "url": "http://button.topsy.com/authorsearch.json?q=pengwynn"
+    },
+    "response": {
+        "page": 2,
+        "total": 512,
+        "perpage": 10,
+        "list": [{
+            "name": "Bradley Joyce",
+            "nick": "bradleyjoyce",
+            "photo_url": "http://a3.twimg.com/profile_images/421303551/bradley_normal.png",
+            "description": "Entrepreneur and Web Developer -- TweetAbout.com, TickStart.com, TweetCongress.org, Floxee.org, Sherflock.com, Squeejee.com",
+            "influence_level": "7",
+            "hits": 47,
+            "url": "http://twitter.com/bradleyjoyce",
+            "topsy_author_url": "http://topsy.com/twitter/bradleyjoyce"
+        },
+        {
+            "name": "tweetcongress",
+            "nick": "tweetcongress",
+            "photo_url": "http://s.twimg.com/a/1253209888/images/default_profile_0_normal.png",
+            "description": "Grassroots effort to get Congress tweeting!",
+            "influence_level": "10",
+            "hits": 13,
+            "url": "http://twitter.com/tweetcongress",
+            "topsy_author_url": "http://topsy.com/twitter/tweetcongress"
+        },
+        {
+            "name": "Jim Mulholland",
+            "nick": "mully",
+            "photo_url": "http://a3.twimg.com/profile_images/385459831/twitterProfilePhoto_normal.jpg",
+            "description": "Partner at Squeejee, a Ruby / Rails consultancy; Co-Creator of TweetCongress; Husband and father of 3; ",
+            "influence_level": "4",
+            "hits": 19,
+            "url": "http://twitter.com/mully",
+            "topsy_author_url": "http://topsy.com/twitter/mully"
+        },
+        {
+            "name": "Chris McCroskey",
+            "nick": "curvezilla",
+            "photo_url": "http://a1.twimg.com/profile_images/413047412/chrisheadshot_normal.jpg",
+            "description": "Mission Control at Squeejee and Co-Founder of TweetCongress.org & Founder of Heroes4Heroes a charity that sends care packets to the troops. Proud Razorback!",
+            "influence_level": "4",
+            "hits": 16,
+            "url": "http://twitter.com/curvezilla",
+            "topsy_author_url": "http://topsy.com/twitter/curvezilla"
+        },
+        {
+            "name": "Steve Lunceford",
+            "nick": "dslunceford",
+            "photo_url": "http://a3.twimg.com/profile_images/420259957/headshot_tight_normal.JPG",
+            "description": "20-year media and PR pro focusing on Government; TiVo, Home Theater & general gadget fanatic. Creator of http://GovTwit.com",
+            "influence_level": "10",
+            "hits": 11,
+            "url": "http://twitter.com/dslunceford",
+            "topsy_author_url": "http://topsy.com/twitter/dslunceford"
+        },
+        {
+            "name": "Damon Clinkscales",
+            "nick": "damon",
+            "photo_url": "http://a1.twimg.com/profile_images/561257818/mo5_crop_normal.jpg",
+            "description": "I'm a shepherd. Software engineer at VitalSource and leader of Austin On Rails. I also build apps like http://snaptweet.com and http://doesfollow.com. ",
+            "influence_level": "10",
+            "hits": 8,
+            "url": "http://twitter.com/damon",
+            "topsy_author_url": "http://topsy.com/twitter/damon"
+        },
+        {
+            "name": "Wynn Netherland",
+            "nick": "pengwynn",
+            "photo_url": "http://a1.twimg.com/profile_images/485575482/komikazee_normal.png",
+            "description": "Christian husband and father, Ruby developer and web designer. Co-founder of TweetCongress.org and Squeejee, makers of Good clean fun!™",
+            "influence_level": "10",
+            "hits": 8,
+            "url": "http://twitter.com/pengwynn",
+            "topsy_author_url": "http://topsy.com/twitter/pengwynn"
+        },
+        {
+            "name": "Luigi Montanez",
+            "nick": "luigimontanez",
+            "photo_url": "http://a3.twimg.com/profile_images/523899985/Comic_Book_normal.png",
+            "description": "Web App Developer at the Sunlight Labs",
+            "influence_level": "10",
+            "hits": 6,
+            "url": "http://twitter.com/luigimontanez",
+            "topsy_author_url": "http://topsy.com/twitter/luigimontanez"
+        },
+        {
+            "name": "Locomotivation",
+            "nick": "locomotivation",
+            "photo_url": "http://a1.twimg.com/profile_images/386446850/twitterProfilePhoto_normal.jpg",
+            "description": "The code blog from the guys at Squeejee.",
+            "influence_level": "5",
+            "hits": 12,
+            "url": "http://twitter.com/locomotivation",
+            "topsy_author_url": "http://topsy.com/twitter/locomotivation"
+        },
+        {
+            "name": "Adam Stacoviak",
+            "nick": "adamstac",
+            "photo_url": "http://a1.twimg.com/profile_images/493267610/twitterProfilePhoto_normal.jpg",
+            "description": "Co-founder of Handcrafted, co-producer of The Web 2.0 Show podcast, and a lover of beautiful UI/UX. You should follow me :)",
+            "influence_level": "3",
+            "hits": 11,
+            "url": "http://twitter.com/adamstac",
+            "topsy_author_url": "http://topsy.com/twitter/adamstac"
+        }]
+    }
+}

data/test/fixtures/linkposts-page2.json

@@ -0,0 +1,75 @@
+{
+    "request": {
+        "response_type": "json",
+        "resource": "linkposts",
+        "parameters": {
+            "url": "http://twitter.com/pengwynn"
+        },
+        "url": "http://button.topsy.com/linkposts.json?url=http%3A%2F%2Ftwitter.com%2Fpengwynn"
+    },
+    "response": {
+        "page": 2,
+        "total": 987,
+        "perpage": 5,
+        "list": [{
+            "permalink_url": "http://twitter.com/pengwynn/status/7253938349",
+            "date": 1262307998,
+            "content": "For auld lang syne, my dear: http://en.wikipedia.org/wiki/Auld_Lang_Syne#Lyrics",
+            "date_alpha": "16 hours ago",
+            "target": {
+                "topsy_trackback_url": "http://topsy.com/trackback?url=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FAuld_Lang_Syne%23Lyrics",
+                "url": "http://en.wikipedia.org/wiki/Auld_Lang_Syne#Lyrics",
+                "title": "Auld Lang Syne - Wikipedia, the free encyclopedia",
+                "trackback_total": 8
+            }
+        },
+        {
+            "permalink_url": "http://twitter.com/pengwynn/status/7212961312",
+            "date": 1262216148,
+            "content": "Treating the in-laws to some Texas BBQ  — at Rudy's http://gowal.la/s/dVo",
+            "date_alpha": "2 days ago",
+            "target": {
+                "topsy_trackback_url": "http://topsy.com/tb/gowalla.com/spots/43464",
+                "url": "http://gowalla.com/spots/43464",
+                "title": "Rudy's on Gowalla",
+                "trackback_total": 2
+            }
+        },
+        {
+            "permalink_url": "http://twitter.com/pengwynn/status/7167706422",
+            "date": 1262112340,
+            "content": "Catching a matinee of Sherlock Holmes — at Stagecoach Theater http://gowal.la/s/Grk",
+            "date_alpha": "3 days ago",
+            "target": {
+                "topsy_trackback_url": "http://topsy.com/tb/gowalla.com/spots/136029",
+                "url": "http://gowalla.com/spots/136029",
+                "title": "Stagecoach Theater on Gowalla",
+                "trackback_total": 1
+            }
+        },
+        {
+            "permalink_url": "http://twitter.com/pengwynn/status/7162128190",
+            "date": 1262100992,
+            "content": "Learning about the Pacific War  — at National Museum of The Pacific War http://gowal.la/s/575",
+            "date_alpha": "3 days ago",
+            "target": {
+                "topsy_trackback_url": "http://topsy.com/tb/gowalla.com/spots/13808",
+                "url": "http://gowalla.com/spots/13808",
+                "title": "National Museum of The Pacific War on Gowalla",
+                "trackback_total": 1
+            }
+        },
+        {
+            "permalink_url": "http://twitter.com/pengwynn/status/7139983009",
+            "date": 1262045378,
+            "content": "Rails Magazine #5 is out http://ow.ly/QuFY /via @rupakg",
+            "date_alpha": "4 days ago",
+            "target": {
+                "topsy_trackback_url": "http://topsy.com/tb/www.railsmagazine.com/issues/5",
+                "url": "http://www.railsmagazine.com/issues/5",
+                "title": "Issue #5: Winter Jam",
+                "trackback_total": 13
+            }
+        }]
+    }
+}