ruby-aaws 0.6.0 → 0.7.0

data/lib/amazon/aws/search.rb

@@ -1,4 +1,4 @@
-# $Id: search.rb,v 1.35 2009/05/26 16:27:12 ianmacd Exp $
+# $Id: search.rb,v 1.43 2009/06/14 22:28:27 ianmacd Exp $
 #
 
 module Amazon
@@ -28,10 +28,17 @@ module Amazon
 	#
 	class LocaleError < Amazon::AWS::Error::AWSError; end
 
-	# Requests can be authenticated using the SHA-256 Secure Hash
-	# Algorithm.
+	# Do we have support for the SHA-256 Secure Hash Algorithm?
 	#
-	DIGEST = OpenSSL::Digest::Digest.new( 'sha256' )
+	# Note that Module#constants returns Strings in Ruby 1.8 and Symbols
+	# in 1.9.
+	#
+	DIGEST_SUPPORT = OpenSSL::Digest.constants.include?( 'SHA256' ) ||
+			 OpenSSL::Digest.constants.include?( :SHA256 )
+
+	# Requests are authenticated using the SHA-256 Secure Hash Algorithm.
+	#
+	DIGEST = OpenSSL::Digest::Digest.new( 'sha256' ) if DIGEST_SUPPORT
 
 	attr_reader :conn, :config, :locale, :query, :user_agent
 	attr_writer :cache
@@ -40,9 +47,12 @@ module Amazon
 	# This method is used to generate an AWS search request object.
 	#
 	# _key_id_ is your AWS {access key
-	# ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html],
+	# ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html].
+	# Note that your secret key, used for signing requests, can be
+	# specified only in your <tt>~/.amazonrc</tt> configuration file.
+	#
 	# _associate_ is your
-	# Associates[http://docs.amazonwebservices.com/AWSECommerceService/2009-01-06/GSG/BecominganAssociate.html]
+	# Associates[http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/GSG/BecominganAssociate.html]
 	# tag (if any), _locale_ is the locale in which you which to work
 	# (*us* for amazon.com[http://www.amazon.com/], *uk* for
 	# amazon.co.uk[http://www.amazon.co.uk], etc.), _cache_ is whether or
@@ -184,7 +194,7 @@ module Amazon
 	# _xml_ is the XML node below which to search.
 	#
 	def error_check(xml)
-	  if xml = xml.elements['Errors/Error']
+	  if ! xml.nil? && xml = xml.elements['Errors/Error']
 	    raise Amazon::AWS::Error.exception( xml )
 	  end
 	end
@@ -195,7 +205,8 @@ module Amazon
 	#
 	def timestamp
 	  @query << '&Timestamp=%s' %
-	    [ Amazon.url_encode( Time.now.utc.strftime( '%FT%TZ' ) ) ]
+	    [ Amazon.url_encode(
+		Time.now.utc.strftime( '%Y-%m-%dT%H:%M:%SZ' ) ) ]
 	end
 	private :timestamp
 
@@ -204,6 +215,8 @@ module Amazon
 	# also adds a timestamp.
 	#
 	def sign
+	  return false unless DIGEST_SUPPORT
+
 	  timestamp
 	  params = @query[1..-1].split( '&' ).sort.join( '&' )
   
@@ -225,15 +238,32 @@ module Amazon
 
 	  params << '&Signature=%s' % [ signature ]
 	  @query = '?' + params
+
+	  true
 	end
 
 
-	# Perform a search of the AWS database. _operation_ is one of the
-	# objects subclassed from _Operation_, such as _ItemSearch_,
-	# _ItemLookup_, etc. It may also be a _MultipleOperation_ object.
+	# Perform a search of the AWS database, returning an AWSObject.
+	#
+	# _operation_ is an object of a subclass of _Operation_, such as
+	# _ItemSearch_, _ItemLookup_, etc. It may also be a _MultipleOperation_
+	# object.
+	#
+	# _response_group_, if supplied, is a set of one or more response
+	# groups to use in combination with _operation_ for the purpose of
+	# determining which data sets AWS should return.
+	#
+	# If _response_group_ is *nil*, Ruby/AWS will instead use the response
+	# groups specified by the _@response_group_ attribute of _operation_.
+	# That is now the preferred way of specifying response groups to use
+	# with a given operation. The _response_group_ parameter may later be
+	# removed from this method altogether.
 	#
-	# _response_group_ will apply to all both operations contained in
-	# _operation_, if _operation_ is a _MultipleOperation_ object.
+	# If _response_group_ is given, it will apply to all sub-operations of
+	# _operation_, if _operation_ is of class MultipleOperation. To use a
+	# different set of response groups for each sub-operation, you should
+	# assign to the _@response_group_ attribute of each of them before
+	# instantiating a MultipleOperation to combine them.
 	#
 	# _nr_pages_ is the number of results pages to return. It defaults to
 	# <b>1</b>. If a higher number is given, pages 1 to _nr_pages_ will be
@@ -243,17 +273,23 @@ module Amazon
 	# The maximum page number that can be returned for each type of
 	# operation is documented in the AWS Developer's Guide:
 	#
-	# http://docs.amazonwebservices.com/AWSECommerceService/2009-01-06/DG/index.html?MaximumNumberofPages.html
+	# http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/DG/index.html?MaximumNumberofPages.html
 	#
 	# Note that _ItemLookup_ operations can use three separate pagination
 	# parameters. Ruby/AWS, however, uses _OfferPage_ for the purposes of
 	# returning multiple pages.
 	#
 	# If operation is of class _MultipleOperation_, the operations
-	# combined within will return only the first page, regardless of
+	# specified within will return only the first page, regardless of
 	# whether a higher number of pages is requested.
 	#
-	def search(operation, response_group, nr_pages=1)
+	# If a block is passed to this method, each successive page of results
+	# will be yielded to the block.
+	#
+	def search(operation, response_group=nil, nr_pages=1)
+	  response_group ||=
+	    operation.response_group || ResponseGroup.new( :Large )
+
 	  parameters = Amazon::AWS::SERVICE.
 			 merge( { 'AWSAccessKeyId' => @key_id,
 				  'AssociateTag'   => @tag } ).
@@ -267,6 +303,11 @@ module Amazon
 
 	  @query = Amazon::AWS.assemble_query( parameters, @encoding )
 	  page = Amazon::AWS.get_page( self )
+
+	  # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
+	  #
+	  page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'
+
 	  doc = Document.new( page )
 
 	  # Some errors occur at the very top level of the XML. For example,
@@ -369,6 +410,11 @@ module Amazon
 		      parameters.merge( { page_parameter => page_nr } ),
 		      @encoding)
 	    page = Amazon::AWS.get_page( self )
+
+	    # Ruby 1.9 needs to know that the page is UTF-8, not ASCII-8BIT.
+	    #
+	    page.force_encoding( 'utf-8' ) if RUBY_VERSION >= '1.9.0'
+
 	    doc = Document.new( page )
 
 	    # Check for errors.

data/test/setup.rb

@@ -1,4 +1,4 @@
-# $Id: setup.rb,v 1.4 2009/05/25 23:35:54 ianmacd Exp $
+# $Id: setup.rb,v 1.5 2009/06/14 00:28:48 ianmacd Exp $
 #
 
 # Attempt to load Ruby/AWS using RubyGems.
@@ -27,6 +27,8 @@ class AWSTest < Test::Unit::TestCase
     @req.encoding = 'utf-8'
   end
 
-  undef_method :default_test
+  # The default_test method needs to be removed before Ruby 1.9.0.
+  #
+  undef_method :default_test if method_defined? :default_test
  
 end

data/test/tc_aws.rb

@@ -1,4 +1,4 @@
-# $Id: tc_aws.rb,v 1.11 2008/10/02 21:33:58 ianmacd Exp $
+# $Id: tc_aws.rb,v 1.12 2009/06/14 00:29:28 ianmacd Exp $
 #
 
 require 'test/unit'
@@ -13,7 +13,7 @@ class TestAWSBasics < AWSTest
   CACHE_PATH = File.join( Dir.tmpdir, 'aws_cache' )
 
   def test_version
-    v = '1.8.6'
+    v = '1.8.7'
     assert( RUBY_VERSION >= v, "Ruby version is lower than #{v}." )
   end
 

data/test/tc_browse_node_lookup.rb

@@ -0,0 +1,62 @@
+# $Id: tc_browse_node_lookup.rb,v 1.2 2009/06/02 00:39:43 ianmacd Exp $
+#
+
+require 'test/unit'
+require './setup'
+
+class TestBrowseNodeLookup < AWSTest
+
+  def test_browse_node_lookup
+
+    bnl = BrowseNodeLookup.new( 694212 )
+    rg = ResponseGroup.new( :BrowseNodeInfo )
+
+    response = @req.search( bnl, rg )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_no_response_group
+
+    bnl = BrowseNodeLookup.new( 694212 )
+    bnl.response_group = ResponseGroup.new( :BrowseNodeInfo )
+    response = @req.search( bnl, nil )
+
+    results = response.kernel
+
+    # Ensure we got more than 10 results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_class_method
+
+    response = Amazon::AWS.browse_node_lookup( 694212 )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_browse_node_lookup_class_method_block
+
+    Amazon::AWS.browse_node_lookup( '694212' ) do |r|
+
+      results = r.kernel
+
+      # Ensure we got some actual results back.
+      #
+      assert( results.size > 0 )
+    end
+  end
+
+end

data/test/tc_customer_content_lookup.rb

@@ -0,0 +1,64 @@
+# $Id: tc_customer_content_lookup.rb,v 1.1 2009/06/02 00:29:18 ianmacd Exp $
+#
+
+require 'test/unit'
+require './setup'
+
+class TestCustomerContentLookup < AWSTest
+
+  def test_customer_content_lookup
+
+    @req.locale = 'us'
+    ccl = CustomerContentLookup.new( 'AJDWXANG1SYZP' )
+    rg = ResponseGroup.new( :CustomerReviews )
+
+    response = @req.search( ccl, rg )
+
+    review = response.customer_content_lookup_response.customers.customer.
+	     customer_reviews.review[0]
+
+    # Ensure we got the right review.
+    #
+    assert_equal( 3746, review.content[0].size )
+
+  end
+
+  def test_customer_content_lookup_no_response_group
+
+    @req.locale = 'us'
+    ccl = CustomerContentLookup.new( 'AJDWXANG1SYZP' )
+    ccl.response_group = ResponseGroup.new( :CustomerReviews )
+    response = @req.search( ccl, nil )
+
+    review = response.customer_content_lookup_response.customers.customer.
+	     customer_reviews.review[0]
+
+    # Ensure we got the right review.
+    #
+    assert_equal( 3746, review.content[0].size )
+
+  end
+
+  def test_customer_content_lookup_class_method
+
+    response = Amazon::AWS.customer_content_lookup( 'AA5QZU6TJQXEN' )
+
+    nickname = response.customer_content_lookup_response.customers.customer.
+	       nickname
+
+    assert_equal( 'jimwood43', nickname )
+
+  end
+
+  def test_item_search_class_method_block
+
+    Amazon::AWS.customer_content_lookup( 'AA5QZU6TJQXEN' ) do |r|
+
+      nickname = r.customer_content_lookup_response.customers.customer.nickname
+
+      assert_equal( 'jimwood43', nickname )
+
+    end
+  end
+
+end

data/test/tc_help.rb

@@ -0,0 +1,60 @@
+# $Id: tc_help.rb,v 1.2 2009/06/02 00:39:23 ianmacd Exp $
+#
+
+require 'test/unit'
+require './setup'
+
+class TestHelp < AWSTest
+
+  def test_help
+
+    h = Help.new( 'ResponseGroup', 'Large' )
+    rg = ResponseGroup.new( 'Help' )
+    response = @req.search( h, rg )
+
+    # Get a list of valid operations for the Large response group.
+    #
+    results = response.help_response[0].information.response_group_information.
+	      valid_operations.operation
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_help_no_response_group
+
+    h = Help.new( 'ResponseGroup', 'Large' )
+    h.response_group = ResponseGroup.new( 'Help' )
+    response = @req.search( h, nil )
+
+    # Get a list of valid operations for the Large response group.
+    #
+    results = response.help_response[0].information.response_group_information.
+	      valid_operations.operation
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_help_class_method
+
+    response = Amazon::AWS.help( 'ResponseGroup', 'Large' )
+
+    # With no response group, Large will be tried. The resulting exception
+    # will be rescued and the text of the message returned by AWS will be used
+    # to determine a response group that will work.
+    #
+    results = response.help_response[0].information.response_group_information.
+	      valid_operations.operation
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+end

data/test/tc_item_lookup.rb

@@ -0,0 +1,60 @@
+# $Id: tc_item_lookup.rb,v 1.2 2009/05/30 11:11:27 ianmacd Exp $
+#
+
+require 'test/unit'
+require './setup'
+
+class TestItemLookup < AWSTest
+
+  def test_item_lookup
+
+    is = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000AE4QEC' } )
+    response = @req.search( is, @rg )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_item_lookup_no_response_group
+
+    is = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000AE4QEC' } )
+    is.response_group = ResponseGroup.new( :Small )
+    response = @req.search( is, nil )
+
+    results = response.kernel
+
+    # Ensure we got more than 10 results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_item_lookup_class_method
+
+    response = Amazon::AWS.item_lookup( 'ASIN', { 'ItemId' => 'B000AE4QEC' } )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_item_search_class_method_block
+
+    Amazon::AWS.item_lookup( 'ASIN', { 'ItemId' => 'B000AE4QEC' } ) do |r|
+
+      results = r.kernel
+
+      # Ensure we got some actual results back.
+      #
+      assert( results.size > 0 )
+    end
+  end
+
+end

data/test/tc_item_search.rb

@@ -1,5 +1,10 @@
-# $Id: tc_item_search.rb,v 1.3 2009/05/26 16:18:14 ianmacd Exp $
+# encoding: ASCII-8BIT
 #
+# $Id: tc_item_search.rb,v 1.6 2009/06/15 10:18:07 ianmacd Exp $
+#
+# The encoding at the top of this file is necessary for Ruby 1.9, which will
+# otherwise choke with 'invalid multibyte char (US-ASCII)' when it reads the
+# ISO-8859-1 encoded accented 'e' in the test_item_search_iso_8859_15 method.
 
 require 'test/unit'
 require './setup'
@@ -12,7 +17,9 @@ class TestItemSearch < AWSTest
     # ISO-8859-15, a.k.a. Latin-15.
     #
     @req.encoding = 'iso-8859-15'
-    is = ItemSearch.new( 'Books', { 'Title' => 'Caf�' } )
+
+    str = 'Caf�'
+    is = ItemSearch.new( 'Books', { 'Title' => str } )
     response = @req.search( is, @rg )
 
     results = response.kernel
@@ -28,7 +35,9 @@ class TestItemSearch < AWSTest
     # Manually set UTF-8 encoding.
     #
     @req.encoding = 'utf-8'
-    is = ItemSearch.new( 'Books', { 'Title' => 'Café' } )
+
+    str = 'Café'
+    is = ItemSearch.new( 'Books', { 'Title' => str } )
     response = @req.search( is, @rg )
 
     results = response.kernel
@@ -41,13 +50,28 @@ class TestItemSearch < AWSTest
 
   def test_item_search_multiple_pages
 
+    @req.encoding = 'utf-8'
     is = ItemSearch.new( 'Books', { 'Title' => 'programming' } )
     responses = @req.search( is, @rg, 5 )
 
     results = []
-    responses.each do |response|
-      results += response.kernel
-    end
+    responses.each { |response| results += response.kernel }
+
+    # Ensure we got more than 10 results back.
+    #
+    assert( results.size > 10 )
+
+  end
+
+  def test_item_search_no_response_group
+
+    @req.encoding = 'utf-8'
+    is = ItemSearch.new( 'Books', { 'Title' => 'programming' } )
+    is.response_group = ResponseGroup.new( :Small )
+    responses = @req.search( is, nil, 5 )
+
+    results = []
+    responses.each { |response| results += response.kernel }
 
     # Ensure we got more than 10 results back.
     #
@@ -55,4 +79,28 @@ class TestItemSearch < AWSTest
 
   end
 
+  def test_item_search_class_method
+
+    response = Amazon::AWS.item_search( 'Books', { 'Title' => 'programming' } )
+
+    results = response.kernel
+
+    # Ensure we got some actual results back.
+    #
+    assert( results.size > 0 )
+
+  end
+
+  def test_item_search_class_method_block
+
+    Amazon::AWS.item_search( 'Books', { 'Title' => 'programming' } ) do |r|
+
+      results = r.kernel
+
+      # Ensure we got some actual results back.
+      #
+      assert( results.size > 0 )
+    end
+  end
+
 end