nytimes-congress 1.4.0

data/LICENSE

@@ -0,0 +1,19 @@
+#
+# Copyright (c) 2010 Patrick Ewing (<patrick.henry.ewing@gmail.com>) and Derek Willis (<dwillis@gmail.com>).
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in the
+# Software without restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+# Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.mkdn

@@ -0,0 +1,108 @@
+NY Times Congress
+===============
+
+A Ruby wrapper for the New York Times Congress API.
+---------------------
+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/).  [nytimes-congress](http://github.com/dwillis/nytimes-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.
+
+Introducing Congresh
+---------------------
+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
+---------------------
+You get a Congress object either by calling Congress.new with a number and chamber with an optional session number, or by using the Senate and House constants which return the current session of each:
+
+    current_senate          = Senate
+    current_house           = House
+    2007_senate             = Congress.new(109, 'senate')
+    2009_house_2nd_session  = Congress.new(111, 'house', 2)
+
+Through a Congress object, you can get a hash of Legislators, keyed by congressional Bio ID.
+
+    senators = Senate.members
+
+Legislator
+---------------------
+You could crawl the Hash values to find the bio ID in question, as this is a useful key to use across other open government APIs (notably Sunlight).
+
+    $ hrc = senators.values.find {|legislator| legislator.name == "Hillary Clinton"}
+    $ bio_id = hrc.bio_id
+
+Legislators come down the wire with a lot of interesting info, such as how often they vote along party lines, what roles they serve in Congress and more.  Check out the full set of attributes in the Legislator class.  
+
+You can also grab a Legislator directly by their Bio ID. This call includes full details on the congressperson's roles, biographical info and more:
+
+    $ 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.
+
+Current Member
+---------------------
+If you need to check the current representative for a House district or senators from a state, each chamber exposes a method for that. Note that the senate call does not need a district and returns a list of two senators.
+
+    $ pa19 = House.current_member_for_state_district("PA", 19)
+    $ pa19.name
+    "Todd R. Platts"
+
+    
+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.  Recent votes can be found easily through [Thomas](http://thomas.loc.gov/home/rollcallvotes.html). Curious about the details of the "American Recovery and Reinvestment Act"?  That's vote number 61:
+
+    $ vote = Senate.roll_call_vote(1, 61)
+    
+This returns a Vote object which also has an array of Positions, showing which legislators voted for and against this bill.  Thus it would be simple to collect everyone who voted for and against this bill:
+
+    $ vote.positions.find_all {|position| position.for?}
+    $ vote.positions.find_all {|position| position.against?}
+    
+The vote also includes an array of vacant seats, if present.
+
+You can also find recent votes by any given senator:
+    
+    $ 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 nytimes-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 NY_TIMES_CONGRESS_API_KEY="123456789ETC"
+    
+Then, just call 'congresh' at the command line, which will open up the Congresh shell.
+    
+Within an app, you can use the library like so:
+    
+    require 'ny-times-congress'
+    include NYTimes::Congress
+    Base.api_key = '123456789ETC'
+    
+
+Acknowledgements
+---------------------
+All information made available through this software is generously gathered and hosted by the New York Times (read Terms of Use below).  Inspiration and code was borrowed from the excellent nytimes-movies gem written by Jacob Harris and the sunlight gem by Luigi Montanez.  Thanks to Marcel Molina, Jr. for pairing with me on the lazy-loading idea.
+
+
+Terms of Use
+---------------------
+All information made available through this software is generously organized and hosted by the New York Times and is subject to copyright.  By obtaining an API key throught their Developer program and accessing this data you are agreeing to abide by certain rules and restrictions. These are available at the URLs below and you should read them before proceeding:
+
+  http://developer.nytimes.com/attribution
+  http://developer.nytimes.com/Api_terms_of_use
+
+
+License
+---------------------
+Copyright (c) 2010 Patrick Ewing (<patrick.henry.ewing@gmail.com>) and Derek Willis (<dwillis@gmail.com>).
+
+
+Made available under the MIT License (read LICENSE for details).
+

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "nytimes-congress"
+    s.executables = "congresh" 
+    s.summary = "Ruby wrapper and command shell for the New York Times Congress API"
+    s.authors = ["Patrick Ewing", "Derek Willis"]
+    s.files =  FileList["[A-Z]*", "{bin,lib,spec}/**/*"] 
+    s.add_dependency("json", [">= 1.1.3"])
+    s.email = "dwillis@gmail.com"
+    s.homepage = "http://github.com/dwillis/nytimes-congress"
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'ny-times-congress'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+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
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.verbose = true
+  end
+rescue LoadError
+  puts "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+end
+
+task :default => :spec

data/TODO

@@ -0,0 +1,20 @@
+Currently Supported:
+* Roll-Call Votes
+* Members of Congress
+* Member Bio and Roles
+* Member Vote Positions
+* Member Vote Comparison
+* New Members
+* Current member for state/district
+
+Not yet supported:
+  Missed Votes and Party Votes
+  Nomination Votes
+  Committees and Committee Members
+  Bills Cosponsored by a Member
+  Member Floor Appearances
+  Recent Bills
+  Bills by Member
+  Bill Details
+  Bill Subjects, Amendments and Related Bills
+  Bill Cosponsors

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:build: 
+:patch: 0
+:major: 1
+:minor: 4

data/bin/congresh

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+congress_lib  = File.dirname(__FILE__) + '/../lib/ny-times-congress'
+setup    = File.dirname(__FILE__) + '/setup'
+irb_name = RUBY_PLATFORM =~ /mswin32/ ? 'irb.bat' : 'irb'
+
+exec "#{irb_name} -r #{congress_lib} -r #{setup} --simple-prompt"

data/bin/setup.rb

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

data/lib/ny-times-congress.rb

@@ -0,0 +1,17 @@
+$LOAD_PATH.push(File.join(File.dirname(__FILE__), "../lib/ny-times"))
+
+require 'rubygems'
+require 'open-uri'
+require 'JSON'
+
+require 'congress/base'
+require 'congress/attribute_transformation'
+require 'congress/congress'
+require 'congress/legislator'
+require 'congress/legislator_vote_comparison'
+require 'congress/role'
+require 'congress/roll_call_vote'
+require 'congress/position'
+require 'congress/nomination'
+require 'congress/floor'
+require 'congress/current_member'

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

@@ -0,0 +1,75 @@
+module NYTimes
+	module Congress
+    module AttributeTransformation
+      
+      def transform(args, attributes_map)
+        raise "Can only transform a hash" unless args.kind_of?(Hash)
+        new_values = {}
+        attributes_map.each_pair do |transformation, attributes|
+   		    attributes.each do |attribute_name|
+   		      value = args[attribute_name.to_s]
+			      new_values[attribute_name] = do_transformation(transformation, value)
+          end
+  			end
+  			new_values
+    	end
+      
+      def do_transformation(transformation, value)
+        send(transformation, value) unless empty?(value)
+      end
+      
+      def date_for(string)
+        Date.parse(string)
+      end
+  
+      def string_for(value)
+        value.to_s
+      end
+      
+      def float_for(value)
+        value.to_f
+      end
+  
+      def integer_for(string)
+        if string.respond_to? :to_i
+          string.to_i
+        else
+          string
+        end
+      end
+      
+      def symbol_for(string)
+        string.to_sym
+      end
+      
+      def roles_for(roles_array)
+        roles_array.collect {|e| Role.new(e)}
+      end
+      
+      def appearances_for(floor_array)
+        floor_array.collect do |floor_hash|
+          Floor.new(floor_hash['date'], floor_hash['title'], floor_hash['url'], floor_hash['start_time'], floor_hash['end_time'])
+        end
+      end
+      
+      def votes_for(votes_array)        
+        votes_array.collect {|vote_hash| RollCallVote.new(vote_hash['vote'])}
+      end
+      
+      def positions_for(votes_array)        
+        votes_array.collect do |vote_hash|
+          Position.new(vote_hash['member_id'], vote_hash['vote_position'])
+        end
+      end
+      
+      def vacant_seats_for(seats_array)
+        seats_array.collect {|s| Role.new(s)}
+      end
+      
+      def empty?(value)
+        value.nil? || value == "N/A" || value == ""
+      end
+            
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module NYTimes
+	module Congress
+		class Base
+		  API_NAME    = 'congress'
+		  API_SERVER  = 'api.nytimes.com'
+		  API_VERSION = 3
+		  API_BASE    = "/svc/politics/v#{API_VERSION}/us/legislative/#{API_NAME}"
+			
+			@@api_key = nil
+			@@copyright = nil
+			
+			class << self
+				
+				# The copyright footer to be placed at the bottom of any data from the New York Times. Note this is only set after an API call.
+				def copyright
+					@@copyright
+				end
+				
+				# Set the API key used for operations. This needs to be called before any requests against the API. To obtain an API key, go to http://developer.nytimes.com/
+				def api_key=(key)
+					@@api_key = key
+				end
+				
+				def api_key
+					@@api_key
+				end
+				
+				# Builds a request URI to call the API server
+				def build_request_url(path, params)
+					URI::HTTP.build :host => API_SERVER,
+													:path => "#{API_BASE}/#{path}",
+													:query => params.map {|k,v| "#{k}=#{v}"}.join('&')
+				end
+				
+				def invoke(path, params={})
+					begin
+						if @@api_key.nil?
+							raise "You must initialize the API key before you run any API queries"
+						end
+						
+						full_params = params.merge 'api-key' => @@api_key
+						uri = build_request_url(path, full_params)
+
+						reply = uri.read
+						reply = JSON.parse(reply)
+												
+						raise "Empty reply returned from API" if reply.nil?
+
+						@@copyright = reply['copyright']
+						
+						reply
+					rescue OpenURI::HTTPError => e
+						return nil if e.message =~ /^404/						
+						raise "Error connecting to URL #{uri} #{e}"
+					end
+				end
+        
+        def define_lazy_reader_for_attribute_named(attribute)
+          class_eval(<<-EVAL, __FILE__, __LINE__)
+            def #{attribute}
+              load_fully if attributes[:#{attribute}].nil? && !fully_loaded
+              attributes[:#{attribute}]
+            end
+          EVAL
+        end
+			end
+			
+		end
+	end
+end

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

@@ -0,0 +1,82 @@
+module NYTimes
+	module Congress
+		class Congress < Base
+		  attr_reader :number, :session, :chamber
+		  
+		  include AttributeTransformation
+      
+      def initialize(number, chamber, session = nil)
+        @number, @session = integer_for(number), integer_for(session)
+        @chamber = symbol_for(chamber)
+        raise AttributeError unless number && chamber
+      end
+      
+      def members(params = {})        
+        @members ||= fetch_members(Base.invoke("#{api_path}/members.json")['results'].first)
+      end
+      
+      def self.new_members(params = {})
+        Congress.fetch_new_members
+      end
+      
+      def current_member_for_state_district(state, district=nil)
+        if district
+          api_path = "members/house/#{state}/#{district}/current.json"
+        else
+          api_path = "members/senate/#{state}/current.json"
+        end
+        response = Base.invoke(api_path)['results']
+        fetch_current_members(response)
+      end
+      
+      def roll_call_vote(session_number, roll_call_number, params = {})
+        results = Base.invoke("#{api_path}/sessions/#{session_number}/votes/#{roll_call_number}.json")['results']['votes']
+        RollCallVote.new(results)
+      end
+      
+      def to_s
+        "#{number} #{chamber.upcase}"
+      end
+      
+      def compare(legislator_1, legislator_2)
+        response = Base.invoke("members/#{legislator_1}/compare/#{legislator_2}/#{number}/#{chamber}.json")
+        if response 
+          LegislatorVoteComparison.new(response['results'].first)
+        end
+      end
+      
+      protected
+      
+      def fetch_members(results)
+  			results.inject({}) do |hash, member| 
+  			  hash[member['id']] = Legislator.new(member)
+  			  hash.delete_if {|k,v| k.nil? }
+  			  hash
+  			end
+      end
+
+      def fetch_current_members(results)
+        if results.length > 1
+    			results.collect do |member| 
+    			  CurrentMember.new(member)
+    			end
+    		else
+    		  CurrentMember.new(results.first)
+    		end
+      end
+
+      def self.fetch_new_members
+        results = Base.invoke("/members/new.json")['results'].first
+  			results['members'].inject({}) do |hash, member|
+  			  hash[member['id']] = Legislator.new(member)
+  			  hash
+  			end
+      end
+      
+      def api_path
+        "#{number}/#{chamber}"
+      end        
+    end
+    
+  end
+end