hoverbird-ny-times-congress 1.1.0 → 1.2.0

data/README.mkdn

@@ -3,12 +3,11 @@ NY Times Congress
 
 A Ruby wrapper for the New York Times Congress API.
 ---------------------
-The NY Times has graciously been scraping the web for data related to the United States Congress!  This is a Ruby library and command-shell intended to make it even easier to get at that data and turn it into useful information.
+The NY Times has been quietly scraping the web for data related to the United States Congress, and making the data freely available through a public [API](http://open.blogs.nytimes.com/2009/01/08/introducing-the-congress-api/).  [ny-times-congress](http://github.com/hoverbird/ny-times-congress/) aims to make it even easier to write Ruby applications using this data, and also provides a command shell for interacting with the API directly.
 
 Introdushing Congresh
 ---------------------
-The Congress Shell (congresh for short/cute) is a simple interactive prompt for interacting with the API.  It provides a few conveniences to make it easy to get at the current chambers of congress.
-
+The Congress Shell (congresh for short/cute) is a simple interactive prompt that wraps IRB.  It includes your API key (see setup below) and provides a few conveniences for test-driving the API. 
 
 Congress.new
 ---------------------
@@ -16,7 +15,7 @@ You get a Congress object either by calling Congress.new with the session and ch
 
     current_senate = Senate
     current_house  = House
-    2007_senate    = Congressnew(109, 'senate')
+    2007_senate    = Congress.new(109, 'senate')
     2008_house     = Congress.new(110, 'house')
 
 Through a Congress object, you can get a list of its representatives as a hash, keyed by congressional Bio ID.
@@ -26,15 +25,17 @@ Through a Congress object, you can get a list of its representatives as a hash,
 Legislator
 ---------------------
 
-    hillary = senators.values.find {|legislator| legislator.name == "Hillary Clinton"}
+    $ senators.values.find {|legislator| legislator.name == "Hillary Clinton"}
 
   or
 
-    hillary = senators['C001041']
+    $ senators['C001041']
 
-For full details on Bios and roles, use:
+You can also grav a Legislator directly by their Bio ID. This call includes full details on the congressperson's roles, biographical info and more:
 
-    Legislator.find('C001041')
+    $ Legislator.find('C001041')
+    
+When accessing a Legislator from a collection of congress members, they include only a limited set of attributes.  However, the library will make a second API call and lazy-load full attributes if you ask for them specifically.  So even though a Legislator object returned through Congress.members don't have the #gender attribute, if you call for a specific Legislators gender, that data will be fetched and populated just in time.
     
     
 Roll Call Votes
@@ -42,11 +43,29 @@ Roll Call Votes
 
 To find a vote in any congress, you need to know the session (usually 1 or 2, although rarely congress will go into a 3rd session) and then the ID of the vote:
 
-    Senate.roll_call_vote(session_number, vote_number)
+    $ Senate.roll_call_vote(session_number, vote_number)
     
 You can also find recent votes for any given senator:
-    hillary = Legislator.find('C001041')
-    hillary.votes
+    
+    $ hillary = Legislator.find('C001041')
+    $ hillary.votes
+
+
+Setup
+_____________________
+
+Add Github to your rubygems sources (if you haven't already) and then install the gem:
+    $ gem sources -a http://gems.github.com 
+    $ sudo gem install hoverbird-ny-times-congress
+    
+You'll also need to [get an API key]:http://developer.nytimes.com/apps/register from the [NY Times Developer Network]: http://developer.nytimes.com/.  If you set the key returned to an environment variable as shown below, Congresh will pick it up and include it in all your requests.  You can keep this in your bash profile, but I also recommend putting all your developer keys in a separate .api_keys file in your path
+
+    export NYTIMES_CONGRESS_API_KEY="123456789ETC"
+    
+Within your app, you can also set this directly like so:
+
+    NYTimes::Congress::Base.api_key = "123456789ETC"
+    
 
 Acknowledgements
 ---------------------

data/Rakefile

@@ -25,11 +25,14 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib' << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
+begin
+  require 'spec/rake/spectask'
+  desc "Run all examples"
+  Spec::Rake::SpecTask.new('spec') do |t|
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+rescue LoadError
+  puts "RSpec is not available.  You'll need it to test ny-times-congress."
 end
 
 begin
@@ -50,4 +53,4 @@ rescue LoadError
   puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
 end
 
-task :default => :test
+task :default => :spec

data/TODO

@@ -0,0 +1,2 @@
+* Auto-fill current session number based on the year.
+* Select congress members by state.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 1
-:patch: 0
 :major: 1
+:minor: 2
+:patch: 0

data/bin/setup.rb

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 include NYTimes::Congress
 
-if ENV['NYTIMES_CONGRESS_API_KEY']
-  NYTimes::Congress::Base.api_key = ENV['NYTIMES_CONGRESS_API_KEY']
+if ENV['NY_TIMES_CONGRESS_API_KEY']
+  NYTimes::Congress::Base.api_key = ENV['NY_TIMES_CONGRESS_API_KEY']
   
   Senate = Congress.new(111, :senate)
   House  = Congress.new(111, :house)

data/lib/ny-times/congress/attribute_transformation.rb

@@ -39,17 +39,16 @@ module NYTimes
       end
       
       def roles_for(roles_array)
-        roles_array.collect {|e| Role.new e}
+        roles_array.collect {|e| Role.new(e)}
       end
       
       def votes_for(votes_array)        
-        votes_array.collect {|vote_hash| RollCallVote.new vote_hash['vote'] }
+        votes_array.collect {|vote_hash| RollCallVote.new(vote_hash['vote'])}
       end
       
       def positions_for(votes_array)        
         votes_array.collect do |vote_hash|
-          vote = vote_hash['vote']
-          Position.new vote['member_id'], vote['vote_position'], vote
+          Position.new(vote_hash['member_id'], vote_hash['vote_position'])
         end
       end
       

data/lib/ny-times/congress/base.rb

@@ -1,10 +1,10 @@
 module NYTimes
 	module Congress
 		class Base
-		  API_NAME              = 'congress'
-		  API_SERVER            = 'api.nytimes.com'
-		  API_VERSION           = 2
-		  API_BASE              = "/svc/politics/v#{API_VERSION}/us/legislative/#{API_NAME}"
+		  API_NAME    = 'congress'
+		  API_SERVER  = 'api.nytimes.com'
+		  API_VERSION = 2
+		  API_BASE    = "/svc/politics/v#{API_VERSION}/us/legislative/#{API_NAME}"
 			
 			@@api_key = nil
 			@@copyright = nil
@@ -40,7 +40,7 @@ module NYTimes
 						
 						full_params = params.merge 'api-key' => @@api_key
 						uri = build_request_url(path, full_params)
-												
+
 						reply = uri.read
 						reply = JSON.parse(reply)
 												
@@ -64,7 +64,7 @@ module NYTimes
           EVAL
         end
 			end
+			
 		end
-		
 	end
 end

data/lib/ny-times/congress/congress.rb

@@ -5,12 +5,12 @@ module NYTimes
 		  include AttributeTransformation
       
       def initialize(number, chamber)
-        @number  = integer_for number
-        @chamber = symbol_for chamber
+        @number = integer_for(number)
+        @chamber = symbol_for(chamber)
         raise AttributeError unless number && chamber
       end
       
-      def members(params = {})
+      def members(params = {})        
         @members ||= fetch_members
       end
       
@@ -36,8 +36,8 @@ module NYTimes
       
       def api_path
         "#{number}/#{chamber}"
-      end      
-    
+      end        
     end
+    
   end
 end

data/lib/ny-times/congress/legislator.rb

@@ -5,14 +5,17 @@ module NYTimes
 			ATTRIBUTE_MAP = { :date_for    =>  [:date_of_birth],
                         :roles_for   =>  [:roles],
                 			  :integer_for =>  [:govtrack_id, :district],
-                			  :string_for  =>  [:url, :state, :gender, :name, :party] }
+                			  :string_for  =>  [:url, :state, :gender, :name, :party,
+                			                    :missed_votes_pct, :votes_with_party_pct] }
                 			  
       ATTRIBUTES = ATTRIBUTE_MAP.values.flatten
       ATTRIBUTES.each {|attribute| define_lazy_reader_for_attribute_named attribute }
       
       def self.find(id)
-        response = invoke("members/#{id}.json")['results']        
-				new(response.first)
+        response = invoke("members/#{id}.json")
+        require 'ruby-debug'
+        debugger if response.inspect unless response.has_key?('results')
+				new(response['results'].first)
       end
 		  attr_reader :attributes, :id
 		  
@@ -46,7 +49,7 @@ module NYTimes
 			  end
 			  
 	  		def load_fully
-	  		  full_legislator = self.class.find(id)
+	  		  full_legislator = Legislator.find(id)
 	  		  attributes.merge!(full_legislator.attributes)
 	  		  @fully_loaded = true
   			end

data/lib/ny-times/congress/position.rb

@@ -6,11 +6,10 @@ module NYTimes
 		  
 		  VALUES = ['Yes', 'No', 'Not Voting', 'Present', 'Speaker']
 		  
-		  def initialize(member_id, vote_position, vote)
-		    raise "Member ID required" unless member_id
+		  def initialize(member_id, vote_position, vote = nil)
 		    @member_id = member_id
 		    @vote_position = vote_position
-		    @vote = RollCallVote.new(extra_attrs)
+        @vote = vote
 		  end
 		  
 		  def legislator
@@ -36,5 +35,3 @@ module NYTimes
 		end
 	end
 end
-
-# {"votes"=>[{"vote"=>{"chamber"=>"Senate", "time"=>"11:57:00", "date"=>"2008-06-10", "roll_call"=>"147", "session"=>"2", "member_id"=>"B001210", "congress"=>"110", "position"=>"Not Voting"}}], "total_votes"=>"100", "member_id"=>"B001210", "offset"=>"0"}

data/lib/ny-times/congress/roll_call_vote.rb

@@ -6,7 +6,8 @@ module NYTimes
 			ATTRIBUTE_MAP = { 
 			  :date_for       =>  [:date],
         :integer_for    =>  [:session_number, :congress, :roll_call],
-        :string_for     =>  [:chamber, :bill_number, :question, :vote_type, :time, :result, :description],
+        :symbol_for     =>  [:chamber],
+        :string_for     =>  [:bill_number, :question, :vote_type, :time, :result, :description],
         :positions_for  =>  [:positions]
       }    			  
       attr_reader *ATTRIBUTE_MAP.values.flatten

data/spec/base_spec.rb

@@ -10,7 +10,7 @@ describe Base do
 		end
 		
 		it "returns a string matching the expected URL" do
-		  url.should eql expected_url
+		  url.should eql(expected_url)
 		end
 		
 	end
@@ -22,8 +22,8 @@ describe Base do
       end
     
 	  it "makes a call to a given url and parses the returned JSON into a response hash" do
-	    FakeWeb.register_uri(api_url_for('congress/111/senate/members.json'), :string => example_data)
-      @response = NYTimes::Congress::Base.invoke("congress/111/senate/members.json")
+	    FakeWeb.register_uri(api_url_for('111/senate/members.json'), :string => example_data)
+      @response = NYTimes::Congress::Base.invoke("111/senate/members.json")
       response.should == JSON.parse(example_data)
 	  end
 	  

data/spec/congress_spec.rb

@@ -9,11 +9,11 @@ describe Congress do
   
   describe "initializing with a congress number and chamber symbol", :shared => true do
     it "is numbered with an Integer" do
-      congress.number.should be_kind_of Integer
+      congress.number.should be_kind_of(Integer)
     end
     
     it "has a symbol representing the chamber" do
-      congress.chamber.should be_kind_of Symbol
+      congress.chamber.should be_kind_of(Symbol)
     end
   end
   
@@ -29,7 +29,7 @@ describe Congress do
     attr_accessor :members
   
     def example_data
-      File.read('example_data/members.json')
+      members_response
     end
 
     before do
@@ -38,13 +38,13 @@ describe Congress do
     end
 
     it "should return an hash of Legislators keyed by ID" do
-      members.should be_kind_of Hash
+      members.should be_kind_of(Hash)
       members.values.all? {|e| e.class.should == Legislator}
-      members['R000409'].name.should == "Dana Rohrabacher"
+      members['M000303'].name.should == "John McCain"
     end
 
     it "should return all members" do
-      members.size.should == 448
+      members.size.should == 102
     end
     
   end  

data/spec/example_data/example_data.rb

@@ -1,49 +1,75 @@
 def member_response
-  File.read('example_data/member.json')
+  File.read(File.dirname(__FILE__) + '/member.json')
+end
+
+def members_response
+  File.read(File.dirname(__FILE__) + '/members.json')
+end
+
+def roll_call_votes_response
+  File.read(File.dirname(__FILE__) + '/roll_call_votes.json')
 end
 
 def limited_legislator_attributes
   <<-JSON
-    {"id":"B000444",
-    "name":"Joseph Biden",
-    "party":"D",
-    "state":"DE",
-    "district":"N/A"}
+   {
+    "id": "L000304",
+    "name": "Joseph I. Lieberman",
+    "first_name": "Joseph I.",
+    "middle_name": "I.",
+    "last_name": "Lieberman",
+    "party": "ID",
+    "state": "CT",
+                     "missed_votes_pct": "0.00",
+    "votes_with_party_pct": "93.44" 
+    }
   JSON
 end
 
 def full_legislator_attributes
   <<-JSON
   {
-     "member_id":"B000444",
-     "name":"Joseph Biden",
-     "date_of_birth":"1942-11-20",
-     "gender":"M",
-     "url":"http://biden.senate.gov",
-     "govtrack_id":"300008",
-     "roles":[
-        {
-           "congress":"111",
-           "chamber":"Senate",
-           "title":"Senator, 2nd Class",
-           "state":"DE",
-           "party":"D",
-           "district":"N/A",
-           "start_date":"2009-01-06",
-           "end_date":"2009-01-20"
-        },
+     "status":"OK",
+     "copyright":"Copyright (c) 2009 The New York Times Company.  All Rights Reserved.",
+     "results":[
         {
-           "congress":"110",
-           "chamber":"Senate",
-           "title":"Senator, 2nd Class",
-           "state":"DE",
-           "party":"D",
-           "district":"N/A",
-           "start_date":"2007-01-04",
-           "end_date":"2009-01-03"
+           "member_id": "L000304",
+           "name": "Joseph I. Lieberman",
+           "first_name": "Joseph I.",
+           "middle_name": "I.",
+           "last_name": "Lieberman",
+           "date_of_birth": "1942-02-24",
+           "gender": "M",
+           "url": "http://lieberman.senate.gov/",
+           "govtrack_id": "300067",
+           "roles": [
+           {
+             "congress": "111",
+             "chamber": "Senate",
+             "title": "Senator, 1st Class",
+             "state": "CT",
+             "party": "ID",
+             "district": "N/A",
+             "start_date": "2009-01-06",
+             "end_date": "2011-01-04",
+             "missed_votes_pct": "0.00",
+             "votes_with_party_pct": "93.44"
+           },        {
+             "congress": "110",
+             "chamber": "Senate",
+             "title": "Senator, 1st Class",
+             "state": "CT",
+             "party": "ID",
+             "district": "N/A",
+             "start_date": "2007-01-04",
+             "end_date": "2009-01-03",
+             "missed_votes_pct": "3.20",
+             "votes_with_party_pct": "86.79"
+           }
+          ]
         }
-     ]
-   }
+      ]
+    }
   JSON
 end
 

data/spec/example_data/member.json

@@ -5,6 +5,9 @@
       {
          "member_id": "L000304",
          "name": "Joseph I. Lieberman",
+         "first_name": "Joseph I.",
+         "middle_name": "I.",
+         "last_name": "Lieberman",
          "date_of_birth": "1942-02-24",
          "gender": "M",
          "url": "http://lieberman.senate.gov/",
@@ -18,7 +21,9 @@
            "party": "ID",
            "district": "N/A",
            "start_date": "2009-01-06",
-           "end_date": "2011-01-04"
+           "end_date": "2011-01-04",
+           "missed_votes_pct": "0.00",
+           "votes_with_party_pct": "93.44"
          },        {
            "congress": "110",
            "chamber": "Senate",
@@ -27,7 +32,9 @@
            "party": "ID",
            "district": "N/A",
            "start_date": "2007-01-04",
-           "end_date": "2009-01-03"
+           "end_date": "2009-01-03",
+           "missed_votes_pct": "3.20",
+           "votes_with_party_pct": "86.79"
          },        {
            "congress": "109",
            "chamber": "Senate",
@@ -36,7 +43,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "2005-01-04",
-           "end_date": "2006-12-09"
+           "end_date": "2006-12-09",
+           "missed_votes_pct": "7.44",
+           "votes_with_party_pct": "88.78"
          },        {
            "congress": "108",
            "chamber": "Senate",
@@ -45,7 +54,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "2003-01-07",
-           "end_date": "2004-12-08"
+           "end_date": "2004-12-08",
+           "missed_votes_pct": "39.11",
+           "votes_with_party_pct": "92.21"
          },        {
            "congress": "107",
            "chamber": "Senate",
@@ -54,7 +65,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "2001-01-03",
-           "end_date": "2002-11-22"
+           "end_date": "2002-11-22",
+           "missed_votes_pct": "1.90",
+           "votes_with_party_pct": "92.11"
          },        {
            "congress": "106",
            "chamber": "Senate",
@@ -63,7 +76,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1999-01-06",
-           "end_date": "2000-12-15"
+           "end_date": "2000-12-15",
+           "missed_votes_pct": "10.12",
+           "votes_with_party_pct": "90.56"
          },        {
            "congress": "105",
            "chamber": "Senate",
@@ -72,7 +87,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1997-01-07",
-           "end_date": "1998-12-19"
+           "end_date": "1998-12-19",
+           "missed_votes_pct": "0.65",
+           "votes_with_party_pct": "85.03"
          },        {
            "congress": "104",
            "chamber": "Senate",
@@ -81,7 +98,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1995-01-04",
-           "end_date": "1996-10-04"
+           "end_date": "1996-10-04",
+           "missed_votes_pct": "1.21",
+           "votes_with_party_pct": "61.50"
          },        {
            "congress": "103",
            "chamber": "Senate",
@@ -90,7 +109,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1993-01-05",
-           "end_date": "1994-12-01"
+           "end_date": "1994-12-01",
+           "missed_votes_pct": "1.38",
+           "votes_with_party_pct": "83.94"
          },        {
            "congress": "102",
            "chamber": "Senate",
@@ -99,7 +120,9 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1991-01-03",
-           "end_date": "1993-01-03"
+           "end_date": "1993-01-03",
+           "missed_votes_pct": "1.09",
+           "votes_with_party_pct": "84.19"
          },        {
            "congress": "101",
            "chamber": "Senate",
@@ -108,8 +131,10 @@
            "party": "D",
            "district": "N/A",
            "start_date": "1989-01-03",
-           "end_date": "1991-01-03"
+           "end_date": "1991-01-03",
+           "missed_votes_pct": "0.63",
+           "votes_with_party_pct": "84.86"
          }       ]
         } 
     ]
-}
+}