clever-ruby 0.6.2 → 0.7.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NmI3NzcwOGI0ZjVjNTRmMDRiZTg5YjZiZjAyNWZjNzkzNTUxNTg2Yg==
+    NTMxM2FkNGQzYzQ0YTJjZjE0YzhkMGM0ZDAyNjg2MTg3MjFlYzU0Ng==
   data.tar.gz: !binary |-
-    MGViMmNhMjI2Mjg4MDc5Nzc1ZDFmNjM5OTc1ODhkMGIyMmZmMDFlZA==
+    NDgzOWE5NzdhZjM2NWY4YjQyNzU1ZjY1NWQ5YThiZDlkM2IzNzgyYg==
 SHA512:
   metadata.gz: !binary |-
-    YmJhMTU5OThjMWQ2ZDJhYmI0NDY4MmEyNmQ5NGY2YmI4NDQ3NTZmMjY5M2Ux
-    YjUwNzcwMGE5ZDEwOTA4YjcyMzA3OGY0OGYyYzlmZDJjNmI2NTgxOTE5NjRh
-    ZmNkN2U3YTUwYjMzNTA3OGM1N2NlNzEyNzE2MDYzZmZmODc3MzA=
+    ODIyYTg2NTQwOTA4YWUyNjgxNjhhNjU3ZTk1YWNhYmMyZTA3NjYzM2NhZGJj
+    NGI2YWJlOTkyZTFhMTI0ZjlmN2U2MzExNzgyYjliY2JmN2Y1YzZhM2NmZjk0
+    ZjY2MjgzODk0ZWNiOTM3YjI5N2EyNDUxZmY5MTIxYTlmNTM0YTA=
   data.tar.gz: !binary |-
-    OWJhZjIzMDVjNzlkODM4NmVhMjJiYzcxYTk5MTM3NmIyOWFhY2NkYTI3MzBl
-    ZWFhMWYxMTlhNzMxY2RhMzQ1YzQyMTc4NGVjOTQxMmFjZDM4NjczYWUwOWI4
-    MjY5Y2YyMzhmODNjNjFiOGE0MzYzY2JkODU1YmFhMjZlNmJkYmQ=
+    YjE5MzgwMTJiMWRjYTYyMjQ3N2MzOTMwM2VkODcxZTViZjdhNTkyYjM0Y2Iw
+    Y2FjMjE2MjI2ZGQ4MWFlNTkwZWVmMDMxZTM1ZTBkZDkzYTkwZTc1OGY1OGVj
+    NzNiOGFmN2U1OTNkYzhhMjAxNDg3ZWIzZjIwNzFiNWU3MDljZmU=

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.7.0 (2014-09-12)
+
+* Make nested resources support full queries, including find and count
+* Make tests more robust to data changes
+
 ## 0.6.2 (2014-09-12)
 
 * Update dependencies

data/lib/clever-ruby.rb

@@ -1,6 +1,7 @@
 # rubocop:disable FileName
 require 'rest_client'
 require 'multi_json'
+require 'active_support/inflector'
 require 'open-uri'
 require 'set'
 require 'uri'
@@ -10,6 +11,7 @@ require 'clever-ruby/version'
 
 # API operations
 require 'clever-ruby/api_operations/list'
+require 'clever-ruby/api_operations/nested_list'
 require 'clever-ruby/api_operations/pagelist'
 require 'clever-ruby/api_operations/results_list'
 require 'clever-ruby/api_operations/page'
@@ -22,6 +24,7 @@ require 'clever-ruby/configuration'
 # Resources
 require 'clever-ruby/clever_object'
 require 'clever-ruby/api_resource'
+require 'clever-ruby/nested_resource'
 require 'clever-ruby/district'
 require 'clever-ruby/school'
 require 'clever-ruby/student'

data/lib/clever-ruby/api_operations/nested_list.rb

@@ -0,0 +1,46 @@
+module Clever
+  module APIOperations
+    # Methods for interacting with the API on nested resources
+    module NestedList
+      # Query a nested list with Clever API params, overriding initialized keys
+      # @api public
+      # @note You don't need to call this if you aren't using additional filters;
+      #   instead just iterate on the NestedResource itself.
+      # @param filters [Hash] Parameters to use
+      # @return [Clever::APIOperations::ResultList] list of results
+      # @example
+      #   # Without any overriding
+      #   district = Clever::Districts.retrieve id
+      #   district.schools.find(starting_after: lower_bound).each do |school|
+      #     puts school.name
+      #   end
+      #
+      #   # With overriding
+      #   district = Clever::Districts.retrieve id
+      #   schools = district.schools(starting_after: lower_bound)
+      #   # The above filter has been overridden for the query below!
+      #   schools.find(starting_after: even_lower_bound).each do |school|
+      #     puts school.name
+      #   end
+      def find(filters = {})
+        filters = @filters.merge filters
+        Clever::APIOperations::PageList.new(@uri, filters).to_results_list
+      end
+
+      # Request the number of elements in a nested list from the API
+      # @note This does not count a data structure in memory; it runs an HTTP query!
+      # @api public
+      # @param filters [Hash] Parameters to use
+      # @return [Integer] Results
+      # @example
+      #   district = Clever::Districts.retrieve id
+      #   num_schools_in_district = district.schools.count
+      def count(filters = {})
+        filters = @filters.merge filters
+        filters[:count] = true
+        response = Clever.request :get, @uri, filters
+        response[:count]
+      end
+    end
+  end
+end

data/lib/clever-ruby/api_resource.rb

@@ -1,6 +1,45 @@
 module Clever
   # Superclass of API resources in the Clever API
   class APIResource < CleverObject
+    @resources = []
+
+    class << self
+      # Get valid API resources
+      # @api private
+      # @return [Array] List of valid API resource classes
+      attr_reader :resources
+
+      # Get a list of nested resources in the Clever API for this resource
+      # @api private
+      # @return [Array] List of resources nested under this resource
+      attr_reader :linked_resources
+    end
+
+    # Registers valid API resources
+    # @api private
+    # @return [Object]
+    def self.inherited(child_class)
+      @resources << child_class
+      super
+    end
+
+    # Get a canonical name for a resource
+    # @api private
+    # @return [String]
+    def self.shortname
+      name.split('::')[-1].downcase.singularize
+    end
+
+    # Convert the name of a resource to its APIResource subclass
+    # @api private
+    # @return [APIResource]
+    def self.named(name)
+      name = name.to_s.downcase.singularize
+      matching = resources.select { |res| res.shortname == name }
+      return nil if matching.empty?
+      matching.first
+    end
+
     # Get URL for a resource
     # @api private
     # @return [String] url to query for a resource
@@ -9,8 +48,7 @@ module Clever
         fail NotImplementedError, 'APIResource is an abstract class. You should perform actions '\
           'on its subclasses (School, Student, etc.)'
       end
-      shortname = name.split('::')[-1]
-      "v1.1/#{CGI.escape shortname.downcase}s"
+      "v1.1/#{CGI.escape shortname.pluralize}"
     end
 
     # Get URL for an instance of a resource
@@ -32,16 +70,17 @@ module Clever
     def refresh
       response = Clever.request :get, url
       refresh_from response[:data]
+
+      @links = response[:links].map do
+        |link| { :"#{link[:rel]}" => link[:uri] }
+      end.reduce({}, :merge)
       self
     end
 
     # Get hypermedia links for this resource instance
     # @api private
     # @return [Array] list of links for this resource instance
-    def links
-      response = Clever.request :get, url
-      response[:links]
-    end
+    attr_reader :links
 
     # Get an instance of a resource
     # @api public
@@ -56,33 +95,34 @@ module Clever
       instance
     end
 
-    # Request resource instances by following hypermedia links
+    # Get the URI for a hypermedia link
     # @api private
-    # @return [Array] List of resources found
-    def get_linked_resources(resource_type, filters = {})
-      Util.convert_to_clever_object Clever.request(:get, get_uri(resource_type), filters)[:data]
-    end
-
-    class << self
-      # Get a list of nested resources in the Clever API for this resource
-      # @api private
-      # @return [Array] List of resources nested under this resource
-      attr_reader :linked_resources
+    # @return [String]
+    def get_link_uri(resource_type)
+      refresh if links.nil?
+      links[resource_type.to_sym]
     end
 
-    # Create an instance of APIResource, defining links to nested resources
-    # @api public
-    # @param [String] id of object to instantiate
-    # @return [APIResoruce] resource instance
-    # @example
-    #   Clever::District.new '531fabe082d522cds8e22'
+    # Construct an APIResource. Generates methods for nested resources
+    # @abstract
+    # @api private
+    # @return [APIResource]
     def initialize(id)
       super id
+      return if self.class.linked_resources.nil?
 
-      resources = self.class.linked_resources || []
-      resources.each do |resource|
-        self.class.send :define_method, resource do |filters = {}|
-          get_linked_resources resource.to_s, filters
+      self.class.linked_resources.each do |resource|
+        if Clever::Util.singular? resource.to_s
+          # Get single resource
+          self.class.send :define_method, resource do
+            response = Clever.request :get, get_link_uri(resource)
+            return Util.convert_to_clever_object response
+          end
+        else
+          # Get list of nested resources
+          self.class.send :define_method, resource do |filters = {}|
+            Clever::NestedResource.new get_link_uri(resource), filters
+          end
         end
       end
     end

data/lib/clever-ruby/clever_object.rb

@@ -10,9 +10,11 @@ module Clever
     # The default :id method is deprecated and isn't useful to us
     undef :id if method_defined? :id
 
-    # Create a CleverObject. Only for inheritance purposes
+    # Create an instance of CleverObject by id
+    # @abstract
     # @api private
-    # @return [CleverObject]
+    # @param id [String, Hash] id, or values to instantiate from
+    # @return [CleverObject] resource instance
     def initialize(id = nil)
       @values = {}
       @values[:id] = id if id
@@ -194,9 +196,13 @@ module Clever
     # @api private
     # @return [Object]
     def add_accessors(keys)
+      obj = self
       metaclass.instance_eval do
         keys.each do |k|
           next if @@permanent_attributes.include? k
+          unless obj.class.linked_resources.nil?
+            next if obj.class.linked_resources.include? k
+          end
           k_eq = :"#{k}="
           define_method(k) { @values[k] }
           define_method(k_eq) { |v| @values[k] = v }

data/lib/clever-ruby/district.rb

@@ -4,6 +4,30 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:schools, :teachers, :sections, :students, :events]
 
+    # Get admins for the current district
+    # @todo This is not implemented!
+    # @api public
+    # @raise [NotImplementedError]
+    # @return [Object]
+    # @example
+    #   district = district.retrieve id
+    #   admins = district.admins
+    def admins
+      fail NotImplementedError, 'admins nested resource not yet implemented.'
+    end
+
+    # Get status of the current district
+    # @todo This is not implemented!
+    # @api public
+    # @raise [NotImplementedError]
+    # @return [Object]
+    # @example
+    #   district = district.retrieve id
+    #   puts district.status
+    def status
+      fail NotImplementedError, 'status nested resource not yet implemented.'
+    end
+
     # @see Clever::CleverObject.optional_attributes
     # @api private
     # @return [Array]
@@ -15,18 +39,8 @@ module Clever
     # TODO: remove
     [:school_pages, :teacher_pages, :section_pages, :student_pages, :event_pages].each do |name|
       define_method(name) do |filters = {}|
-        Clever::APIOperations::PageList.new get_uri(name.to_s.gsub('_page', '')), filters
+        Clever::APIOperations::PageList.new get_link_uri(name.to_s.gsub('_page', '')), filters
       end
     end
-
-    private
-
-    # Get the URI for a hypermedia link
-    # @api private
-    # @return [String]
-    def get_uri(resource_type)
-      refresh
-      links.find { |link| link[:rel] == resource_type }[:uri]
-    end
   end
 end

data/lib/clever-ruby/event.rb

@@ -17,7 +17,7 @@ module Clever
     # @example
     #   district = event.object
     def object
-      klass = Util.types_to_clever_class type_pieces[0]
+      klass = APIResource.named type_pieces[0]
       klass ||= CleverObject
       klass.construct_from data[:object]
     end

data/lib/clever-ruby/nested_resource.rb

@@ -0,0 +1,40 @@
+module Clever
+  # An interface for querying nested resources
+  class NestedResource
+    include Clever::APIOperations::NestedList
+    include Enumerable
+
+    # Create a nested resource
+    # @api private
+    # @return [Clever::APIOperations::NestedList]
+    def initialize(uri, filters = {})
+      @uri = uri
+      @filters = filters
+      @results_list = Clever::APIOperations::PageList.new(uri, filters).to_results_list
+    end
+
+    # Query and iterate over results for the params provided during initialization
+    # @api public
+    # @return [Clever::APIOperations::NestedResource] self
+    # @example
+    #   district = Clever::Districts.retrieve id
+    #   district.schools.each { |school| puts school.name }
+    def each(&blk)
+      @results_list.each(&blk)
+      self
+    end
+
+    # Query for all results and count them
+    # @api public
+    # @note This queries for the actual elements! If you wish to just do a
+    #   count query, use the count method
+    # @return [Integer]
+    # @example
+    #   district = Clever::District.retrieve id
+    #   num_schools_for_district = district.schools.length
+    def length
+      @results_list.count
+    end
+    alias_method :size, :length
+  end
+end

data/lib/clever-ruby/school.rb

@@ -2,7 +2,7 @@ module Clever
   # School resource
   class School < APIResource
     include Clever::APIOperations::List
-    @linked_resources = [:teachers, :students, :sections, :districts, :events]
+    @linked_resources = [:students, :district, :sections, :teachers, :events]
 
     # Optional attributes
     # @see Clever::CleverObject.optional_attributes

data/lib/clever-ruby/section.rb

@@ -2,7 +2,7 @@ module Clever
   # Section resource
   class Section < APIResource
     include Clever::APIOperations::List
-    @linked_resources = [:teachers, :students, :schools, :districts, :events]
+    @linked_resources = [:school, :district, :students, :teacher, :events]
 
     # Optional attributes
     # @see Clever::CleverObject.optional_attributes

data/lib/clever-ruby/student.rb

@@ -2,7 +2,19 @@ module Clever
   # Student resource
   class Student < APIResource
     include Clever::APIOperations::List
-    @linked_resources = [:teachers, :sections, :schools, :districts, :events, :contacts]
+    @linked_resources = [:school, :district, :sections, :teachers, :events]
+
+    # Get contacts for the current student
+    # @todo This is not implemented!
+    # @api public
+    # @raise [NotImplementedError]
+    # @return [Object]
+    # @example
+    #   student = student.retrieve id
+    #   contacts = student.admins
+    def contacts
+      fail NotImplementedError, 'contacts nested resource not implemented yet.'
+    end
 
     # Optional attributes
     # @see Clever::CleverObject.optional_attributes

data/lib/clever-ruby/teacher.rb

@@ -2,7 +2,7 @@ module Clever
   # Teacher resource
   class Teacher < APIResource
     include Clever::APIOperations::List
-    @linked_resources = [:sections, :students, :schools, :districts, :events, :grade_levels]
+    @linked_resources = [:school, :district, :students, :sections, :events]
 
     # Optional attributes
     # @see Clever::CleverObject.optional_attributes

data/lib/clever-ruby/util.rb

@@ -1,6 +1,14 @@
 module Clever
   # Library helper methods
   module Util
+    # Check if a given word is singular
+    # @api private
+    # @param word [String] Word to check
+    # @return [Boolean] False if plural, true if singular
+    def self.singular?(word)
+      word.singularize == word
+    end
+
     # Check if a given ID is a valid format (MongoDB BSON ObjectID)
     # @api private
     # @param id [String] ID to check
@@ -27,21 +35,6 @@ module Clever
       end
     end
 
-    # Convert the name of a resource to its APIResource class
-    # @api private
-    # @return [APIResource]
-    def self.types_to_clever_class(type)
-      types = {
-        'students'  => Student,
-        'sections'  => Section,
-        'teachers'  => Teacher,
-        'districts' => District,
-        'schools'   => School,
-        'events'    => Event
-      }
-      types.fetch type
-    end
-
     # Convert an object containing data from Clever into a CleverObject
     # @api private
     # @return [CleverObject]
@@ -52,8 +45,14 @@ module Clever
       when Hash
         # Try converting to a known object class. If none available, fall back to generic
         # APIResource.
-        klass_name = %r{/v1.1/([a-z]+)/\S+$}.match(resp[:uri])[1]
-        klass = types_to_clever_class klass_name if klass_name
+        if resp.key? :uri
+          uri = resp[:uri]
+        else
+          uri = resp[:links].select { |l| l[:rel] == 'self' }[0][:uri]
+        end
+
+        klass_name = %r{/v1.1/([a-z]+)/\S+$}.match(uri)[1]
+        klass = APIResource.named klass_name if klass_name
         klass ||= CleverObject
         klass.construct_from resp[:data]
       else