sucker 2.0.0.pre.4 → 2.0.0.pre.5

data/README.md

@@ -1,55 +1,91 @@
-Sucker
-======
+# Sucker
 
-Sucker is a Nokogiri-based, optionally-evented Ruby wrapper to the [Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html).
+Sucker is a Nokogiri-based, optionally-evented Ruby wrapper to the
+[Amazon Product Advertising API](https://affiliate-program.amazon.co.uk/gp/advertising/api/detail/main.html).
 
 ![Hoover](https://github.com/papercavalier/sucker/raw/master/hoover.jpg)
 
-Caption: Workers queuing to download data from Amazon.
+> Workers queuing to download data from Amazon.
 
-Usage
------
+## Usage
 
-Read the [Amazon API](http://aws.amazon.com/archives/Product%20Advertising%20API).
-Check out [these examples](http://relishapp.com/papercavalier/sucker) if in a hurry.
+_Note_: For the README of version 1.6.1 and earlier, [click here](https://github.com/papercavalier/sucker/tree/v1.6.1).
 
-Set up.
+1.  Define your Amazon credentials.
 
-```ruby
-request = Sucker.new(
-  :locale => :us,
-  :key    => amazon_key,
-  :secret => amazon_secret)
-```
+    ```ruby
+    Sucker.configure do |c|
+      c.locale        = :us
+      c.key           = amazon_key
+      c.secret        = amazon_secret
+      c.associate_tag = associate_tag
+    end
 
-Build a request.
+2.  Set up a request.
 
-```ruby
-request << {
-  'Operation'     => 'ItemLookup',
-  'IdType'        => 'ASIN',
-  'ItemId'        => 10.asins,
-  'ResponseGroup' => 'ItemAttributes' }
-```
+    ```ruby
+    request = Sucker.new
+    ```
 
-Get a response.
+    Alternatively, you may your credentials when initializing the request.
 
-```ruby
-response = request.get
-```
+    ```ruby
+    request = Sucker.new(
+      :locale => :us,
+      :key    => amazon_key,
+      :secret => amazon_secret)
+    end
+    ```
+
+2.  Build a request.
+
+    ```ruby
+    request << {
+      'Operation'     => 'ItemLookup',
+      'IdType'        => 'ASIN',
+      'ItemId'        => 10.asins,
+      'ResponseGroup' => 'ItemAttributes' }
+    ```
+
+    Amazon provides countless configuration options to fine-tune your query. Read
+    [their API](http://aws.amazon.com/archives/Product%20Advertising%20API) or 
+    check out [these common scenarios](http://relishapp.com/papercavalier/sucker)
+    if in a hurry.
+
+3.  Get a response.
 
-Fulfill a business value.
+    ```ruby
+    response = request.get
+    ```
+
+    Fulfill a business value.
+
+    ```ruby
+    if response.valid?
+      response.find('Item').each do |item|
+        # consume
+      end
+    end
+    ```
+
+4.  Repeat ad infinitum.
+
+    ```ruby
+    request << { 'ItemId' => 10.new.asins }
+    request.get["Item"].each do |item|
+      # consume
+    end
+    ```
+
+
+## Some tips
+
+Inspect the response as a hash to find out nodes you are interested in.
 
 ```ruby
-if response.valid?
-  response.each('Item') do |item|
-    consume(item)
-  end
-end
+p response.to_hash
 ```
 
-Repeat ad infinitum.
-
 The following are all valid ways to query a response:
 
 ```ruby
@@ -67,7 +103,6 @@ p response.valid?,
   response.code,
   response.errors,
   response.has_errors?,
-  response.to_hash,
   response.xml
 ```
 
@@ -83,7 +118,8 @@ adapter.socket_local.host = '10.0.0.2'
 Evented Requests
 ----------------
 
-I am including a EM:Synchrony patch in the 2.0 release.
+Large responses can block! I am including an EM:Synchrony patch in the 2.0
+release.
 
 ```ruby
 require 'sucker/synchrony'
@@ -95,8 +131,8 @@ EM.synchrony do
   EM.stop
 end
 
-For more meaningful examples, read [these examples](http://relishapp.com/papercavalier/sucker/evented-requests).
 ```
+For more meaningful examples, read [here](http://relishapp.com/papercavalier/sucker/evented-requests).
 
 Stubbing Tests
 --------------

data/lib/sucker.rb

@@ -1,3 +1,4 @@
+require 'sucker/config'
 require 'sucker/request'
 require 'sucker/response'
 
@@ -5,9 +6,7 @@ require 'sucker/response'
 #
 # Sucker is a Ruby wrapper to the Amazon Product Advertising API.
 module Sucker
-
   class << self
-
     # Initializes a request object.
     #
     #   request = Sucker.new(
@@ -18,5 +17,18 @@ module Sucker
     def new(args={})
       Request.new(args)
     end
+
+    # Configures locale-specific details.
+    #
+    #   Sucker.configure do |c|
+    #     c.locale        = :us
+    #     c.key           = api_key
+    #     c.secret        = api_secret
+    #     c.associate_tag = associate_tag
+    #   end
+    #
+    def configure(&block)
+      block.call(Config)
+    end
   end
 end

data/lib/sucker/config.rb

@@ -0,0 +1,18 @@
+module Sucker
+  # Amazon credentials.
+  module Config
+    extend self
+
+    # The Amazon locale.
+    attr_accessor :locale
+
+    # The Amazon Web Services access key.
+    attr_accessor :key
+
+    # The Amazon Web Services secret.
+    attr_accessor :secret
+
+    # The Amazon associate tag.
+    attr_accessor :associate_tag
+  end
+end

data/lib/sucker/parameters.rb

@@ -35,8 +35,8 @@ module Sucker
 
     private
 
-      def timestamp
-        Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
-      end
+    def timestamp
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+    end
   end
 end

data/lib/sucker/request.rb

@@ -5,6 +5,8 @@ require 'sucker/parameters'
 module Sucker
   # A wrapper around the API request.
   class Request
+    extend Forwardable
+
     HOSTS = {
       :us  => 'ecs.amazonaws.com',
       :uk  => 'ecs.amazonaws.co.uk',
@@ -13,27 +15,14 @@ module Sucker
       :fr  => 'ecs.amazonaws.fr',
       :jp  => 'ecs.amazonaws.jp' }
 
-    class << self
-
-      # Available Amazon locales.
-      def locales
-        @locales ||= HOSTS.keys
-      end
-    end
-
-    # The Amazon associate tag.
-    attr_accessor :associate_tag
-
-    # The Amazon Web Services access key.
-    attr_accessor :key
-
-    # The Amazon locale.
-    attr_accessor :locale
+    LOCALES = HOSTS.keys
 
-    # The Amazon Web Services secret.
-    attr_accessor :secret
+    def_delegators :@config, :associate_tag, :associate_tag=,
+                             :key, :key=,
+                             :locale, :locale=,
+                             :secret, :secret=
 
-    # Initializes a request object.
+    # Creates a new a request.
     #
     # Takes an optional hash of attribute and value pairs.
     #
@@ -43,13 +32,9 @@ module Sucker
     #     :secret        => amazon_secret)
     #     :associate_tag => amazon_tag)
     #
-    def initialize(args={})
-      args.each { |k, v| send("#{k}=", v) }
-    end
-
-    # The HTTP adapter.
-    def adapter
-      @adapter ||= HTTPClient.new
+    def initialize(args = {})
+      @config = Config
+      args.each { |k, v| self.send("#{k}=", v) }
     end
 
     # Merges a hash into the existing parameters.
@@ -63,6 +48,11 @@ module Sucker
       parameters.merge!(hash)
     end
 
+    # The HTTP adapter.
+    def adapter
+      @adapter ||= HTTPClient.new
+    end
+
     # Performs a request and returns a response.
     #
     #   response = request.get
@@ -80,7 +70,6 @@ module Sucker
     # Resets parameters and returns self.
     def reset
       parameters.reset
-
       self
     end
 
@@ -100,33 +89,33 @@ module Sucker
 
     private
 
-      def build_query_string
-        parameters.
-          normalize.
-          merge({ 'AWSAccessKeyId' => key,
-                  'AssociateTag'   => associate_tag.to_s }).
-          sort.
-          map { |k, v| "#{k}=" + escape(v) }.
-          join('&')
-      end
-
-      def sign(query_string)
-        digest = OpenSSL::Digest::Digest.new('sha256')
-        url_string = ['GET', host, '/onca/xml', query_string].join("\n")
-        hmac = OpenSSL::HMAC.digest(digest, secret, url_string)
-        signature = escape([hmac].pack('m').chomp)
+    def build_query_string
+      parameters.
+        normalize.
+        merge({ 'AWSAccessKeyId' => key,
+                'AssociateTag'   => associate_tag.to_s }).
+        sort.
+        map { |k, v| "#{k}=" + escape(v) }.
+        join('&')
+    end
 
-        query_string + '&Signature=' + signature
+    def escape(value)
+      value.gsub(/([^a-zA-Z0-9_.~-]+)/) do
+        '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
       end
+    end
 
-      def escape(value)
-        value.gsub(/([^a-zA-Z0-9_.~-]+)/) do
-          '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
-        end
-      end
+    def host
+      HOSTS[locale.to_sym]
+    end
 
-      def host
-        HOSTS[locale.to_sym]
-      end
+    def sign(query_string)
+      digest = OpenSSL::Digest::Digest.new('sha256')
+      url_string = ['GET', host, '/onca/xml', query_string].join("\n")
+      hmac = OpenSSL::HMAC.digest(digest, secret, url_string)
+      signature = escape([hmac].pack('m').chomp)
+
+      query_string + '&Signature=' + signature
+    end
   end
 end

data/lib/sucker/synchrony.rb

@@ -3,13 +3,13 @@ require 'em-synchrony'
 require 'em-synchrony/em-http'
 
 module Sucker
-  # Below, we minimally patch Request and Response to make them fiber-aware.
+  # We minimally patch Request and Response to make them fiber-aware.
   class Request
     def adapter
       @adapter ||= EM::HttpRequest
     end
 
-    # Performs an evented request and yields a response to provided block.
+    # Performs an evented request and yields a response to given block.
     def aget(&block)
       http = EM::HttpRequest.new(url).aget
       http.callback { block.call(Response.new(http)) }

data/lib/sucker/version.rb

@@ -1,3 +1,3 @@
 module Sucker
-  VERSION = '2.0.0.pre.4'
+  VERSION = '2.0.0.pre.5'
 end

data/spec/sucker/config_spec.rb

@@ -0,0 +1,6 @@
+require 'spec_helper'
+
+module Sucker
+  describe Config
+  # nothing to spec here.
+end

data/spec/sucker/request_spec.rb

@@ -5,16 +5,10 @@ module Sucker
     use_vcr_cassette 'spec/sucker/request', :record => :new_episodes
 
     let(:request) do
-      Request.new(
-        :locale => :us,
-        :key    => 'key',
-        :secret => 'secret')
-    end
-
-    describe ".locales" do
-      it "returns available locales" do
-        Request.locales.should =~ [:us, :uk, :de, :ca, :fr, :jp]
-      end
+      Request.new(:locale        => :us,
+                  :key           => 'key',
+                  :secret        => 'secret',
+                  :associate_tag => 'tag')
     end
 
     describe '#<<' do
@@ -39,8 +33,8 @@ module Sucker
         request.parameters['foo'].should be_nil
       end
 
-      it "returns the request object" do
-        request.reset.should be_a Request
+      it "returns itself" do
+        request.reset.should eql request
       end
     end
 
@@ -63,7 +57,7 @@ module Sucker
       end
 
       it 'canonicalizes query' do
-        query.should match /AWSAccessKeyId=key&AssociateTag=&Service=([^&]+)&Timestamp=([^&]+)&Version=([^&]+)/
+        query.should match /AWSAccessKeyId=key&AssociateTag=tag&Service=([^&]+)&Timestamp=([^&]+)&Version=([^&]+)/
       end
 
       it 'includes a timestamp' do
@@ -90,10 +84,10 @@ module Sucker
       end
     end
 
-    describe '#host' do
-      it 'returns a host' do
-        request.locale = :fr
-        request.send(:host).should eql 'ecs.amazonaws.fr'
+    describe "#host" do
+      it "returns the host for specified locale" do
+        request.locale = :uk
+        request.send(:host).should eql Request::HOSTS[request.locale]
       end
     end
   end

data/spec/sucker/response_spec.rb

@@ -9,10 +9,10 @@ module Sucker
     let(:asins) { ['0816614024', '0143105825'] }
 
     let(:response) do
-      request = Sucker.new(
-        :locale => :us,
-        :key    => amazon_key,
-        :secret => amazon_secret)
+      request = Request.new(:locale        => :us,
+                            :key           => 'key',
+                            :secret        => 'secret',
+                            :associate_tag => 'tag')
       request << {
           'Operation' => 'ItemLookup',
           'IdType'    => 'ASIN',

data/spec/sucker_spec.rb

@@ -2,8 +2,15 @@ require "spec_helper"
 
 describe Sucker do
   describe ".new" do
-    it "returns a Request object" do
-      Sucker.new.should be_an_instance_of Sucker::Request
+    it "returns a request" do
+      subject.new.should be_a Sucker::Request
+    end
+  end
+
+  describe ".configure" do
+    it "yields a configuration object" do
+      subject.should_receive(:configure).and_yield(Sucker::Config)
+      subject.configure { |c| }
     end
   end
 end

metadata

@@ -7,8 +7,8 @@ version: !ruby/object:Gem::Version
   - 0
   - 0
   - pre
-  - 4
-  version: 2.0.0.pre.4
+  - 5
+  version: 2.0.0.pre.5
 platform: ruby
 authors: 
 - Paper Cavalier
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-21 00:00:00 +01:00
+date: 2011-07-04 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -43,28 +43,14 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 1
-        - 4
-        version: "1.4"
+        - 5
+        version: "1.5"
   type: :runtime
   version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: bundler
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 0
-        version: "1.0"
-  type: :development
-  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: cucumber
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -74,11 +60,11 @@ dependencies:
         - 10
         version: "0.10"
   type: :development
-  version_requirements: *id004
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: em-http-request
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -91,11 +77,11 @@ dependencies:
         - 4
         version: 1.0.0.beta.4
   type: :development
-  version_requirements: *id005
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: em-synchrony
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -108,25 +94,11 @@ dependencies:
         - 1
         version: 0.3.0.beta.1
   type: :development
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: relish
-  prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 4
-        version: "0.4"
-  type: :development
-  version_requirements: *id007
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -136,11 +108,11 @@ dependencies:
         - 6
         version: "2.6"
   type: :development
-  version_requirements: *id008
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: vcr
   prerelease: false
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -150,11 +122,11 @@ dependencies:
         - 10
         version: "1.10"
   type: :development
-  version_requirements: *id009
+  version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: webmock
   prerelease: false
-  requirement: &id010 !ruby/object:Gem::Requirement 
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -164,7 +136,7 @@ dependencies:
         - 6
         version: "1.6"
   type: :development
-  version_requirements: *id010
+  version_requirements: *id008
 description: A Nokogiri-based, optionally-evented Ruby wrapper to the Amazon Product Advertising API
 email: 
 - code@papercavalier.com
@@ -175,6 +147,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/sucker/config.rb
 - lib/sucker/hash_builder.rb
 - lib/sucker/parameters.rb
 - lib/sucker/request.rb
@@ -203,6 +176,7 @@ files:
 - spec/fixtures/cassette_library/spec/sucker/request.yml
 - spec/fixtures/cassette_library/spec/sucker/response.yml
 - spec/spec_helper.rb
+- spec/sucker/config_spec.rb
 - spec/sucker/hash_builder_spec.rb
 - spec/sucker/parameters_spec.rb
 - spec/sucker/request_spec.rb
@@ -266,6 +240,7 @@ test_files:
 - spec/fixtures/cassette_library/spec/sucker/request.yml
 - spec/fixtures/cassette_library/spec/sucker/response.yml
 - spec/spec_helper.rb
+- spec/sucker/config_spec.rb
 - spec/sucker/hash_builder_spec.rb
 - spec/sucker/parameters_spec.rb
 - spec/sucker/request_spec.rb