pyr 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e1491c2bf3745ed6129b38b129f867e3e45c411c
-  data.tar.gz: a9117f49800abfef2b3c80c4078e6ca2679db14f
+  metadata.gz: 05417621a790e6818011d19f83a9307b77e12522
+  data.tar.gz: b1685e7ade99c0fb3f5577892599604c5c3fc590
 SHA512:
-  metadata.gz: ae1fce84b54cdc4d868b087f5c6d1550d08d9498f174214096feca50772da3da9f00c79b8784dbc8257158e810bda35c471b35b1f5cdcc99d5572cfd77263a6b
-  data.tar.gz: bf442cd044a7cdcbe29b75e9a4448043e73d8c78ba43671388768ee26ff0782ae02cd2487d02673ffca81f6c9b39ee1467ee02cd595391c694a83aa2ef6fe91c
+  metadata.gz: '0938235b38f8b3c0a02255086e39a244fc63704164b3910bee275234ec945e17ee1cbe1aa8ba981a38ebf76321934f5725dc21ff8b8647f78aef2d6513ec25a3'
+  data.tar.gz: 8b9396fcb11c3bf5d6ef45ec2c2233314d67b333614d92abd7db4485a69df29f6e431da5f1aa6539773323e9170055cdaae941e30fac50fc029dbfac1e43fec9

data/README.md

@@ -66,6 +66,8 @@ reps.first.office_locations.first.phone
 ### Querying the full index and narrowing with scopes
 ```ruby
 response = PYR.call :reps
+# is equivalent to
+response = PYR.reps
 
 reps = response.objects
 
@@ -96,7 +98,7 @@ bernie = PYR.call(:reps, 'S000033').objects.first
 
 ### Querying by Object
 ```ruby
-office = PYR.call(:reps, 'S000033').objects.first.office_locations.district.first
+office = PYR.reps('S000033').objects.first.office_locations.district.first
 => #<PYR::OfficeLocation id: 1, city: "Burlington", rep: "https://phone-your-rep.herokuapp.com/api/beta/reps/S000033", active: true, office_id: "S000033-burlington", bioguide_id: "S000033", office_type: "district", distance: nil, building: "", address: "1 Church St.", suite: "3rd Floor", city: "Burlington", state: "VT", zip: "05401", phone: "802-862-0697", fax: "802-860-6370", hours: "", latitude: 44.4802081, longitude: -73.2130702, v_card_link: "https://phone-your-rep.herokuapp.com/v_cards/S000033-burlington", downloads: 14, qr_code_link: "https://s3.amazonaws.com/phone-your-rep-images/S000033_burlington.png">
 
 # Pass in the object itself as the param to PYR.call
@@ -110,7 +112,7 @@ office.office_id == office.call.objects.first.office_id
 
 ### Querying by Phone Your Rep URI
 ```ruby
-rep = PYR.call(:reps) { |r| r.address = 'vermont' }.objects.representatives.first
+rep = PYR.reps { |r| r.address = 'vermont' }.objects.representatives.first
 
 uri = rep.district.self
 => "https://phone-your-rep.herokuapp.com/api/beta/districts/5000"

data/lib/pyr.rb

@@ -23,6 +23,7 @@
 require 'faraday'
 require 'faraday_middleware'
 
+require 'pyr/geo_findable'
 require 'pyr/param'
 require 'pyr/parser'
 require 'pyr/resource'
@@ -41,66 +42,15 @@ require 'pyr/response_objects/zcta'
 require 'pyr/request'
 require 'pyr/version'
 
-# PYR provides an easy interface to the Phone Your Rep API,
-# converting the data payloads into Plain Old Ruby Objects.
-# There is one class method on the PYR module, ::call.
-#
-# The method takes two arguments: :resource and :id. The resource
-# is the API resource, or controller name, that you want to
-# query. The name must be in plural form. The options are 'reps',
-# 'office_locations', 'states', 'districts', and 'zctas' (Zip Code
-# Tabulation Areas).
-#
-# The :id is the primary key id of a particular object. Each
-# resource has its own data attribute as ID.
-#
-#   ids = {
-#     reps: :bioguide_id,
-#     office_locations: :office_id,
-#     states: :state_code,
-#     districts: :full_code,
-#     zctas: :zcta
-#   }
-#
-# The ::call method takes a block, to which it yields an object
-# inherited from the PYR::Resource class. You can then pass params to
-# the PYR::Resource object. The particular descendant of PYR::Resource,
-# and therefore the available params, depends on the resource/controller
-# that you are querying.
-#
-# The return value of ::call is an instance of the PYR::Response class.
-# You can call these methods on the object:
-#
-#   #objects => A collection, similar to an ActiveRecord Relation, of
-#               objects descended from the PYR::ResponseObject superclass,
-#               which have getter methods for each data attribute.
-#               The objects may be nested inside other PYR::ResponseObjects,
-#               e.g. a :rep has_one :state and has_many :office_locations.
-#               The collection can be iterated over, and can be queried
-#               similarly to how you would query in ActiveRecord, using the
-#               #where method, which can take hash syntax for checking equality
-#               of discreet attributes, or block syntax if you need to do
-#               more complex comparisons. Some scopes are also available
-#               depending on the resource, e.g. `reps.democratic.senators`
-#
-#   #uri => The URI that the request was sent to.
-#
-#   #body => The raw JSON data response
-#
-#   #code => The HTTP status code e.g. 200
-#
-#   #message => The HTTP status message e.g. 'OK'
-#
-#   #controller => The API controller that was hit e.g. :reps, :zctas etc...
-#
-#   #headers => A hash containing the HTTP response headers
+# PYR wraps the Phone Your Rep API in an easy interface,
+# converting the data payloads into Ruby objects.
 #
 # ==== Examples
 #
 #   response = PYR.call(:reps) { |r| r.address = 'vermont' }
 #
 #   response.body # => { ... }
-#   response.uri # => 'https://phone-your-rep.herokuapp.com/api/beta/reps?address=vermont'
+#   response.path # => 'reps?address=vermont'
 #   reps = response.objects
 #   reps.count # => 3
 #   reps.independent.senators.first.official_full # => "Bernard Sanders"
@@ -111,6 +61,26 @@ require 'pyr/version'
 #   independent_senators = response.objects.independent.senators
 #   vt_fav_son = independent_senators.where { |r| r.state.abbr == 'VT' }.first
 #   vt_fav_son.official_full # => "Bernard Sanders"
+#   vt_fav_son.bioguide_id # => "S000033"
+#
+#   response = PYR.call :reps, 'S000033'
+#
+#   response.objects.first.official_full # => "Bernard Sanders"
+#
+#   PYR.reps('S000033').objects.first.official_full # => "Bernard Sanders"
+#
+# Any of the following resources can be passed as the first argument to `PYR.call`,
+# or called as a class method directly to the PYR module, as in the above example.
+# Both options yield a resource to the block for setting params.
+#   :reps, :office_locations, :states, :districts, :zctas
+#
+# So
+#
+#   PYR.call(:reps) { |r| r.address = 'vermont' }
+#
+# Is equivalent to
+#
+#   PYR.reps { |r| r.address = 'vermont' }
 module PYR
   # The base URI for all requests
   API_BASE_URI = 'https://phone-your-rep.herokuapp.com/api/beta/'
@@ -151,16 +121,51 @@ module PYR
   #
   # or, perhaps most commonly, a resource name (String or Symbol) with
   # optional ID(String).
-  def self.call(resource, id = nil)
+  def self.call(resource, id = nil, &config_block)
     if resource.is_a?(ResponseObject)
       request_object = { response_object: resource }
     elsif resource.to_s.include? API_BASE_URI
       request_object = { uri: resource }
     else
       resource = Request.build(resource, id)
-      yield resource if block_given?
+      config_block.call resource if block_given?
       request_object = { resource: resource }
     end
     Response.new request_object
   end
+
+  # Call the :reps resource.
+  #
+  #   PYR.reps { |r| r.address = '123 Main St, USA 12345' }
+  def self.reps(id = nil, &config_block)
+    call(:reps, id, &config_block)
+  end
+
+  # Call the :office_locations resource.
+  #
+  #   PYR.office_locations { |r| r.address = '123 Main St, USA 12345' }
+  def self.office_locations(id=nil, &config_block)
+    call(:office_locations, id, &config_block)
+  end
+
+  # Call the :zctas resource.
+  #
+  #   PYR.zctas('90026') { |r| r.reps = true }
+  def self.zctas(id = nil, &config_block)
+    call(:zctas, id, &config_block)
+  end
+
+  # Call the :states resource.
+  #
+  #   PYR.states '50'
+  def self.states(id = nil, &config_block)
+    call(:states, id, &config_block)
+  end
+
+  # Call the :districts resource.
+  #
+  #   PYR.districts '5000'
+  def self.districts(id = nil, &config_block)
+    call(:districts, id, &config_block)
+  end
 end

data/lib/pyr/geo_findable.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PYR
+  # Shared params for resources that can be looked up by location.
+  module GeoFindable
+    # Read the lat param
+    attr_reader :lat
+    # Read the long param
+    attr_reader :long
+    # Read the address param
+    attr_reader :address
+    # Read the generate param
+    attr_reader :generate
+
+    # Set the lat param : float
+    # Needs to be accompanied by :long.
+    #
+    # Usage:
+    #   PYR.call :reps do |r|
+    #     r.lat  = 45.0
+    #     r.long = -70.0
+    #   end
+    # Resulting URI
+    #   'https://phone-your-rep.herokuapp.com/api/beta/reps?lat=45.0&long=-45.0'
+    def lat=(float)
+      @lat = Param.new(:lat, float)
+      params << @lat
+    end
+
+    # Set the long param : float
+    # Needs to be accompanied by :lat.
+    #
+    # Usage:
+    #   PYR.call :reps do |r|
+    #     r.lat  = 45.0
+    #     r.long = -70.0
+    #   end
+    #
+    # Resulting URI
+    #   'https://phone-your-rep.herokuapp.com/api/beta/reps?lat=45.0&long=-45.0'
+    def long=(float)
+      @long = Param.new(:long, float)
+      params << @long
+    end
+
+    # Set the address param : string
+    # :lat and :long take precedence
+    #
+    # Usage:
+    #   PYR.call(:reps) { |r| r.address = '123 Main St., USA'}
+    #
+    # Resulting URI:
+    #   'https://phone-your-rep.herokuapp.com/api/beta/reps?lat=45.0&long=-45.0'
+    def address=(string)
+      @address = Param.new(:address, string)
+      params << @address
+    end
+
+    # Set the generate param : boolean
+    #
+    # By default making a call to the full index will return a cached
+    # JSON file. The cached file is updated regularly (usually every day).
+    # However, if you want to generate a fresh response directly from the
+    # database, you can set :generate to true. The response will be much
+    # slower, and in most cases will never be necessary. Has no effect
+    # when used with either :address or :lat/:long
+    #
+    # Usage:
+    #   PYR.call(:reps) { |r| r.generate = true }
+    #
+    # Resulting URI:
+    #   'https://phone-your-rep.herokuapp.com/api/beta/reps?generate=true'
+    def generate=(boolean)
+      @generate = Param.new(:generate, boolean)
+      params << @generate
+    end
+  end
+end

data/lib/pyr/parser.rb

@@ -1,4 +1,3 @@
-
 # frozen_string_literal: true
 
 module PYR

data/lib/pyr/resources/office_locations.rb

@@ -4,6 +4,32 @@ module PYR
   class Resource
     # Request object for sending requests to the /office_locations
     # resource of the API
-    class OfficeLocations < Resource; end
+    class OfficeLocations < Resource
+      include GeoFindable
+
+      # Read the radius param
+      attr_reader :radius
+
+      # Set the radius param : integer
+      # Needs to be accompanied by :address or :lat & :long.
+      # When doing a geo search for office_locations the API returns
+      # a set that is sorted by distance to the request location.
+      # The radius param narrows down the geo search for office_locations to
+      # only those within the specified radius in miles.
+      # Without specifying the radius, the method will return all
+      # 1,900 - 2,000 active office_locations for Congress sorted by distance,
+      # which is seldom what you want.
+      #
+      # Usage:
+      #   PYR.office_locations do |r|
+      #     r.lat    = 45.0
+      #     r.long   = -70.0
+      #     r.radius = 100
+      #   end
+      def radius=(integer)
+        @radius = Param.new(:radius, integer)
+        params << @radius
+      end
+    end
   end
 end

data/lib/pyr/resources/reps.rb

@@ -4,72 +4,7 @@ module PYR
   class Resource
     # Resource object for sending requests to the /reps resource of the API
     class Reps < Resource
-      # Read the lat param
-      attr_reader :lat
-      # Read the long param
-      attr_reader :long
-      # Read the address param
-      attr_reader :address
-      # Read the generate param
-      attr_reader :generate
-
-      # Set the lat param : float
-      # Needs to be accompanied by :long.
-      #
-      # Usage:
-      #   PYR.call :reps do |r|
-      #     r.lat  = 45.0
-      #     r.long = -70.0
-      #   end
-      def lat=(float)
-        @lat = Param.new(:lat, float)
-        params << @lat
-      end
-
-      # Set the long param : float
-      # Needs to be accompanied by :lat.
-      #
-      # Usage:
-      #   PYR.call :reps do |r|
-      #     r.lat  = 45.0
-      #     r.long = -70.0
-      #   end
-      #
-      # Resulting URI: 'https://phone-your-rep.herokuapp.com/api/beta/reps?lat=45.0&long=-45.0'
-      def long=(float)
-        @long = Param.new(:long, float)
-        params << @long
-      end
-
-      # Set the address param : string
-      # :lat and :long take precedence
-      #
-      # Usage:
-      #   PYR.call(:reps) { |r| r.address = '123 Main St., USA'}
-      #
-      # Resulting URI: 'https://phone-your-rep.herokuapp.com/api/beta/reps?lat=45.0&long=-45.0'
-      def address=(string)
-        @address = Param.new(:address, string)
-        params << @address
-      end
-
-      # Set the generate param : boolean
-      #
-      # By default making a call to the full :reps index will return a cached
-      # JSON file. The cached file is updated regularly (usually every day).
-      # However, if you want to generate a fresh response directly from the
-      # database, you can set :generate to true. The response will be much
-      # slower, and in most cases will never be necessary. Has no effect
-      # when used with either :address or :lat/:long
-      #
-      # Usage:
-      #   PYR.call(:reps) { |r| r.generate = true }
-      #
-      # Resulting URI: 'https://phone-your-rep.herokuapp.com/api/beta/reps?generate=true'
-      def generate=(boolean)
-        @generate = Param.new(:generate, boolean)
-        params << @generate
-      end
+      include GeoFindable
     end
   end
 end

data/lib/pyr/resources/zctas.rb

@@ -8,8 +8,8 @@ module PYR
       attr_reader :reps
 
       # Set the 'reps' param value
-      def reps=(value)
-        @reps = Param.new(:reps, value)
+      def reps=(boolean)
+        @reps = Param.new(:reps, boolean)
         params << @reps
       end
     end

data/lib/pyr/response_object.rb

@@ -28,7 +28,7 @@ module PYR
       @controller ||= self.class.to_s.split('::').last.tableize
     end
 
-    #
+    # Send a request to the API for the object.
     def call
       PYR.call self
     end

data/lib/pyr/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+
 module PYR
-  VERSION = '0.2.9' # :nodoc:
+  VERSION = '0.3.0' # :nodoc:
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pyr
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - M. Simon Borg
@@ -86,6 +86,7 @@ files:
 - bin/console
 - bin/setup
 - lib/pyr.rb
+- lib/pyr/geo_findable.rb
 - lib/pyr/param.rb
 - lib/pyr/parser.rb
 - lib/pyr/request.rb