sucker 1.0.0 → 1.1.0

data/CHANGELOG.md

@@ -1,34 +1,25 @@
-Version 1.0.0
+Version 1.1.0
 =============
 
-Release date: 2010-11-04
+* Removed Request#get!. Bloat.
+* Added Request#get_all to fetch responses from all venues
+  simultaneously.
+* Added Request#associate_tags= to set associate tags for all locales.
+* Added Request#keys= to set distinct keys for locales.
+* Request#get validates presence of key and locale.
 
-Added
------
+Version 1.0.0
+=============
 
 * Added #each and #map to Response. #find no longer yields.
 
 Version 1.0.0.beta4
 ===================
 
-Release date: 2010-10-28
-
-Added
------
-
 * Sucker::Request#get! raises an error if response is not valid.
 
 Version 1.0.0.beta3
 ===================
 
-Release date: 2010-10-25
-
-Added
------
-
 * Sucker::Response#find yields to a block if given one.
-
-Deprecated
-----------
-
 * Renamed #node to #find

data/README.md

@@ -1,9 +1,9 @@
 Sucker
 ======
 
-Sucker is a Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html). It runs on [curb](http://github.com/taf2/curb) and [the Nokogiri implementation of the XML Mini module](http://github.com/rails/rails/blob/master/activesupport/lib/active_support/xml_mini/nokogiri.rb) in Active Support. It's fast and supports __the entire API__.
+Sucker is a minimal Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html). It runs on [curb](http://github.com/taf2/curb) and [the Nokogiri implementation of the XML Mini module](http://github.com/rails/rails/blob/master/activesupport/lib/active_support/xml_mini/nokogiri.rb) in Active Support. It's fast and supports __the entire API__.
 
-![Sucker](http://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg/480px-FEMA_-_32011_-_FEMA_Joint_Field_Office_%28JFO%29_preparation_in_Ohio.jpg)
+![Electrolux](http://github.com/papercavalier/sucker/raw/master/electrolux.jpg)
 
 Examples
 --------
@@ -43,10 +43,14 @@ Iterate over items in your item lookup.
 
     response.each("Item") { |item| ... }
 
-Iterate over errors.
+Map errors to a block.
 
     errors = response.map("Error") { |error| ... }
 
+Or simply get a hash of matching items.
+
+    items = response.find("Item")
+
 Repeat ad infinitum.
 
 Check my [integration specs](http://github.com/papercavalier/sucker/tree/master/spec/integration/) for more examples. See [twenty items](http://github.com/papercavalier/sucker/tree/master/spec/integration/twenty_items_spec.rb) and [multiple locales](http://github.com/papercavalier/sucker/tree/master/spec/integration/multiple_locales_spec.rb) for relatively advanced usage.
@@ -58,12 +62,12 @@ Stubbing
 
 Use [VCR](http://github.com/myronmarston/vcr) to stub your requests.
 
-Caveat: Match URIs on host only and create a new cassette for each query. [This is how I do it](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb).
+Caveat: Match URIs on host only and create a new cassette for each query. [This is how my VCR helper looks like.](http://github.com/papercavalier/sucker/blob/master/spec/support/vcr.rb).
 
 Compatibility
 -------------
 
-Specs pass against Ruby 1.8.7, Ruby 1.9.2, and Rubinius 1.1.
+Specs pass against Ruby 1.8.7 and Ruby 1.9.2.
 
 Sucker works seamlessly with or without Rails.
 

data/lib/sucker.rb

@@ -1,8 +1,5 @@
-require "active_support/xml_mini/nokogiri"
-require "curb"
 require "sucker/request"
 require "sucker/response"
-require "uri"
 
 # = Sucker
 #

data/lib/sucker/request.rb

@@ -1,3 +1,7 @@
+require "curb"
+require "ostruct"
+require "uri"
+
 module Sucker #:nodoc:
 
   # A wrapper around the API request
@@ -49,56 +53,125 @@ module Sucker #:nodoc:
       self.parameters.merge!(hash)
     end
 
-    # Sets the associate tag
+    # Returns the associate tag for the current locale
+    def associate_tag
+      @associate_tags[locale.to_sym] rescue nil
+    end
+
+    # Sets the associate tag for the current locale
     #
     #   worker = Sucker.new
     #   worker.associate_tag = 'foo-bar'
     #
     def associate_tag=(token)
-      parameters["AssociateTag"] = token
+      @associate_tags = HOSTS.keys.inject({}) do |tags, loc|
+        tags[loc] = token
+        tags
+      end
+    end
+
+    # Sets associate tags for all locales
+    #
+    #    tags = {
+    #      :us => 'foo-bar-10',
+    #      :uk => 'foo-bar-20',
+    #      :de => 'foo-bar-30',
+    #      ... }
+    #
+    #    worker = Sucker.new
+    #    worker.associate_tags = tags
+    #
+    def associate_tags=(tokens)
+      @associate_tags = tokens
     end
 
-    # A configurable curl object
+    # Returns options for curl and yields them if given a block
     #
     #   worker = Sucker.new
     #   worker.curl { |c| c.interface = "eth1" }
     #
-    def curl
-      @curl ||= Curl::Easy.new
-      yield @curl if block_given?
-      @curl
+    def curl_opts
+      @curl_opts ||= CurlOptions.new
+      yield @curl_opts if block_given?
+
+      @curl_opts.marshal_dump
     end
 
-    # Performs the request and returns a response object
+    # Performs a request and returns a response
     #
     #   worker = Sucker.new
     #   response = worker.get
     #
     def get
-      curl.url = uri.to_s
-      curl.perform
+      raise ArgumentError.new "Locale missing"         unless locale
+      raise ArgumentError.new "AWS access key missing" unless key
+
+      curl = Curl::Easy.perform(uri.to_s) do |easy|
+        curl_opts.each { |k, v| easy.send(k, v) }
+      end
 
       Response.new(curl)
     end
 
-    # Similar to get but raises an error if response is not valid
-    def get!
-      response = get
+    # Performs a request for all locales, returns an array of responses, and
+    # yields them if given a block
+    #
+    #    worker = Sucker.new
+    #
+    #    # This blocks until all requests are complete
+    #    responses = worker.get_all
+    #
+    #    # This does not block
+    #    worker.get_all do |response|
+    #      process_response
+    #    end
+    #
+    def get_all
+      uris = HOSTS.keys.map do |locale|
+        self.locale = locale
+        uri.to_s
+      end
+      responses = []
 
-      unless response.valid?
-        raise ResponseError, response.inspect
+      Curl::Multi.get(uris, curl_opts) do |curl|
+        response = Response.new(curl)
+        yield response if block_given?
+        responses << response
       end
 
-      response
+      responses
     end
 
-    # Sets the AWS Access Key ID
+    # Returns the AWS access key for the current locale
+    def key
+      @keys[locale.to_sym]
+    end
+
+    # Sets a global AWS access key ID
     #
     #   worker = Sucker.new
     #   worker.key = 'foo'
     #
     def key=(token)
-      parameters["AWSAccessKeyId"] = token
+      @keys = HOSTS.keys.inject({}) do |keys, locale|
+        keys[locale] = token
+        keys
+      end
+    end
+
+    # Sets distinct AWS access keys for the locales
+    #
+    #   keys = {
+    #     :us => 'foo',
+    #     :uk => 'bar',
+    #     :de => 'baz',
+    #     ... }
+    #
+    #   worker = Sucker.new
+    #   worker.keys = keys
+    #
+    def keys=(tokens)
+      @keys = tokens
     end
 
     # Sets the Amazon API version
@@ -116,6 +189,8 @@ module Sucker #:nodoc:
     def build_query
       parameters.
         merge(timestamp).
+        merge({ "AWSAccessKeyId" => key }).
+        merge({ "AssociateTag"   => associate_tag }).
         sort.
         collect do |k, v|
           "#{k}=" + escape(v.is_a?(Array) ? v.join(",") : v.to_s)
@@ -156,4 +231,7 @@ module Sucker #:nodoc:
       { "Timestamp" => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ') }
     end
   end
+
+  # Curl options
+  class CurlOptions < OpenStruct; end
 end

data/lib/sucker/response.rb

@@ -1,3 +1,5 @@
+require "active_support/xml_mini/nokogiri"
+
 module Sucker #:nodoc:
 
   # A Nokogiri-driven wrapper around the cURL response
@@ -12,19 +14,23 @@ module Sucker #:nodoc:
     # Transaction time in seconds for request
     attr_accessor :time
 
+    # The request URI
+    attr_accessor :uri
+
     def initialize(curl)
       self.body = curl.body_str
       self.code = curl.response_code
       self.time = curl.total_time
+      self.uri  = curl.url
     end
 
-		# A shorthand that yields each match to a block
-		#
-		#   worker.get.each("Item") { |item| process(item) }
-		#
-		def each(path)
-			find(path).each { |node| yield node }
-		end
+    # A shorthand that yields each match to a block
+    #
+    #   worker.get.each("Item") { |item| process(item) }
+    #
+    def each(path)
+      find(path).each { |e| yield e }
+    end
 
     # Queries an xpath and returns an array of matching nodes
     #
@@ -32,15 +38,15 @@ module Sucker #:nodoc:
     #   response.find("Item").each { |item| ... }
     #
     def find(path)
-      xml.xpath("//xmlns:#{path}").map { |node| strip_content(node.to_hash[path]) }
+      xml.xpath("//xmlns:#{path}").map { |e| strip_content(e.to_hash[path]) }
     end
 
-		# A shorthand that yields matches to a block and collects returned values
-		#
-		#   descriptions = worker.get.map("Item") { |item| build_description(item) }
-		#
-		def map(path)
-			find(path).map { |e| yield e }
+    # A shorthand that yields matches to a block and collects returned values
+    #
+    #   descriptions = worker.get.map("Item") { |item| build_description(item) }
+    #
+    def map(path)
+      find(path).map { |e| yield e }
     end
 
     def node(path) # :nodoc:

data/lib/sucker/version.rb

@@ -1,3 +1,3 @@
 module Sucker #:nodoc:
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/integration/multiple_locales_spec.rb

@@ -5,11 +5,36 @@ module Sucker
 
   describe "Item lookup" do
 
-    context "when using threads to search multiple locales" do
+    use_vcr_cassette "integration/multiple_locales", :record => :new_episodes
 
-      use_vcr_cassette "integration/multiple_locales", :record => :new_episodes
+    context "when using Curl::Multi to search all locales simultaneously" do
 
-      it "returns matches across all locales" do
+      it "returns matches for all locales" do
+        worker = Sucker.new(
+          :key    => amazon["key"],
+          :secret => amazon["secret"])
+        worker << {
+          "Operation"     => "ItemLookup",
+          "IdType"        => "ASIN",
+          "ResponseGroup" => "ItemAttributes",
+          "ItemId"        => "0816614024" }
+
+        bindings = worker.get_all.map do |response|
+          item = response.find("Item").first
+          item["ItemAttributes"]["Binding"]
+        end
+
+        bindings.uniq.should =~ %w{ Paperback Taschenbuch Broché ペーパーバック }
+
+      end
+
+    end
+
+    context "when using threads to search all locales simultaneously" do
+
+      # Leaving this spec here for reference purposes. Use approach in above spec.
+
+      it "returns matches for all locales" do
         locales = %w{us uk de ca fr jp}
 
         params = {

data/spec/support/vcr.rb

@@ -2,10 +2,11 @@ require 'vcr'
 
 VCR.config do |c|
   c.cassette_library_dir     = File.dirname(__FILE__) + '/../fixtures/cassette_library'
-  c.http_stubbing_library    = :webmock
   c.default_cassette_options = {
-    :record             => :new_episodes,
+    :record             => :none,
     :match_requests_on  => [:host] }
+
+  c.stub_with :webmock
 end
 
 RSpec.configure do |config|

data/spec/unit/sucker/request_spec.rb

@@ -42,60 +42,134 @@ module Sucker
 
     end
 
-    describe "#associate_tag=" do
+    describe "#associate_tag" do
 
-      it "sets the associate tag in the parameters" do
-        worker.associate_tag = "foo"
-        worker.parameters["AssociateTag"].should eql "foo"
+      it "returns the associate tag for the current locale" do
+        worker.instance_variable_set(:@associate_tags, { :us => 'foo-bar'})
+
+        worker.associate_tag.should eql 'foo-bar'
+      end
+
+      it "returns nil if an associate tag is not set for the current locale" do
+        worker.associate_tag.should eql nil
       end
 
     end
 
-    describe "#curl" do
+    describe "#associate_tags=" do
 
-      it "returns curl" do
-        worker.curl.should be_an_instance_of Curl::Easy
+      it "sets associate tags for the locales" do
+        tags = {
+          :us => 'foo',
+          :uk => 'bar',
+          :de => 'baz',
+          :ca => 'foo',
+          :fr => 'bar',
+          :jp => 'baz' }
+        worker.associate_tags = tags
+
+        worker.instance_variable_get(:@associate_tags).should eql tags
       end
 
-      context "when given a block" do
+    end
 
-        it "yields curl" do
-          worker.curl.interface.should be_nil
+    describe "#curl_opts" do
 
-          worker.curl { |curl| curl.interface = "eth1" }
+      it "returns options for curl" do
+        worker.curl_opts.should be_an_instance_of Hash
+      end
+
+      context "when given a block" do
 
-          worker.curl.interface.should eql "eth1"
+        it "yields options for curl" do
+          worker.curl_opts { |c| c.interface = "eth1" }
+
+          worker.curl_opts[:interface].should eql "eth1"
         end
 
       end
 
     end
 
-    describe "#get!" do
+    describe "#get" do
+
+      it "returns a response" do
+        worker.get.class.ancestors.should include Response
+      end
 
-      it "raises if response is not valid" do
-        worker << {
-          "Operation"     => "ItemLookup",
-          "IdType"        => "ASIN",
-          "ItemId"        => "0816614024" }
-        lambda { worker.get! }.should raise_error ResponseError
+      it "raises an argument error if no key is provided" do
+        worker.key = nil
+        expect do
+          worker.get
+        end.to raise_error(/AWS access key missing/)
       end
 
+      it "raises an argument error if no locale is provided" do
+        worker.locale = nil
+        expect do
+          worker.get
+        end.to raise_error(/Locale missing/)
+      end
     end
 
-    describe "#get" do
+    describe "#get_all" do
 
-      it "returns a response" do
-        worker.get.class.ancestors.should include Response
+      it "returns an array of responses" do
+        responses = worker.get_all
+
+        responses.should be_an_instance_of Array
+        responses.each { |resp| resp.should be_an_instance_of Response }
+      end
+
+      context "when given a block" do
+
+        it "yields responses" do
+          count = 0
+          worker.get_all do |resp|
+            resp.should be_an_instance_of Response
+            count += 1
+          end
+
+          count.should eql Request::HOSTS.size
+        end
+      end
+    end
+
+    describe "#key" do
+
+      it "returns the Amazon AWS access key for the current locale" do
+        worker.instance_variable_set(:@keys, { :us => 'foo' })
+
+        worker.key.should eql 'foo'
       end
 
     end
 
     describe "#key=" do
 
-      it "sets the Amazon AWS access key in the parameters" do
+      it "sets a global Amazon AWS access key" do
         worker.key = "foo"
-        worker.parameters["AWSAccessKeyId"].should eql "foo"
+        keys = worker.instance_variable_get(:@keys)
+
+        keys.size.should eql Request::HOSTS.size
+        keys.values.uniq.should eql ["foo"]
+      end
+
+    end
+
+    describe "#keys=" do
+
+      it "sets distinct Amazon AWS access keys for the locales" do
+        keys = {
+          :us => 'foo',
+          :uk => 'bar',
+          :de => 'baz',
+          :ca => 'foo',
+          :fr => 'bar',
+          :jp => 'baz' }
+        worker.keys = keys
+
+        worker.instance_variable_get(:@keys).should eql keys
       end
 
     end
@@ -104,32 +178,38 @@ module Sucker
 
       describe "#build_query" do
 
+        let(:query) { worker.send(:build_query) }
+
         it "canonicalizes parameters" do
-          query = worker.send(:build_query)
           query.should match /Service=([^&]+)&Timestamp=([^&]+)&Version=([^&]+)/
         end
 
+        it "includes the key for the current locale" do
+          worker.instance_variable_set(:@keys, { :us => 'foo' })
+          query.should include 'AWSAccessKeyId=foo'
+        end
+
+        it "includes a timestamp" do
+          query.should include 'Timestamp='
+        end
+
         it "sorts parameters" do
           worker.parameters["AAA"] = "foo"
-          query = worker.send(:build_query)
           query.should match /^AAA=foo/
         end
 
         it "converts a parameter whose value is an array to a string" do
           worker.parameters["Foo"] = ["bar", "baz"]
-          query = worker.send(:build_query)
           query.should match /Foo=bar%2Cbaz/
         end
 
         it "handles integer parameter values" do
           worker.parameters["Foo"] = 1
-          query = worker.send(:build_query)
           query.should match /Foo=1/
         end
 
         it "handles floating-point parameter values" do
           worker.parameters["Foo"] = 1.0
-          query = worker.send(:build_query)
           query.should match /Foo=1/
         end