carbon 1.1.3 → 2.0.0

data/.gitignore

@@ -1,23 +1,5 @@
-## MAC OS
-.DS_Store
-
-## TEXTMATE
-*.tmproj
-tmtags
-
-## EMACS
-*~
-\#*
-.\#*
-
-## VIM
-*.swp
-
-## PROJECT::GENERAL
-coverage
-rdoc
-pkg
-
-## PROJECT::SPECIFIC
 Gemfile.lock
-*.gem
+.DS_Store
+.rvmrc
+.yardoc/
+doc/

data/CHANGELOG

@@ -0,0 +1,11 @@
+2.0.0 / 2012-03-09
+
+* Breaking changes
+
+  * #emission_estimate has been removed in favor of #impact
+  * Response structure now mirrors what you get from http://impact.brighterplanet.com
+
+* Enhancements
+
+  * Carbon.multi method for parallelizing requests
+  * Tested with MRI 1.8 and MRI 1.9

data/Gemfile

@@ -1,3 +1,12 @@
 source :rubygems
 
-gemspec :path => '.'
+gemspec
+
+# dev deps
+gem 'minitest'
+gem 'minitest-reporters'
+gem 'timeframe'
+gem 'webmock'
+gem 'aruba'
+gem 'cucumber'
+gem 'yard'

data/README.markdown

@@ -0,0 +1,185 @@
+# Carbon
+
+Carbon is a Ruby API client and command-line console for the [Brighter Planet impact estimate web service](http://impact.brighterplanet.com), which is located at http://impact.brighterplanet.com. By querying the web service, it can estimate the carbon emissions, energy usage, and other environmental impacts of many real-life objects, such as cars and houses, based on particular characteristics that they may have.
+
+Full documentation: [RDoc](http://rdoc.info/projects/brighterplanet/carbon) 
+
+## Quick start 1: experimenting with the console
+
+<b>You'll need a Brighter Planet API key. See the "API keys" section below for details.</b>
+
+First get the gem:
+
+    $ gem install carbon
+
+Then start the console:
+
+    $ carbon
+    carbon->
+
+Provide your key:
+
+    carbon-> key '123ABC'
+      => Using key 123ABC
+      
+Start a flight calculation:
+
+    carbon-> flight
+      => 1210.66889895298 kg CO2e
+    flight*>
+
+Start providing characteristics:
+
+    flight*> origin_airport 'jfk'
+      => 1593.46008200024 kg CO2e
+    flight*> destination_airport 'lax'
+      => 1766.55536727522 kg CO2e
+
+Review what you've entered:
+
+    flight*> characteristics
+      => origin_airport: jfk
+         destination_airport: lax
+
+See how the calculation's being made:
+
+    flight*> methodology
+      => emission: from fuel and passengers with coefficients
+         [ ... ]
+         cohort: from t100
+         
+See intermediate calculations:
+
+    flight*> reports
+      => emission: 1766.55536727522
+         [ ... ]
+         cohort: {"members"=>262}
+
+Generate a methodology URL:
+
+    flight*> url
+      => http://impact.brighterplanet.com/flights.json?origin_airport=jfk&destination_airport=lax&key=123ABC
+
+And when you're done:
+
+    flight*> done
+      => Saved as flight #0
+    carbon->
+
+You can recall this flight anytime during this same session:
+
+    carbon-> flight 0
+      => 1766.55536727522 kg CO2e
+    flight*> characteristics
+      => origin_airport: jfk
+         destination_airport: lax
+         
+For more, see the "Console" section below.
+
+## Quick start 2: using the library in your application
+
+<b>You'll need a Brighter Planet API key. See the "API keys" section below for details.</b>
+
+Carbon works by extending any Ruby class to be an emission source. You `include Carbon` and then use the `emit_as` DSL...
+
+{render:Carbon::ClassMethods#emit_as}
+
+The final URL will be something like
+
+    http://impact.brighterplanet.com/flights.json?segments_per_trip=1&trips=1&origin_airport[iata_code]=MSN&destination_airport[iata_code]=ORD&airline[iata_code]=UA&aircraft[icao_code]=B737
+
+When you want to calculate impacts, simply call `MyFlight#impact`.
+
+{render:Carbon#impact}
+
+## API keys
+
+You should get an API key from http://keys.brighterplanet.com and set it globally:
+
+    Carbon.key = '12903019230128310293'
+
+Now all of your queries will use that key.
+
+## Gotcha: timeframes and 0.0kg results
+
+You submit this query about a flight in 2009, but the result is 0.0 kilograms. Why?
+
+  $ carbon 
+  carbon-> flight
+  [...]
+  flight*> date '2009-05-03'
+    => 0.0 kg CO2e
+  flight*> url
+    => http://impact.brighterplanet.com/flights?date=2009-05-03
+
+It's telling you that a flight in 2009 did not result in any 2011 emissions (the default timeframe is the current year).
+
+  flight*> timeframe '2009'
+    => 847.542137647608 kg CO2e
+  flight*> url
+    => http://impact.brighterplanet.com/flights?date=2009-05-03&timeframe=2009-01-01/2010-01-01
+
+So, 850 kilograms emitted in 2009.
+
+## Console
+
+This library includes a special console for performing calculations interactively. Quick Start #1 provides an example session. Here is a command reference:
+
+### Shell mode
+
+`help`
+:  Displays a list of emitter types.
+
+`key` _yourkey_
+:  Set the [developer key](http://keys.brighterplanet.com) that should be used for this session. Alternatively, put this key in `~/.brighter_planet` and it will be auto-selected on console startup.
+
+_emitter_
+:  (e.g. `Flight`) Enters emitter mode using this emitter type.
+
+_emitter num_
+:  (e.g. `Flight 0`) Recalls a previous emitter from this session.
+
+`exit`
+:  Quits.
+  
+### Emitter mode
+
+In Emitter mode, the prompt displays the emitter type in use. If a timeframe has been set, the timeframe is also included in the prompt.
+
+`help`
+:  Displays a list of characteristics for this emitter type.
+
+_characteristic value_
+:  (e.g. `origin_airport 'lax'`)
+:  Provide a characteristic. Remember, this is Ruby we're dealing with, so strings must be quoted.
+
+`timeframe`
+:  Display the current timeframe in effect on the emission estimate.
+
+`timeframe` _timeframe_
+:  (e.g. `timeframe '2009-01-01/2010-01-01'` or just `timeframe '2009'`) Set a timeframe on the emission estimate.
+
+`emission`
+:  Displays the current emission in kilograms CO2e for this emitter.
+
+`lbs`, `pounds`, or `tons`
+:  Display the emission using different units.
+
+`characteristics`
+:  Lists the characteristics you have provided so far.
+
+`methodology`
+:  Summarizes how the calculation is being made.
+
+`reports`
+:  Displays intermediate calculations that were made in pursuit of the emission estimate.
+
+`url`
+:  Generates a methodology URL suitable for pasting into your browser for further inspection.
+
+`done`
+:  Saves this emitter and returns to shell mode.
+
+## Copyright
+
+Copyright (c) 2012 Brighter Planet.

data/Rakefile

@@ -1,33 +1,20 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
-
-require 'rspec/core/rake_task'
-
-desc "Run all examples"
-RSpec::Core::RakeTask.new('examples') do |c|
-  c.rspec_opts = '-Ispec'
-end
-
-task :test => [:examples, :cucumber]
-task :default => :test
-
-desc "Run specs with RCov"
-RSpec::Core::RakeTask.new(:examples_with_coverage) do |t|
-  t.rcov = true
-  t.rcov_opts = ['--exclude', 'spec']
-  t.rspec_opts = '-Ispec'
-end
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
 
 require 'rake'
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'carbon'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
 end
 
 require 'cucumber/rake/task'
 Cucumber::Rake::Task.new
 
+require 'yard'
+YARD::Rake::YardocTask.new do |y|
+  y.options << '--no-private' << '--title' << "Brighter Planet CM1 client for Ruby"
+end
+
+task :default => [:test, :cucumber]

data/bin/carbon

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
-$:.unshift(File.dirname(__FILE__) + '/../lib') unless $:.include?(File.dirname(__FILE__) + '/../lib')
-
 require 'rubygems'
-require 'carbon'
+
+$LOAD_PATH.unshift(File.expand_path('../../lib', __FILE__)) unless $LOAD_PATH.include?(File.expand_path('../../lib', __FILE__))
 require 'carbon/shell'
+
 Bombshell.launch(Carbon::Shell)

data/carbon.gemspec

@@ -1,33 +1,27 @@
 # -*- encoding: utf-8 -*-
-$:.unshift File.expand_path("../lib", __FILE__)
-require "carbon/version"
+require File.expand_path('../lib/carbon/version', __FILE__)
 
 Gem::Specification.new do |s|
-  s.name        = "carbon"
+  s.name        = 'carbon'
   s.version     = Carbon::VERSION
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ['Derek Kastner', 'Seamus Abshere', 'Andy Rossmeissl']
-  s.email       = ['derek.kastner@brighterplanet.com']
+  s.author      = 'Seamus Abshere'
+  s.email       = ['seamus@abshere.net', 'dkastner@gmail.com', 'andy@rossmeissl.net']
+  s.summary     = 'Brighter Planet API client for Ruby'
+  s.description = 'Brighter Planet API client for Ruby'
   s.homepage    = 'https://github.com/brighterplanet/carbon'
-  s.summary     = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com).}
-  s.description = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com). By querying the web service, it can estimate the carbon emissions of many real-life objects, such as cars and houses, based on particular attributes that they may have.}
 
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  
-  s.add_dependency 'activesupport', '>=2.3.5'
-  s.add_dependency 'i18n' # activesupport?
-  s.add_dependency 'nap'
-  s.add_dependency 'timeframe'
-  s.add_dependency 'blockenspiel'
-  s.add_dependency 'conversions'
-  s.add_dependency 'brighter_planet_metadata'
-  s.add_dependency 'bombshell'
-  s.add_development_dependency 'fakeweb'
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'aruba'
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'vcr'
+
+  s.add_runtime_dependency 'em-http-request'
+  s.add_runtime_dependency 'activesupport'
+  s.add_runtime_dependency 'multi_json'
+  s.add_runtime_dependency 'hashie'
+
+  # CLI
+  s.add_runtime_dependency 'bombshell'
+  s.add_runtime_dependency 'conversions'
+  s.add_runtime_dependency 'brighter_planet_metadata'
 end

data/developer_notes/MULTI.markdown

@@ -0,0 +1,25 @@
+Had this for a while
+
+    def self.impacts(enumerable)
+      queries = enumerable.map do |instance|
+        [ Registry.instance[instance.class.name].emitter, instance.impact_params ]
+      end
+      multi queries
+    end
+
+Tested like this
+
+    describe :impacts do
+      it "works" do
+        impacts = Carbon.impacts(MyNissanAltima.all(:order => :year))
+        impacts.length.must_equal 5
+        impacts.map do |impact|
+          impact.decisions.carbon.object.value.round
+        end.uniq.length.must_be :>, 3
+        impacts.each_with_index do |impact, idx|
+          impact.decisions.carbon.object.value.must_be :>, 0
+          impact.characteristics.make.description.must_match %r{Nissan}i
+          impact.characteristics.year.description.to_i.must_equal(2000+idx)
+        end
+      end
+    end

data/developer_notes/REDUCE_HTTP_CONNECTIONS.markdown

@@ -0,0 +1,46 @@
+One way to reduce the number of connections by a constant... but it makes it slower (because requests are serialized) and less reliable (because there is a 30s heroku limit)
+
+    def self.multi(queries)
+      unsorted = {}
+      pool_size = (queries.length.to_f / 3).ceil
+      $stderr.puts "Starting #{pool_size} workers"
+      ::EventMachine.run do
+        multi = ::EventMachine::MultiRequest.new
+        pool = 0.upto(pool_size).map do
+          ::EventMachine::HttpRequest.new("http://#{domain}")
+        end
+        pool_idx = 0
+        queries.each_with_index do |(emitter, params), query_idx|
+          params ||= {}
+          multi.add query_idx, pool[pool_idx].post(:path => "/#{emitter.underscore.pluralize}.json", :body => params, :keepalive => true)
+          pool_idx = (pool_idx + 1) % pool_size
+        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

data/features/shell.feature

@@ -169,7 +169,7 @@ Feature: Shell
     And I type "exit"
     Then the output should contain:
       """
-      http://carbon.brighterplanet.com/computations.json?duration=10
+      http://impact.brighterplanet.com/computations?duration=10
       """
 
   Scenario: Retrieving stored emitter

data/features/support/env.rb

@@ -1,9 +1,8 @@
-$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
 require 'aruba/cucumber'
 require 'fileutils'
-require 'rspec/expectations'
-require 'carbon'
-require 'conversions'
+
+$LOAD_PATH.unshift File.expand_path('../../../lib', __FILE__)
+require 'carbon/shell'
 
 Before do
   @aruba_io_wait_seconds = 2