kosapi_client 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 46750e332cf19232187a8a9e5c66b9fa128e246a
+  data.tar.gz: 8d9a60a7399406d633ddb03bbadd51bc151b8372
+SHA512:
+  metadata.gz: 424aeb28f513261f67bdb98783d22fcf6dbc536f80f652386c9d666b5a9d437e49c92951d4bce03c71dd9ddeb8c518a2f1c23e760eba260a6fce530f1a3c03d7
+  data.tar.gz: 8b55b7666492503cf2d382475b4dead2d3f4dc0a9e4aff95df143339e9c3e5613a582a6d77555c1c3d261406baa4880142e2d29ec68a410477902474335e23fe

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dotenv"
+require "kosapi_client"
+
+Dotenv.load
+
+KOSapiClient.configure do |c|
+  c.client_id = ENV['KOSAPI_OAUTH_CLIENT_ID']
+  c.client_secret = ENV['KOSAPI_OAUTH_CLIENT_SECRET']
+end
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+echo "You will need OAuth credentials to access KOSapi and run integration tests."
+echo "Register new project at https://auth.fit.cvut.cz/manager/ with readonly access to KOSapi
+and enter client ID and secret for your default service account."
+
+echo -n "Client ID (KOSAPI_OAUTH_CLIENT_ID): "
+read client_id
+echo -n "Client secret (KOSAPI_OAUTH_CLIENT_SECRET): "
+read client_secret
+
+script_path=$(cd `dirname "${BASH_SOURCE[0]}"` && pwd)
+env_file=$(realpath "$script_path/../.env")
+echo "Writing credentials to $env_file"
+cat << EOF > "$env_file"
+KOSAPI_OAUTH_CLIENT_ID=$client_id
+KOSAPI_OAUTH_CLIENT_SECRET=$client_secret
+EOF
+
+echo "Running bundle install"
+bundle install

data/lib/kosapi_client.rb

@@ -0,0 +1,22 @@
+require 'corefines'
+require 'uri_template'
+require 'escape_utils'
+
+require 'kosapi_client/entity'
+require 'kosapi_client/resource'
+
+require 'kosapi_client/response_links'
+require 'kosapi_client/configuration'
+require 'kosapi_client/url_builder'
+require 'kosapi_client/request_builder'
+require 'kosapi_client/request_builder_delegator'
+require 'kosapi_client/resource_mapper'
+require 'kosapi_client/kosapi_client'
+require 'kosapi_client/api_client'
+require 'kosapi_client/hash_utils'
+require 'kosapi_client/http_client'
+require 'kosapi_client/kosapi_response'
+require 'kosapi_client/response_preprocessor'
+require 'kosapi_client/oauth2_http_adapter'
+require 'kosapi_client/response_converter'
+require 'kosapi_client/version'

data/lib/kosapi_client/api_client.rb

@@ -0,0 +1,43 @@
+using Corefines::String::camelcase
+
+module KOSapiClient
+
+  class ApiClient
+    include ResourceMapper
+
+    # accessible resources definition
+    resource :courses
+    resource :course_events
+    resource :parallels
+    resource :exams
+    resource :teachers
+
+    attr_reader :http_client
+
+    ##
+    # Creates a new KOSapi client.
+    #
+    def initialize(config = Configuration.new)
+      http_adapter = OAuth2HttpAdapter.new(config.credentials, config.base_url)
+      @http_client = HTTPClient.new(http_adapter)
+    end
+
+    def create_builder(resource_name)
+      builder_name = "#{resource_name}_builder".camelcase(:upper).to_sym
+      builder_class = find_builder_class(builder_name)
+      builder_class.new(resource_name.to_s.camelcase(:lower), @http_client)
+    end
+
+    private
+    def find_builder_class(builder_name)
+      KOSapiClient::Resource.constants.each do |m|
+        constant = KOSapiClient::Resource.const_get(m)
+        if constant.is_a?(Class) && m == builder_name
+          return constant
+        end
+      end
+      RequestBuilder
+    end
+
+  end
+end

data/lib/kosapi_client/configuration.rb

@@ -0,0 +1,23 @@
+module KOSapiClient
+  class Configuration < Struct.new(:client_id, :client_secret, :base_url)
+
+    DEFAULT_OPTIONS = {
+      base_url: 'https://kosapi.fit.cvut.cz/api/3'
+    }
+
+    def initialize(options = {})
+      DEFAULT_OPTIONS.merge(options).each do |option, value|
+        self[option] = value
+      end
+    end
+
+    def credentials
+      if client_id && client_secret
+        {client_id: client_id, client_secret: client_secret}
+      else
+        {}
+      end
+    end
+
+  end
+end

data/lib/kosapi_client/entity.rb

@@ -0,0 +1,19 @@
+require 'kosapi_client/entity/boolean'
+require 'kosapi_client/entity/link'
+require 'kosapi_client/entity/id'
+require 'kosapi_client/entity/author'
+require 'kosapi_client/entity/enum'
+require 'kosapi_client/entity/ml_string'
+require 'kosapi_client/entity/data_mappings'
+require 'kosapi_client/entity/base_entity'
+require 'kosapi_client/entity/result_page'
+require 'kosapi_client/entity/course_event'
+require 'kosapi_client/entity/course'
+require 'kosapi_client/entity/teacher_timetable_slot'
+require 'kosapi_client/entity/timetable_slot'
+require 'kosapi_client/entity/parallel'
+require 'kosapi_client/entity/base_person'
+require 'kosapi_client/entity/person'
+require 'kosapi_client/entity/teacher'
+require 'kosapi_client/entity/student'
+require 'kosapi_client/entity/exam'

data/lib/kosapi_client/entity/author.rb

@@ -0,0 +1,17 @@
+module KOSapiClient
+  module Entity
+    class Author
+
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def self.parse(contents)
+        new(contents[:atom_name])
+      end
+    end
+  end
+end
+

data/lib/kosapi_client/entity/base_entity.rb

@@ -0,0 +1,16 @@
+module KOSapiClient
+  module Entity
+    class BaseEntity
+
+      include DataMappings
+
+      map_data :id, String, namespace: :atom
+      map_data :title, String, namespace: :atom
+      map_data :updated, Time, namespace: :atom
+      map_data :link, Link, namespace: :atom
+      map_data :author, Author, namespace: :atom
+
+    end
+  end
+end
+

data/lib/kosapi_client/entity/base_person.rb

@@ -0,0 +1,20 @@
+module KOSapiClient
+  module Entity
+    class BasePerson < BaseEntity
+
+      map_data :first_name
+      map_data :last_name
+      map_data :personal_number, Integer
+      map_data :titles_post
+      map_data :titles_pre
+      map_data :username
+
+      def full_name
+        prefix = "#{titles_pre} " if titles_pre
+        suffix = " #{titles_post}" if titles_post
+        "#{prefix}#{first_name} #{last_name}#{suffix}"
+      end
+
+    end
+  end
+end

data/lib/kosapi_client/entity/boolean.rb

@@ -0,0 +1,14 @@
+module KOSapiClient
+  module Entity
+    class Boolean
+
+      def self.parse(str)
+        return true if str == 'true'
+        return false if str == 'false'
+        raise "Boolean parsing failed, invalid string: #{str}"
+      end
+
+    end
+  end
+end
+

data/lib/kosapi_client/entity/course.rb

@@ -0,0 +1,34 @@
+module KOSapiClient
+  module Entity
+    class Course < BaseEntity
+
+      map_data :allowed_enrollment_count, Integer
+      map_data :approval_date, Time
+      map_data :classes_lang, Enum
+      map_data :classes_type, [Enum]
+      map_data :code
+      map_data :completion, Enum
+      map_data :credits, Integer
+      map_data :department, Link
+      map_data :description, MLString
+      map_data :homepage
+      map_data :keywords, MLString
+      map_data :lectures_contents, MLString
+      map_data :literature, MLString
+      map_data :name, MLString
+      map_data :note, MLString
+      map_data :objectives, MLString
+      map_data :programme_type, Enum
+      map_data :range
+      map_data :requirements, MLString
+      map_data :season, Enum
+      map_data :state, Enum
+      map_data :study_form, Enum
+      map_data :superior_course, Link
+      map_data :subcourses, Link
+      map_data :tutorials_contents, MLString
+      map_data :instance #todo
+
+    end
+  end
+end

data/lib/kosapi_client/entity/course_event.rb

@@ -0,0 +1,20 @@
+module KOSapiClient
+  module Entity
+    class CourseEvent < BaseEntity
+
+      map_data :target_branch, [Link]
+      map_data :capacity, Integer
+      map_data :course, Link
+      map_data :creator, Link
+      map_data :end_date, Time
+      map_data :name, MLString
+      map_data :note, MLString
+      map_data :occupied, Integer
+      map_data :room, Link
+      map_data :semester, Link
+      map_data :signin_deadline, Time
+      map_data :start_date, Time
+
+    end
+  end
+end

data/lib/kosapi_client/entity/data_mappings.rb

@@ -0,0 +1,122 @@
+module KOSapiClient
+  module Entity
+    module DataMappings
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      def to_hash
+        result = {}
+        self.class.attr_mappings.each_key { |k| result[k] = convert_value(send(k)) }
+        result
+      end
+
+      private
+      def convert_value(val)
+        if val.respond_to? :to_hash
+          val.to_hash
+        elsif val.is_a?(Array)
+          val.map { |it| convert_value(it) }
+        else
+          val
+        end
+      end
+
+      module ClassMethods
+
+        def map_data(name, type=String, opts = {})
+          attr_accessor name
+          opts[:type] = type
+          @data_mappings ||= {}
+          @data_mappings[name] = opts
+        end
+
+        def attr_mappings
+          if self.superclass.respond_to? :attr_mappings
+            parent_mappings = self.superclass.attr_mappings
+          end
+          (parent_mappings || {}).merge(@data_mappings)
+        end
+
+        # Parses composed domain type from hash response structure.
+        #
+        # @param [Hash] content hash structure from API response corresponding to single domain object
+        # @return [BaseEntity] parsed domain object
+        def parse(content, context = {})
+          instance = new()
+          set_mapped_attributes(instance, content)
+          instance
+        end
+
+        # Creates new domain object instance and sets values
+        # of mapped domain object attributes from source hash.
+        # Attributes are mapped by .map_data method.
+        def set_mapped_attributes(instance, source_hash)
+          if self.superclass.respond_to? :set_mapped_attributes
+            self.superclass.set_mapped_attributes(instance, source_hash)
+          end
+          raise "Missing data mappings for entity #{self}" unless @data_mappings
+          @data_mappings.each do |name, options|
+            set_mapped_attribute(instance, name, source_hash, options)
+          end
+        end
+
+        private
+        def set_mapped_attribute(instance, name, source_hash, mapping_options)
+          namespace = mapping_options[:namespace]
+          src_element = mapping_options[:element] || name
+          if namespace
+            key = "#{namespace}_#{src_element}".to_sym
+          else
+            key = src_element
+          end
+          value = retrieve_value(source_hash, key, mapping_options)
+          if value.nil?
+            raise "Missing value for attribute #{name}" if mapping_options[:required]
+            if mapping_options[:type].is_a?(Array)
+              value = []
+            else
+              return
+            end
+          else
+            value = convert_type(value, mapping_options[:type])
+          end
+            instance.send("#{name}=".to_sym, value)
+        end
+
+        def convert_type(value, type)
+          return value.to_i if type == Integer
+          return value if type == String
+          return convert_array(value, type.first) if type.is_a?(Array)
+
+          return type.parse(value) if type.respond_to? :parse
+          raise "Unknown type #{type} to convert value #{value} to."
+        end
+
+        # Converts values of array type to proper domain objects.
+        # It checks whether the value is really an array, because
+        # when API returns a single value it does not get parsed
+        # into an array.
+        def convert_array(values, type)
+          if values.is_a?(Array)
+            values.map { |it| convert_type(it, type) }
+          else
+            [ convert_type(values, type) ]
+          end
+        end
+
+        def retrieve_value(source_hash, key, mapping_options)
+          path = mapping_options[:path]
+          if path
+            parent_element = source_hash[path]
+          else
+            parent_element = source_hash
+          end
+          parent_element[key] if parent_element
+        end
+
+      end
+    end
+  end
+end

data/lib/kosapi_client/entity/enum.rb

@@ -0,0 +1,11 @@
+module KOSapiClient
+  module Entity
+    class Enum
+
+      def self.parse(contents)
+        contents.downcase.to_sym
+      end
+
+    end
+  end
+end

data/lib/kosapi_client/entity/exam.rb

@@ -0,0 +1,25 @@
+module KOSapiClient
+  module Entity
+    class Exam < BaseEntity
+
+      map_data :cancel_deadline, Time
+      map_data :capacity, Integer
+      map_data :course, Link
+      map_data :department, Link
+      map_data :end_date, Time
+      map_data :examiner, Link
+      map_data :examiners, [Link], element: :teacher, path: :examiners
+      map_data :note
+      map_data :occupied, Integer
+      map_data :resit, Boolean
+      map_data :room, Link
+      map_data :semester, Link
+      map_data :signin_deadline, Date
+      map_data :start_date, Time
+      map_data :substitutes, Enum
+      map_data :superior, Link
+      map_data :term_type, Enum 
+
+    end
+  end
+end