academic_benchmarks 0.0.8 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 22555b94fb0f906a0e7dcfa8b0d1ef53c5d0e2ba
-  data.tar.gz: 35b214fa68304abfee8dad1a398080de77ef2775
+SHA256:
+  metadata.gz: 50df986c030289fb9f248460b600eebc30b059c7386fa6c5cdeba4d39bbe714a
+  data.tar.gz: 4421c98acc7fbe617d2a8b1b3a8c9a4eb736d7ea65016c4ba5933a52b6f28d35
 SHA512:
-  metadata.gz: aacbcd26798eb35a8b6bad99bcf3ceb946d34a7690cf99adc3735617fa75845c9bc0084d9b71ea55dc42e0916400ed5644c20a3fc3bbf62d377f52ef73d935c7
-  data.tar.gz: 71662373e163044b7afa10977d7e71b9956c3e6be76d60e96c7d493e2e4dc70dd2f611bb33b2c68af88c0818faaf7189e2f260f3f91584cee660add9866728f7
+  metadata.gz: 6f777d12e41775ac0cac11b9a76922b5b10c2957e480f16c0a5ff3c61328b92abfa409389cc6e116d4d41503c8821fce2cb99e0d401bdee09ce2daea2561ab8a
+  data.tar.gz: cf26bcd052ff8b71be7a360ba095580f3c6993dfd235d39e57a378a846bffbfc50790654c285a829e943c638a6f069492211c4c6fe1ec3f91a2e5cc93e040970

data/lib/academic_benchmarks/api/auth.rb

@@ -8,10 +8,12 @@ module AcademicBenchmarks
           "partner.id" => partner_id,
           "auth.signature" => signature_for(
             partner_key: partner_key,
-            message: self.message(expires: expires, user_id: user_id)),
-          "auth.expires" => expires,
-          "user.id" => user_id
-        }
+            message: self.message(expires: expires, user_id: user_id)
+          ),
+          "auth.expires" => expires
+        }.tap do |params|
+          params["user.id"] = user_id unless user_id.empty?
+        end
       end
 
       def self.signature_for(partner_key:, message:)
@@ -39,7 +41,7 @@ module AcademicBenchmarks
       end
 
       def self.expire_time_in(offset)
-        Time.now.to_i + offset
+        Time.now.to_i + offset.to_i
       end
     end
   end

data/lib/academic_benchmarks/api/constants.rb

@@ -2,11 +2,11 @@ module AcademicBenchmarks
   module Api
     module Constants
       def self.base_url
-        'https://api.academicbenchmarks.com/rest/v3'
+        'https://api.abconnect.certicaconnect.com/rest/v4.1'
       end
 
       def self.api_version
-        '3'
+        '4.1'
       end
 
       def self.partner_id_env_var
@@ -20,24 +20,6 @@ module AcademicBenchmarks
       def self.user_id_env_var
         'ACADEMIC_BENCHMARKS_USER_ID'
       end
-
-      def self.standards_search_params
-        %w[
-          query
-          authority
-          subject
-          grade
-          subject_doc
-          course
-          document
-          parent
-          deepest
-          limit
-          offset
-          list
-          fields
-        ]
-      end
     end
   end
 end

data/lib/academic_benchmarks/api/handle.rb

@@ -1,5 +1,5 @@
-require_relative 'constants'
-require_relative 'standards'
+require 'academic_benchmarks/api/constants'
+require 'academic_benchmarks/api/standards'
 
 module AcademicBenchmarks
   module Api
@@ -44,30 +44,10 @@ module AcademicBenchmarks
         @user_id = user_id.to_s
       end
 
-      def related(guid:, fields: [])
-        raise StandardError.new("Sorry, not implemented yet!")
-      end
-
       def standards
         Standards.new(self)
       end
 
-      def assets
-        raise StandardError.new("Sorry, not implemented yet!")
-      end
-
-      def alignments
-        raise StandardError.new("Sorry, not implemented yet!")
-      end
-
-      def topics
-        raise StandardError.new("Sorry, not implemented yet!")
-      end
-
-      def special
-        raise StandardError.new("Sorry, not implemented yet!")
-      end
-
       private
 
       def api_resp_to_array_of_standards(api_resp)

data/lib/academic_benchmarks/api/standards.rb

@@ -1,99 +1,81 @@
 require 'active_support/hash_with_indifferent_access'
 
-require_relative 'auth'
-require_relative 'constants'
+require 'academic_benchmarks/api/auth'
+require 'academic_benchmarks/api/constants'
 
 module AcademicBenchmarks
   module Api
     class Standards
       DEFAULT_PER_PAGE = 100
 
+      STANDARDS_FIELDS = %w[
+        guid
+        education_levels.grades.code
+        label
+        level
+        section.guid
+        section.descr
+        number.raw
+        number.enhanced
+        status
+        disciplines.subjects.code
+        document.guid
+        document.descr
+        document.adopt_year
+        document.publication.descr
+        document.publication.guid
+        document.publication.authorities
+        statement.descr
+        utilizations.type
+        parent
+      ]
+
       def initialize(handle)
         @handle = handle
       end
 
-      def search(opts = {})
-        # query: "", authority: "", subject: "", grade: "", subject_doc: "", course: "",
-        # document: "", parent: "", deepest: "", limit: -1, offset: -1, list: "", fields: []
-        invalid_params = invalid_search_params(opts)
-        if invalid_params.empty?
-          raw_search(opts).map do |standard|
-            AcademicBenchmarks::Standards::Standard.new(standard)
-          end
-        else
-          raise ArgumentError.new(
-            "Invalid search params: #{invalid_params.join(', ')}"
-          )
-        end
-      end
-
-      alias_method :where, :search
-
-      def guid(guid, fields: [])
-        query_params = if fields.empty?
-                         auth_query_params
-                       else
-                         auth_query_params.merge({
-                           fields: fields.join(",")
-                         })
-                       end
-        @handle.class.get(
-          "/standards/#{guid}",
-          query: query_params
-        ).parsed_response["resources"].map do |r|
-          AcademicBenchmarks::Standards::Standard.new(r["data"])
+      # TODO: in the future, support OData filtering for flexible querying
+      def search(authority_guid: nil, publication_guid: nil)
+        raw_search(authority: authority_guid, publication: publication_guid).map do |standard|
+          AcademicBenchmarks::Standards::Standard.new(standard)
         end
       end
 
-      def all
-        request_search_pages_and_concat_resources(auth_query_params)
-      end
-
-      def authorities(query_params = {})
-        raw_search({list: "authority"}.merge(query_params)).map do |a|
-          AcademicBenchmarks::Standards::Authority.from_hash(a["data"]["authority"])
+      def authorities
+        raw_facet("document.publication.authorities").map do |a|
+          AcademicBenchmarks::Standards::Authority.from_hash(a["data"])
         end
       end
 
-      def documents(query_params = {})
-        raw_search({list: "document"}.merge(query_params)).map do |a|
-          AcademicBenchmarks::Standards::Document.from_hash(a["data"]["document"])
+      def publications(authority_guid: nil)
+        raw_facet("document.publication", authority: authority_guid).map do |a|
+          AcademicBenchmarks::Standards::Publication.from_hash(a["data"])
         end
       end
 
-      def authority_documents(authority_or_auth_code_guid_or_desc)
+      def authority_publications(authority_or_auth_code_guid_or_desc)
         authority = auth_from_code_guid_or_desc(authority_or_auth_code_guid_or_desc)
-        documents(authority: authority.code)
+        publications(authority_guid: authority.guid)
       end
 
-      def authority_tree(authority_or_auth_code_guid_or_desc, include_obsolete_standards: true)
+      def authority_tree(authority_or_auth_code_guid_or_desc, include_obsolete_standards: true, exclude_examples: false)
         authority = auth_from_code_guid_or_desc(authority_or_auth_code_guid_or_desc)
-        auth_children = search(authority: authority.code)
+        auth_children = raw_search(authority: authority.guid, include_obsoletes: include_obsolete_standards, exclude_examples: exclude_examples)
         AcademicBenchmarks::Standards::StandardsForest.new(
-          auth_children,
-          include_obsoletes: include_obsolete_standards
+          auth_children
         ).consolidate_under_root(authority)
       end
 
-      def document_tree(document_or_guid, include_obsolete_standards: true)
-        document = doc_from_guid(document_or_guid)
-        doc_children = search(document: document.guid)
+      def publication_tree(publication_or_pub_code_guid_or_desc, include_obsolete_standards: true, exclude_examples: false)
+        publication = pub_from_guid(publication_or_pub_code_guid_or_desc)
+        pub_children = raw_search(publication: publication.guid, include_obsoletes: include_obsolete_standards, exclude_examples: exclude_examples)
         AcademicBenchmarks::Standards::StandardsForest.new(
-          doc_children,
-          include_obsoletes: include_obsolete_standards
-        ).consolidate_under_root(document)
+          pub_children
+        ).consolidate_under_root(publication)
       end
 
       private
 
-      def doc_from_guid(document_or_guid)
-        if document_or_guid.is_a?(AcademicBenchmarks::Standards::Document)
-          document_or_guid
-        else
-          find_type(type: "document", data: document_or_guid)
-        end
-      end
-
       def auth_from_code_guid_or_desc(authority_or_auth_code_guid_or_desc)
         if authority_or_auth_code_guid_or_desc.is_a?(AcademicBenchmarks::Standards::Authority)
           authority_or_auth_code_guid_or_desc
@@ -102,6 +84,14 @@ module AcademicBenchmarks
         end
       end
 
+      def pub_from_guid(publication_or_pub_code_guid_or_desc)
+        if publication_or_pub_code_guid_or_desc.is_a?(AcademicBenchmarks::Standards::Publication)
+          publication_or_pub_code_guid_or_desc
+        else
+          find_type(type: "publication", data: publication_or_pub_code_guid_or_desc)
+        end
+      end
+
       def find_type(type:, data:)
         matches = send("match_#{type}", data)
         if matches.empty?
@@ -110,7 +100,7 @@ module AcademicBenchmarks
           )
         elsif matches.count > 1
           raise StandardError.new(
-            "Authority code, guid, or description matched more than one authority.  " \
+            "#{type.upcase} code, guid, or description matched more than one #{type}.  " \
             "matched '#{matches.map(&:to_json).join('; ')}'"
           )
         end
@@ -119,22 +109,26 @@ module AcademicBenchmarks
 
       def match_authority(data)
         authorities.select do |auth|
-          auth.code  == data ||
+          auth.acronym  == data ||
           auth.guid  == data ||
           auth.descr == data
         end
       end
 
-      def match_document(data)
-        documents.select { |doc| doc.guid == data }
+      def match_publication(data)
+        publications.select do |pub|
+          pub.acronym == data ||
+          pub.guid == data ||
+          pub.descr == data
+        end
       end
 
-      def raw_search(opts = {})
-        request_search_pages_and_concat_resources(opts.merge(auth_query_params))
+      def raw_facet(facet, query_params = {})
+        request_facet({facet: facet}.merge(query_params).merge(auth_query_params))
       end
 
-      def invalid_search_params(opts)
-        opts.keys.map(&:to_s) - AcademicBenchmarks::Api::Constants.standards_search_params
+      def raw_search(opts = {})
+        request_search_pages_and_concat_resources(opts.merge(auth_query_params))
       end
 
       def auth_query_params
@@ -146,7 +140,49 @@ module AcademicBenchmarks
         )
       end
 
+      def odata_filters(query_params)
+        if query_params.key? :authority
+          value = query_params.delete :authority
+          query_params['filter[standards]'] = "document.publication.authorities.guid eq '#{value}'" if value
+        end
+        if query_params.key? :publication
+          value = query_params.delete :publication
+          query_params['filter[standards]'] = "document.publication.guid eq '#{value}'" if value
+        end
+
+        if query_params.key? :include_obsoletes
+          unless query_params.delete :include_obsoletes
+            if query_params.key? 'filter[standards]'
+              query_params['filter[standards]'] += " and status eq 'active'"
+            else
+              query_params['filter[standards]'] = "status eq 'active'"
+            end
+          end
+        end
+
+        if query_params.delete :exclude_examples
+          if query_params.key? 'filter[standards]'
+            query_params['filter[standards]'] += " and utilizations.type not eq 'example'"
+          else
+            query_params['filter[standards]'] = "utilizations.type not eq 'example'"
+          end
+        end
+      end
+
+      def request_facet(query_params)
+        odata_filters query_params
+        page = request_page(
+          query_params: query_params,
+          limit: 0, # return no standards since facets are separate
+          offset: 0
+        ).parsed_response
+
+        page.dig("meta", "facets", 0, "details")
+      end
+
       def request_search_pages_and_concat_resources(query_params)
+        query_params['fields[standards]'] = STANDARDS_FIELDS.join(',')
+        odata_filters query_params
         query_params.reverse_merge!({limit: DEFAULT_PER_PAGE})
 
         if !query_params[:limit] || query_params[:limit] <= 0
@@ -161,10 +197,9 @@ module AcademicBenchmarks
           offset: 0
         ).parsed_response
 
-        resources = first_page["resources"]
-        count = first_page["count"]
+        resources = first_page["data"]
+        count = first_page["meta"]["count"]
         offset = query_params[:limit]
-
         while offset < count
           page = request_page(
             query_params: query_params,
@@ -172,7 +207,7 @@ module AcademicBenchmarks
             offset: offset
           )
           offset += query_params[:limit]
-          resources.push(page.parsed_response["resources"])
+          resources.push(page.parsed_response["data"])
         end
 
         resources.flatten
@@ -183,19 +218,29 @@ module AcademicBenchmarks
           limit: limit,
           offset: offset,
         })
-        resp = @handle.class.get(
-          '/standards',
-          query: query_params.merge({
-            limit: limit,
-            offset: offset,
-          })
-        )
-        if resp.code != 200
-          raise RuntimeError.new(
-            "Received response '#{resp.code}: #{resp.message}' requesting standards from Academic Benchmarks:"
+        1.times do
+          resp = @handle.class.get(
+            '/standards',
+            query: query_params.merge({
+              limit: limit,
+              offset: offset,
+            })
           )
+          if resp.code == 429
+            sleep retry_after(resp)
+            redo
+          end
+          if resp.code != 200
+            raise RuntimeError.new(
+              "Received response '#{resp.code}: #{resp.message}' requesting standards from Academic Benchmarks:"
+            )
+          end
+          return resp
         end
-        resp
+      end
+
+      def retry_after(response)
+        ENV['ACADEMIC_BENCHMARKS_TOO_MANY_REQUESTS_RETRY']&.to_f || 5
       end
     end
   end

data/lib/academic_benchmarks/lib/attr_to_vals.rb

@@ -0,0 +1,7 @@
+module AttrToVals
+  def attr_to_vals(klass, arr)
+    return [] if arr.nil?
+
+    arr.map {|v| klass.from_hash(v)}
+  end
+end

data/lib/academic_benchmarks/lib/inst_vars_to_hash.rb

@@ -19,6 +19,8 @@ module InstVarsToHash
   def to_h(omit_parent: true, omit_empty_children: true)
     retval = {}
     instance_variables.each do |iv|
+      # Don't hashify these attributes, otherwise it can lead to infinite recursion
+      next if %w[@authority @document @publication @section].include? iv.to_s
       if !(skip_parent?(omit_parent, iv) || skip_children?(omit_empty_children, iv))
         retval[iv.to_s.delete('@').to_sym] = elem_to_h(instance_variable_get(iv))
       end

data/lib/academic_benchmarks/standards/authority.rb

@@ -1,30 +1,56 @@
-require_relative '../lib/inst_vars_to_hash'
-require_relative '../lib/remove_obsolete_children'
+require 'academic_benchmarks/lib/inst_vars_to_hash'
 
 module AcademicBenchmarks
   module Standards
     class Authority
       include InstVarsToHash
-      include RemoveObsoleteChildren
 
-      attr_accessor :code, :guid, :description, :children
+      attr_accessor :acronym, :descr, :guid, :children
 
-      alias_method :descr, :description
+      alias_method :code, :acronym
+      alias_method :description, :descr
 
       def self.from_hash(hash)
         self.new(
-          code: hash["code"],
+          acronym: hash["acronym"],
           guid: hash["guid"],
-          description: (hash["descr"] || hash["description"])
+          descr: hash["descr"]
         )
       end
 
-      def initialize(code:, guid:, description:, children: [])
-        @code = code
+      def initialize(acronym:, guid:, descr:, children: [])
+        @acronym = acronym
         @guid = guid
-        @description = description
+        @descr = descr
         @children = children
       end
+
+      # Children are standards, so rebranch them so we have
+      # the following structure:
+      #
+      #   Authority -> Publication -> Document -> Section -> Standard
+      def rebranch_children
+        @seen = Set.new()
+        @guid_to_obj = {}
+        new_children = []
+        @children.each do |child|
+          pub = reparent(child.document.publication, new_children)
+          doc = reparent(child.document, pub.children)
+          sec = reparent(child.section, doc.children)
+          sec.children.push(child)
+        end
+        @children.replace(new_children)
+        remove_instance_variable('@seen')
+        remove_instance_variable('@guid_to_obj')
+      end
+
+      private
+
+      def reparent(object, children)
+        cached_object = (@guid_to_obj[object.guid] ||= object)
+        children.push(cached_object) if @seen.add? cached_object.guid
+        cached_object
+      end
     end
   end
 end