carbon 2.2.1 → 2.2.2

data/CHANGELOG

@@ -1,3 +1,14 @@
+2.2.2 / 2012-04-05
+
+* Enhancements
+
+  * Allow choosing domain (API endpoint)
+  * Slightly improved method signature explanations: query_array -> plain_query, o -> obj, os -> array
+
+* Bug fixes
+
+  * Actually send keys set with Carbon.key
+
 2.2.1 / 2012-03-21
 
 * Enhancements

data/lib/carbon.rb

@@ -4,13 +4,17 @@ require 'carbon/registry'
 require 'carbon/future'
 
 module Carbon
-  DOMAIN = 'http://impact.brighterplanet.com'
+  DOMAIN = 'http://impact.brighterplanet.com'.freeze
   CONCURRENCY = 16
 
   # @private
   # Make sure there are no warnings about class vars.
   @@key = nil unless defined?(@@key)
 
+  # @private
+  # Make sure there are no warnings about class vars.
+  @@domain = nil unless defined?(@@domain)
+
   # Set the Brighter Planet API key that you can get from http://keys.brighterplanet.com
   #
   # @param [String] key The alphanumeric key.
@@ -28,6 +32,23 @@ module Carbon
     @@key
   end
 
+  # Set an alternate API endpoint. You probably shouldn't do this.
+  #
+  # @param [String] domain ("http://impact.brighterplanet.com") The API endpoint
+  #
+  # @return [nil]
+  def Carbon.domain=(domain)
+    @@domain = domain
+    nil
+  end
+
+  # Where we send queries.
+  #
+  # @return [String] The API endpoint.
+  def Carbon.domain
+    @@domain || DOMAIN
+  end
+
   # Get impact estimates from Brighter Planet CM1; low-level method that does _not_ require you to define {Carbon::ClassMethods#emit_as} blocks; just pass emitter/param or objects that respond to +#as_impact_query+.
   #
   # Return values are {http://rdoc.info/github/intridea/hashie/Hashie/Mash Hashie::Mash} objects because they are a simple way to access a deeply nested response.
@@ -50,7 +71,7 @@ module Carbon
   #     timeframe.startDate
   #
   # @overload query(emitter, params)
-  #   Simplest form.
+  #   The simplest form.
   #   @param [String] emitter The {http://impact.brighterplanet.com/emitters.json emitter name}.
   #   @param [optional, Hash] params Characteristics like airline/airport/etc., your API key (if you didn't set it globally), timeframe, compliance, etc.
   #   @option params [Timeframe] :timeframe (Timeframe.this_year) What time period to focus the calculation on. See {https://github.com/rossmeissl/timeframe timeframe} documentation.
@@ -58,18 +79,20 @@ module Carbon
   #   @option params [String, Numeric] <i>characteristic</i> Pieces of data about an emitter. The {http://impact.brighterplanet.com/flights/options Flight characteristics API} lists valid keys like +:aircraft+, +:origin_airport+, etc.
   #   @return [Hashie::Mash] The API response, contained in an easy-to-use +Hashie::Mash+
   #
-  # @overload query(o)
+  # @overload query(obj)
   #   Pass in a single query-able object.
-  #   @param [#as_impact_query] o An object that responds to +#as_impact_query+, generally because you've declared {Carbon::ClassMethods#emit_as} on its parent class.
+  #   @param [#as_impact_query] obj An object that responds to +#as_impact_query+, generally because you've declared {Carbon::ClassMethods#emit_as} on its parent class.
   #   @return [Hashie::Mash] The API response, contained in an easy-to-use +Hashie::Mash+
   #
-  # @overload query(os)
-  #   Get multiple impact estimates for arrays and/or query-able objects concurrently.
-  #   @param [Array<Array, #as_impact_query>] os An array of arrays in +[emitter, params]+ format and/or objects that respond to +#as_impact_query+.
+  # @overload query(array)
+  #   Get impact estimates for multiple query-able objects concurrently.
+  #   @param [Array<Array, #as_impact_query>] array An array of plain queries and/or objects that respond to +#as_impact_query+.
   #   @return [Hash{Object => Hashie::Mash}] A +Hash+ of +Hashie::Mash+ objects, keyed on the original query object.
   #
   # @note We make up to 16 requests concurrently (hardcoded, per the Brighter Planet Terms of Service) and it can be more than 90% faster than running queries serially!
   #
+  # @note +[emitter, params]+ is called a "plain query."
+  #
   # @raise [ArgumentError] If your arguments don't match any of the method signatures.
   #
   # @example A flight taken in 2009
@@ -105,29 +128,23 @@ module Carbon
   #   Carbon.query(queries)
   #
   # @example Flights and cars (concurrently, as query-able objects)
-  #   Carbon.query(MyFlight.all+MyCar.all)
-  #
-  # @example Cars month-by-month (note that you won't get MyCar objects back, you'll get Arrays back. This will be fixed soon.)
-  #   cars_by_month = MyCar.all.inject([]) do |memo, my_car|
-  #     months.each do |first_day_of_the_month|
-  #       my_car.as_impact_query(:date => first_day_of_the_month)
-  #     end
+  #   Carbon.query(MyFlight.all+MyCar.all).each do |car_or_flight, impact|
+  #     puts "Carbon emitter by #{car_or_flight} was #{impact.decisions.carbon.object.value.round(1)}"
   #   end
-  #   Carbon.query(cars_by_month)
   def Carbon.query(*args)
     case Carbon.method_signature(*args)
-    when :query_array
-      query_array = args
-      future = Future.wrap query_array
+    when :plain_query
+      plain_query = args
+      future = Future.wrap plain_query
       future.result
-    when :o
-      o = args.first
-      future = Future.wrap o
+    when :obj
+      obj = args.first
+      future = Future.wrap obj
       future.result
-    when :os
-      os = args.first
-      futures = os.map do |o|
-        future = Future.wrap o
+    when :array
+      array = args.first
+      futures = array.map do |obj|
+        future = Future.wrap obj
         future.multi!
         future
       end
@@ -136,13 +153,13 @@ module Carbon
         memo
       end
     else
-      raise ::ArgumentError, "Didn't match any of the method signatures. If you want multiple queries, make sure to pass an unsplatted Array."
+      raise ::ArgumentError, "You must pass one plain query, or one object that responds to #as_impact_query, or an array of such objects. Please check the docs!"
     end
   end
 
   # Determine if a variable is a +[emitter, param]+ style "query"
   # @private
-  def Carbon.is_query_array?(query)
+  def Carbon.is_plain_query?(query)
     return false unless query.is_a?(::Array)
     return false unless query.first.is_a?(::String) or query.first.is_a?(::Symbol)
     return true if query.length == 1
@@ -156,20 +173,20 @@ module Carbon
     first_arg = args.first
     case args.length
     when 1
-      if is_query_array?(args)
+      if is_plain_query?(args)
         # query('Flight')
-        :query_array
+        :plain_query
       elsif first_arg.respond_to?(:as_impact_query)
         # query(my_flight)
-        :o
-      elsif first_arg.is_a?(::Array) and first_arg.all? { |o| o.respond_to?(:as_impact_query) or is_query_array?(o) }
+        :obj
+      elsif first_arg.is_a?(::Array) and first_arg.all? { |obj| obj.respond_to?(:as_impact_query) or is_plain_query?(obj) }
         # query([my_flight, my_flight])
-        :os
+        :array
       end
     when 2
-      if is_query_array?(args)
+      if is_plain_query?(args)
         # query('Flight', :origin_airport => 'LAX')
-        :query_array
+        :plain_query
       end
     end
   end
@@ -287,8 +304,8 @@ module Carbon
   #   ?> my_impact.methodology
   #   => "http://impact.brighterplanet.com/flights?[...]"
   def impact(extra_params = {})
-    query_array = as_impact_query extra_params
-    future = Future.wrap query_array
+    plain_query = as_impact_query extra_params
+    future = Future.wrap plain_query
     future.result
   end
 end

data/lib/carbon/future.rb

@@ -8,18 +8,18 @@ module Carbon
   # @private
   class Future
     class << self
-      def wrap(query_array_or_o)
-        future = if query_array_or_o.is_a?(::Array)
-          new(*query_array_or_o)
+      def wrap(plain_query_or_o)
+        future = if plain_query_or_o.is_a?(::Array)
+          new(*plain_query_or_o)
         else
-          new(*query_array_or_o.as_impact_query)
+          new(*plain_query_or_o.as_impact_query)
         end
-        future.object = query_array_or_o
+        future.object = plain_query_or_o
         future
       end
 
       def single(future)
-        uri = ::URI.parse("#{Carbon::DOMAIN}/#{future.emitter.underscore.pluralize}.json")
+        uri = ::URI.parse("#{future.domain}/#{future.emitter.underscore.pluralize}.json")
         raw_result = ::Net::HTTP.post_form(uri, future.params)
         future.finalize raw_result.code.to_i, raw_result.body
         future
@@ -41,14 +41,18 @@ module Carbon
 
     attr_reader :emitter
     attr_reader :params
+    attr_reader :domain
 
     attr_accessor :object
 
     def initialize(emitter, params = {})
       @result = nil
       @emitter = emitter
-      params = params || {}
-      params.reverse_merge(:key => Carbon.key) if Carbon.key
+      params = params.dup || {}
+      @domain = params.delete(:domain) || Carbon.domain
+      if Carbon.key and not params.has_key?(:key)
+        params[:key] = Carbon.key
+      end
       @params = params
     end
 
@@ -90,7 +94,7 @@ module Carbon
     cache_method :result, 3_600 # one hour
 
     def as_cache_key
-      [ @emitter, @params ]
+      [ @domain, @emitter, @params ]
     end
 
     def hash

data/lib/carbon/version.rb

@@ -1,3 +1,3 @@
 module Carbon
-  VERSION = "2.2.1"
+  VERSION = "2.2.2"
 end

data/test/carbon_test.rb

@@ -73,9 +73,20 @@ describe Carbon do
       end
       it "sends key properly" do
         with_web_mock do
-          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:key => 'carbon_test').to_return(:status => 500, :body => 'Good job')
-          result = Carbon.query('Flight')
-          result.errors.first.must_equal 'Good job'
+          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:body => hash_including(:key => 'carbon_test')).to_return(:status => 500, :body => 'default')
+          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:body => hash_including(:key => 'carbon_test1')).to_return(:status => 500, :body => 'A')
+          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:body => hash_including(:key => 'carbon_test2')).to_return(:status => 500, :body => 'B')
+          Carbon.query('Flight', :key => 'carbon_test2').errors.first.must_equal 'B'
+          Carbon.query('Flight').errors.first.must_equal 'default'
+          Carbon.query('Flight', :key => 'carbon_test1').errors.first.must_equal 'A'
+        end
+      end
+      it "allows choosing domain" do
+        with_web_mock do
+          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').to_return(:status => 500, :body => 'used impact')
+          WebMock.stub_request(:post, 'http://foo.brighterplanet.com/flights.json').to_return(:status => 500, :body => 'used foo')
+          Carbon.query('Flight', :domain => 'http://foo.brighterplanet.com').errors.first.must_equal 'used foo'
+          Carbon.query('Flight').errors.first.must_equal 'used impact'
         end
       end
       it "raises ArgumentError if args are bad" do
@@ -116,7 +127,13 @@ describe Carbon do
         Timeout.timeout(0.5) { Carbon.query([]) }.must_equal(Hash.new)
       end
       it "can be used on objects that respond to #as_impact_query" do
-        Carbon.query([MyNissanAltima.new(2001), MyNissanAltima.new(2006)]).values.map(&:decisions).map(&:carbon).map(&:object).map(&:value).must_equal Carbon.query([MyNissanAltima.new(2001).as_impact_query, MyNissanAltima.new(2006).as_impact_query]).values.map(&:decisions).map(&:carbon).map(&:object).map(&:value)
+        a = MyNissanAltima.new(2001)
+        b = MyNissanAltima.new(2006)
+        ab1 = Carbon.query([a, b])
+        ab2 = Carbon.query([a.as_impact_query, b.as_impact_query])
+        ab1.each do |k, v|
+          ab2[k.as_impact_query].must_equal v
+        end
       end
       it "runs multiple queries at once" do
         reference_results = @queries.inject({}) do |memo, query|
@@ -197,22 +214,22 @@ describe Carbon do
 
   describe :method_signature do
     it "recognizes emitter_param" do
-      Carbon.method_signature('Flight').must_equal :query_array
-      Carbon.method_signature('Flight', :origin_airport => 'LAX').must_equal :query_array
-      Carbon.method_signature(:flight).must_equal :query_array
-      Carbon.method_signature(:flight, :origin_airport => 'LAX').must_equal :query_array
+      Carbon.method_signature('Flight').must_equal :plain_query
+      Carbon.method_signature('Flight', :origin_airport => 'LAX').must_equal :plain_query
+      Carbon.method_signature(:flight).must_equal :plain_query
+      Carbon.method_signature(:flight, :origin_airport => 'LAX').must_equal :plain_query
     end
-    it "recognizes o" do
-      Carbon.method_signature(MyNissanAltima.new(2006)).must_equal :o
+    it "recognizes obj" do
+      Carbon.method_signature(MyNissanAltima.new(2006)).must_equal :obj
     end
-    it "recognizes os" do
-      Carbon.method_signature([MyNissanAltima.new(2001)]).must_equal :os
-      Carbon.method_signature([['Flight']]).must_equal :os
-      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}]]).must_equal :os
-      Carbon.method_signature([['Flight'], ['Flight']]).must_equal :os
-      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}], ['Flight', {:origin_airport => 'LAX'}]]).must_equal :os
+    it "recognizes array" do
+      Carbon.method_signature([MyNissanAltima.new(2001)]).must_equal :array
+      Carbon.method_signature([['Flight']]).must_equal :array
+      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}]]).must_equal :array
+      Carbon.method_signature([['Flight'], ['Flight']]).must_equal :array
+      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}], ['Flight', {:origin_airport => 'LAX'}]]).must_equal :array
       [MyNissanAltima.new(2006), ['Flight'], ['Flight', {:origin_airport => 'LAX'}]].permutation.each do |p|
-        Carbon.method_signature(p).must_equal :os
+        Carbon.method_signature(p).must_equal :array
       end
     end
     it "does not want splats for concurrent queries" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carbon
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-21 00:00:00.000000000 Z
+date: 2012-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &2169272660 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169272660
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &2169272200 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169272200
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &2169271780 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +53,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169271780
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: cache_method
-  requirement: &2169271220 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +69,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169271220
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bombshell
-  requirement: &2169270600 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +85,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169270600
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: conversions
-  requirement: &2169269920 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +101,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169269920
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: brighter_planet_metadata
-  requirement: &2169269500 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +117,12 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2169269500
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Brighter Planet API client for Ruby
 email:
 - seamus@abshere.net
@@ -139,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
 summary: Brighter Planet API client for Ruby