ruby-aaws 0.4.1

data/example/similarity_lookup1

@@ -0,0 +1,48 @@
+#!/usr/bin/ruby -w
+#
+# $Id: similarity_lookup1,v 1.1 2008/04/27 06:03:54 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# Example of a batch operation, using the ASIN as the shared ID.
+#
+sl = SimilarityLookup.new( [ 'B000AE4QEC', 'B000051WBE' ] )
+
+# You can have multiple response groups.
+#
+rg = ResponseGroup.new( 'Medium', 'Offers', 'Reviews' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( sl, rg )
+item_sets = resp.similarity_lookup_response[0].items
+
+item_sets.each do |item_set|
+  item_set.item.each do |item|
+    attribs = item.item_attributes[0]
+    puts attribs.label
+    if attribs.list_price
+      puts attribs.title, attribs.list_price[0].formatted_price
+    end
+  
+    # Availability has become a cumbersome thing to retrieve in AWSv4.
+    #
+    puts 'Availability: %s' %
+      [ item.offers[0].offer[0].offer_listing[0].availability ]
+    puts 'Average rating: %s' % [ item.customer_reviews[0].average_rating ]
+    puts 'Reviewed by %s customers.' %
+      [ item.customer_reviews[0].total_reviews ]
+  
+    puts 'Customers said:'
+    item.customer_reviews[0].review.each do |review|
+      puts '  %s (%s votes)' % [ review.summary, review.total_votes ]
+    end
+  
+    puts
+  end
+end

data/example/tag_lookup1

@@ -0,0 +1,34 @@
+#!/usr/bin/ruby -w
+#
+# $Id: tag_lookup1,v 1.1 2008/04/27 19:46:43 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+tag_str = 'Awful'
+tl = TagLookup.new( tag_str )
+
+# You can have multiple response groups.
+#
+rg = ResponseGroup.new( 'Tags', 'TagsSummary' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( tl, rg )
+tag = resp.tag_lookup_response.tags.tag
+
+printf( "Tag name '%s' has %d distinct items.\n", tag_str, tag.distinct_items )
+printf( "Tag has %d distinct items.\n", tag.distinct_users )
+printf( "Tag has %d total usages.\n", tag.total_usages )
+printf( "Tagged for the first time in entity %s on %s\nby %s..\n",
+        tag.first_tagging.entity_id,
+	tag.first_tagging.time,
+	tag.first_tagging.user_id )
+printf( "Tagged for the last time in entity %s on %s\nby %s..\n",
+        tag.last_tagging.entity_id,
+	tag.last_tagging.time,
+	tag.last_tagging.user_id )

data/example/transaction_lookup1

@@ -0,0 +1,26 @@
+#!/usr/bin/ruby -w
+#
+# $Id: transaction_lookup1,v 1.1 2008/04/27 21:24:21 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+tl = TransactionLookup.new( '103-5663398-5028241' )
+
+rg = ResponseGroup.new( 'TransactionDetails' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( tl, rg )
+trans = resp.transaction_lookup_response.transactions.transaction
+
+printf( "Transaction date was %s.\n", trans.transaction_date )
+printf( "It was in the amount of %s and the seller was %s.\n",
+        trans.totals.total.formatted_price, trans.seller_name )
+printf( "The shipping charge was %s and the package was sent by %s.\n",
+        trans.totals.shipping_charge.formatted_price,
+	trans.shipments.shipment.delivery_method )

data/lib/amazon/aws/cache.rb

@@ -0,0 +1,141 @@
+# $Id: cache.rb,v 1.8 2008/06/10 06:33:46 ianmacd Exp $
+#
+
+module Amazon
+
+  module AWS
+
+    # This class provides a simple results caching system for operations
+    # performed by AWS.
+    #
+    # To use it, set _cache_ to *true* in either <tt>/etc/amazonrc</tt> or
+    # <tt>~/.amazonrc</tt>.
+    #
+    # By default, the cache directory used is <tt>/tmp/amazon</tt>, but this
+    # can be changed by defining _cache_dir_ in either <tt>/etc/amazonrc</tt>
+    # or <tt>~/.amazonrc</tt>.
+    #
+    # When a cache is used, Ruby/AWS will check the cache directory for a
+    # recent copy of a response to the exact operation that you are
+    # performing. If found, the cached response will be returned instead of
+    # the request being forwarded to the AWS servers for processing. If no
+    # (recent) copy is found, the request will be forwarded to the AWS servers
+    # as usual. Recency is defined here as less than 24 hours old.
+    #
+    class Cache
+
+      require 'fileutils'
+
+      begin
+        require 'md5'
+      rescue LoadError
+	# Ruby 1.9 has moved MD5.
+	#
+	require 'digest/md5'
+      end
+
+      # Exception class for bad cache paths.
+      #
+      class PathError < StandardError; end
+
+      # Length of one day in seconds
+      #
+      ONE_DAY = 86400	# :nodoc:
+
+      # Age in days below which to consider cache files valid.
+      #
+      MAX_AGE = 1.0
+
+      # Default cache location.
+      #
+      DEFAULT_CACHE_DIR = '/tmp/amazon'
+
+      attr_reader :path
+
+      def initialize(path=DEFAULT_CACHE_DIR)
+	path ||= DEFAULT_CACHE_DIR
+
+	::FileUtils::mkdir_p( path ) unless File.exists? path
+
+	unless File.directory? path 
+	  raise PathError, "cache path #{path} is not a directory"
+	end
+
+	unless File.readable? path 
+	  raise PathError, "cache path #{path} is not readable"
+	end
+
+	unless File.writable? path
+	  raise PathError, "cache path #{path} is not writable"
+	end
+
+	@path = path
+      end
+
+
+      # Determine whether or not the the response to a given URL is cached.
+      # Returns *true* or *false*.
+      #
+      def cached?(url)
+	digest = Digest::MD5.hexdigest( url )
+
+	cache_files = Dir.glob( File.join( @path, '*' ) ).map do |d|
+	  File.basename( d )
+	end
+
+	return cache_files.include?( digest ) &&
+	  ( Time.now - File.mtime( File.join( @path, digest ) ) ) /
+	  ONE_DAY <= MAX_AGE
+      end
+
+
+      # Retrieve the cached response associated with _url_.
+      #
+      def fetch(url)
+	digest = Digest::MD5.hexdigest( url )
+	cache_file = File.join( @path, digest )
+
+	return nil unless File.exist? cache_file
+
+	Amazon.dprintf( 'Fetching %s from cache...', digest )
+	File.open( File.join( cache_file ) ).readlines.to_s
+      end
+
+
+      # Cache the data from _contents_ and associate it with _url_.
+      #
+      def store(url, contents)
+	digest = Digest::MD5.hexdigest( url )
+	cache_file = File.join( @path, digest )
+
+	Amazon.dprintf( 'Caching %s...', digest )
+	File.open( cache_file, 'w' ) { |f| f.puts contents }
+      end
+
+
+      # This method flushes all files from the cache directory specified
+      # in the object's <i>@path</i> variable.
+      #
+      def flush_all
+	FileUtils.rm Dir.glob( File.join( @path, '*' ) )
+      end
+
+
+      # This method flushes expired files from the cache directory specified
+      # in the object's <i>@path</i> variable.
+      #
+      def flush_expired
+	now = Time.now
+
+	expired_files = Dir.glob( File.join( @path, '*' ) ).find_all do |f|
+	  ( now - File.mtime( f ) ) / ONE_DAY > MAX_AGE
+	end
+
+	FileUtils.rm expired_files
+      end
+
+    end
+
+  end
+
+end

data/lib/amazon/aws/search.rb

@@ -0,0 +1,317 @@
+# $Id: search.rb,v 1.21 2008/05/31 19:42:04 ianmacd Exp $
+#
+
+module Amazon
+
+  module AWS
+
+    require 'amazon/aws'
+    require 'net/http'
+    require 'rexml/document'
+
+    # Load this library with:
+    #
+    #  require 'amazon/aws/search'
+    #
+    module Search
+
+      class Request
+
+	include REXML
+
+	# Exception class for bad access key ID.
+	#
+	class AccessKeyIdError < StandardError; end
+
+	# Exception class for bad locales.
+	#
+	class LocaleError < StandardError; end
+
+	attr_reader :conn, :locale, :user_agent
+	attr_writer :cache
+
+	# 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],
+	# _associate_ is your
+	# Associates[http://docs.amazonwebservices.com/AWSECommerceService/2008-04-07/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
+	# not you wish to utilise a response cache, and _user_agent_ is the
+	# client name to pass when performing calls to AWS. By default,
+	# _user_agent_ will be set to a string identifying the Ruby/AWS
+	# library and its version number.
+	#
+	# _locale_ and _cache_ can also be set later, if you wish to change
+	# the current behaviour.
+	#
+	# Example:
+	#
+	#  req = Request.new( '0Y44V8FAFNM119CX4TR2', 'calibanorg-20' )
+	#
+	def initialize(key_id=nil, associate=nil, locale=nil, cache=nil,
+		       user_agent=USER_AGENT)
+
+	  @config ||= Amazon::Config.new
+
+	  def_locale = locale
+	  locale = 'us' unless locale
+	  locale.downcase!
+
+	  key_id ||= @config['key_id']
+	  cache = @config['cache'] if cache.nil?
+
+	  # Take locale from config file if no locale was passed to method.
+	  #
+	  if @config.key?( 'locale' ) && ! def_locale
+	    locale = @config['locale']
+	  end
+	  validate_locale( locale )
+
+	  if key_id.nil?
+	    raise AccessKeyIdError, 'key_id may not be nil'
+	  end
+
+	  @key_id     = key_id
+	  @tag	      = associate || @config['associate'] || DEF_ASSOC[locale]
+	  @user_agent = user_agent
+	  @cache      = unless cache == 'false' || cache == false
+			  Amazon::AWS::Cache.new( @config['cache_dir'] )
+			else
+			  nil
+			end
+	  self.locale = locale
+	end
+
+
+	# Assign a new locale. If the locale we're coming from is using the
+	# default Associate ID for that locale, then we use the new locale's
+	# default ID, too.
+	#
+	def locale=(l)  # :nodoc:
+	  old_locale = @locale ||= nil
+	  @locale = validate_locale( l )
+
+	  # Use the new locale's default ID if the ID currently in use is the
+	  # current locale's default ID.
+	  #
+	  if @tag == Amazon::AWS::DEF_ASSOC[old_locale]
+	    @tag = Amazon::AWS::DEF_ASSOC[@locale]
+	  end
+
+	  # We must now set up a new HTTP connection to the correct server for
+	  # this locale, unless the same server is used for both.
+	  #
+	  unless Amazon::AWS::ENDPOINT[@locale] ==
+		 Amazon::AWS::ENDPOINT[old_locale]
+	    #connect( @locale )
+	    @conn = nil
+	  end
+	end
+
+
+	# If @cache has simply been assigned *true* at some point in time,
+	# assign a proper cache object to it when it is referenced. Otherwise,
+	# just return its value.
+	#
+	def cache  # :nodoc:
+	  if @cache == true
+	    @cache = Amazon::AWS::Cache.new( @config['cache_dir'] )
+	  else
+	    @cache
+	  end
+	end
+
+
+	# Verify the validity of a locale string. _l_ is the locale string.
+	#
+	def validate_locale(l)
+	  unless Amazon::AWS::ENDPOINT.has_key? l
+	    raise LocaleError, "invalid locale: #{l}"
+	  end
+	  l
+	end
+	private :validate_locale
+
+
+	# Return an HTTP connection for the current _locale_.
+	#
+	def connect(locale)
+	  if ENV.key? 'http_proxy'
+	    uri = URI.parse( ENV['http_proxy'] )
+	    proxy_user = proxy_pass = nil
+	    proxy_user, proxy_pass = uri.userinfo.split( /:/ ) if uri.userinfo
+	    @conn = Net::HTTP::Proxy( uri.host, uri.port, proxy_user,
+				      proxy_pass ).start(
+					Amazon::AWS::ENDPOINT[locale].host )
+	  else
+	    @conn = Net::HTTP::start( Amazon::AWS::ENDPOINT[locale].host )
+	  end
+	end
+	private :connect
+
+
+	# Reconnect to the server if our connection has been lost (due to a
+	# time-out, etc.).
+	#
+	def reconnect  # :nodoc:
+	  connect( self.locale )
+	  self
+	end
+
+
+	# This method checks for errors in an XML response returned by AWS.
+	# _xml_ is the XML node below which to search.
+	#
+	def error_check(xml)
+	  if xml = xml.elements['Errors/Error']
+	    error = Amazon::AWS::Error::AWSError.new( xml )
+	    raise error.exception
+	  end
+	end
+	private :error_check
+
+
+	# Perform a search of the AWS catalogue. _operation_ is one of the
+	# objects subclased from _Operation_, such as _ItemSearch_,
+	# _ItemLookup_, etc. It may also be a _MultipleOperation_ object.
+	#
+	# _response_group_ will apply to all both operations contained in
+	# _operation_, if _operation_ is a _MultipleOperation_ object.
+	#
+	# _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
+	# returned. If the special value <b>:ALL_PAGES</b> is given, all
+	# results pages will be returned.
+	#
+	# 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.
+	#
+	def search(operation, response_group, nr_pages=1)
+	  q_params = Amazon::AWS::SERVICE.
+		       merge( { 'AWSAccessKeyId' => @key_id,
+				'AssociateTag'   => @tag } ).
+		       merge( operation.params ).
+		       merge( response_group.params )
+
+	  query = Amazon::AWS.assemble_query( q_params )
+	  page = Amazon::AWS.get_page( self, query )
+	  doc = Document.new( page )
+
+	  # Some errors occur at the very top level of the XML. For example,
+	  # when no Operation parameter is given. This should not be possible
+	  # with user code, but occurred during debugging of this library.
+	  #
+	  error_check( doc )
+
+	  # Fundamental errors happen at the OperationRequest level. For
+	  # example, if an invalid AWSAccessKeyId is used.
+	  #
+	  error_check( doc.elements['*/OperationRequest'] )
+
+	  # Check for parameter and value errors deeper down, inside Request.
+	  #
+	  if operation.kind == 'MultipleOperation'
+
+	    # Everything is a level deeper, because of the
+	    # <MultiOperationResponse> container.
+	    #
+	    # Check for errors in the first operation.
+	    #
+	    error_check( doc.elements['*/*/*/Request'] )
+
+	    # Check for errors in the second operation.
+	    #
+	    error_check( doc.elements['*/*[3]/*/Request'] )
+
+	    # If second operation is batched, check for errors in its 2nd set
+	    # of results.
+	    #
+	    if batched = doc.elements['*/*[3]/*[2]/Request']
+	      error_check( batched )
+	    end
+	  else
+	    error_check( doc.elements['*/*/Request'] )
+
+	    # If operation is batched, check for errors in its 2nd set of
+	    # results.
+	    #
+	    if batched = doc.elements['*/*[3]/Request']
+	      error_check( batched )
+	    end
+	  end
+
+	  # FIXME: This doesn't work if a MultipleOperation was used, because
+	  # <TotalPages> will be nested one level deeper. It's therefore
+	  # currently only possible to return the first page of results
+	  # for operations combined in a MultipleOperation.
+	  #
+	  if doc.elements['*/*[2]/TotalPages']
+	    total_pages = doc.elements['*/*[2]/TotalPages'].text.to_i
+	  else
+	    total_pages = 1
+	  end
+
+	  # Create a root AWS object and walk the XML response tree.
+	  #
+	  aws = AWS::AWSObject.new( operation )
+	  aws.walk( doc )
+	  result = aws
+
+	  # If only one page has been requested or only one page is available,
+	  # we can stop here. First yield to the block, if given.
+	  #
+	  if nr_pages == 1 || ( tp = total_pages ) == 1
+	     yield result if block_given?
+	     return result
+	  end
+
+	  # Limit the number of pages to the maximum number available.
+	  #
+	  nr_pages = tp.to_i if nr_pages == :ALL_PAGES || nr_pages > tp.to_i
+
+	  # 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|
+	    query = Amazon::AWS.assemble_query(
+		      q_params.merge( { 'ItemPage' => page_nr } ) )
+	    page = Amazon::AWS.get_page( self, query )
+	    doc = Document.new( page )
+
+	    # Check for errors.
+	    #
+	    error_check( doc.elements['*/OperationRequest'] )
+	    error_check( doc.elements['*/*/Request'] )
+
+	    # Create a new AWS object and walk the XML response tree.
+	    #
+	    aws = AWS::AWSObject.new
+	    aws.walk( doc )
+
+	    # When dealing with multiple pages, we return not just an
+	    # AWSObject, but an array of them.
+	    #
+	    result = [ result ] unless result.is_a? Array
+
+	    # Append the new object to the array.
+	    #
+	    result << aws
+	  end
+
+	  # Yield each object to the block, if given.
+	  #
+	  result.each { |r| yield r } if block_given?
+
+	  result
+	end
+
+      end
+
+    end
+
+  end
+
+end