lusi_api 0.1.11

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da1c5f2df15cb658a48d858532d3189d951e7141
+  data.tar.gz: 2e7dfb970b80eeb666c169f72fa563776f21683c
+SHA512:
+  metadata.gz: cfbb149d9f00d6c8e1b7d8c4b6a0fafaaca45346ad007113a0ad795ab48215461959d26dcc2618ce940a6a6c277421cc4378ca539e1e86d514e312d065388e4f
+  data.tar.gz: 64a05269d80fe562a4eba9b51b917da2eb63697f0af0021a64b16d84eb42454756f0380e67c43dd72d7cf967233d1116a4213bdf2699bdd7bdfd8b5612ecce59

data/.gitignore

@@ -0,0 +1,58 @@
+# IntelliJ files
+.idea/
+*.iml
+*.iws
+
+# Created by https://www.gitignore.io/api/ruby
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in lusi_api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 lbaajh
+
+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/README.md

@@ -0,0 +1,235 @@
+# LusiApi
+
+A Ruby client for Lancaster University's LUSI API for student record management.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lusi_api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lusi_api
+
+## Usage
+
+### Basic usage
+
+Create an API instance with your LUSI account credentials:
+
+```ruby
+require 'lusi_api'
+
+api = LUSI::API::Core::API.new(api_user: 'Your LUSI username', api_password: 'Your LUSI password')
+```
+
+Then pass this as the first argumnent of the ```get_instance``` factory methods of the API data classes.
+
+### Common classes
+
+All LUSI API classes are subclasses of ```LUSI::API::Core::Object.```
+
+Entities with identity are subclasses of ```LUSI::API::Core::ObjectWithID.``` Instances use the LUSI ID for equality and
+hashing.
+
+Properties consisting of an id/name pair are instances of ```LUSI::API::Core::Code.```
+
+### Lookup
+
+The LUSI web API frequently provides codes to represent linked or embedded objects (for example, the department a
+student is affiliated with). To assist with resolving codes to objects, the LUSI API provides the
+```LUSI::API::Core::Lookup``` module.
+
+#### LookupTable
+
+The ```LUSI::API::Core::Lookup::LookupTable``` class extends Ruby's ```Hash``` so that failed key lookups trigger an
+attempt to read the value from an external data source by calling the ```get_value(key)``` method.
+
+Subclasses implement ```get_value``` to perform the key lookup in the data source. If the lookup succeeds, the
+corresponding value should be returned. If it fails, ```LUSI::API::Core::Lookup::LookupError``` should be raised.
+
+If ```get_value``` returns a value, this value is added to the lookup table hash and returned as the result of the 
+lookup. If ```LookupError``` is raised, the usual ```Hash``` handling of a failed lookup is invoked (default value or
+code block).
+
+#### LUSILookupTable
+
+The ```LUSI::API::Core::Lookup::LUSILookupTable``` class extends ```LookupTable``` to retrieve data from the LUSI web
+API when a key lookup fails.
+
+```ruby
+require 'lusi_api/core/lookup'
+
+# The API class of the objects to be added to the lookup table
+result_class = LUSI::API::Core::Code
+
+# Positional arguments to the result class' get_instance method
+args = ['arg1', 'arg2']
+
+# Keyword arguments to the result class' get_instance method
+kwargs = { arg1: 'value1', arg2: 'value2' }
+
+# The parameter of the result_class' get_instance method used as the search condition
+param = 'identity'
+
+# The attribute of the result_class instance supplying the key value
+# This may be a String or Symbol (the name of the attribute) or a Proc (accepting the result_class instance as its
+# single argument and returning the key value). If not specified, the result_class instance is expected to have an
+# attribute named 'identity' which supplies the key value.
+# NameError is raised if the attribute lookup fails.
+key_attribute = 'object_id'
+
+begin
+  lookup = LUSI::API::Core::Lookup::LUSILookupTable(api, result_class, *args,
+                                                    key_attribute: key_attribute,
+                                                    param: param,
+                                                    **kwargs)
+rescue NameError
+  # The key attribute lookup failed
+end 
+```
+
+Some lookup tables (for example, academic weeks, countries) can be populated from a single call to the LUSI web API.
+```LUSILookupTable``` provides the ```load``` method to support this.
+
+A lookup table which supports bulk loading should include the constructor parameter ```loadable: true``` and may
+specify an optional hash of default parameter values for the ```load``` method:
+ 
+```ruby
+begin
+  lookup = LUSI::API::Core::Lookup::LUSILookupTable(api, result_class, ...,
+                                                    loadable: true,
+                                                    load_params: {})
+end
+```
+  
+ 
+### Exceptions
+
+All exceptions thrown by the LUSI API are subclasses of ```LUSI::API::Core::APIError.```
+
+The exception hiearchy is:
+```
+ APIError
+     APICallError
+         APITimeoutError  
+     APIResponseError   
+         APIContentError
+         APIPermissionError
+```
+
+Methods which interact with the LUSI web API, such as the ```get_instance``` method of the data classes, should
+rescue at least ```LUSI::API::Core::APIError``` to handle network problems.
+
+```ruby
+begin
+  result = SomeClass.get_instance(api)
+rescue LUSI::API::Core::APITimeoutError
+  # Subclass of APICallError 
+  # Raised when the LUSI API does not respond within the timeout period
+rescue LUSI::API::Core::APICallError
+  # Subclass of APIError
+  # Raised when there is a general problem with the LUSI API call (e.g. network error)
+rescue LUSI::API::Core::APIContentError
+  # Subclass of APIResponseError
+  # Raised when there is a problem parsing the XML response from the LUSI API
+rescue LUSI::API::Core::APIPermissionError
+  # Subclass of APIResponseError
+  # Raised when the LUSI account does not have permission to call the requested API method
+rescue LUSI::API::Core::APIError
+  # Raised when any other problem occurs
+end
+```
+
+### Calendar module
+
+The ```LUSI::API::Calendar``` module provides the classes ```Week``` and ```Year``` to represent LUSI academic week and
+year objects. Both classes extend ```LUSI::API::Core::Code.```
+
+#### Year
+
+Years in LUSI are objects with an 6-digit zero-padded identity code derived from the year: 000nnn
+where nnn = year - 1900.
+
+e.g. 2016 = 2016 - 1900 = 000116
+  
+```ruby
+require 'lusi_api/calendar'
+
+# Get an array of all years in LUSI
+all_years = LUSI::API::Calendar::Year.get_instance(api, lookup)
+year_2016 = all_years.select { |year| year.identity == '000116' }
+
+# Year properties
+puts <<EOF
+  Identity: #{year_2016.identity}
+  Description: #{year_2016.description}
+  Full year description: #{year_2016.full_year}
+EOF
+```
+
+#### Week
+
+```ruby
+require 'lusi_api/calendar'
+
+# Get an array of all weeks in LUSI
+all_weeks = LUSI::API::Calendar::Week.get_instance(api, lookup)
+
+# Get an array of all weeks for a specific year
+# year may be a year identity string or a LUSI::API::Calendar::Year instance
+year_weeks = LUSI::API::Calendar::Week.get_instance(api, lookup, year_identity: '000116')
+
+# Get the current academic week
+current_week = LUSI::API::Calendar::Week.current_academic_week(api)
+
+# Week properties
+# - monday_date is an instance of DateTime
+# - year is an instance of LUSI::API::Calendar::Year
+puts <<EOF
+  Identity: #{current_week.identity}
+  Description: #{current_week.description}
+  Academic timetable week ID: #{current_week.att_identity}
+  Monday date: #{current_week.monday_date}
+  Term: #{current_week.term}
+  Year: #{current_week.year}
+EOF
+```
+
+
+### Country module
+
+### Course module
+
+### Enrolment module
+
+### Organisation module
+
+### Person module
+
+### Service account module
+
+### Service method module
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lusi_api.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+task :default => :spec
+
+# YARD::Rake::YardocTask.new do |t|
+#   t.files   = ['lib/**/*.rb']   # optional
+#   t.options = ['--any', '--extra', '--opts', '--private', '--protected'] # optional
+#   t.stats_options = ['--list-undoc']         # optional
+# end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "lusi_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/lusi_api.rb

@@ -0,0 +1,5 @@
+module LUSI
+  module API
+
+  end
+end

data/lib/lusi_api/calendar.rb

@@ -0,0 +1,234 @@
+require 'lusi_api/core/code'
+require 'lusi_api/core/util'
+require 'lusi_api/core/xml'
+
+
+module LUSI
+  module API
+    module Calendar
+
+
+      # Represents an academic week in the LUSI API
+      class Week < LUSI::API::Core::Code
+
+        # @!attribute [rw] att_identity
+        #   @return [Integer, nil] the academic timetable (ATT) week identity
+        attr_accessor :att_identity
+
+        # @!attribute [rw] monday_date
+        #   @return [DateTime, nil] the Monday starting the week
+        attr_accessor :monday_date
+
+        # @!attribute [rw] term
+        #   @return [String, nil] The term/period the week is in
+        attr_accessor :term
+
+        # @!attribute [rw] year
+        #   @return [LUSI::API::Calendar::Year, nil] the academic year containing the week
+        attr_accessor :year
+
+        # Returns a Week instance for the current academic week
+        # @param api [LUSI::API::Core::API] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @return [LUSI::API::Calendar::Week] the current academic week
+        # @yield [obj] Passes the Week instance to the block
+        # @yieldparam obj [LUSI::API::Calendar::Week] the Week instance
+        def self.get_current_academic_week(api = nil, lookup = nil)
+          xml = api.call('LUSIReference', 'General.asmx', 'GetCurrentAcademicWeek')
+          obj = new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Week'), lookup)
+          yield(obj) if block_given?
+          obj
+        end
+
+        # Returns Week instances for all or one specific academic year
+        # @param api [LUSI::API::Core::API] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @param use_lookup [Boolean] if true, use the lookup service to identify instances before trying the API
+        # @param year [LUSI::API::Calendar::Year, String, nil] the academic year required (all defined weeks if nil)
+        # @return [Array<LUSI::API::Calendar::Week>] the selected acadmic weeks
+        # @yield [obj] Passes the Week instance to the block
+        # @yieldparam obj [LUSI::API::Calendar::Week] the Week instance
+        def self.get_instance(api = nil, lookup = nil, use_lookup: true, year_identity: nil)
+          # Search the lookup service
+          if lookup and use_lookup
+            week = lookup.lookup(:week, year_identity)
+            if week
+              yield(week) if block_given?
+              return week
+            end
+          end
+          # Search the API
+          super(api, lookup, 'LUSIReference', 'General.asmx', 'GetWeeks', 'xmlns:Week', year_identity: year_identity)
+        end
+
+        # Initialises a new Week instance
+        # @param (see LUSI::API::Core::Code#initialize)
+        # @param att_identity [Integer, nil] the default academic timetable (ATT) identity
+        # @param monday_date [DateTime, nil] the default Monday week-start date
+        # @param term [String, nil] the default term
+        # @param year [LUSI::API::Calendar::Year, nil] the default academic year
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, term: nil, monday_date: nil, year: nil, att_identity: nil, **kwargs)
+          super(xml, lookup, **kwargs)
+          @att_identity = LUSI::API::Core::XML.xml_int_at(xml, 'xmlns:ATTIdentity', att_identity)
+          @monday_date = LUSI::API::Core::XML.xml_datetime_at(xml, 'xmlns:MondayDate', monday_date)
+          @term = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:Term', term)
+          @year = LUSI::API::Core::XML.lookup(xml, lookup, :year, 'xmlns:Year/xmlns:Identity', year)
+        end
+
+        protected
+
+        def self.get_instance_params(**kwargs)
+          year = kwargs[:year_identity] || ''
+          year = year.identity if year.is_a?(Year)
+          params = super(**kwargs)
+          params[:YearIdentity] = year || ''
+          params
+        end
+
+      end
+
+
+      # Represents an academic year in the LUSI API
+      class Year < LUSI::API::Core::Code
+
+        extend LUSI::API::Core::Util
+
+        # @!attribute [rw] full_year
+        #   @return [String, nil] the full text description of the academic year
+        attr_accessor :full_year
+
+        # @!attribute [rw] lookup
+        #   @return [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        attr_accessor :lookup
+
+        # Returns a Year instance for the current academic year
+        # @param api [LUSI::API::Core::API] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # @return [LUSI::API::Calendar::Year] the current academic year
+        # @yield [obj] Passes the Year instance to the block
+        # @yieldparam obj [LUSI::API::Calendar::Year] the Year instance
+        def self.get_current_academic_year(api = nil, lookup = nil)
+          xml = api.call('LUSIReference', 'General.asmx', 'GetCurrentAcademicYear')
+          obj = new(LUSI::API::Core::XML.xml_at(xml, 'xmlns:Year'), lookup)
+          yield(obj) if block_given?
+          obj
+        end
+
+        # Returns selected or all defined year instances
+        # @param api [LUSI::API::Core::API] the LUSI API instance
+        # @param lookup [LUSI::API::Core::Lookup::LookupService, nil] the lookup service for object resolution
+        # Remaining positional parameters are years or year identities of the required years
+        # @param use_lookup [Boolean] if true, use the lookup service to identify instances before trying the API
+        # @return [Array<LUSI::API::Calendar::Year>, nil] the defined year instances
+        # @yield [obj] Passes the Year instance to the block
+        # @yieldparam obj [LUSI::API::Calendar::Year] the Year instance
+        def self.get_instance(api = nil, lookup = nil, *years, use_lookup: true, **kwargs)
+          results = nil
+          # Search the lookup service if required
+          if lookup && use_lookup
+            year_lookup = lookup.service(:year)
+            results = year_lookup.values if year_lookup
+          end
+          # Search the API if required
+          results = super(api, lookup, 'LUSIReference', 'General.asmx', 'GetYears', 'xmlns:Year') if results.nil?
+          # Return the results
+          if results.nil? || years.nil? || years.empty?
+            # No results or no filtering required
+            results
+          else
+            # Return the year instances for the specified years
+            years = years.map { |year| lusi_year_identity(year) }
+            results.select { |result| years.include?(result.identity) }
+          end
+        end
+
+        # Initialises a new Year instance
+        # @param (see LUSI::API::Core::Code#initialize)
+        # @param full_year [String, nil] the full text description of the academic year
+        # @return [void]
+        def initialize(xml = nil, lookup = nil, full_year: nil, **kwargs)
+          super(xml, lookup, **kwargs)
+          self.full_year = LUSI::API::Core::XML.xml_content_at(xml, 'xmlns:FullYear', full_year)
+          # Store the lookup service for year arithmetic operations
+          self.lookup = lookup
+        end
+
+        # Returns the year instance n years after this one
+        # @param years [Integer] the number of years to add to the instance's year
+        # @return [LUSI::API::Calendar::Year] the year instance
+        def +(years = 0)
+          self.offset(years)
+        end
+
+        # Returns the year instance n years before this one
+        # @param years [Integer] the number of years to subtract from the instance's year
+        # @return [LUSI::API::Calendar::Year] the year instance
+        def -(years = 0)
+          self.offset(-years)
+        end
+
+        # Returns the year instance immediately following this one
+        # @return [LUSI::API::Calendar::Year] the year instance
+        def next(count = 1)
+          count = count.to_i
+          if count == 1
+            self.offset(1)
+          else
+            result = []
+            (1..count).each { |offset| result.push(self.offset(offset)) }
+            result
+          end
+        end
+
+        # Returns the year instance n years after/before this one
+        # @param years [Integer] the number of years to add to the instance's year
+        # @return [LUSI::API::Calendar::Year] the year instance
+        def offset(years = 0)
+          return self if years == 0
+          year = self.class.lusi_year(self, self.lookup, as_instance: true, offset: years)
+        end
+
+        # Returns the year instance immediately preceding this one
+        # @return [LUSI::API::Calendar::Year] the year instance
+        def previous(count = 1)
+          count = count.to_i
+          if count == 1
+            self.offset(-1)
+          else
+            result = []
+            (1..count).each { |offset| result.push(self.offset(-offset)) }
+            result
+          end
+        end
+
+        # Returns a list of year instances around (immediately preceding and following) this one
+        # @param from [Integer, Range] the starting offset relative to the current year
+        # @param to [Integer] the ending offset relative to the current year
+        # @return [Array<LUSI::API::Calendar::Year>] the year instances
+        def range(from = nil, to = nil)
+          from = (from..to) unless from.is_a?(Range)
+          result = []
+          from.each { |offset| result.push(self.offset(offset)) }
+          result
+        end
+
+        # Returns a string representation of the Year instance
+        # @return [String] the string representation of the Year instance
+        def to_s
+          self.full_year
+        end
+
+        protected
+
+        # Returns an empty parameter hash for the LUSI API call
+        def self.get_instance_params(**kwargs)
+          {}
+        end
+
+      end
+
+
+    end
+  end
+end