chimps 0.3.3 → 0.3.4

data/Gemfile

@@ -5,6 +5,8 @@ gem "configliere", ">= 0.3.2"
 gem 'rest-client', '>= 1.6.1', :require => 'restclient'
 gem 'addressable', :require => 'addressable/uri'
 
-group :test do
+group :development do
   gem "rspec"
 end
+
+gemspec

data/Gemfile.lock

@@ -1,8 +1,13 @@
+PATH
+  remote: .
+  specs:
+    chimps (0.3.3)
+
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.2.4)
-    configliere (0.3.2)
+    addressable (2.2.5)
+    configliere (0.3.4)
     diff-lcs (1.1.2)
     json (1.4.6)
     mime-types (1.16)
@@ -22,6 +27,7 @@ PLATFORMS
 
 DEPENDENCIES
   addressable
+  chimps!
   configliere (>= 0.3.2)
   json (= 1.4.6)
   rest-client (>= 1.6.1)

data/README.rdoc

@@ -5,7 +5,7 @@ and repository where anyone can find, share, and sell data.
 
 Infochimps offers two APIs for users to access and modify data
 
-- a {Dataset API}[http://www.infochimps.com/apis] to list, show, create, update, and destroy datasets and associated resources on Infochimps[http://www.infochimps.com]
+- a {Catalog API}[http://www.infochimps.com/catalog-api] to list, show, create, update, and destroy datasets and associated resources on Infochimps[http://www.infochimps.com]
 - a {Query API}[http://www.infochimps.com/apis] to query data from particular rows of these datasets
 
 *Chimps* is a Ruby library that makes interacting with Infochimps' APIs as easy as
@@ -15,8 +15,8 @@ Infochimps offers two APIs for users to access and modify data
   
   # Sign up for an Infochimps account and get your keys from
   # http://www.infochimps.com/me
-  Chimps.config[:dataset][:key]    = "Your Dataset API key"
-  Chimps.config[:dataset][:secret] = "Your Dataset API secret"
+  Chimps.config[:catalog][:key]    = "Your Catalog API key"
+  Chimps.config[:catalog][:secret] = "Your Catalog API secret"
 
   # list datasets in JSON
   Chimps::Request.new("/datasets").get.print
@@ -50,7 +50,7 @@ Then you can install Chimps with
 You'll need a Dataset API key and secret from Infochimps before you
 can start adding or modifying datasets via the Dataset API.  {Sign up
 for an Infochimps account}[http://www.infochimps.com/signup] and get
-your {Dataset API key}[http://www.infochimps.com/me].
+your {Catalog API key}[http://www.infochimps.com/me].
 
 To query particular rows from a dataset, you'll also need to get a
 {Query API key}[http://www.infochimps.com/apis].
@@ -67,7 +67,7 @@ configuration file looks like
 
     # -*-yaml-*-
     # ~/.chimps
-    :dataset:
+    :catalog:
       :key:      xxxxxxxxxxxxxxxx
       :secret:   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     :query:
@@ -89,23 +89,23 @@ when you require it:
 
 = Making Requests
 
-== Dataset API
+== Catalog API
 
-You can use the {Dataset API}[http://www.infochimps.com/apis] to
-search, list, show, create, update, or destroy datasets and other
+You can use the {Catalog API}[http://www.infochimps.com/catalog-api]
+to search, list, show, create, update, or destroy datasets and other
 resources at Infochimps.
 
 If instead of _creating_ a dataset with 100,000 baby names you want to
 _query_ a dataset of 100,000 baby names then you should skip down to
 the Query API section below.
 
-You can find a complete list of Dataset API endpoints, expected
+You can find a complete list of Catalog API endpoints, expected
 parameters, return codes, documentation, and authentication
-requirements at http://www.infochimps.com/apis.
+requirements at http://www.infochimps.com/catalog-api.
 
 === A Simple +GET+ Request
 
-The <tt>Chimps::Request</tt> class makes requests against the Dataset
+The <tt>Chimps::Request</tt> class makes requests against the Catalog
 API.  Create a request by specifying a path on the Infochimps server.
 The extension of the path determines the MIME type that Infochimps
 will respond with:
@@ -137,12 +137,13 @@ look inside:
 
 === A Signed +GET+ Request
 
-Many Dataset API calls at Infochimps (like listing datasets, above) do
+Many Catalog API calls at Infochimps (like listing datasets, above) do
 not require the request to be signed in any way.  Other requests,
 which reveal your private information or create new datasets, &c. on
-Infochimps will require your Dataset API secret to sign.  You can see
-a full list of the Dataset API endpoints available and whether or not
-requests to each need to be signed at http://www.infochimps.com/apis.
+Infochimps will require your Catalog API secret to sign.  You can see
+a full list of the Catalog API endpoints available and whether or not
+requests to each need to be signed at
+http://www.infochimps.com/catalog-api.
 
 Assuming you've properly configured Chimps (see above) you ask the
 request to sign itself.
@@ -153,7 +154,7 @@ request to sign itself.
   response.print
   # lotsa JSON...but only about *your* datasets
 
-The authentication mechanism uses the Dataset API secret (which is
+The authentication mechanism uses the Catalog API secret (which is
 shared between you and Infochimps) to sign either the query string
 (for the case of +GET+ and +DELETE+ requests) or the request body (for
 +POST+ and +PUT+ requests).
@@ -173,9 +174,9 @@ Here's how to you might create a new dataset via a +POST+ request:
   response.parse!
   response['dataset']['id'] #=> 20876
 
-You can find a complete list of what Dataset API endpoints are
+You can find a complete list of what Catalog API endpoints are
 available and what parameters they take at
-http://www.infochimps.com/apis.
+http://www.infochimps.com/catalog-api.
 
 === Using the Query API
 
@@ -212,7 +213,7 @@ through the Infochimps website.
 = Contributing
 
 Chimps is an open source project created by the Infochimps team to
-encourage adoption of Infochimps' Dataset & Query APIs.  The official
+encourage adoption of Infochimps' Catalog & Query APIs.  The official
 repository is hosted on GitHub
 
   http://github.com/infochimps/chimps

data/Rakefile

@@ -1,25 +1,5 @@
-require 'rubygems'
-require 'rake'
+require 'bundler'  
+Bundler::GemHelper.install_tasks
 
-begin
-  # http://github.com/technicalpickles/jeweler
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "chimps"
-    gem.summary = "Chimps is a Ruby interface for the Infochimps Dataset & Query APIs (http://www.infochimps.com/api)"
-    gem.description = "Chimps allows you to easily make API calls against Infochimps web services.  Chimps!'s Request and Response classes take care of all the details so you can remain calm and RESTful."
-    gem.email = "coders@infochimps.com"
-    gem.homepage = "http://github.com/infochimps/chimps"
-    gem.authors = ["Dhruv Bansal"]
-    gem.files.exclude "old/**/*"
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available.  Install it with: sudo gem install jeweler"
-end
 
-desc "Build tags"
-task :tags do
-  system "etags -R README.rdoc examples lib spec"
-end
 

data/VERSION

@@ -1 +1 @@
-0.3.3
+0.3.4

data/examples/browse.rb

@@ -0,0 +1,82 @@
+# Here are some examples of how to search, list, and show information
+# about datasets on Infochimps.
+#
+# All the Catalog API calls utilized in this file are documented at
+#
+#   http://www.infochimps.com/catalog-api
+#
+# None of the examples in this file require authentication with
+# Infochimps so there's no need to configure Chimps in any way or to
+# even have an Infochimps account.
+#
+# Other examples which modify data in the Infochimps Catalog will
+# require you to have an Infochimps account and to properly configure
+# Chimps to use it.
+
+require 'rubygems'
+$:.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
+require 'chimps'
+
+# Say we wanted to find a list of sources who have contributed
+# downloadable music datasets to Infochimps.
+#
+# We'll do this by searching for datasets about 'music' and examining
+# each one to find its source (there are other ways to do this ;).
+#
+# The first call we'll need to make is the search.  This is documented
+# at
+#
+#   http://www.infochimps.com/catalog-api#search
+request = Chimps::Request.new('/search', :query_params => { :query => 'music', :dataset_type => 'download' })
+
+# We can see the URL that's generated for this query:
+puts "URL for search of downloadable music datasets:"
+puts request.url_with_query_string
+
+# Let's run the query by sending off an HTTP GET request.
+puts "\nSending GET request"
+response = request.get
+
+# The response knows about its HTTP response code and its headers
+puts "\nReceived a #{response.code} response with the following headers"
+p response.headers
+
+# The response has a raw body but we can also parse it.
+response.parse
+puts "\nThere were #{response.size} results:"
+
+# Lets print the titles of each of the datasets.  This works because
+# we just parsed the response above.
+response.each do |result|
+  dataset = result['dataset']
+  puts ""
+  puts dataset['title']
+  if dataset['sources'] && (!dataset['sources'].empty?)
+    dataset['sources'].each do |source|
+      puts "  Source: " + source['title']
+    end
+  else
+    puts "  No sources."
+  end
+end
+
+# Let's look a little deeper at the first result.
+puts("No results!") && exit(1) if response.empty?
+dataset = response.first['dataset']
+
+# Let's get more detail about this dataset.  This uses the "Show
+# Dataset" API documented at
+#
+#   http://www.infochimps.com/catalog-api#dataset_show
+id              = dataset['cached_slug']          # we can also use ID here
+dataset_request = Chimps::Request.new("/datasets/#{id}")
+
+# Let's run this next query
+puts "\n\nURL for details on dataset #{id}"
+puts dataset_request.url_with_query_string
+puts "\nSending GET request"
+dataset_response = dataset_request.get
+
+# Let's just print the body of the response this time.
+puts ""
+puts dataset_response.body

data/examples/create_dataset.rb

@@ -0,0 +1,11 @@
+# Chimps needs a little configuring to enable authentication with
+# Infochimps.  If you have a ~/.chimps file then you can make Chimps
+# read it like this:
+Chimps.boot!
+
+# You could also explicitly set the minimum required configuration
+# directly:
+#
+#   Chimps.config[:catalog][:key]    = "YOUR CATALOG API KEY"
+#   Chimps.config[:catalog][:secret] = "YOUR CATALOG API SECRET"
+#   Chimps.config[:query][:key]      = "YOUR QUERY API KEY"

data/lib/chimps/config.rb

@@ -25,10 +25,10 @@ module Chimps
     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
+    config.define 'catalog.username',   :description => "Your Infochimps username", :type => String
+    config.define 'catalog.host',       :description => "Host to send Catalog API requests to", :type => String, :default => "http://www.infochimps.com", :env_var => "GEORGE", :no_help => true
+    config.define 'catalog.key',        :description => "API key for the Catalog API", :type => String
+    config.define 'catalog.secret',     :description => "API secret for the Catalog API", :type => String
   end
   define_config
 
@@ -39,13 +39,6 @@ module Chimps
     config[:verbose]
   end
 
-  # The username Chimps will pass to Infochimps.
-  #
-  # @return [String]
-  def self.username
-    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]

data/lib/chimps/request.rb

@@ -102,7 +102,7 @@ module Chimps
     #
     # @return [true, false]
     def authenticable?
-      !Chimps.config[:dataset][:key].blank? && !Chimps.config[:dataset][:secret].blank?
+      !Chimps.config[:catalog][:key].blank? && !Chimps.config[:catalog][:secret].blank?
     end
     alias_method :signable?, :authenticable?
 
@@ -110,7 +110,7 @@ module Chimps
     #
     # @return [String]
     def host
-      @host ||= Chimps.config[:dataset][:host]
+      @host ||= Chimps.config[:catalog][:host]
     end
 
     # Return the base URL for this request, consisting of the host and
@@ -203,9 +203,9 @@ module Chimps
     # false.
     def authenticate_if_necessary!
       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)
+      raise Chimps::AuthenticationError.new("Catalog API key (Chimps.config[:catalog][:key]) or secret (Chimps.config[:catalog][: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[:dataset][:key]
+      query_params[:apikey]       = Chimps.config[:catalog][:key]
     end
 
     # Return an unsigned query string for this request.
@@ -246,9 +246,9 @@ module Chimps
     # @param [String]
     # @return [String]
     def sign string
-      raise Chimps::AuthenticationError.new("No API secret stored in #{Chimps.config[:config]} or #{Chimps.config[:site_config]}.") unless (authenticable? || @forgive_authentication_error)
+      raise Chimps::AuthenticationError.new("No Catalog API secret stored in #{Chimps.config[:config]} or #{Chimps.config[:site_config]}.  Set Chimps.config[:catalog][:secret].") unless (authenticable? || @forgive_authentication_error)
       require 'digest/md5'
-      Digest::MD5.hexdigest(string + Chimps.config[:dataset][:secret])
+      Digest::MD5.hexdigest(string + Chimps.config[:catalog][:secret])
     end
 
     # Append the signature to the unsigned query string.

data/lib/chimps/response.rb

@@ -4,11 +4,14 @@ require 'json'
 module Chimps
 
   # A class to wrap responses from the Infochimps API.
-  class Response < Hash
+  class Response
 
     # The response body.
     attr_reader :body
 
+    # The parsed data of the body
+    attr_reader :data
+
     # The error message for this response, if it was an error.
     #
     # This is actually generated within RestClient from the HTTP
@@ -16,8 +19,7 @@ module Chimps
     # initializing a Chimps::Response by a Chimps::Request.
     attr_reader :error
     
-    # Return a response built from a String with the
-    # RestClient::Response module mixed-in.
+    # Return a Response from the +body+.
     #
     # If <tt>:error</tt> is passed then this response is is considered
     # an error with the given message.
@@ -27,7 +29,6 @@ module Chimps
     # @option options [String] error the error message
     # @return [Chimps::Response]
     def initialize body, options={}
-      super()
       @body  = body
       @error = options[:error]
     end
@@ -64,15 +65,7 @@ module Chimps
     #
     # @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
-      when String then self[:string] = data
-      else nil
-      end
+      @data   = parse_response_body
       @parsed = true
       self
     end
@@ -98,20 +91,6 @@ module Chimps
       !! @error
     end
 
-    # Return a new Hash consisting of the data from this response.
-    #
-    # FIXME This is used when pretty printing -- though it shouldn't
-    # be necessary.
-    #
-    # @return [Hash]
-    def data
-      {}.tap do |d|
-        each_pair do |key, value|
-          d[key] = value
-        end
-      end
-    end
-
     # Print this response.
     #
     # @param [Hash] options
@@ -121,23 +100,23 @@ module Chimps
       output = (options[:to] || $stdout)
       if error?
         parse!
-        output.puts self['errors']  if self['errors']
-        output.puts self['message'] if self['message']
+        output.puts data['errors']  if data['errors']
+        output.puts data['message'] if data['message']
       else
         case
         when options[:yaml]
           parse!
-          output.puts self.to_yaml
+          output.puts data.to_yaml
         when options[:json] && options[:pretty]
           parse!
           if options[:pretty]
-            output.puts JSON.pretty_generate(self)
+            output.puts JSON.pretty_generate(data)
           else
-            output.puts self.to_json
+            output.puts data.to_json
           end
         when headers[:content_type] =~ /json/i && options[:pretty]
           parse!
-          output.puts JSON.pretty_generate(self)
+          output.puts JSON.pretty_generate(data)
         when headers[:content_type] =~ /tab/i && options[:pretty]
           Utils::Typewriter.new(self).print
         else
@@ -153,6 +132,10 @@ module Chimps
       end
     end
 
+    def method_missing name, *args, &block
+      data.send(name, *args, &block)
+    end
+    
     protected
 
     # Construct and return a line of diagnostic information on this

data/lib/chimps/utils.rb

@@ -1,5 +1,4 @@
 require 'chimps/config'
-# require 'chimps/utils/extensions'
 require 'chimps/error'
 
 module Chimps

data/lib/chimps/workflows/download.rb

@@ -51,6 +51,8 @@ module Chimps
         case response.code
         when 301, 302, 307
           response.follow_redirection(request, result, &block)
+        when 401
+          raise Error.new("Not authorized to download #{dataset}")
         when 200
           response.return!(request, result, &block)
         else

data/lib/chimps.rb

@@ -21,8 +21,9 @@ module Chimps
   def self.boot!
     config.read config[:site_config] if config[:site_config] && File.exist?(config[:site_config])
     config.read config[:config]      if config[:config]      && File.exist?(config[:config])
+    config[:catalog] = config[:site]    if (! config[:catalog]) && config[:site]    # backwards compatibility
+    config[:catalog] = config[:dataset] if (! config[:catalog]) && config[:dataset] # backwards compatibility
     config.resolve!
-    config[:dataset] = config[:site] if (! config[:dataset]) && config[:site] # backwards compatibility
     true
   end
   

data/spec/chimps/request_spec.rb

@@ -3,9 +3,9 @@ require File.expand_path('../spec_helper', File.dirname(__FILE__))
 describe Chimps::Request do
 
   before do
-    Chimps.config[:dataset][:host]   = 'http://foobar.com'
-    Chimps.config[:dataset][:key]    = 'spec_key'
-    Chimps.config[:dataset][:secret] = 'secret'
+    Chimps.config[:catalog][:host]   = 'http://foobar.com'
+    Chimps.config[:catalog][:key]    = 'spec_key'
+    Chimps.config[:catalog][:secret] = 'secret'
   end
 
   describe "generating the base URL with query string" do
@@ -38,12 +38,12 @@ describe Chimps::Request do
     end
 
     it "should raise an error if asked to sign and no credentials are available" do
-      Chimps.config[:dataset][:key] = nil
+      Chimps.config[:catalog][:key] = nil
       lambda { Chimps::Request.new('/path/to/something', :sign => true).query_string }.should raise_error(Chimps::AuthenticationError)
     end
 
     it "should not raise an error if asked to sign_if_possible and no credentials are avialable" do
-      Chimps.config[:dataset][:key] = nil
+      Chimps.config[:catalog][:key] = nil
       lambda { Chimps::Request.new('/path/to/something', :sign_if_possible => true).query_string }.should_not raise_error(Chimps::AuthenticationError)
     end
 
@@ -79,7 +79,7 @@ describe Chimps::Request do
     end
 
     it "should swallow application-level errors" do
-      Chimps.config[:dataset][:host]   = 'http://www.infochimps.com'
+      Chimps.config[:catalog][:host]   = 'http://www.infochimps.com'
       Chimps::Request.new('/some/made/up/path').get.code.should == 404
     end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: chimps
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 27
   prerelease: false
   segments: 
   - 0
   - 3
-  - 3
-  version: 0.3.3
+  - 4
+  version: 0.3.4
 platform: ruby
 authors: 
 - Dhruv Bansal
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-25 00:00:00 -05:00
+date: 2011-04-12 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -37,6 +37,8 @@ files:
 - Rakefile
 - VERSION
 - examples/batch.yaml
+- examples/browse.rb
+- examples/create_dataset.rb
 - examples/query.yaml
 - lib/chimps.rb
 - lib/chimps/config.rb
@@ -89,7 +91,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Chimps is a Ruby interface for the Infochimps Dataset & Query APIs (http://www.infochimps.com/api)
+summary: Chimps is a Ruby interface for the Infochimps Catalog & Query APIs (http://www.infochimps.com/apis)
 test_files: 
 - spec/chimps/query_request_spec.rb
 - spec/chimps/request_spec.rb