twfy 1.0.1 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2e4a7122b6b66c6ef20ed5fd0291dfa1f76599fc
+  data.tar.gz: c199d960584b65f80b353e9ba5da4b60a8895abc
+SHA512:
+  metadata.gz: c81d7d14a1ce73b2c4f86f501a69afa9299513b1e3d62cd5e82263ed003c0d1c2fff7bfdd1c6313a283a4a0242d6cc37b6ee48fc9a3d5ba18b597d41c4994435
+  data.tar.gz: 1d1b0d34b3be41dfaccefd13e3b856d11fb5f34a6eeaee30797f26ebe332dffdcb529a7c540f40dbe8e7f3c557787cc30a600036ba3366cafdd749860548bfcc

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/History.txt

@@ -1,3 +1,9 @@
+== 1.1.0 / 2013-11-12
+
+* Modernize source
+* Support Ruby 1.9, 2.0
+* Requires >= Ruby 1.9
+
 == 1.0.1 / 2008-08-02
 
 * In the near future the TWFY API will require an API Key for all calls. In preparation for this, this binding now requires an API Key. They are available at http://www.theyworkforyou.com/api/key

data/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2006 - 2013 Bruce Williams, Martin Owen & Tom Hipkin
+
+MIT License
+
+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 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/README.md

@@ -0,0 +1,99 @@
+# They Work For You
+
+A Ruby library to interface with the
+[TheyWorkForYou](http://www.theyworkforyou.com) API.
+
+[![Build Status](https://travis-ci.org/bruce/twfy.png?branch=master)](https://travis-ci.org/bruce/twfy)
+[![Code Climate](https://codeclimate.com/github/bruce/twfy.png)](https://codeclimate.com/github/bruce/twfy)
+
+## Features
+
+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`
+
+## Requirements
+
+Ruby 1.9+
+
+ * multi_json
+ * paginator
+
+## Examples
+
+### Get a Client
+
+```ruby
+require 'twfy'
+client = Twfy::Client.new("YOUR-API-KEY")
+```
+
+You can get an API key from http://www.theyworkforyou.com/api/key
+
+### Call API methods directly on client
+
+```ruby
+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(&: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
+
+```ruby
+# Get the MP for the last constituency (if you sort them alphabetically)
+mp = client.constituencies.sort_by(&: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.
+
+## Support
+
+Please submit issues to https://github.com/bruce/twfy/issues
+
+Pull requests gratefully accepted.
+
+## License
+
+See LICENSE.txt.
+
+Please note that data pulled from the API is licensed separately from
+this library.

data/Rakefile

@@ -1,22 +1,10 @@
-# -*- ruby -*-
+require "bundler/gem_tasks"
 
-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 Owen"]
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
 end
 
-# vim: syntax=Ruby
+task default: :test

data/lib/twfy/api.rb

@@ -0,0 +1,47 @@
+module Twfy
+
+  module API
+
+    VERSION = '1.0.0'
+
+    VALIDATIONS = {
+      convertURL: {require: :url},
+      getConstituency: {require: :postcode},
+      getConstituencies: {allow: [:date, :search, :longitude, :latitude, :distance]},
+      getMP: {allow: [:postcode, :constituency, :id, :always_return]},
+      getMPInfo: {require: :id},
+      getMPs: {allow: [:date, :party, :search]},
+      getLord: {require: :id},
+      getLords: {allow: [:date, :party, :search]},
+      getMLAs: {allow: [:date, :party, :search]},
+      getMSPs: {allow: [:date, :party, :search]},
+      getGeometry: {allow: :name},
+      getCommittee: {require: :name, allow: :date},
+      getDebates: {
+        require: :type,
+        require_one_of: [:date, :person, :search, :gid],
+        allow_dependencies: {
+          search: [:order, :page, :num],
+          person: [:order, :page, :num]
+        }
+      },
+      getWrans: {
+        require_one_of: [:date, :person, :search, :gid],
+        allow_dependencies: {
+          search: [:order, :page, :num],
+          person: [:order, :page, :num]
+        }
+      },
+      getWMS: {
+        require_one_of: [:date, :person, :search, :gid],
+        allow_dependencies: {
+          search: [:order, :page, :num],
+          person: [:order, :page, :num]
+        }
+      },
+      getComments: {allow: [:date, :search, :user_id, :pid, :page, :num]}
+    }
+
+  end
+
+end

data/lib/twfy/client.rb

@@ -0,0 +1,84 @@
+require 'cgi'
+require 'logger'
+require 'multi_json'
+require 'open-uri'
+require 'ostruct'
+
+module Twfy
+
+  class Client
+    include API
+    include Commands
+
+    class Error < ::StandardError; end
+    class APIError < ::StandardError; end
+
+    def initialize(api_key, log_to=$stderr)
+      @api_key = api_key
+      @logger = Logger.new(log_to)
+    end
+
+    def log(message, level=:info)
+      @logger.send(level, message) if $DEBUG
+    end
+
+    private
+
+    def service(name, params = {}, target = OpenStruct, &block)
+      log "Calling service #{name}"
+      url = service_url(name, params)
+      result = MultiJson.load(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
+
+    def service_url(name, params = {})
+      url = BASE + name.to_s
+      url.query = build_query(validate(params, API::VALIDATIONS[name]))
+      url
+    end
+
+    def validate(params, against)
+      Validation.run(params, against)
+      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.merge(api_params).map { |set|
+        set.map { |i|
+          CGI.escape(i.to_s)
+        }.join('=')
+      }.join('&')
+    end
+
+    def api_params
+      @api_params ||= {key: @api_key, version: API::VERSION}
+    end
+
+  end
+
+end

data/lib/twfy/commands.rb

@@ -0,0 +1,73 @@
+module Twfy
+  module Commands
+
+    def convert_url(params = {})
+      service :convertURL, params do |value|
+        URI.parse(value['url'])
+      end
+    end
+
+    def constituency(params = {})
+      service :getConstituency, params, Constituency
+    end
+
+    def constituencies(params = {})
+      service :getConstituencies, params, Constituency
+    end
+
+    def mp(params = {})
+      service :getMP, params, MP
+    end
+
+    def mp_info(params = {})
+      service :getMPInfo, params
+    end
+
+    def mps(params = {})
+      service :getMPs, params, MP
+    end
+
+    def lord(params = {})
+      service :getLord, params
+    end
+
+    def lords(params = {})
+      service :getLords, params
+    end
+
+    # Members of Legislative Assembly
+    def mlas(params = {})
+      service :getMLAs, params
+    end
+
+    # Member of Scottish parliament
+    def msps(params = {})
+      service :getMSPs, params
+    end
+
+    def geometry(params = {})
+      service :getGeometry, params, Geometry
+    end
+
+    def committee(params = {})
+      service :getCommittee, params
+    end
+
+    def debates(params = {})
+      service :getDebates, params
+    end
+
+    def wrans(params = {})
+      service :getWrans, params
+    end
+
+    def wms(params = {})
+      service :getWMS, params
+    end
+
+    def comments(params = {})
+      service :getComments, params
+    end
+
+  end
+end

data/lib/twfy/constituency.rb

@@ -0,0 +1,15 @@
+module Twfy
+
+  class Constituency < DataElement
+
+    def geometry
+      @geometry ||= @client.geometry(name: @name).with(constituency: self)
+    end
+
+    def mp
+      @mp ||= @client.mp(constituency: @name).with(constituency: self)
+    end
+
+  end
+
+end

data/lib/twfy/data_element.rb

@@ -0,0 +1,62 @@
+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
+      update_attributes(data)
+    end
+
+    def update_attributes(data = {})
+      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 with(data = {})
+      update_attributes(data)
+      self
+    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
+
+end

data/lib/twfy/geometry.rb

@@ -0,0 +1,17 @@
+module Twfy
+
+  class Geometry < DataElement
+
+    convert :constituency do |source, value|
+      if value.is_a?(Constituency)
+        value
+      else
+        Constituency.new(source.client,
+                         name:     value,
+                         geometry: source)
+      end
+    end
+
+  end
+
+end

data/lib/twfy/mp.rb

@@ -0,0 +1,39 @@
+module Twfy
+
+  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|
+      if value.is_a?(Constituency)
+        value
+      else
+        Constituency.new(source.client, name: value, mp: source)
+      end
+    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
+
+end

data/lib/twfy/validation.rb

@@ -0,0 +1,88 @@
+module Twfy
+
+  class Validation
+
+    class ServiceArgumentError < ::ArgumentError; end
+
+    def self.run(params = {}, against = {})
+      new(params, against).check!
+    end
+
+    def initialize(params = {}, against = {})
+      @params  = params
+      @against = against
+    end
+
+    def check!
+      unless missing.empty?
+        raise ServiceArgumentError, "Missing required params #{missing.inspect}"
+      end
+      unless extra.empty?
+        raise ServiceArgumentError, "Unknown params #{extra.inspect}"
+      end
+      check_one_required!
+    end
+
+    private
+
+    def required
+      @required ||= list(@against[:require])
+    end
+
+    def allowed
+      @allowed ||= allowed_with_dependencies
+    end
+
+    def one_required
+      @one_required ||= list(@against[:require_one_of])
+    end
+
+    def dependencies_allowed
+      @dependencies_allowed ||= @against[:allow_dependencies] || {}
+    end
+
+    def allowed_with_dependencies
+      base = list(@against[:allow])
+      dependencies_allowed.each_with_object(base) do |(key, dependent_keys), memo|
+        if provided.include?(key)
+          memo.push(*list(dependent_keys))
+        end
+      end
+    end
+
+    def provided
+      @provided ||= @params.keys.map(&:to_sym)
+    end
+
+    def list(candidate)
+      Array(candidate).dup.compact
+    end
+
+    def missing
+      @missing ||= required - provided
+    end
+
+    def extra
+      @extra ||= provided - (required + allowed + one_required)
+    end
+
+    def check_one_required!
+      count = one_required_count
+      if count
+        if count < 1
+          raise ServiceArgumentError, "Need exactly one of #{one_required.inspect}"
+        elsif count > 1
+          raise ServiceArgumentError, "Only one of #{one_required.inspect} allowed"
+        end
+      end
+    end
+
+    def one_required_count
+      if one_required.any?
+        provided.select { |item| one_required.include?(item) }.size
+      end
+    end
+
+  end
+
+end

data/lib/twfy/version.rb

@@ -0,0 +1,3 @@
+module Twfy
+  VERSION = '1.1.0'
+end