sniff 0.0.15 → 0.0.17

data/lib/sniff.rb

@@ -5,6 +5,17 @@ module Sniff
     File.join(File.dirname(__FILE__), '..')
   end
 
+  # Prepares the environment for running tests against Earth data and emitter 
+  # gems.
+  #
+  # local_root: Root directory of the emitter gem to be tested (path to the repo)
+  #
+  # options: 
+  # * :earth is the list of domains Earth.init should load (default: none)
+  # * :load_data determines whether fixture data is loaded (default: true)
+  # * :sqllogdev is a Logger log device used by ActiveRecord (default: nil)
+  # * :fixtures_path is the path to your gem's fixtures (default: local_root/lib/db/fixtures)
+  # * :logdev is a Logger log device used for general logging (default: nil)
   def init(local_root, options = {})
     options[:earth] ||= :none
 

data/lib/sniff/database.rb

@@ -6,6 +6,15 @@ require 'sqlite3'
 module Sniff
   class Database
     class << self
+      # Initialize a database used for testing emitter gems
+      #
+      # local_root: Root directory of the emitter gem to be tested (path to the repo)
+      # options: 
+      # * :earth is the list of domains Earth.init should load (default: none)
+      # * :load_data determines whether fixture data is loaded (default: true)
+      # * :sqllogdev is a Logger log device used by ActiveRecord (default: nil)
+      # * :fixtures_path is the path to your gem's fixtures (default: local_root/lib/db/fixtures)
+      # * :logdev is a Logger log device used for general logging (default: nil)
       def init(local_root, options = {})
         db_init options
         earth_init(options[:earth])
@@ -22,10 +31,18 @@ module Sniff
         environments.each { |e| e.populate_fixtures }
       end
 
+      # Used within an emitter's custom schema definition - aggregates muliple 
+      # schemas into a single schema generation transaction.
+      #
+      # Instead of:
+      # <tt>ActiveRecord::Schema.define(:version => XYZ) do</tt>
+      # It's:
+      # <tt>Sniff::Database.define_schema do</tt>
       def define_schema(&blk)
         schemas << blk
       end
 
+      # The list of schemas that have been loaded via define_schema
       def schemas
         @schemas = [] unless defined?(@schemas)
         @schemas
@@ -38,12 +55,15 @@ module Sniff
         db
       end
 
+      # Connect to the database and set up an ActiveRecord logger
       def db_init(options)
         ActiveRecord::Base.logger = Logger.new options[:sqllogdev]
         ActiveRecord::Base.establish_connection :adapter => 'sqlite3',
           :database => ':memory:'
       end
 
+      # Initialize Earth, tell it to load schemas defined by each domain model's
+      # data_miner definition
       def earth_init(domains)
         domains ||= :none
         domains = [domains] unless domains.is_a? Array
@@ -53,6 +73,7 @@ module Sniff
         Earth.init *args
       end
 
+      # Apply defined schemas to database
       def load_all_schemas
         orig_std_out = STDOUT.clone
         STDOUT.reopen File.open(File.join('/tmp', 'schema_output'), 'w') 

data/lib/sniff/tasks.rb

@@ -1,8 +1,3 @@
-task :environment do
-  ENV['SCHEMA'] = File.join Sniff.root, 'db', 'schema.rb'
-  ENV['FIXTURES_PATH'] = File.join Sniff.root, 'test', 'fixtures'
-end
-
 task :console do
   require 'sniff'
   cwd = Dir.pwd

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sniff
 version: !ruby/object:Gem::Version 
-  hash: 1
+  hash: 61
   prerelease: false
   segments: 
   - 0
   - 0
-  - 15
-  version: 0.0.15
+  - 17
+  version: 0.0.17
 platform: ruby
 authors: 
 - Derek Kastner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-23 00:00:00 -04:00
+date: 2010-07-28 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -93,12 +93,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 7
+        hash: 3
         segments: 
         - 0
         - 0
-        - 12
-        version: 0.0.12
+        - 14
+        version: 0.0.14
   requirement: *id005
 - !ruby/object:Gem::Dependency 
   type: :runtime
@@ -220,66 +220,7 @@ dependencies:
         - 4
         version: 0.0.4
   requirement: *id013
-description: |
-  # sniff
-  Development environment for Brighter Planet emitters.
-  
-  ## Background
-  Brighter Planet's emitters, such as [`flight`](http://github.com/brighterplanet/flight), inhabit a complex production runtime environment backing its [emission estimates web service](http://carbon.brighterplanet.com). Sniff simulates this environment, including representative data, fixtures, and other supporting code, so that developers can test improvements to the emitters before submitting them back to Brighter Planet.
-  
-  ### Caution
-  The data and other supporting information in the sniff environment is only representative of production data and in many cases is purely fictional, contrived to return predictable results in tests. Emission estimates and other information gleaned from execution within this environment will undoubtedly be--to put it simply--wrong. For real numbers, always use live queries to the [emission estimate web service](http://carbon.brighterplanet.com).
-  
-  ## Usage
-  Sniff is never used directly but rather as a requirement of a specific emitter. Current production emitters include, for example:
-  
-  * [Automobile](http://github.com/brighterplanet/automobile)
-  * [Flight](http://github.com/brighterplanet/flight)
-  * [Residence](http://github.com/brighterplanet/residence)
-  
-  For a complete list, see the emission estimate service's [documentation](http://carbon.brighterplanet.com/use).
-  
-  ## The emitter
-  An emitter is a software model of a real-world emission source, like a flight. Brighter Planet's emitter libraries each comprise a carbon model, an attribute curation policy, a persistence schema, and a summarization strategy.
-  
-  ### Persistence schema
-  Although the production environment does not persist emitter instances, we nevertheless define emitter schemas to enable ActiveRecord assocations. An emitter's schema is defined in `lib/*emitter_name*/data.rb` within an emitter library. For example, here is [flight's schema](http://github.com/brighterplanet/flight/blob/master/lib/flight/data.rb).
-  
-  Schema are defined using a DSL provided by the [data_miner](http://github.com/seamusabshere/data_miner) library.
-  
-  ### Attribute curation policy
-  This defines how an emitter's attributes (initialized and stored with respect to the schema) are curated and decorated into a snapshot for later use by the carbon model. The policy is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's characterization](http://github.com/brighterplanet/flight/blob/master/lib/flight/characterization.rb).
-  
-  Characterizations are defined using a DSL provided by the [characterizable](http://github.com/seamusabshere/characterizable) library.
-  
-  ### Carbon model
-  An emission estimate is obtained by giving an emitter's curated characteristics as input to an execution of its carbon model. The model is defined in `lib/*emitter_name*/characterization.rb` within an emitter library. For example, here is [flight's carbon model](http://github.com/brighterplanet/flight/blob/master/lib/flight/carbon_model.rb).
-  
-  Carbon models are defined using a DSL provided by the [leap](http://github.com/rossmeissl/leap) library.
-  
-  ### Summarization strategy
-  Summaries are human-friendly descriptions of characterized emitters. The strategy is defined in `lib/*emitter_name*/summarization.rb` within an emitter library. For example, here is [flight's summarization strategy](http://github.com/brighterplanet/flight/blob/master/lib/flight/summarization.rb).
-  
-  Summarizations are defined using a DSL provided by the [summary_judgement](http://github.com/rossmeissl/summary_judgement) library.
-  
-  ## Collaboration cycle 
-  Brighter Planet vigorously encourages collaborative improvement of its emitter libraries. Collaboration requires a (free) GitHub account.
-  
-  ### You
-  1.  Fork the emitter repository on GitHub.
-  1.  Write a test proving the existing implementation's inadequacy. Ensure that the test fails. Commit the test.
-  1.  Improve the code until your new test passes and commit your changes.
-  1.  Push your changes to your GitHub fork.
-  1.  Submit a pull request to brighterplanet.
-  
-  ### Brighter Planet
-  1.  Receive a pull request.
-  1.  Pull changes from forked repository.
-  1.  Ensure tests pass.
-  1.  Review changes for scientific accuracy.
-  1.  Merge changes to master repository and publish.
-  1.  Direct production environment to use new emitter version.
-
+description: Provides data environment for emitter gems
 email: derek.kastner@brighterplanet.com
 executables: []