parliament-ruby 0.5.19 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e992a0e8626c4a188ab4b3bff46dff2f0a6c8e7f
-  data.tar.gz: aacaa9952878ee6e6735cf4699ed587e32e3dbb7
+  metadata.gz: 792a61423210db4d06e2690193e47bc5949ffc6b
+  data.tar.gz: e0649c47b1ba552d2045cbbde8f37c26ab6365c1
 SHA512:
-  metadata.gz: 31a11f36cb3f29e87e037caa5a07456d66c8bacc829ed07cb581f38fb03841f2f5c806bd23775a2de0dbe22d247925dd19b347d432079bed59980ba3d0c0a84b
-  data.tar.gz: a1ae6ee4be3375e83170a9b623281640683ad2e25249165c551d02f93ca20b7ce658c7a5741fc046af7ec82ce72420ea30fcb3e9ceace118fa70c5540fb8aa66
+  metadata.gz: c790934d4d403ec1e1a06af7d22c81eb7dea09dcaacc98b2c085ff2025f5ca0aa462c5ae8c2e35b00277e1527b26ee272e45fe5ca1b7e06c93733c03db73c831
+  data.tar.gz: c208d4dab4609203665386c20995500830a88bbae85ff8fe7dbee2aa91d3f457cbc9088ae81b00d1754040b47e66095c1b77142f48e482062850cc5b04544dea

data/.rubocop.yml

@@ -1,9 +1,7 @@
 Metrics/LineLength:
   Description: 'Limit lines to 120 characters.'
   Max: 120
-
-Style/Documentation:
-  Enabled: false
+  IgnoredPatterns: ['\A#', '\A([ ]{2}|[ ]{4})#']
 
 Style/SpaceBeforeFirstArg:
   Enabled: false

data/.travis.yml

@@ -1,4 +1,3 @@
-sudo: false
 language: ruby
 rvm:
   - 2.3.1

data/Gemfile

@@ -5,3 +5,5 @@ gemspec
 
 # Include coveralls for CI coverage reports
 gem 'coveralls', require: false
+
+gem 'pry'

data/Makefile

@@ -1,8 +1,13 @@
 test:
-bundle exec rspec spec
+	bundle exec rake
 
 build:
-gem build parliament-ruby.gemspec
+	gem build parliament-ruby.gemspec
+
+release: build test
+	gem push parliament-ruby-*.gem
+	rm parliament-ruby-*.gem
+
+
+
 
-release: build test 
-gem push parliament-ruby-*.gem ; rm parliament-ruby-*.gem

data/README.md

@@ -16,7 +16,15 @@
   - [Setting up a connection](#setting-up-a-connection)
     - [Setting a base URL 'globally'](#setting-a-base-url-globally)
   - [Building an 'endpoint'](#building-an-endpoint)
-    - [What's #get?](#whats-get)
+  - [Methods](#methods)
+    - [`#get`](#get)
+    - [`#filter`](#filter)
+    - [`#sort_by`](#sort_by)
+    - [`#reverse_sort_by`](#reverse_sort_by)
+  - [`Partliament::Utils`](#partliamentutils)
+    - [Methods](#methods-1)
+      - [`Parliament::Utils.sort_by`](#parliamentutilssort_by)
+      - [`Parliament::Utils.reverse_sort_by`](#parliamentutilsreverse_sort_by)
 - [Getting Started with Development](#getting-started-with-development)
   - [Running the tests](#running-the-tests)
 - [Contributing](#contributing)
@@ -41,6 +49,8 @@ gem 'parliament', git: 'https://github.com/ukparliament/parliament-ruby.git', br
 ## Usage
 This gem's main function is fetching an n-triple file from a remote server and converting it into linked ruby objects.
 
+> **Note:** Comprehensive class documentation can be found on [rubydocs][rubydocs].
+
 ### Setting up a connection
 In order to connect to a remote server, we first need to set a base_url value, from which we will build an 'endpoint'. The base_url should be the beginning of a url without the trailing slash. For example `http://example.com` instead of `http://example.com/`.
 ```ruby
@@ -76,20 +86,182 @@ An endpoint is effectively just a full URL to an n-triple file on a remote serve
 
 Building an endpoint is simple, once you have a Parliament::Request object, you do something like this:
 ```ruby
-parliament = Parliament::Request.new(base_url: 'http://test.com') #=>  #<Parliament::Request>
+parliament = Parliament::Request.new(base_url: 'http://test.com') #=>  #<Parliament::Request [...]>
+
+# Target endpoint: 'http://test.com/parties/current'
+parliament.parties.current
+
+# Target endpoint: 'http://test.com/parties/123/people/current'
+parliament.parties('123').people.current
+
+# Target endpoint: 'http://test.com/people/123/letters/456'
+parliament.people('123').letters('456')
+```
+
+
+### Methods
+[parliament-ruby][parliament-ruby] comes with the following common methods:
+
+| Method                                 | Description |
+|----------------------------------------|-------------|
+| [`#get`](#get)                         | **Make a GET request** - Make a HTTP GET request to the endpoint we have built, and create Ruby objects. |
+| [`#filter`](#filter)                   | **Filter the response** - After making a GET request, filter the objects returned by type attribute. |
+| [`#sort_by`](#sort_by)                 | **Sort the response (ASC)** - After making a GET request, sort the result in ascending order. |
+| [`#reverse_sort_by`](#reverse_sort_by) | **Sort the response (DESC)** - After making a GET request, sort the result in descending order. |
+
+> **Note:** Comprehensive class documentation can be found on [rubydocs][rubydocs].
+
+#### `#get`
+Once you've built your endpoint (`parliament.people.current`), we use the `#get` method to tell us you're ready to get the data.
+
+```ruby
+# Target endpoint: 'http://test.com/people/123/letters/456'
+response = parliament.people('123').letters('456').get #=> #<Parliament::Response [...]>
+
+response.each do |node|
+  # If your n-triple file contains a literal object it is stored into an instance variable accessible via the predicate
+  # name. For example, with the following triple:
+  # <http://id.ukpds.org/1234> <http://id.ukpds.org/schema/name> 'Matthew Rayner' .
+  #
+  # You would be able to access the `name` attribute like so:
+  puts node.name #=> 'Matthew Rayner'
+  
+  # If your n-triple file contains a triple who's object is a URI, and that URI is defined within your file, a link will
+  # be created, allowing you to 'connect' the two objects. For example, with the following triples:
+  # <http://id.ukpds.org/1234> <http://id.ukpds.org/schema/name> 'Matthew Rayner' .
+  # <http://id.ukpds.org/1234> <http://id.ukpds.org/schema/partyMembership> <http://id.ukpds.org/5678> .
+  # <http://id.ukpds.org/5678> <http://id.ukpds.org/schema/startDate> "1992-04-09"^^<http://www.w3.org/2001/XMLSchema#date> .
+  #
+  # You would be able to access the start date attribute on the linked object like so:
+  puts node.graph_id        #=> '12345'
+  puts node.name            #=> 'Matthew Rayner'
+  puts node.partyMembership #=> [#<Grom::Node @startDate=...>]
+  
+  puts node.partyMembership.first.startDate #=> "1992-04-09"
+end
+```
+
+`#get` returns a `Parliament::Response` object which contains all of the nodes from our n-triple response.
+
+#### `#filter`
+If your n-triple file contains a number of different objects you can filter based on type attribute.
+
+```ruby
+# Target endpoint: 'http://test.com/people/members/current'
+response = parliament.people.members.current.get #=> #<Parliament::Response [...]>
+
+# Given the below set of triples, you will be able to filter on 'type' attribute.
+# <http://id.ukpds.org/cea89432-e046-4013-a9ba-e93d0468d186> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.ukpds.org/schema/Person> .
+# <http://id.ukpds.org/4ef6c7b7-a5c8-4dde-a5a5-29c9f80d8a27> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.ukpds.org/schema/Constituency> .
+# <http://id.ukpds.org/80234c90-f86a-4942-b6ae-d1e57a0b378d> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.ukpds.org/schema/Party> .
+# <http://id.ukpds.org/HouseOfCommons> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.ukpds.org/schema/House> .
+#
+# The filter method returns an array of filtered responses. Each response holding just items with the given type attribute.
+filtered_responses = response.filter('http://id.ukpds.org/schema/Person', 'http://id.ukpds.org/schema/Party', 'http://id.ukpds.org/schema/Constituency')
+filtered_responses #=> [<#Parliament::Response [...]>, <#Parliament::Response []>, <#Parliament::Response [...]>]
+```
 
-# target endpoint: 'http://test.com/parties/current'
-parliament.parties.current.get
+#### `#sort_by`
+Once you have a `Parliament::Response` object, you can perform an ascending sort on the results by using the `#sort_by` method.
 
-# target endpoint: 'http://test.com/parties/123/people/current'
-parliament.parties('123').people.current.get
+> **`#sort_by`** is an ascending order sort i.e. (a..z, 0..9)
 
-# target endpoint: 'http://test.com/people/123/letters/456'
-parliament.people('123').letters('456').get
+```ruby
+# Target endpoint: 'http://test.com/people/members/current'
+response = parliament.people.members.current.get #=> #<Parliament::Response [...]>
+
+# Given the below set of triples, you can sort ascending like so:
+# <http://id.ukpds.org/1234> <http://id.ukpds.org/schema/startDate> "1997-01-01"^^<http://www.w3.org/2001/XMLSchema#date> .
+# <http://id.ukpds.org/5678> <http://id.ukpds.org/schema/startDate> "1991-03-15"^^<http://www.w3.org/2001/XMLSchema#date> .
+# <http://id.ukpds.org/9101> <http://id.ukpds.org/schema/startDate> "2011-09-04"^^<http://www.w3.org/2001/XMLSchema#date> .
+# <http://id.ukpds.org/1121> <http://id.ukpds.org/schema/startDate> "1981-07-31"^^<http://www.w3.org/2001/XMLSchema#date> .
+# <http://id.ukpds.org/3141> <http://id.ukpds.org/schema/endDate> "1997-07-31"^^<http://www.w3.org/2001/XMLSchema#date> .
+#
+# The sort_by method returns a sorted array of Grom::Nodes, sorted by one, or many, symbols passed to it.
+sorted_response = response.sort_by(:startDate)
+
+# Output each of the graph_id and startDate values
+sorted_response.each { |node| puts "#{node.graph_id} - #{node.respond_to?(:startDate) ? node.startDate : 'undefined'}" }
+# http://id.ukpds.org/3141 - undefined
+# http://id.ukpds.org/1121 - 1981-07-31
+# http://id.ukpds.org/5678 - 1991-03-15
+# http://id.ukpds.org/1234 - 1997-01-01
+# http://id.ukpds.org/9101 - 2011-09-04
+```
+
+> **NOTE:** `#sort_by` places all `nil` responses at the start of the sort. For a more custom sort, take a look at `Parliament::Utils.sort_by`.
+
+#### `#reverse_sort_by`
+`#reverse_sort_by` simple implements `#sort_by` and calls `#reverse!` on the resulting array. The above example would become:
+
+```ruby
+# http://id.ukpds.org/9101 - 2011-09-04
+# http://id.ukpds.org/1234 - 1997-01-01
+# http://id.ukpds.org/5678 - 1991-03-15
+# http://id.ukpds.org/1121 - 1981-07-31
+# http://id.ukpds.org/3141 - undefined
 ```
 
-#### What's #get?
-Once you've built your endpoint (`parliament.people.current`), we use the `#get` method to tell us you're finished building and ready to get the data. 
+### `Partliament::Utils`
+Included with [parliament-ruby][parliament-ruby] is `Parliament::Utils`. This module includes helper methods commonly used throughout parliament.uk.
+
+#### Methods
+
+| Method                                                | Description |
+|-------------------------------------------------------|-------------|
+| [`#sort_by`](#parliamentutilssort_by)                 | **Sort an enumerable thing (ASC)** - An implementation of ruby's `#sort_by` method that allows nil sorts. |
+| [`#reverse_sort_by`](#parliamentutilsreverse_sort_by) | **Sort an enumerable thing (DESC)** - Reverse the result of `Parliament::Utils.reverse_sort_by` |
+
+
+##### `Parliament::Utils.sort_by`
+One of the common use cases we have is sorting objects by a date (e.g. seat incumbency end date) where an object without an end date is considered 'current' and should be sorted to the top (or bottom) of a list.
+
+Because we working with graph databases, a node without an endDate simply has no method when converted to an object with [GROM][grom].
+
+The `Parliament::Utils.sort_by` method takes a hash of options, detailed below:
+
+```ruby
+response = parliament.people('123').get.filter('http://id.ukpds.org/schema/Person')
+
+objects = response.first.incumbencies
+
+options = {
+  list: objects,          # An enumerable of objects (most commonly an Array)
+  parameters: [:endDate], # An array of actions which we will sort by
+  prepend_rejected: false # {optional  default=true} Should any objects that are 'rejected' be prepended to the sorted list, or appended. i.e. where to put objects that don't respond to parameters provided
+}
+
+sorted_list = Parliament::Util.sort_by(options)
+
+sorted_list.each { |incumbency| puts incumbency.respond_to?(:endDate) ? incumbency.endDate : 'Current' }
+# http://id.ukpds.org/1121 - 1981-07-31
+# http://id.ukpds.org/5678 - 1991-03-15
+# http://id.ukpds.org/1234 - 1997-01-01
+# http://id.ukpds.org/9101 - 2011-09-04
+# http://id.ukpds.org/3141 - Current
+```
+
+##### `Parliament::Utils.reverse_sort_by`
+This method, under the hood, calls `Parliament::Utils.sort_by` and runs `#reverse!` on the result.
+
+Following the above example, and changing:
+```ruby
+sorted_list = Parliament::Util.sort_by(options)
+```
+
+to:
+```ruby
+sorted_list = Parliament::Util.reverse_sort_by(options)
+```
+
+should result in:
+```ruby
+    # http://id.ukpds.org/3141 - Current
+    # http://id.ukpds.org/9101 - 2011-09-04
+    # http://id.ukpds.org/1234 - 1997-01-01
+    # http://id.ukpds.org/5678 - 1991-03-15
+    # http://id.ukpds.org/1121 - 1981-07-31
+```
 
 
 ## Getting Started with Development
@@ -127,9 +299,11 @@ If you wish to submit a bug fix or feature, you can create a pull request and it
 [parliament-ruby]: https://github.com/ukparliament/parliament-ruby
 [pds]:             https://www.parliament.uk/mps-lords-and-offices/offices/bicameral/parliamentary-digital-service/
 [ruby-version]:    https://github.com/ukparliament/parliament-ruby/blob/master/.ruby-version
+[grom]:            https://github.com/ukparliament/grom
+[rubydocs]:        http://www.rubydoc.info/github/ukparliament/parliament-ruby/master/file/README.md
 
 [info-gem]:  https://rubygems.org/gems/parliament-ruby
-[shield-gem]: https://img.shields.io/gem/v/formatador.svg
+[shield-gem]: https://img.shields.io/gem/v/parliament-ruby.svg
 
 [info-travis]:   https://travis-ci.org/ukparliament/parliament-ruby
 [shield-travis]: https://img.shields.io/travis/ukparliament/parliament-ruby.svg

data/Rakefile

@@ -3,4 +3,4 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+task default: :spec

data/lib/parliament/client_error.rb

@@ -0,0 +1,21 @@
+module Parliament
+  # An error raised when a 4xx status code is returned by Net::HTTP inside of Parliament::Request.
+  #
+  # @see Parliament::ServerError
+  #
+  # @since 0.6.0
+  class ClientError < Parliament::NetworkError
+    # @param [String] url the url that caused the Parliament::ClientError
+    # @param [Net::HTTPClientError] response the Net:HTTPClientError that caused the Parliament::ClientError
+    #
+    # @example Creating a Parliament::ClientError
+    #   url = 'http://localhost:3030/foo/bar'
+    #
+    #   response = Net::HTTP.get_response(URI(url))
+    #
+    #   raise Parliament::ClientError.new(url, response) if response.is_a?(Net::HTTPClientError)
+    def initialize(url, response)
+      super
+    end
+  end
+end

data/lib/parliament/decorator/constituency_area.rb

@@ -0,0 +1,27 @@
+module Parliament
+  module Decorator
+    # Decorator namespace for Grom::Node instances with type: http://id.ukpds.org/schema/ConstituencyArea
+    module ConstituencyArea
+      # Alias constituencyAreaLatitude with fallback.
+      #
+      # @return [String, String] the latitude of the Grom::Node or an empty string.
+      def latitude
+        respond_to?(:constituencyAreaLatitude) ? constituencyAreaLatitude : ''
+      end
+
+      # Alias constituencyAreaLongitude with fallback.
+      #
+      # @return [String, String] the longitude of the Grom::Node or an empty string.
+      def longitude
+        respond_to?(:constituencyAreaLongitude) ? constituencyAreaLongitude : ''
+      end
+
+      # Alias constituencyAreaExtent with fallback.
+      #
+      # @return [String, String] the polygon of the Grom::Node or an empty string.
+      def polygon
+        respond_to?(:constituencyAreaExtent) ? constituencyAreaExtent : ''
+      end
+    end
+  end
+end

data/lib/parliament/{decorators → decorator}/constituency_group.rb

@@ -1,22 +1,38 @@
 module Parliament
-  module Decorators
+  module Decorator
+    # Decorator namespace for Grom::Node instances with type: http://id.ukpds.org/schema/ConstituencyGroup
     module ConstituencyGroup
+      # Alias constituencyGroupName with fallback.
+      #
+      # @return [String, String] the name of the Grom::Node or an empty string.
       def name
         respond_to?(:constituencyGroupName) ? constituencyGroupName : ''
       end
 
+      # Alias constituencyGroupStartDate with fallback.
+      #
+      # @return [DateTime, nil] the start date of the Grom::Node or nil.
       def start_date
         respond_to?(:constituencyGroupStartDate) ? DateTime.parse(constituencyGroupStartDate) : nil
       end
 
+      # Alias constituencyGroupEndDate with fallback.
+      #
+      # @return [DateTime, nil] the end date of the Grom::Node or nil.
       def end_date
         respond_to?(:constituencyGroupEndDate) ? DateTime.parse(constituencyGroupEndDate) : nil
       end
 
+      # Alias constituencyGroupHasHouseSeat with fallback.
+      #
+      # @return [Array, Array] the house seats of the Grom::Node or an empty array.
       def seats
         respond_to?(:constituencyGroupHasHouseSeat) ? constituencyGroupHasHouseSeat : []
       end
 
+      # Alias houseSeatHasSeatIncumbency with fallback.
+      #
+      # @return [Array, Array] the seat incumbencies of the Grom::Node or an empty array.
       def seat_incumbencies
         return @seat_incumbencies unless @seat_incumbencies.nil?
 
@@ -28,6 +44,9 @@ module Parliament
         @seat_incumbencies = seat_incumbencies.flatten.uniq
       end
 
+      # Alias incumbencyHasMember with fallback.
+      #
+      # @return [Array, Array] the members of the Grom::Node or an empty array.
       def members
         return @members unless @members .nil?
 
@@ -39,10 +58,16 @@ module Parliament
         @members = members.flatten.uniq
       end
 
+      # Alias constituencyGroupHasConstituencyArea with fallback.
+      #
+      # @return [Grom::Node, nil] a Grom::Node with type http://id.ukpds.org/schema/ConstituencyArea or nil.
       def area
         respond_to?(:constituencyGroupHasConstituencyArea) ? constituencyGroupHasConstituencyArea.first : nil
       end
 
+      # Alias incumbencyHasContactPoint with fallback.
+      #
+      # @return [Array, Array] the contact points of the Grom::Node or an empty array.
       def contact_points
         return @contact_points unless @contact_points.nil?
 
@@ -54,6 +79,9 @@ module Parliament
         @contact_points = contact_points.flatten.uniq
       end
 
+      # Checks if Grom::Node has an end date.
+      #
+      # @return [Boolean] a boolean depending on whether or not the Grom::Node has an end date.
       def current?
         has_end_date = respond_to?(:constituencyGroupEndDate)
 

data/lib/parliament/decorator/contact_point.rb

@@ -0,0 +1,48 @@
+module Parliament
+  module Decorator
+    # Decorator namespace for Grom::Node instances with type: http://id.ukpds.org/schema/ContactPoint
+    module ContactPoint
+      # Alias contactPointHasPostalAddress with fallback.
+      #
+      # @return [Array, Array] an array of the postal addresses for the Grom::Node or an empty array.
+      def postal_addresses
+        respond_to?(:contactPointHasPostalAddress) ? contactPointHasPostalAddress : []
+      end
+
+      # Alias email with fallback.
+      #
+      # @return [String, String] the email of the Grom::Node or an empty string.
+      def email
+        instance_variable_get('@email'.to_sym).nil? ? '' : instance_variable_get('@email'.to_sym)
+      end
+
+      # Alias phoneNumber with fallback.
+      #
+      # @return [String, String] the phone number of the Grom::Node or an empty string.
+      def phone_number
+        respond_to?(:phoneNumber) ? phoneNumber : ''
+      end
+
+      # Alias faxNumber with fallback.
+      #
+      # @return [String, String] the fax number of the Grom::Node or an empty string.
+      def fax_number
+        respond_to?(:faxNumber) ? faxNumber : ''
+      end
+
+      # Alias contactPointHasPerson with fallback.
+      #
+      # @return [Array, Array] the person connected to the Grom::Node or an empty array.
+      def person
+        respond_to?(:contactPointHasPerson) ? contactPointHasPerson : []
+      end
+
+      # Alias contactPointHasIncumbency with fallback.
+      #
+      # @return [Grom::Node, nil] the incumbency of the Grom::Node or nil.
+      def incumbency
+        respond_to?(:contactPointHasIncumbency) ? contactPointHasIncumbency.first : nil
+      end
+    end
+  end
+end