twfy 1.0.0

data/History.txt

@@ -0,0 +1,10 @@
+== 1.0.0 / 2006-11-08
+
+* Initial release supporting all services from TWFY API 1.0.0
+* Basic support for 'daisy-chained' service calls via DataElement subclasses, caching results
+  * MP (info, debates, comments)
+  * Constituency (mp, geometry)
+* Coming up:
+  * Easy pagination of debates, comments, etc
+  * Data mining MPInfo information (ie expenses, accessible directly from MP instance)
+  * Other stuff :-)

data/Manifest.txt

@@ -0,0 +1,8 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/data_element.rb
+lib/twfy.rb
+test/test_twfy.rb
+test/test_twfy_chain.rb

data/README.txt

@@ -0,0 +1,105 @@
+twfy
+    by Bruce Williams (http://codefluency.com)
+    and Martin Owens
+
+== DESCRIPTION:
+  
+Ruby library to interface with the TheyWorkForYou API.
+
+From their website:
+
+"TheyWorkForYou.com is a non-partisan, volunteer-run website which aims to make it easy
+for people to keep tabs on their elected and unelected representatives in Parliament."
+
+== FEATURES/PROBLEMS:
+  
+All services [currently] provided by the API are supported.
+
+The Ruby API closely mirrors that of TWFY, with the exception that the client
+methods are in lowercase and don't include the 'get' prefix.
+
+Some examples:
+
+getComments:: comments
+getMPs:: mps
+getMPInfo:: mp_info
+
+Please submit bug reports to the RubyForge tracker via the project's homepage at
+http://rubyforge.org/projects/twfy
+
+== SYNOPSIS:
+
+Use is very easy.  
+
+=== Get a Client
+
+  require 'twfy'
+  client = Twfy::Client.new
+
+=== Call API methods directly on client
+
+  puts client.constituency(:postcode=>'IP6 9PN').name
+  # => Central Suffolk & North Ipswich
+
+  mp = client.mp(:postcode=>'IP6 9PN')
+  puts mp.full_name
+  # => Michael Lord
+
+  # Get a *lot* of info about this MP
+  info = client.mp_info(:id=>mp.person_id)
+
+  # Get a sorted list of all the parties in the House of Lords
+  client.lords.map{|l| l.party}.uniq.sort
+	#=> ["Bishop", "Conservative", "Crossbench", "DUP", "Green", "Labour", "Liberal Democrat", "Other"]
+
+  # Get number of debates in the House of Commons mentioning 'Iraq'
+  number = client.debates(:type=>'commons',:search=>'Iraq').info['total_results']
+
+=== Daisy chaining
+
+A few methods on the client return non-OpenStruct instances that support daisy chaining.  Using these to access related data more naturally (with caching).
+
+Here are some examples
+
+  # Get the MP for the last constituency (if you sort them alphabetically) 
+  mp = client.constituencies.sort_by{|c| c.name }.last.mp
+  # get the geometry information for that constituency (coming from the MP)
+  geometry = mp.constituency.geometry
+
+  # An overkill example showing caching (no services are called here, since
+  # the results have already been cached from above)
+  mp = mp.constituency.mp.constituency.geometry.constituency.mp
+
+  # These return equivalent results (Note how much easier the first is)
+  info1 = mp.info # this is cached for subsequent calls
+  info2 = client.mp_info(:id=>mp.person_id)
+
+  # Get pages of debates mentioning 'medicine'
+  debates1 = mp.debates(:search=>'medicine')
+  debates2 = mp.debates(:search=>'medicine', :page=>2)
+  
+See http://www.theyworkforyou.com/api/docs for API documentation.
+
+Please note that data pulled from the API is licensed separately;
+see the LICENSE portion of this README for further details.
+
+== REQUIREMENTS:
+
++ json library (available as a gem)
+
+== INSTALL:
+
+No special instructions.
+
+== LICENSE:
+
+This library uses the MIT License
+Copyright (c) 2006 Bruce Williams
+
+Data is licensed separately:
+
+The TheyWorkForYou license statement, from their website (http://www.theyworkforyou.com/api/), is:
+
+To use parliamentary material yourself (that's data returned from getDebates, getWrans, and getWMS), you will need to get a Parliamentary Licence from the Office of Public Sector Information. Our own data - lists of MPs, Lords, constituencies and so on - is available under the Creative Commons Attribution-ShareAlike license version 2.5.
+
+Non-commercial use is free, please contact us for commercial use.

data/Rakefile

@@ -0,0 +1,22 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'lib/twfy.rb'
+
+Hoe.new('twfy', Twfy::VERSION) do |p|
+    p.rubyforge_name = 'twfy'
+    p.summary = 'Ruby library to interface with the TheyWorkForYou(.com) API; an information source on Parliament'
+    p.description =<<EOD
+      Ruby library to interface with the TheyWorkForYou API. TheyWorkForYou.com is 
+      "a non-partisan, volunteer-run website which aims to make it easy for people to keep
+      tabs on their elected and unelected representatives in Parliament."
+EOD
+    p.url = "http://twfy.rubyforge.org"
+    p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+    p.extra_deps = ['json', 'paginator']
+    p.email = %q{bruce@codefluency.com}
+    p.author = ["Bruce Williams", "Martin Owens"]
+end
+
+# vim: syntax=Ruby

data/lib/data_element.rb

@@ -0,0 +1,101 @@
+require 'uri'
+require 'date'
+
+module Twfy
+  
+  class DataElement
+    @@conversions = {}
+    class << self
+      def convert(*fields,&block)
+        fields.each do |field|
+          @@conversions[field] = block 
+        end
+      end
+      def convert_to_date(*fields)
+        fields.each do |field|
+          convert field do |d|
+            Date.parse(d)
+          end
+        end
+      end
+    end
+    
+    attr_reader :client
+    def initialize(client, data={})
+      @client = client
+      data.each do |field,value|
+        instance_variable_set("@#{field}", convert(field, value))
+        unless self.respond_to?(field)
+          self.class.send(:define_method, field) do
+            instance_variable_get("@#{field}")
+          end
+        end
+      end
+    end
+    
+    def convert(field, value)
+      if conversion = @@conversions[field.to_sym]
+        args = [value]
+        args.unshift self if conversion.arity == 2
+        conversion.call(*args)
+      else
+        value
+      end
+    end
+    
+  end
+  
+  class MP < DataElement
+    
+    convert_to_date :entered_house, :left_house
+    convert :image do |value|
+      URI.parse("http://theyworkforyou.com#{value}")
+    end
+    convert :constituency do |source,value|
+      Constituency.new(source.client, :name => value, :mp => source)
+    end
+    
+    def in_office?
+      @left_reason == 'still_in_office'
+    end
+    
+    def info
+      @info ||= @client.mp_info(:id => @person_id)
+    end
+    
+    def debates(params={})
+      @debates ||= {}
+      @debates[params] ||= @client.debates(params.merge(:person=>@person_id, :type=>'commons'))
+    end
+    
+    def comments(params={})
+      @comments ||= {}
+      @comments[params] ||= @client.comments(params.merge(:pid=>@person_id))
+    end
+    
+  end
+  
+  class Constituency < DataElement
+    
+    def initialize(*args)
+      super
+    end
+    def geometry
+      @geometry ||= @client.geometry(:name=>@name)
+    end
+    
+    def mp
+      @mp ||= @client.mp(:constituency=>@name)
+    end
+    
+  end
+  
+  class Geometry < DataElement
+    
+    convert :constituency do |source,value|
+      Constituency.new(source.client, :name => value, :geometry => source)
+    end
+    
+  end
+  
+end

data/lib/twfy.rb

@@ -0,0 +1,173 @@
+require 'open-uri'
+require 'json'
+require 'cgi'
+require 'ostruct'
+require 'logger'
+
+require File.join(File.dirname(__FILE__), 'data_element')
+
+module Twfy
+  
+  VERSION = '1.0.0'
+  BASE = URI.parse('http://www.theyworkforyou.com/api/')
+  
+  API_VERSION = '1.0.0'
+  
+  class Client
+    
+    class Error < ::StandardError; end
+    class ServiceArgumentError < ::ArgumentError; end
+    class APIError < ::StandardError; end
+            
+    def initialize(log_to=$stderr)
+      @logger = Logger.new(log_to)
+    end
+    
+    def log(message, level=:info)
+      @logger.send(level, message) if $DEBUG
+    end
+    
+    def convert_url(params={})
+      service :convertURL, validate(params, :require => :url) do |value|
+        URI.parse(value['url'])
+      end
+    end
+
+    def constituency(params={})
+      service :getConstituency, validate(params, :require => :postcode), Constituency
+    end
+
+    def constituencies(params={})
+      service :getConstituencies, validate(params, :allow => [:date, :search, :longitude, :latitude, :distance]), Constituency
+    end
+
+    def mp(params={})
+      service :getMP, validate(params, :allow => [:postcode, :constituency, :id, :always_return]), MP
+    end
+
+    def mp_info(params={})
+      service :getMPInfo, validate(params, :require => :id)
+    end
+
+    def mps(params={})
+      service :getMPs, validate(params, :allow => [:date, :search]), MP
+    end
+
+    def lord(params={})
+      service :getLord, validate(params, :require => :id)
+    end
+
+    def lords(params={})
+      service :getLords, validate(params, :allow => [:date, :search])
+    end
+
+    def geometry(params={})
+      service :getGeometry, validate(params, :allow => :name), Geometry
+    end
+
+    def committee(params={})
+      service :getCommittee, validate(params, :require => :name, :allow => :date)
+    end
+
+    def debates(params={})
+      service :getDebates, validate(params, :require => :type, :require_one_of => [:date, :person, :search, :gid], :allow_dependencies => {
+        :search => [:order, :page, :num],
+        :person => [:order, :page, :num]
+      })
+    end
+    
+    def wrans(params={})
+      service :getWrans, validate(params, :require_one_of => [:date, :person, :search, :gid], :allow_dependencies => {
+        :search => [:order, :page, :num],
+        :person => [:order, :page, :num]
+      } )
+    end
+    
+    def wms(params={})
+      service :getWMS, validate(params, :require_one_of => [:date, :person, :search, :gid], :allow_dependencies => {
+        :search => [:order, :page, :num],
+        :person => [:order, :page, :num]
+      } )
+    end
+    
+    def comments(params={})
+      service :getComments, validate(params, :allow => [:date, :search, :user_id, :pid, :page, :num])
+    end
+    
+    def service(name, params={}, target=OpenStruct, &block)
+      log "Calling service #{name}"
+      url = BASE + name.to_s
+      url.query = build_query(params)
+      result = JSON.parse(url.read)
+      log result.inspect
+      unless result.kind_of?(Enumerable)
+        raise Error, "Could not handle result: #{result.inspect}"
+      end
+      if result.kind_of?(Hash) && result['error']
+        raise APIError, result['error'].to_s
+      else
+        structure result, block || target
+      end
+    end
+            
+    #######
+    private
+    #######
+    
+    def validate(params, against)
+      requirements = against[:require].kind_of?(Array) ? against[:require] : [against[:require]].compact
+      allowed = against[:allow].kind_of?(Array) ? against[:allow] : [against[:allow]].compact
+      require_one = against[:require_one_of].kind_of?(Array) ? against[:require_one_of] : [against[:require_one_of]].compact
+      allow_dependencies = against[:allow_dependencies] || {}
+      provided_keys = params.keys.map{|k| k.to_sym }
+      
+      # Add allowed dependencies
+      allow_dependencies.each do |key,dependent_keys|
+        dependent_keys = dependent_keys.kind_of?(Array) ? dependent_keys : [dependent_keys].compact
+        allowed += dependent_keys if provided_keys.include?(key)
+      end
+      
+      if (missing = requirements.select{|r| !provided_keys.include? r }).any?
+        raise ServiceArgumentError, "Missing required params #{missing.inspect}"
+      end
+      
+      if require_one.any?
+        if (count = provided_keys.inject(0){|count,item| count + (require_one.include?(item) ? 1 : 0) }) < 1
+          raise ServiceArgumentError, "Need exactly one of #{require_one.inspect}"
+        elsif count > 1
+          raise ServiceArgumentError, "Only one of #{require_one.inspect} allowed"
+        end
+      end
+      
+      unless (extra = provided_keys - (requirements + allowed + require_one)).empty?
+        raise ServiceArgumentError, "Unknown params #{extra.inspect}"
+      end
+      
+      params
+    end
+    
+    def structure(value, target)
+      case value
+      when Array
+        value.map{|r| structure(r, target) }
+      when Hash
+        if target.kind_of?(Proc)
+          target.call(value)
+        elsif target == Hash
+          value
+        else
+          target.ancestors.include?(DataElement) ? target.new(self,value) : target.new(value)
+        end
+      else
+        result
+      end
+    end
+    
+    def build_query(params)
+      params.update(:version=>API_VERSION)
+      params.map{|set| set.map{|i| CGI.escape(i.to_s)}.join('=') }.join('&')
+    end
+        
+  end
+  
+end

data/test/test_twfy.rb

@@ -0,0 +1,44 @@
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/twfy')
+
+class BasicReturnedDataTest < Test::Unit::TestCase
+  
+  def setup
+    @client = Twfy::Client.new
+  end
+  
+  def test_convert_url
+    uri = @client.convert_url(:url=>'http://www.publications.parliament.uk/pa/cm200506/cmhansrd/cm061018/debtext/61018-0002.htm#06101834000471')
+    assert_kind_of URI::HTTP, uri
+    assert_equal "www.theyworkforyou.com", uri.host
+  end
+  
+  def test_mp_and_mp_info
+    mp = @client.mp(:postcode=>'IP6 9PN')
+    assert_kind_of Twfy::MP, mp
+    assert_kind_of OpenStruct, @client.mp_info(:id=>mp.person_id)
+  end
+  
+  def test_mps
+    mps = @client.mps
+    assert_kind_of Array, mps
+    mps.each do |mp|
+      assert_kind_of Twfy::MP, mp
+    end
+  end
+  
+  def test_constituency_and_geometry
+    c = @client.constituency(:postcode => 'IP6 9PN')
+    assert_kind_of Twfy::Constituency, c
+    assert_kind_of Twfy::Geometry, @client.geometry(:name=>c.name)
+  end
+  
+  def test_constituencies
+    cs = @client.constituencies
+    assert_kind_of Array, cs
+    cs.each do |c|
+      assert_kind_of Twfy::Constituency, c
+    end
+  end
+  
+end

data/test/test_twfy_chain.rb

@@ -0,0 +1,49 @@
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/twfy')
+
+class ChainDataTest < Test::Unit::TestCase
+  
+  def setup
+    @client = Twfy::Client.new
+    @mp = @client.mp(:postcode=>'IP6 9PN')
+  end
+  
+  def test_single_chain_class
+    assert_kind_of Twfy::Constituency, @mp.constituency
+    c = @mp.instance_eval{ @constituency }
+    assert c
+    assert_kind_of Twfy::Constituency, c
+  end
+  
+  def test_reflexive_chain_class
+    c = @mp.constituency
+    assert_kind_of Twfy::Constituency, c
+    mp = @mp.constituency.mp
+    assert_kind_of Twfy::MP, mp
+    assert c.instance_eval{ @mp }
+    assert_equal mp, c.instance_eval{ @mp }
+  end
+  
+  def test_round_trip_chain_class
+    c = @mp.constituency
+    assert_kind_of Twfy::Constituency, c
+    c2 = @mp.constituency.mp.constituency
+    assert_kind_of Twfy::Constituency, @mp.instance_eval{ @constituency }
+    assert_kind_of Twfy::MP, @mp.constituency.instance_eval{ @mp }
+    assert_kind_of Twfy::Constituency, @mp.constituency.mp.instance_eval{ @constituency }
+    assert_kind_of Twfy::Constituency, c2
+    assert_equal c.name, c2.name
+  end
+  
+  def test_overkill_chain_class
+    mp = @mp.constituency.mp.constituency.geometry.constituency.mp
+    assert_kind_of Twfy::MP, mp
+    assert_equal @mp.full_name, mp.full_name    
+  end
+  
+  def test_simple_chain_and_direct_call_are_equivalent
+    assert_equal @client.mp_info(:id=>@mp.person_id), @mp.info
+  end
+  
+end
+  

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: twfy
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-11-20 00:00:00 -07:00
+summary: Ruby library to interface with the TheyWorkForYou(.com) API; an information source on Parliament
+require_paths: 
+- lib
+- test
+email: bruce@codefluency.com
+homepage: http://twfy.rubyforge.org
+rubyforge_project: twfy
+description: Ruby library to interface with the TheyWorkForYou API. TheyWorkForYou.com is  "a non-partisan, volunteer-run website which aims to make it easy for people to keep tabs on their elected and unelected representatives in Parliament."
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Bruce Williams
+- Martin Owens
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/data_element.rb
+- lib/twfy.rb
+- test/test_twfy.rb
+- test/test_twfy_chain.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: paginator
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: