chimps 0.2.2 → 0.3.0

data/lib/chimps/config.rb

@@ -4,48 +4,62 @@ module Chimps
 
   # Chimps configuration.  Managed by
   # Configliere[http://github.com/infochimps/configliere]
-  Config = Configliere.new
-
-  Config.define :site_config,      :description => "Path to site-wide configuration file", :env_var => "CHIMPS_ETC", :default => "/etc/chimps/chimpsrc.yaml", :type => String, :no_help => true
-  Config.define :config,           :description => "Path to user configuration file", :env_var => "CHIMPS_RC", :default => (ENV["HOME"] && File.expand_path("~/.chimps")), :flag => :c, :type => String
-  Config.define :log,              :description => "Path to log file", :flag => :l, :type => String
-  Config.define :timestamp_format, :description => "Format for timestamps", :type => String, :no_help => true, :default => "%Y%m%d-%H%M%S"
-  Config.define :plugin_dirs,      :description => "List of directories from which to load plugins", :type => Array, :no_help => true, :default => ['/usr/share/chimps', '/usr/local/share/chimps']
-  Config.define :skip_plugins,     :description => "Don't load any plugins", :flag => :q, :type => :boolean
-  Config.define :verbose,          :description => "Be verbose", :flag => :v, :type => :boolean
-   
-  Config.define 'query.host',      :description => "Host to send Query API requests to", :type => String, :default => "http://api.infochimps.com", :no_help => true, :env_var => "CHIMPS_QUERY_HOST"
-  Config.define 'query.key',       :description => "API key for the Query API", :type => String, :no_help => true
+  #
+  # @return [Configliere::Param]
+  def self.config
+    @config ||= Configliere.new
+  end
+
+  # Backwards compatibility for version < 0.3.0.
+  Config = config
   
-  Config.define 'site.username',   :description => "Your Infochimps username", :type => String
-  Config.define 'site.host',       :description => "Host to send Dataset API requests to", :type => String, :default => "http://infochimps.org", :env_var => "CHIMPS_DATASET_HOST"
-  Config.define 'site.key',        :description => "API key for the Dataset API", :type => String
-  Config.define 'site.secret',     :description => "API secret for the Dataset API", :type => String
+  def self.define_config
+    config.define :site_config,      :description => "Path to site-wide configuration file", :env_var => "CHIMPS_ETC", :default => "/etc/chimps/chimps.yaml", :type => String, :no_help => true
+    config.define :config,           :description => "Path to user configuration file", :env_var => "CHIMPS_RC", :default => (ENV["HOME"] && File.expand_path("~/.chimps")), :flag => :c, :type => String
+    config.define :log,              :description => "Path to log file", :flag => :l, :type => String
+    config.define :timestamp_format, :description => "Format for timestamps", :type => String, :no_help => true, :default => "%Y%m%d-%H%M%S"
+    config.define :plugin_dirs,      :description => "List of directories from which to load plugins", :type => Array, :no_help => true, :default => ['/usr/share/chimps', '/usr/local/share/chimps']
+    config.define :skip_plugins,     :description => "Don't load any plugins", :flag => :q, :type => :boolean
+    config.define :verbose,          :description => "Be verbose", :flag => :v, :type => :boolean
+    
+    config.define 'query.host',      :description => "Host to send Query API requests to", :type => String, :default => "http://api.infochimps.com", :no_help => true, :env_var => "APEYEYE", :no_help => true
+    config.define 'query.key',       :description => "API key for the Query API", :type => String, :no_help => true
+    
+    config.define 'dataset.username',   :description => "Your Infochimps username", :type => String
+    config.define 'dataset.host',       :description => "Host to send Dataset API requests to", :type => String, :default => "http://www.infochimps.com", :env_var => "GEORGE", :no_help => true
+    config.define 'dataset.key',        :description => "API key for the Dataset API", :type => String
+    config.define 'dataset.secret',     :description => "API secret for the Dataset API", :type => String
+  end
+  define_config
 
   # Is Chimps in verbose mode?
   #
   # @return [true, false, nil]
   def self.verbose?
-    Config[:verbose]
+    config[:verbose]
   end
 
   # The username Chimps will pass to Infochimps.
   #
   # @return [String]
   def self.username
-    Config[:site][:username] or raise AuthenticationError.new("No Dataset API username set in #{Chimps::Config[:config]} or #{Chimps::Config[:site_config]}")
+    config[:dataset][:username] or raise AuthenticationError.new("No Dataset API username set in #{Chimps.config[:config]} or #{Chimps.config[:site_config]}")
   end
 
+  # The current Chimps library version.
+  #
+  # @return [String]
   def self.version
+    return @version if @version
     version_path = File.join(File.dirname(__FILE__), '../../VERSION')
     @version ||= File.exist?(version_path) && File.new(version_path).read
   end
 
   # Require all Ruby files in the directory
-  # Chimps::Config[:plugin_dirs].
+  # Chimps.config[:plugin_dirs].
   def self.load_plugins
-    return if Chimps::Config[:skip_plugins]
-    plugin_dirs = Chimps::Config[:plugin_dirs]
+    return if Chimps.config[:skip_plugins]
+    plugin_dirs = Chimps.config[:plugin_dirs]
     plugin_dirs.each do |dir|
       Dir[File.expand_path(dir) + "/*.rb"].each { |plugin| require plugin }
     end

data/lib/chimps/{utils/error.rb → error.rb}

@@ -3,9 +3,6 @@ module Chimps
   # subclasses of Chimps::Error so they can be easily caught.
   Error = Class.new(StandardError)
 
-  # Raised when the user provides bad input on the command line.
-  CLIError = Class.new(Error)
-
   # Raised when the user hasn't specified any API credentials or the
   # server rejects the user's API credentials.
   #
@@ -18,9 +15,6 @@ module Chimps
   # Roughly corresponds to HTTP status code 5xx.
   ServerError = Class.new(Error)
 
-  # Raised when IMW fails to properly package files to upload.
-  PackagingError = Class.new(Error)
-
   # Raised when there is an error in uploading to S3 or in notifiying
   # Infochimps of the new package.
   UploadError = Class.new(Error)
@@ -29,12 +23,7 @@ module Chimps
   # methods.
   NotImplementedError = Class.new(Error)
 
-  # Raised when the response from Infochimps isn't well-formed or is
-  # unexpected.
+  # Raised when the response from Infochimps isn't well-formed.
   ParseError = Class.new(Error)
-  
-  # Raised when Chimps encounters response data it doesn't know how to
-  # pretty print.
-  PrintingError = Class.new(Error)
 end
 

data/lib/chimps/query_request.rb

@@ -0,0 +1,67 @@
+module Chimps
+  
+  # A class to encapsulate requests made against the Infochimps paid
+  # query API.
+  class QueryRequest < Request
+
+    # Is this request authentiable (has the Chimps user specified an
+    # API key and secret in their configuration file)?
+    #
+    # @return [true, false]
+    def authenticable?
+      !Chimps.config[:query][:key].blank?
+    end
+
+    def url_with_query_string
+      qs = (query_string && query_string.size > 0 ? query_string : nil)
+      case
+      when qs.nil?
+        base_url
+      when base_url.include?("?")
+        base_url + "&#{qs}"
+      else
+        base_url + "?#{qs}"
+      end
+    end
+
+    # The host to send requests to.
+    #
+    # @return [String]
+    def host
+      @host ||= Chimps.config[:query][:host]
+    end
+
+    # All Query API requests must be signed.
+    #
+    # @return [true]
+    def authenticate?
+      return true
+    end
+
+    # Authenticate this request by stuffing the <tt>:requested_at</tt>
+    # and <tt>:apikey</tt> properties into its <tt>:query_params</tt>
+    # hash.
+    #
+    # Will do nothing at all if Chimps::Request#authenticate? returns
+    # false.
+    def authenticate_if_necessary!
+      return unless authenticate? && should_encode?
+      raise Chimps::AuthenticationError.new("Query API key (Chimps.config[:query][:key]) from #{Chimps.config[:config]} or #{Chimps.config[:site_config]}") unless authenticable?
+      query_params[:requested_at] = Time.now.to_i.to_s
+      query_params[:apikey]       = Chimps.config[:query][:key]
+    end
+    
+    # Append the signature to the unsigned query string.
+    #
+    # The signature made from the Chimps user's API secret and either
+    # the query string text (stripped of <tt>&</tt> and <tt>=</tt>)
+    # for GET and DELETE requests or the request body for POST and PUT
+    # requests.
+    #
+    # @return [String]
+    def signed_query_string
+      unsigned_query_string
+    end
+    
+  end
+end

data/lib/chimps/request.rb

@@ -12,25 +12,28 @@ module Chimps
     # Default headers to pass with every request.
     DEFAULT_HEADERS = { :content_type => 'application/json', :accept => 'application/json', :user_agent => "Chimps #{Chimps.version}" }
 
-    # Path of the URL to submit to.  Must be a String.
+    # Path of the URL to submit to.  Must be a String.  Can start with
+    # an initial '/' or not -- no big deal ;)
     attr_accessor :path
 
     # Parameters to include in the query string of the URL to submit
-    # to.  Must be a Hash.
+    # to.  Can be a string or a Hash
     attr_accessor :query_params
 
-    # Data to include in the body of the request.  Must be a Hash.
-    attr_accessor :data
+    # Data to include in the body of the request.  Can be a Hash or a
+    # String.
+    attr_accessor :body
 
     # Initialize a Request to the given +path+.
     #
     # Query parameters and data can be passed in as hashes named
-    # <tt>:params</tt> and <tt>:data</tt>, respectively.
+    # <tt>:params</tt> and <tt>:body</tt>, respectively.
     #
     # If <tt>:sign</tt> is passed in the +options+ then the URL of
     # this request will be signed with the Chimps user's Infochimps
-    # API key and secret.  Failure to properly sign will raise an
-    # error.
+    # API key and secret.  Signing a request which doesn't need to be
+    # signed is just fine.  Forgetting to sign a request which needs
+    # to be signed will result in a 401 error from Infochimps.
     #
     # If <tt>:sign_if_possible</tt> is passed in the +options+ then an
     # attemp to sign the URL will be made though an error will _not_
@@ -38,21 +41,36 @@ module Chimps
     #
     # @param [String] path
     # @param [Hash] options
-    # @option options [Hash] params Query parameters to include in the URL
-    # @option options [Hash] data Data to include in the request body
+    # @option options [Hash] query Query parameters to include in the URL
+    # @option options [Hash] body Data to include in the request body
     # @option options [true, false] sign Sign this request, raising an error on failure
     # @option options [true, false] sign_if_possible Sign this request, no error on failure
+    # @option potions [true, false] raw If raw then encoding the query string and request body is up to you.
     # @return [Chimps::Request]
     def initialize path, options={}
-      @path         = path
-      @query_params = options[:query_params] || options[:params] || {}
-      @data         = options[:data]         || {}
-      @authentication_required      = [:authenticate, :authenticated, :authenticate_if_possible, :sign, :signed, :sign_if_possible].any? { |key| options.include?(key) }
+      self.path         = path
+      self.query_params = options[:query_params] || options[:query]  || options[:params] || {}
+      self.body         = options[:body]         || options[:data]   || {}
+
+      @authentication_required      = [:authenticate, :authenticated, :authenticate_if_possible, :sign, :signed, :sign_if_possible].any? { |key| options[key] }
       @forgive_authentication_error = options[:sign_if_possible] || options[:authenticate_if_possible]
+      @raw                          = options[:raw]
       authenticate_if_necessary!
-      super url_with_query_string
+      super(url_with_query_string, {:headers => DEFAULT_HEADERS.merge(options[:headers] || {})})
     end
 
+    # Return the URL for this request with the (signed, if necessary)
+    # query string appended.
+    #
+    # @return [String]
+    def url_with_query_string
+      if query_string && query_string.size > 0
+        base_url + "?#{query_string}"
+      else
+        base_url
+      end
+    end
+    
     # Should the request be authenticated?
     #
     # @return [true, false]
@@ -61,12 +79,30 @@ module Chimps
     end
     alias_method :sign?, :authenticate?
 
+    # Should the query string and request body be encoded?
+    #
+    # Control this by passing in the <tt>:raw</tt> keyword when
+    # initializing this Request.
+    #
+    # @return [true, false]
+    def should_encode?
+      !@raw
+    end
+
+    # Should this be considered a raw request in which neither the
+    # query string nor the body should be encoded or escaped?
+    #
+    # @return [true, false]
+    def raw?
+      !!@raw
+    end
+
     # Is this request authentiable (has the Chimps user specified an
     # API key and secret in their configuration file)?
     #
     # @return [true, false]
     def authenticable?
-      !Chimps::Config[:site][:key].blank? && !Chimps::Config[:site][:secret].blank?
+      !Chimps.config[:dataset][:key].blank? && !Chimps.config[:dataset][:secret].blank?
     end
     alias_method :signable?, :authenticable?
 
@@ -74,17 +110,15 @@ module Chimps
     #
     # @return [String]
     def host
-      @host ||= Chimps::Config[:site][:host]
+      @host ||= Chimps.config[:dataset][:host]
     end
 
-    # Return the URL for this request with the (signed, if necessary)
-    # query string appended.
+    # Return the base URL for this request, consisting of the host and
+    # path but *not* the query string.
     #
     # @return [String]
-    def url_with_query_string
-      base_url = File.join(host, path)
-      base_url += "?#{query_string}" unless query_string.blank?
-      base_url
+    def base_url
+      File.join(host, path)
     end
 
     # Return the query string for this request, signed if necessary.
@@ -93,7 +127,7 @@ module Chimps
     def query_string
       (authenticate? && authenticable?) ? signed_query_string : unsigned_query_string
     end
-
+    
     # Perform a GET request to this URL, returning a parsed response.
     #
     # Any headers in +options+ will passed to
@@ -101,10 +135,10 @@ module Chimps
     #
     # @param [Hash] options
     # @return [Chimps::Response]
-    def get options={}
+    def get options={}, &block
       handle_exceptions do
         Chimps.log.info("GET #{url}")
-        Response.new(super(DEFAULT_HEADERS.merge(options)))
+        Response.new(super(options, &block))
       end
     end
 
@@ -115,10 +149,10 @@ module Chimps
     #
     # @param [Hash] options
     # @return [Chimps::Response]
-    def post options={}
+    def post options={}, &block
       handle_exceptions do
         Chimps.log.info("POST #{url}")
-        Response.new(super(data_text, DEFAULT_HEADERS.merge(options)))
+        Response.new(super(encoded_body, options, &block))
       end
     end
 
@@ -129,10 +163,10 @@ module Chimps
     #
     # @param [Hash] options
     # @return [Chimps::Response]
-    def put options={}
+    def put options={}, &block
       handle_exceptions do
         Chimps.log.info("PUT #{url}")
-        Response.new(super(data_text, DEFAULT_HEADERS.merge(options)))
+        Response.new(super(encoded_body, options, &block))
       end
     end
 
@@ -144,21 +178,20 @@ module Chimps
     #
     # @param [Hash] options
     # @return [Chimps::Response]
-    def delete options={}
+    def delete options={}, &block
       handle_exceptions do
         Chimps.log.info("DELETE #{url}")
-        Response.new(super(DEFAULT_HEADERS.merge(options)))
+        Response.new(super(options, &block))
       end
     end
     
-    protected
     # Yield to +block+ but rescue any RestClient errors by wrapping
     # them in a Chimps::Response.
     def handle_exceptions &block
       begin
         yield
       rescue RestClient::Exception => e
-        return Response.new(e.response, :error => e.message)
+        Response.new(e.response, :error => e.message)
       end
     end
 
@@ -169,17 +202,17 @@ module Chimps
     # Will do nothing at all if Chimps::Request#authenticate? returns
     # false.
     def authenticate_if_necessary!
-      return unless authenticate?
-      raise Chimps::AuthenticationError.new("API key or secret missing from #{Config[:config]} or #{Config[:site_config]}") unless (authenticable? || @forgive_authentication_error)
+      return unless authenticate? && should_encode?
+      raise Chimps::AuthenticationError.new("Dataset API key (Chimps.config[:dataset][:key]) or secret (Chimps.config[:dataset][:secret]) missing from #{Chimps.config[:config]} or #{Chimps.config[:site_config]}") unless (authenticable? || @forgive_authentication_error)
       query_params[:requested_at] = Time.now.to_i.to_s
-      query_params[:apikey]      = Chimps::Config[:site][:key]
+      query_params[:apikey]       = Chimps.config[:dataset][:key]
     end
 
     # Return an unsigned query string for this request.
     #
     # @return [String]
     def unsigned_query_string
-      RestClient::Payload.generate(query_params)
+      (should_encode? ? RestClient::Payload.generate(query_params) : query_params).to_s
     end
 
     # Return an unsigned query string for this request without the
@@ -193,14 +226,18 @@ module Chimps
       @query_params_text ||= obj_to_stripped_string(query_params)
     end
 
-    # Return the data of this request as a string.
+    # Return this Requests's body as a suitably encoded string.
     #
     # This is the text that will be signed for POST and PUT requests.
     #
     # @return [String]
-    def data_text
+    def encoded_body
+      @encoded_body ||= should_encode? ? encode(body) : body.to_s
+    end
+
+    def encode obj
       require 'json'
-      @data_text ||= JSON.generate(data, {:max_nesting => false})
+      JSON.generate((obj == true ? {} : obj), {:max_nesting => false})
     end
 
     # Sign +string+ by concatenting it with the secret and computing
@@ -209,9 +246,9 @@ module Chimps
     # @param [String]
     # @return [String]
     def sign string
-      raise Chimps::AuthenticationError.new("No API secret stored in #{Config[:config]} or #{Config[:site_config]}.") unless (authenticable? || @forgive_authentication_error)
+      raise Chimps::AuthenticationError.new("No API secret stored in #{Chimps.config[:config]} or #{Chimps.config[:site_config]}.") unless (authenticable? || @forgive_authentication_error)
       require 'digest/md5'
-      Digest::MD5.hexdigest(string + Config[:site][:secret])
+      Digest::MD5.hexdigest(string + Chimps.config[:dataset][:secret])
     end
 
     # Append the signature to the unsigned query string.
@@ -223,7 +260,9 @@ module Chimps
     #
     # @return [String]
     def signed_query_string
-      signature = sign(data.blank? ? unsigned_query_string_stripped : data_text)
+      return unsigned_query_string unless should_encode?
+      text_to_sign = ((body == true || (! body.blank?)) ? encoded_body : unsigned_query_string_stripped)
+      signature    = sign(text_to_sign)
       "#{unsigned_query_string}&signature=#{signature}"
     end
 
@@ -240,69 +279,4 @@ module Chimps
     end
     
   end
-
-  # A class to encapsulate requests made against the Infochimps paid
-  # query API.
-  class QueryRequest < Request
-
-    # Is this request authentiable (has the Chimps user specified an
-    # API key and secret in their configuration file)?
-    #
-    # @return [true, false]
-    def authenticable?
-      !Chimps::Config[:query][:key].blank?
-    end
-
-    # The host to send requests to.
-    #
-    # @return [String]
-    def host
-      @host ||= Chimps::Config[:query][:host]
-    end
-
-    # All Query API requests must be signed.
-    #
-    # @return [true]
-    def authenticate?
-      return true
-    end
-
-    # Authenticate this request by stuffing the <tt>:requested_at</tt>
-    # and <tt>:apikey</tt> properties into its <tt>:query_params</tt>
-    # hash.
-    #
-    # Will do nothing at all if Chimps::Request#authenticate? returns
-    # false.
-    def authenticate_if_necessary!
-      return unless authenticate?
-      raise Chimps::AuthenticationError.new("API key or secret missing from #{Config[:config]} or #{Config[:site_config]}") unless (authenticable? || @forgive_authentication_error)
-      query_params[:requested_at] = Time.now.to_i.to_s
-      query_params[:apikey]       = Chimps::Config[:query][:key]
-    end
-
-    # Sign +string+ by concatenting it with the secret and computing
-    # the MD5 digest of the whole thing.
-    #
-    # @param [String]
-    # @return [String]
-    def sign string
-      raise Chimps::AuthenticationError.new("No API secret stored in #{Config[:config]} or #{Config[:site_config]}.") unless (authenticable? || @forgive_authentication_error)
-      require 'digest/md5'
-      Digest::MD5.hexdigest(string + Config[:query][:secret])
-    end
-
-    # Append the signature to the unsigned query string.
-    #
-    # The signature made from the Chimps user's API secret and either
-    # the query string text (stripped of <tt>&</tt> and <tt>=</tt>)
-    # for GET and DELETE requests or the request body for POST and PUT
-    # requests.
-    #
-    # @return [String]
-    def signed_query_string
-      unsigned_query_string
-    end
-    
-  end
-
 end

data/lib/chimps/response.rb

@@ -1,3 +1,6 @@
+require 'yaml'
+require 'json'
+        
 module Chimps
 
   # A class to wrap responses from the Infochimps API.
@@ -27,7 +30,6 @@ module Chimps
       super()
       @body  = body
       @error = options[:error]
-      parse!
     end
 
     # The HTTP status code of the response.
@@ -59,15 +61,27 @@ module Chimps
     end
     
     # Parse the response from Infochimps.
+    #
+    # @return [Chimps::Response]
     def parse!
       data = parse_response_body
       case data
         # hack...sometimes we get back an array instead of a
         # hash...should change the API at Chimps end
       when Hash   then merge!(data)
-      when Array  then self[:array]  = data # see Chimps::Typewriter#accumulate
+      when Array  then self[:array]  = data
       when String then self[:string] = data
+      else nil
       end
+      @parsed = true
+      self
+    end
+
+    # Parse the response from Infochimps -- will do nothing if the
+    # response has already been parsed.
+    def parse
+      return if @parsed
+      parse!
     end
 
     # Was this response a success?
@@ -91,7 +105,7 @@ module Chimps
     #
     # @return [Hash]
     def data
-      returning({}) do |d|
+      {}.tap do |d|
         each_pair do |key, value|
           d[key] = value
         end
@@ -100,16 +114,43 @@ module Chimps
 
     # Print this response.
     #
-    # Options are also passed to Chimps::Typewriter.new; consult for
-    # details.
-    #
     # @param [Hash] options
-    # @option options
+    # @option options [true, false] pretty whether to pretty print the response
     def print options={}
-      out = options[:to] || options[:out] || $stdout
-      err =                 options[:err] || $stderr
-      err.puts(diagnostic_line) if error? || Chimps.verbose?
-      Typewriter.new(self, options).print(out)
+      $stderr.puts(diagnostic_line) if error? || Chimps.verbose?
+      output = (options[:to] || $stdout)
+      if error?
+        parse!
+        output.puts self['errors']  if self['errors']
+        output.puts self['message'] if self['message']
+      else
+        case
+        when options[:yaml]
+          parse!
+          output.puts self.to_yaml
+        when options[:json] && options[:pretty]
+          parse!
+          if options[:pretty]
+            output.puts JSON.pretty_generate(self)
+          else
+            output.puts self.to_json
+          end
+        when headers[:content_type] =~ /json/i && options[:pretty]
+          parse!
+          output.puts JSON.pretty_generate(self)
+        when headers[:content_type] =~ /tab/i && options[:pretty]
+          Utils::Typewriter.new(self).print
+        else
+          output.puts body unless body.chomp.strip.size == 0
+        end
+      end
+    end
+
+    def print_headers options={}
+      output = (options[:output]  || $stdout)
+      self.body.raw_headers.each_pair do |name, value|
+        output.puts "#{name}: #{value}"
+      end
     end
 
     protected
@@ -126,9 +167,11 @@ module Chimps
 
     # Raise a Chimps::ParseError, optionally including the response
     # body in the error message if Chimps is verbose.
-    def parse_error!
-      message = Chimps.verbose? ? "#{diagnostic_line}\n\n#{body}" : diagnostic_line
-      raise ParseError.new(message)
+    def parse_error! error
+      if Chimps.verbose?
+        puts "\n\n#{body}" 
+      end
+      nil
     end
 
     # Parse the body of this response using the YAML or JSON libraries
@@ -138,21 +181,18 @@ module Chimps
     def parse_response_body
       return {} if body.blank? || body == 'null'
       if content_type == :yaml
-        require 'yaml'
         begin
-          YAML.parse(body)
+          YAML.load(StringIO.new(body))
         rescue YAML::ParseError => e 
-          parse_error!
-        rescue ArgumentError => e # WHY does YAML return an ArgumentError on malformed input...?
-          @error = "Response was received but was malformed"
-          parse_error!
+          parse_error! e
+        rescue ArgumentError => e
+          parse_error! e
         end
       else
-        require 'json'
         begin
           JSON.parse(body)
         rescue JSON::ParserError => e
-          parse_error!
+          parse_error! e
         end
       end
     end