ruby-aaws 0.4.1 → 0.4.2

data/NEWS

@@ -1,4 +1,41 @@
-$Id: NEWS,v 1.9 2008/08/18 08:37:54 ianmacd Exp $
+$Id: NEWS,v 1.12 2008/09/10 22:15:41 ianmacd Exp $
+
+
+0.4.2
+-----
+
+The version of the Amazon AWS API requested when performing operations is now
+2008-08-19. This is the latest at the time of writing.
+
+The exception class Amazon::Config::ConfigError was mysteriously not defined.
+
+Amazon::Config.new now accepts an optional argument, config_str, which may
+contain the string equivalent of a config file's contents. When config_str is
+not nil (nil is the default), this string is read instead of /etc/amazonrc and
+~/.amazonrc. This addition is really just to aid unit-testing of the
+Amazon::Config class, as Amazon::Config.new never needs to be called by user
+code.
+
+Config file lines may now contain leading whitespace.
+
+The Amazon::AWS::MAX_PAGES constant has gone, replaced by the PAGINATION hash.
+Only ItemSearch should use ItemPage to page through results up to MAX_PAGES
+when ALL_PAGES has been requested, but the same approach was attempted for all
+types of operation.
+     
+Each operation has its own pagination parameter and its own maximum number of
+pages that can be fetched. This is now stored in the Amazon::AWS::PAGINATION
+hash.
+        
+Note that ItemLookup has three possible pagination parameters: OfferPage,
+VariationPage and ReviewPage. Ruby/AWS uses OfferPage for the purposes of
+ALL_PAGES.
+	   
+Operations that do not explicitly provide a pagination parameter (or, at
+least, those for which there isn't one listed in the AWS Developer's Guide)
+use ItemPage and pagination up to page 400. This is likely to throw an
+exception, as such operations almost certainly don't support multiple results
+pages.
 
 
 0.4.1
@@ -17,6 +54,10 @@ file:
 
 Choose one of these at your convenience.
 
+The Ruby/AWS gem has been renamed ruby-aaws (from ruby-aws) to avoid a
+namespace clash with another project. This clash prevented remote installation
+of the gem.
+
 
 0.4.0
 -----

data/README.rdoc

@@ -1,5 +1,5 @@
 #--
-# $Id: README.rdoc,v 1.14 2008/07/05 16:10:04 ianmacd Exp $
+# $Id: README.rdoc,v 1.17 2008/09/10 21:56:13 ianmacd Exp $
 #++
 #
 #
@@ -80,11 +80,9 @@
 # RubyGems[http://www.rubygems.org/] installation.
 #
 # Note, however, if choosing the gem installation, that whilst Ruby/AWS's
-# RubyForge UNIX name is ruby-aws, that name is already claimed by an {earlier
-# project}[http://rubyforge.org/projects/ruby-aws/]. For that reason, it's
-# necessary to download the gem to a local file before installing, because
-# RubyForge's gem repository will always find the other ruby-aws project when
-# queried for this name.
+# RubyForge UNIX name is now ruby-aaws. The ruby-aws name was taken by
+# {another project}[http://rubyforge.org/projects/ruby-aws/] and this clash
+# prevented remote installation of the Ruby/AWS gem.
 #
 #
 # == Prerequisites
@@ -115,22 +113,22 @@
 # where you can discuss all Ruby/AWS-related subjects and issues.
 #
 # Please see the Amazon Web Services
-# documentation[http://www.amazon.com/E-Commerce-Service-AWS-home-page/b/ref=sc_fe_c_0_15763381_1?node=12738641]
+# documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5]
 # for definitive information on the capabilities and inner workings of the AWS
 # API.
 #
 #
 # == Download
 #
-# Version 0.4.1
-# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.4.1.tar.gz]
-# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.4.1.gem]
-# === {Fedora 7 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aaws-0.4.1-1.fc7.noarch.rpm]
-# === {Fedora 7 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.4.1-1.fc7.noarch.rpm]
-# === {Fedora 7 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.4.1-1.fc7.src.rpm]
+# Version 0.4.2
+# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.4.2.tar.gz]
+# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.4.2.gem]
+# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.4.2-1.fc9.noarch.rpm]
+# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.4.2-1.fc9.noarch.rpm]
+# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.4.2-1.fc9.src.rpm]
 # 
 # 
 # ---
 # Author::   Ian Macdonald <mailto:ian@caliban.org>
-# Version::  0.4.1
+# Version::  0.4.2
 # Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

data/lib/amazon.rb

@@ -1,4 +1,4 @@
-# $Id: amazon.rb,v 1.18 2008/08/17 12:00:39 ianmacd Exp $
+# $Id: amazon.rb,v 1.20 2008/09/08 22:42:30 ianmacd Exp $
 #
 
 module Amazon
@@ -48,26 +48,59 @@ module Amazon
   #
   class Config < Hash
 
-    def initialize
+    require 'stringio'
 
-      config_files = [ File.join( '', 'etc', 'amazonrc' ) ]
+    # Exception class for configuration file errors.
+    #
+    class ConfigError < StandardError; end
+
+    # A configuration may be passed in as a string. Otherwise, the files
+    # <tt>/etc/amazonrc</tt> and <tt>~/.amazonrc</tt> are read if they exist
+    # and are readable.
+    #
+    def initialize(config_str=nil)
+
+      if config_str
+
+	# We have been passed a config file as a string.
+	#
+        config_files = [ config_str ]
+	config_class = StringIO
+
+      else
+
+	# Perform the usual search for the system and user config files.
+	#
+	config_files = [ File.join( '', 'etc', 'amazonrc' ) ]
 
-      # Figure out where home is. The subsequent locations are for Windows.
-      # [ruby-core:12347]
-      #
-      home = ENV['HOME'] || ENV['HOMEDRIVE'] + ENV['HOMEPATH'] ||
-	     ENV['USERPROFILE']
+	# Figure out where home is. The subsequent locations are for Windows.
+	# [ruby-core:12347]
+	#
+	home = ENV['HOME'] || ENV['HOMEDRIVE'] + ENV['HOMEPATH'] ||
+	       ENV['USERPROFILE']
 
-      if home
-        config_files << File.expand_path( File.join( '~', '.amazonrc' ) )
+	if home
+	  config_files << File.expand_path( File.join( '~', '.amazonrc' ) )
+	end
+
+	config_class = File
       end
 
       config_files.each do |cf|
-	if File.exists?( cf ) && File.readable?( cf )
 
-	  Amazon.dprintf( 'Opening %s ...', cf )
+	if config_class == StringIO
+	  readable = true
+	else
+	  # We must determine whether the file is readable.
+	  #
+	  readable = File.exists?( cf ) && File.readable?( cf )
+	end
+
+	if readable
+
+	  Amazon.dprintf( 'Opening %s ...', cf ) if config_class == File
     
-	  File.open( cf ) { |f| lines = f.readlines }.each do |line|
+	  config_class.open( cf ) { |f| lines = f.readlines }.each do |line|
 	    line.chomp!
     
 	    # Skip comments and blank lines.
@@ -79,9 +112,10 @@ module Amazon
 	    # Store these, because we'll probably find a use for these later.
 	    #
 	    begin
-      	    match = line.match( /^(\S+)\s*=\s*(['"]?)([^'"]+)(['"]?)/ )
+      	      match = line.match( /^\s*(\S+)\s*=\s*(['"]?)([^'"]+)(['"]?)/ )
 	      key, begin_quote, val, end_quote = match[1, 4]
 	      raise ConfigError if begin_quote != end_quote
+
 	    rescue NoMethodError, ConfigError
 	      raise ConfigError, "bad config line: #{line}"
 	    end

data/lib/amazon/aws.rb

@@ -1,4 +1,4 @@
-# $Id: aws.rb,v 1.65 2008/08/18 08:38:36 ianmacd Exp $
+# $Id: aws.rb,v 1.68 2008/09/10 21:56:14 ianmacd Exp $
 #
 #:include: ../../README.rdoc
 
@@ -12,7 +12,7 @@ module Amazon
     require 'rexml/document'
 
     NAME = '%s/%s' % [ Amazon::NAME, 'AWS' ]
-    VERSION = '0.4.1'
+    VERSION = '0.4.2'
     USER_AGENT = '%s %s' % [ NAME, VERSION ]
 
     # Default Associate tags to use per locale.
@@ -29,7 +29,7 @@ module Amazon
     # Service name and version for AWS.
     #
     SERVICE = { 'Service' => 'AWSECommerceService',
-		'Version' => '2008-06-26'
+		'Version' => '2008-08-19'
     }
 
     # Maximum number of 301 and 302 HTTP responses to follow, should Amazon
@@ -38,10 +38,29 @@ module Amazon
     MAX_REDIRECTS = 3
 
     # Maximum number of results pages that can be retrieved for a given
-    # search.
+    # search operation, using whichever pagination parameter is relevant to
+    # that type of operation.
     #
-    MAX_PAGES = 400
-
+    PAGINATION = { 'ItemSearch' =>	      { 'parameter' => 'ItemPage',
+						'max_page'  =>  400 },
+		   'ItemLookup'	=>	      { 'paraneter' => 'OfferPage',
+						'max_page'  => 100 },
+		   'ListLookup' =>	      { 'parameter' => 'ProductPage',
+						'max_page'  =>  30 },
+		   'ListSearch' =>	      { 'parameter' => 'ListPage',
+						'max_page'  =>  20 },
+		   'CustomerContentLookup' => { 'parameter' => 'ReviewPage',
+						'max_page'  => 10 },
+		   'CustomerContentSearch' => { 'parameter' => 'CustomerPage',
+						'max_page'  => 20 }
+		 }
+    # N.B. ItemLookup can also use the following two pagination parameters
+    #
+    #		      max. page
+    #		      ---------
+    # VariationPage   150
+    # ReviewPage       20
+	  
     # Exception class for HTTP errors.
     #
     class HTTPError < StandardError; end

data/lib/amazon/aws/search.rb

@@ -1,4 +1,4 @@
-# $Id: search.rb,v 1.21 2008/05/31 19:42:04 ianmacd Exp $
+# $Id: search.rb,v 1.23 2008/09/10 21:43:58 ianmacd Exp $
 #
 
 module Amazon
@@ -174,8 +174,8 @@ module Amazon
 	private :error_check
 
 
-	# Perform a search of the AWS catalogue. _operation_ is one of the
-	# objects subclased from _Operation_, such as _ItemSearch_,
+	# 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.
 	#
 	# _response_group_ will apply to all both operations contained in
@@ -186,6 +186,15 @@ module Amazon
 	# returned. If the special value <b>:ALL_PAGES</b> is given, all
 	# results pages will be returned.
 	#
+	# 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/2008-08-19/DG/index.html?CHAP_MakingRequestsandUnderstandingResponses.html#PagingThroughResults
+	#
+	# 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
 	# whether a higher number of pages is requested.
@@ -273,11 +282,19 @@ module Amazon
 	  #
 	  nr_pages = tp.to_i if nr_pages == :ALL_PAGES || nr_pages > tp.to_i
 
+	  if PAGINATION.key? operation.kind
+	    page_parameter = PAGINATION[operation.kind]['parameter']
+	    max_pages = PAGINATION[operation.kind]['max_page']
+	  else
+	    page_parameter = 'ItemPage'
+	    max_pages = 400
+	  end
+
 	  # Iterate over pages 2 and higher, but go no higher than MAX_PAGES.
 	  #
-	  2.upto( nr_pages < MAX_PAGES ? nr_pages : MAX_PAGES ) do |page_nr|
+	  2.upto( nr_pages < max_pages ? nr_pages : max_pages ) do |page_nr|
 	    query = Amazon::AWS.assemble_query(
-		      q_params.merge( { 'ItemPage' => page_nr } ) )
+		      q_params.merge( { page_parameter => page_nr } ) )
 	    page = Amazon::AWS.get_page( self, query )
 	    doc = Document.new( page )
 

data/test/tc_aws.rb

@@ -1,4 +1,4 @@
-# $Id: tc_aws.rb,v 1.8 2008/08/12 09:50:48 ianmacd Exp $
+# $Id: tc_aws.rb,v 1.9 2008/09/08 21:23:01 ianmacd Exp $
 #
 
 require 'test/unit'
@@ -92,8 +92,22 @@ class TestAWSBasics < AWSTest
 
   end
 
+  def test_config
+    assert_raise( Amazon::Config::ConfigError ) do
+      cf = Amazon::Config.new( <<'      EOF' )
+      bad_syntax = 'bad quotes"
+      EOF
+    end
+
+    assert_nothing_raised do
+      cf = Amazon::Config.new( <<'      EOF' )
+      good_syntax = 'good quotes'
+      EOF
+    end
+  end
+
   def test_exceptions
-    assert_raise( Amazon::AWS::HTTPError) { raise Amazon::AWS::HTTPError }
+    assert_raise( Amazon::AWS::HTTPError ) { raise Amazon::AWS::HTTPError }
   end
 
   include Amazon

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: ruby-aaws
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
-date: 2008-08-18 00:00:00 +02:00
+  version: 0.4.2
+date: 2008-09-11 00:00:00 +02:00
 summary: Ruby interface to Amazon Associates Web Services
 require_paths: 
 - lib