clever-ruby 0.14.0 → 1.0.0

data/.document

@@ -1,5 +0,0 @@
-lib/**/*.rb
-bin/*
-- 
-features/**/*.feature
-LICENSE.txt

data/.gitignore

@@ -1,22 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-doc_coverage.txt
-.rvmrc
-.ruby-version
-.ruby-gemset
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*~

data/.rubocop.yml

@@ -1,4 +0,0 @@
-Metrics/LineLength:
-  Max: 100
-Metrics/MethodLength:
-  Max: 20

data/.yardopts

@@ -1,2 +0,0 @@
---markup markdown
---title clever-ruby

data/LICENSE.txt

@@ -1,20 +0,0 @@
-Copyright (c) 2012 Rafael Garcia
-
-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/lib/clever-ruby/api_operations/list.rb

@@ -1,130 +0,0 @@
-module Clever
-  # API Operations
-  module APIOperations
-    # A list of API resource instances
-    module List
-      # Class methods for those that include List
-      # @api public
-      module ClassMethods
-        # Get all elements of a resource
-        # @api public
-        # @deprecated This can be costly since it places all matching elements
-        #   in memory. Instead just iterate over the collection using each.
-        # @param filters [Hash] parameters to apply, as per the Clever API spec
-        # @return [Array] array of all elements matching the request
-        # @example
-        #   Clever::District.all
-        def all(filters = {}, headers = {})
-          accum = []
-          Clever::APIOperations::PageList.new(url, filters, headers).each do |page|
-            accum += page.all
-          end
-          accum
-        end
-
-        # Get elements of a resource. Supports 1 or more ids, or open-ended query
-        # @api public
-        # @param id [String, Array, nil] ID or array of ids to match, or nil
-        #   for query
-        # @param filters [Hash, nil] Query parameters to pass, as per Clever API spec
-        # @return [Clever::APIResource, Clever::APIOperations::ResultsList]
-        #   single resource or iterable list of results
-        # @raise [ArgumentError] Bad ID/IDs provided
-        # @example
-        #   # Get first 20 clever districts
-        #   districts = Clever::District.find.take 20
-        #
-        #   # Get specific district
-        #   id = '...'
-        #   district = Clever::District.find id
-        #
-        #   # Get districts with given ids
-        #   ids = ['...', '...']
-        #   districts = Clever::District.find ids
-        def find(id = nil, filters = {}, headers = {})
-          if id.is_a? Array
-            unless id.select { |e| !Clever::Util.valid_id? e }.empty?
-              fail ArgumentError, 'Array of IDs must only contain valid ObjectIDs'
-            end
-
-            filters[:where] = JSON.dump(_id: { :'$in' => id })
-          end
-
-          if id.nil? || id.is_a?(Array)
-            Clever::APIOperations::PageList.new(url, filters, headers).to_results_list
-          elsif Clever::Util.valid_id? id
-            retrieve id
-          else
-            fail ArgumentError, 'id must be a valid ObjectID, an array of them, or nil.'
-          end
-        end
-
-        # Query for the first element or n elements in the resource
-        # @api public
-        # @param num [nil, Integer] If nil, first elem; else, num elems to fetch
-        # @param filters [Hash] Filters to request with, as per Clever API spec
-        # @return [CleverObject, Clever::APIOperations::Page] elem, or
-        #   elems found.
-        # @example
-        #   first_elem = Clever::District.first
-        #   first_elems = Clever::District.first 20
-        #   first_elems.each do |e|
-        #     puts e.name
-        #   end
-        def first(num = nil, filters = {}, headers = {})
-          if num.nil?
-            filters[:limit] = 1
-            response = Clever.request :get, url, filters, headers
-            Util.convert_to_clever_object response[:data].last
-          else
-            filters[:limit] = num
-            Clever::APIOperations::PageList.new(url, filters, headers).first
-          end
-        end
-
-        # Query for the last element or n elements in the resource
-        # @api public
-        # @param num [nil, Integer] If nil, last elem; else, num elems to fetch
-        # @param filters [Hash] Filters to request with, as per Clever API spec
-        # @return [CleverObject, Clever::APIOperations::ResultsList] elem, or
-        #   elems found. If list, sorted in ascending order of ids.
-        # @example
-        #   last_elem = Clever::District.last
-        #   last_elems = Clever::District.last 20
-        #   last_elems.each do |e|
-        #     puts e.name
-        #   end
-        def last(num = nil, filters = {}, headers = {})
-          filters[:ending_before] = 'last'
-          if num.nil?
-            filters[:limit] = 1
-            response = Clever.request :get, url, filters, headers
-            Util.convert_to_clever_object response[:data].last
-          else
-            filters[:limit] = num
-            Clever::APIOperations::PageList.new(url, filters, headers).to_results_list
-          end
-        end
-
-        # Requests number of elements matching the query
-        # @api public
-        # @param filters [Hash, nil] Query parameters to pass, as per Clever API spec
-        # @return [Integer] Number of elements matching
-        # @example
-        #   num_districts = Clever::District.count
-        def count(filters = {}, headers = {})
-          filters[:count] = true
-          response = Clever.request :get, url, filters, headers
-          response[:count]
-        end
-      end
-
-      # Add ClassMethods to classes that include List
-      # @api private
-      # @return [nil]
-      def self.included(base)
-        base.extend ClassMethods
-      end
-    end
-  end
-end

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

@@ -1,95 +0,0 @@
-module Clever
-  module APIOperations
-    # Methods for interacting with the API on nested resources
-    # TODO: find a way to not duplicate list.rb code
-    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, headers).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, headers
-        response[:count]
-      end
-
-      # Query for the first element or n elements in the resource
-      # @api public
-      # @param num [nil, Integer] If nil, last elem; else, num elems to fetch
-      # @param filters [Hash] Filters to request with, as per Clever API spec
-      # @return [CleverObject, Clever::APIOperations::Page] elem, or
-      #   elems found. If list, sorted in ascending order of ids.
-      # @example
-      #   first_elem = Clever::District.first
-      #   first_elems = Clever::District.first 20
-      #   first_elems.each do |e|
-      #     puts e.name
-      #   end
-      def first(num = nil, filters = {})
-        filters = @filters.merge filters
-        if num.nil?
-          filters[:limit] = 1
-          response = Clever.request :get, url, filters, headers
-          Util.convert_to_clever_object response[:data].last
-        else
-          filters[:limit] = num
-          Clever::APIOperations::PageList.new(url, filters, headers).first
-        end
-      end
-
-      # Query for the last element or n elements in the resource
-      # @api public
-      # @param num [nil, Integer] If nil, last elem; else, num elems to fetch
-      # @return [CleverObject, Clever::APIOperations::ResultsList] elem, or
-      #   elems found. If list, sorted in ascending order of ids.
-      # @example
-      #   last_elem = Clever::District.last
-      #   last_elems = Clever::District.last 20
-      #   last_elems.each do |e|
-      #     puts e.name
-      #   end
-      def last(num = nil, filters = {})
-        filters = @filters.merge filters
-        filters[:ending_before] = 'last'
-        if num.nil?
-          filters[:limit] = 1
-          response = Clever.request :get, @uri, filters, headers
-          Util.convert_to_clever_object response[:data].last
-        else
-          filters[:limit] = num
-          Clever::APIOperations::PageList.new(@uri, filters, headers).to_results_list
-        end
-      end
-    end
-  end
-end

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

@@ -1,71 +0,0 @@
-module Clever
-  module APIOperations
-    # Represents a page of data
-    class Page
-      include Enumerable
-
-      # Request a page of data and store the results in this instance
-      # @api private
-      # @return [Clever::APIOperations::Page]
-      # @example
-      #   page = Page.new '/v1.1/districts'
-      def initialize(uri, filters = {}, headers = {})
-        @uri = uri
-        @filters = filters
-        @headers = headers
-
-        response = Clever.request :get, uri, filters, @headers
-
-        @auth_token = @headers[:Authorization].split[1]
-        response[:data].map { |x| x[:data][:auth_token] = @auth_token }
-
-        @all = Util.convert_to_clever_object response[:data]
-        @links = {}
-        response[:links].each do |link|
-          @links[link[:rel].to_sym] = link[:uri]
-        end
-      end
-
-      # Gets next page if one is present, nil otherwise
-      # @api private
-      # @return [Clever::APIOperations::Page, nil] Next page, or nil if last
-      # @example
-      #   next_page = page.next
-      #   unless next_page.nil?
-      #     next_page.each do |elem| puts elem; end
-      def next
-        @links.key?(:next) ? Page.new(@links[:next], {}, @headers) : nil
-      end
-
-      # Iterate over all elements in the page
-      # @api private
-      # @return [Array] List of all elements
-      # @example
-      #   page.each { |elem| puts elem }
-      def each(&blk)
-        @all.each(&blk)
-      end
-
-      # Get all elements in page
-      # @api private
-      # @return [Array] List of all elements
-      # @example
-      #   all_elems = page.all
-      attr_reader :all
-
-      # Retrieve the last element or n elements in the resource
-      # @api public
-      # @param num [nil, Integer] If nil, last elem; else, num elems to fetch
-      # @return [CleverObject, Clever::APIOperations::Page] elem, or
-      #   elems found. If list, sorted in ascending order of ids.
-      # @example
-      #   elems = Clever::District.first(20)
-      #   last_elem = elems.last
-      #   last_elems = elems.last 5
-      def last(num = nil)
-        return @all.last num if num
-        @all.last
-      end
-    end
-  end
-end

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

@@ -1,43 +0,0 @@
-module Clever
-  module APIOperations
-    # Handles paginated requests.
-    class PageList
-      include Enumerable
-
-      # Create a new PageList, without making any requests immediately
-      # @api private
-      # @return [PageList]
-      def initialize(uri, filters = {}, headers = {})
-        @uri = uri
-        @filters = filters
-        @headers = headers
-      end
-
-      # Iterate through each page, making requests as you iterate
-      # @api private
-      # @return [nil]
-      # @example
-      #   pagelist.each do |page|
-      #     page.each do |elem|
-      #       puts elem
-      #     end
-      #   end
-      def each
-        page = Page.new @uri, @filters, @headers
-        until page.nil?
-          yield page
-          page = page.next
-        end
-      end
-
-      # Convert PageList into a ResultsList for easier iteration
-      # @api private
-      # @return [Clever::APIOperations::ResultsList]
-      # @example
-      #   pagelist.to_results_list.each { |elem| puts elem }
-      def to_results_list
-        Clever::APIOperations::ResultsList.new self
-      end
-    end
-  end
-end

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

@@ -1,31 +0,0 @@
-module Clever
-  module APIOperations
-    # Represents a list of results for a paged request.
-    class ResultsList
-      include Enumerable
-
-      # Create a results list from a PageList
-      # @api private
-      # @return [ResultsList]
-      def initialize(pagelist)
-        @pages = pagelist
-      end
-
-      # Iterate over results list
-      # @api public
-      # @return [nil]
-      # @example
-      #   results = Clever::District.find # returns a ResultsList
-      #   results.each do |district|
-      #     puts district.name
-      #   end
-      def each
-        @pages.each do |page|
-          page.each do |elem|
-            yield elem
-          end
-        end
-      end
-    end
-  end
-end

data/lib/clever-ruby/api_resource.rb

@@ -1,174 +0,0 @@
-module Clever
-  # Superclass of API resources in the Clever API. API objects are to be
-  # singular, not plural; as in class Student, for the /students endpoint.
-  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
-
-      # Get the plural form of a resource's name
-      #
-      # For instance, for class Student, returns "students"
-      # @api private
-      # @return [String] Plural name of a resource
-      attr_reader :plural
-
-      # Get the URI corresponding to a resource
-      #
-      # For instance, for class Student, urls start with /v1.1/students, so
-      # this returns "students"
-      # @api private
-      # @return [String] URI corresponding to a resource
-      attr_reader :uri
-
-      # Get the event name corresponding to a resource
-      #
-      # For some events, event type names have an inconsistent format with plurals and URIs.
-      # For example, SchoolAdmin events are "schooladmins"
-      # @api private
-      # @return [String] event type name of a resource
-      attr_reader :event_name
-    end
-
-    # Registers valid API resources
-    # @api private
-    # @return [Object]
-    def self.inherited(child_class)
-      @resources << child_class
-      super
-    end
-
-    # Check if the name of an APIResource is in its singular form
-    #
-    # For instance, the Student API resource can be referred to as
-    # "student" or "students"; this returns true on the former.
-    # @api private
-    # @param word [String] APIResource name to check
-    # @return [Boolean] False if plural, true if singular
-    def self.singular?(resource_name)
-      klass = named resource_name
-      unless klass
-        fail 'Clever::APIResource only supports checking singularity of words '\
-          'that refer to children of Clever::APIResource; received ' \
-          "'#{resource_name}'"
-      end
-
-      klass.plural != resource_name.downcase
-    end
-
-    # Get a canonical name for a resource
-    # @api private
-    # @return [String]
-    def self.shortname
-      name.split('::')[-1].gsub(/([a-z\d])([A-Z])/, '\1_\2'.freeze).downcase
-    end
-
-    # Convert the uri of a resource to its APIResource subclass
-    # @api private
-    # @return [APIResource]
-    def self.named(name)
-      name = name.to_s.downcase
-      matching = resources.select do |res|
-        (name == res.shortname) || (name == res.plural) || (name == res.event_name)
-      end
-      return nil if matching.empty?
-      matching.first
-    end
-
-    # Get URL for a resource
-    # @api private
-    # @return [String] url to query for a resource
-    def self.url
-      if self == APIResource
-        fail NotImplementedError, 'APIResource is an abstract class. You should perform actions '\
-          'on its subclasses (School, Student, etc.)'
-      end
-      "v1.1/#{uri}"
-    end
-
-    # Get URL for an instance of a resource
-    # @api private
-    # @return [String] url to query for an instance of a resource
-    def url
-      id = self['id']
-      unless id
-        fail InvalidRequestError.new(
-          "Could not determine which URL to request: #{self.class} instance has " \
-          "invalid ID: #{id.inspect}", 'id')
-      end
-      "#{self.class.url}/#{CGI.escape id}"
-    end
-
-    # Request the current resource data and update this object
-    # @api private
-    # @return [APIResource] The updated resource instance
-    def refresh
-      response = Clever.request :get, url, nil, headers
-      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
-    attr_reader :links
-
-    # Get an instance of a resource
-    # @api public
-    # @param id [String] ID of the instance to find
-    # @return [APIResource] resource instance
-    # @example
-    #   id = '...'
-    #   district = Clever::District.retrieve id
-    def self.retrieve(id, auth_token = nil)
-      instance = new id, auth_token
-      instance.refresh
-      instance
-    end
-
-    # Get the URI for a hypermedia link
-    # @api private
-    # @return [String]
-    def get_link_uri(resource_type)
-      refresh if links.nil?
-      links[resource_type.to_sym]
-    end
-
-    # Construct an APIResource. Generates methods for nested resources
-    # @abstract
-    # @api private
-    # @return [APIResource]
-    def initialize(id, auth_token = nil)
-      super id, auth_token
-      return if self.class.linked_resources.nil?
-
-      self.class.linked_resources.each do |resource|
-        if APIResource.singular? resource.to_s
-          # Get single resource
-          self.class.send :define_method, resource do
-            response = Clever.request :get, get_link_uri(resource), {}, headers
-            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, headers
-          end
-        end
-      end
-    end
-  end
-end