carbon 1.1.3 → 2.0.0

data/lib/carbon.rb

@@ -1,115 +1,261 @@
-require 'uri'
-require 'blockenspiel'
-require 'timeframe'
-require 'digest/sha1'
-require 'rest'    # provided by nap gem
-require 'active_support'
-require 'active_support/version'
-%w{
-  active_support/core_ext
-  active_support/inflector
-  active_support/inflector/inflections
-  active_support/json/decoding
-}.each do |active_support_3_requirement|
-  require active_support_3_requirement
-end if ActiveSupport::VERSION::MAJOR >= 3
+require 'net/http'
+require 'hashie/mash'
+require 'multi_json'
+require 'active_support/core_ext'
 
-require 'logger'
+require 'carbon/registry'
 
-# A module (aka mixin) that lets you estimate carbon emissions by querying the {Brighter Planet carbon middleware emission estimate web service}[http://carbon.brighterplanet.com].
-#
-#   class RentalCar
-#     include Carbon
-#     [...]
-#     emit_as :automobile do
-#       provide :make
-#       provide :model
-#       provide :model_year
-#     end
-#   end
-#
-# The DSL consists of the methods <tt>emit_as</tt> and <tt>provide</tt>.
-#
-# In this example, the DSL says:
-# * A rental car emits carbon like an "automobile", which is one of Brighter Planet's recognized emitter classes.
-# * Your implementation can provide up to three data points about a rental car: its make, its model, and its model year (but not necessarily all of them, all the time.)
-#
-# Once you've mixed in <tt>Carbon</tt>, you get the method <tt>emission_estimate</tt>, which you can call at any time to request an emission estimate.
 module Carbon
-  autoload :Base, 'carbon/base'
-  autoload :EmissionEstimate, 'carbon/emission_estimate'
-  autoload :Registry, 'carbon/registry'
-  
-  def self.included(klass) # :nodoc:
-    klass.extend ClassMethods
-  end
-  
-  class RealtimeEstimateFailed < RuntimeError # :nodoc:
-  end
-  class QueueingFailed < RuntimeError # :nodoc:
-  end
-  class RateLimited < RuntimeError # :nodoc:
-  end
-  class TriedToUseAsyncResponseAsNumber < RuntimeError # :nodoc:
-  end
+  DOMAIN = 'http://impact.brighterplanet.com'
 
-  # The api key obtained from http://keys.brighterplanet.com
-  mattr_accessor :key
+  # @private
+  # Make sure there are no warnings about class vars.
+  @@key = nil unless defined?(@@key)
 
-  mattr_accessor :log
+  # Set the Brighter Planet API key that you can get from http://keys.brighterplanet.com
+  #
+  # @param [String] key The alphanumeric key.
+  #
+  # @return [nil]
+  def self.key=(key)
+    @@key = key
+  end
 
-  def self.log #:nodoc:
-    @log ||= Logger.new STDOUT
+  # Get the key you've set.
+  #
+  # @return [String] The key you set.
+  def self.key
+    @@key
   end
-  
-  def self.warn(msg) #:nodoc:
-    log.warn msg
+
+  # Do a simple query.
+  #
+  # See the {file:README.html#API_response section about API responses} for an explanation of +Hashie::Mash+.
+  #
+  # @param [String] emitter The {http://impact.brighterplanet.com/emitters.json camelcased emitter name}.
+  # @param [Hash] params Characteristics, 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.
+  # @option params [Array<Symbol>] :comply ([]) What {http://impact.brighterplanet.com/protocols.json calculation protocols} to require.
+  # @option params [String, Numeric] _characteristic_ 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] An {file:README.html#API_response API response as documented in the README}
+  #
+  # @example A flight taken in 2009
+  #   Carbon.query('Flight', :origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr])
+  def self.query(emitter, params = {})
+    params ||= {}
+    params = params.reverse_merge(:key => key) if key
+    uri = ::URI.parse("#{DOMAIN}/#{emitter.underscore.pluralize}.json")
+    raw_response = ::Net::HTTP.post_form(uri, params)
+    response = ::Hashie::Mash.new
+    case raw_response
+    when ::Net::HTTPSuccess
+      response.status = raw_response.code.to_i
+      response.success = true
+      response.merge! ::MultiJson.decode(raw_response.body)
+    else
+      response.status = raw_response.code.to_i
+      response.success = false
+      response.error_body = raw_response.respond_to?(:body) ? raw_response.body : ''
+      response.errors = [raw_response.class.name]
+    end
+    response
   end
-    
-  # You will probably never access this module directly. Instead, you'll use it through the DSL.
+
+  # Perform many queries in parallel. Can be >90% faster than doing them serially (one after the other).
   #
-  # It's mixed into any class that includes <tt>Carbon</tt>.
+  # See the {file:README.html#API_response section about API responses} for an explanation of +Hashie::Mash+.
+  #
+  # @param [Array<Array>] queries Multiple queries like you would pass to {Carbon.query}
+  #
+  # @return [Array<Hashie::Mash>] An array of {file:README.html#API_response API responses} in the same order as the queries.
+  #
+  # @note Not supported on JRuby because it uses {https://github.com/igrigorik/em-http-request em-http-request}, which suffers from {https://github.com/eventmachine/eventmachine/issues/155 an issue with +pending_connect_timeout+}.
+  #
+  # @example Two flights and an automobile trip
+  #   queries = [
+  #     ['Flight', :origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr]],
+  #     ['Flight', :origin_airport => 'SFO', :destination_airport => 'LAX', :date => '2011-09-29', :timeframe => Timeframe.new(:year => 2011), :comply => [:iso]],
+  #     ['AutomobileTrip', :make => 'Nissan', :model => 'Altima', :timeframe => Timeframe.new(:year => 2008), :comply => [:tcr]]
+  #   ]
+  #   Carbon.multi(queries)
+  def self.multi(queries)
+    require 'em-http-request'
+    unsorted = {}
+    multi = ::EventMachine::MultiRequest.new
+    ::EventMachine.run do
+      queries.each_with_index do |(emitter, params), query_idx|
+        params ||= {}
+        params = params.reverse_merge(:key => key) if key
+        multi.add query_idx, ::EventMachine::HttpRequest.new(DOMAIN).post(:path => "/#{emitter.underscore.pluralize}.json", :body => params)
+      end
+      multi.callback do
+        multi.responses[:callback].each do |query_idx, http|
+          response = ::Hashie::Mash.new
+          response.status = http.response_header.status
+          if (200..299).include?(response.status)
+            response.success = true
+            response.merge! ::MultiJson.decode(http.response)
+          else
+            response.success = false
+            response.errors = [http.response]
+          end
+          unsorted[query_idx] = response
+        end
+        multi.responses[:errback].each do |query_idx, http|
+          response = ::Hashie::Mash.new
+          response.status = http.response_header.status
+          response.success = false
+          response.errors = ['Timeout or other network error.']
+          unsorted[query_idx] = response
+        end
+        ::EventMachine.stop
+      end
+    end
+    unsorted.sort_by do |query_idx, _|
+      query_idx
+    end.map do |_, response|
+      response
+    end
+  end
+
+  # Called when you +include Carbon+ and adds the class method +emit_as+.
+  # @private
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  # Mixed into any class that includes +Carbon+.
   module ClassMethods
-    # Indicate that this class "emits as" an <tt>:automobile</tt>, <tt>:flight</tt>, or another of the Brighter Planet emitter classes.
+    # DSL for declaring how to represent this class an an emitter.
     #
-    # See the {emission estimate web service use documentation}[http://carbon.brighterplanet.com/use]
+    # You get this when you +include Carbon+ in a class.
     #
-    # For example,
-    #   emit_as :automobile do
-    #     provide :make
+    # @param [String] emitter The {http://impact.brighterplanet.com/emitters.json camelcased emitter name}.
+    #
+    # @return [nil]
+    #
+    # Things to note in the MyFlight example:
+    #
+    # * Sending +:origin+ to Brighter Planet *as* +:origin_airport+. Otherwise Brighter Planet won't recognize +:origin+.
+    # * Saying we're *keying* on one code or another. Otherwise Brighter Planet will first try against full names and possibly other columns.
+    # * Giving *blocks* to pull codes from +MyAircraft+ and +MyAirline+ objects. Otherwise you might get a querystring like +airline[iata_code]=#<MyAirline [...]>+
+    #
+    # @example MyFlight
+    #   # A a flight in your data warehouse
+    #   class MyFlight
+    #     def airline
+    #       # ... => MyAirline(:name, :icao_code, ...)
+    #     end
+    #     def aircraft
+    #       # ... => MyAircraft(:name, :icao_code, ...)
+    #     end
+    #     def origin
+    #       # ... => String
+    #     end
+    #     def destination
+    #       # ... => String
+    #     end
+    #     def segments_per_trip
+    #       # ... => Integer
+    #     end
+    #     def trips
+    #       # ... => Integer
+    #     end
+    #     include Carbon
+    #     emit_as 'Flight' do
+    #       provide :segments_per_trip
+    #       provide :trips
+    #       provide :origin, :as => :origin_airport, :key => :iata_code
+    #       provide :destination, :as => :destination_airport, :key => :iata_code
+    #       provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
+    #       provide(:aircraft, :key => :icao_code) { { |f| f.aircraft.icao_code }
+    #     end
     #   end
-    def emit_as(emitter_common_name, &block)
-      Registry.instance[name] = ::Carbon::Base.new emitter_common_name
-      ::Blockenspiel.invoke block, carbon_base
+    def emit_as(emitter, &blk)
+      emitter = emitter.to_s.singularize.camelcase
+      registrar = Registry::Registrar.new self, emitter
+      registrar.instance_eval(&blk)
     end
-    # Third-person singular preferred.
-    alias :emits_as :emit_as
-    
-    def carbon_base # :nodoc:
-      Registry.instance[name]
+  end
+
+  # What will be sent to Brighter Planet CM1.
+  # @private
+  def impact_params
+    return unless registration = Registry.instance[self.class.name]
+    registration.characteristics.inject({}) do |memo, (method_id, translation_options)|
+      k = translation_options.has_key?(:as) ? translation_options[:as] : method_id
+      if translation_options.has_key?(:key)
+        k = "#{k}[#{translation_options[:key]}]"
+      end
+      v = if translation_options.has_key?(:blk)
+        translation_options[:blk].call self
+      else
+        send method_id
+      end
+      memo[k] = v
+      memo
     end
   end
 
-  # Returns an emission estimate.
-  #
-  # Note: please see the README about <b>exceptions that you should watch out for</b>.
-  # 
-  # You can use it like a number...
-  #   > my_car.emission_estimate + 5.1
-  #   => 415.39
-  # Or you can get information about the response
-  #   > my_car.emission_estimate.methodology
-  #   => 'http://carbon.brighterplanet.com/automobiles.html?[...]'
-  #
-  # === Options:
-  #
-  # * <tt>:timeframe</tt> (optional) pass an instance of Timeframe[http://github.com/rossmeissl/timeframe] to request an emission for a specific time period.
-  # * <tt>:callback</tt> (optional) where to POST the result when it's been calculated. You need a server waiting for it!
-  # * <tt>:callback_content_type</tt> (optional if <tt>:callback</tt> is specified, ignored otherwise) pass a MIME type like 'text/yaml' so we know how to format the result when we send it to your waiting server. Defaults to 'application/json'.
-  # * <tt>:key</tt> (optional, overrides general <tt>Carbon</tt>.<tt>key</tt> setting just for this query) If you want to use different API keys for different queries.
-  def emission_estimate(options = {})
-    @emission_estimate ||= ::Carbon::EmissionEstimate.new self
-    @emission_estimate.take_options options
-    @emission_estimate
+  # Get an impact estimate from Brighter Planet CM1.
+  #
+  # You get this when you +include Carbon+ in a class.
+  #
+  # The return value is a {http://rdoc.info/github/intridea/hashie/Hashie/Mash Hashie::Mash} because it's a simple way to access a deep response object.
+  #
+  # Here's a map of what's included in a response:
+  #
+  #       certification
+  #       characteristics.{}.description
+  #       characteristics.{}.object
+  #       compliance.[]
+  #       decisions.{}.description
+  #       decisions.{}.methodology
+  #       decisions.{}.object
+  #       emitter
+  #       equivalents.{}
+  #       errors.[]
+  #       methodology
+  #       scope
+  #       timeframe.endDate
+  #       timeframe.startDate
+  #
+  # @param [Hash] extra_params Anything that your +emit_as+ won't include.
+  #
+  # @option extra_params [Timeframe] :timeframe
+  # @option extra_params [Array<Symbol>] :comply
+  # @option extra_params [String] :key In case you didn't define it globally, or want to use a different one here.
+  #
+  # @return [Hashie::Mash]
+  #
+  # @example Getting impact estimate for MyFlight
+  #   ?> my_flight = MyFlight.new([...])
+  #   => #<MyFlight [...]>
+  #   ?> my_impact = my_flight.impact(:timeframe => Timeframe.new(:year => 2009))
+  #   => #<Hashie::Mash [...]>
+  #   ?> my_impact.decisions.carbon.object.value
+  #   => 1014.92
+  #   ?> my_impact.decisions.carbon.object.units
+  #   => "kilograms"
+  #   ?> my_impact.methodology
+  #   => "http://impact.brighterplanet.com/flights?[...]"
+  #
+  # @example How do I use a Hashie::Mash?
+  #   ?> mash['hello']
+  #   => "world"
+  #   ?> mash.hello
+  #   => "world"
+  #   ?> mash.keys
+  #   => ["hello"]
+  #
+  # @example Other examples of what's in the response
+  #   my_impact.carbon.object.value
+  #   my_impact.characteristics.airline.description
+  #   my_impact.equivalents.lightbulbs_for_a_week
+  def impact(extra_params = {})
+    return unless registration = Registry.instance[self.class.name]
+    Carbon.query registration.emitter, impact_params.merge(extra_params)
   end
 end

data/lib/carbon/registry.rb

@@ -1,6 +1,56 @@
 require 'singleton'
+
 module Carbon
+  # Used internally to hold the information about how each class that has called `emit_as`.
+  # @private
   class Registry < ::Hash
     include ::Singleton
+
+    # Used internally to record the emitter and parameters (characteristics) provided by a class that has called `emit_as`.
+    # @private
+    class Registration < ::Struct.new(:emitter, :characteristics)
+    end
+
+    # Used internally when instance-eval'ing the `emit_as` DSL.
+    # @private
+    class Registrar
+      # @private
+      def initialize(klass, emitter)
+        @klass = klass
+        Registry.instance[klass.name] = Registration.new
+        Registry.instance[klass.name].emitter = emitter
+        Registry.instance[klass.name].characteristics = {}
+      end
+      
+      # Indicate that you will send in a piece of data about the emitter.
+      #
+      # @param [Symbol] method_id What method to call to get the value in question.
+      #
+      # @option translation_options [Symbol] :as (name of the method) If your method name does not match the Brighter Planet characteristic name.
+      # @option translation_options [Symbol] :key (a number of columns) What you are keying on. By default, we do a fuzzy match against a number of fields, including full names and various codes.
+      #
+      # @yield [] Pass a block for the common use case of calling a method on a object.
+      #
+      # @example Your method is named one thing but should be sent +:as+ something else.
+      #   provide :my_distance, :as => :distance
+      #
+      # @example You are keying on something well-known like {http://en.wikipedia.org/wiki/Airline_codes IATA airline codes}.
+      #   provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
+      #
+      # @example Better to use a block
+      #   provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
+      #   # is equivalent to
+      #   def airline_iata_code
+      #     airline.iata_code
+      #   end
+      #   provide :airline_iata_code, :as => :airline, :key => :iata_code
+      def provide(method_id, translation_options = {}, &blk)
+        translation_options = translation_options.dup
+        if block_given?
+          translation_options[:blk] = blk
+        end
+        Registry.instance[@klass.name].characteristics[method_id] = translation_options
+      end
+    end
   end
 end

data/lib/carbon/shell.rb

@@ -1,8 +1,18 @@
-require 'brighter_planet_metadata'
+require 'carbon'
 require 'bombshell'
 require 'conversions'
+require 'brighter_planet_metadata'
+
 module Carbon
+  # @private
   class Shell < Bombshell::Environment
+    class << self
+      # @private
+      def emitters
+        ::BrighterPlanet.metadata.emitters
+      end
+    end
+
     include Bombshell::Shell
     
     before_launch do
@@ -20,24 +30,21 @@ module Carbon
     
     prompt_with 'carbon-'
 
+    # @private
     def help
       puts "  => #{self.class.emitters.join ', '}"
     end
 
+    # @private
     def key(k)
       ::Carbon.key = k
       puts "  => Using key #{::Carbon.key}"
     end
 
+    # @private
     def emitter(e, saved = {})
       Emitter.launch e, saved
     end
-
-    class << self
-      def emitters
-        ::BrighterPlanet.metadata.emitters
-      end
-    end
   end
 end
 
@@ -48,4 +55,3 @@ if File.exist?(dotfile = File.join(ENV['HOME'], '.brighter_planet'))
 end
 
 require 'carbon/shell/emitter'
-