pcr 0.5

data/.gitignore

@@ -0,0 +1,24 @@
+token.dat
+main.rb
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+instructors.txt
+examples.rb
+json_responses.txt
+
+*.swp

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 parm289
+
+MIT License
+
+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,160 @@
+# pcr-ruby: A Penn Course Review Ruby API Wrapper #
+
+pcr-ruby is a simple, intuitive way to retrieve course data from the Penn Course Review API in Ruby.  With pcr-ruby and a valid API token (which you can request [here](https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dGZOZkJDaVkxdmc5QURUejAteFdBZGc6MQ#gid=0)), your Ruby project has access to reviews, ratings, and other information for all Penn courses.
+
+## Installation ##
+
+pcr-ruby is a gem hosted on rubygems, so installation is as simple as:
+```
+gem install pcr-ruby
+```
+
+## How to use pcr-ruby #
+
+*This section may change a lot as pcr-ruby is developed.  As such, this section may not be fully accurate, but I will try to keep the instructions as current as possible.*
+
+pcr-ruby follows the structure of the PCR API, with a few name changes to make object identities and roles clearer in your code.  (Before using pcr-ruby, you should most definitely read the PCR API documentation, the link to which you should recieve upon being granted your API token.)
+
+The PCR API essentially consists of four types of objects: 'Courses', 'Sections', 'Instructors', and 'Course Histories'.  pcr-ruby aims to provide intuitive access to the data contained in these four object types while abstracting you and your user from background processing and unnecessary data.  To that end, pcr-ruby (thus far) consists of the same four types of objects: 'Course Histories', 'Courses', 'Sections', and 'Instructors' (coming soon).
+
+### CourseHistories in pcr-ruby ###
+Course Histories represent a course through time, and contain Course objects that represent the course offering in each semester.
+
+To create a Course History (the first step in getting PCR data):
+```ruby
+require 'pcr-ruby'
+pcr = PCR.new(API_TOKEN)
+course_history = pcr.coursehistory(COURSE_CODE)
+```
+
+All other attributes will auto-populate based on data from the PCR API.
+
+Course Histories have the following attributes:
+* **course_code** -- the course code entered by the user at initialization (String)
+* **courses** -- an array of Courses associated with the Course History (Array)
+* **id** -- the Course History's PCR API ID (String)
+* **path** -- the Course History's PCR API URL path (String)
+* **retrieved** -- the date the Course History was retreived (String)
+* **valid** -- true/false whether or not the query was valid (String)
+* **version** -- version of the PCR API hit (String)
+
+The most useful way to think about a Course History is as a collection of Course objects.
+
+Course Histories have the following instance methods:
+*	**average(metric)** -- returns the average value, across all Courses, of "metric" as a Float.  "Metric" must be a recognized rating in the PCR API.  (Currently the names of these ratings are not intuitive, so I may provide plain-English access to rating names in the future.)
+*	**recent(metric)** -- returns the most recent value of "metric" as a Float. (If there are multiple Sections offered in the most recent semester, the average across those Sections is returned.)  "Metric" must be a recognized rating in the PCR API.  (Currently the names of these ratings are not intuitive, so I may provide plain-English access to rating names in the future.)
+
+### 'Courses' in pcr-ruby ###
+
+Courses in the PCR API represent a collection of Sections of a course code during a given semester, and are treated similarly in pcr-ruby.
+
+Courses are accessed from within their "parent" Course History:
+```ruby
+require 'pcr-ruby'
+pcr = PCR.new(API_TOKEN)
+course_history = pcr.coursehistory(course_code)
+courses = course_history.courses
+earliest_course = courses.first
+most_recent_course = courses.last
+```
+
+pcr-ruby's Course objects have the following instance variables:
+* **aliases** -- an array of crosslistings (Array)
+* **credits** -- the number of credits awarded for the course (String)
+* **description** -- the PCR course description (String)
+* **history** -- the PCR API path to the course's history (String)
+* **id** -- the PCR API ID of the course (String)
+* **name** -- the plain-English name of the course, taken from the most recent Semester (String)
+* **path** -- the PCR API URL path of the course (String)
+* **reviews** -- a hash that usually contains one key, the path to the course's reviews (String) 
+* **sections** -- an array of Sections associated with the course (Array)
+* **semester** -- the semester in which the course was offered (String)
+* **retrieved** -- the date/time the course was retrieved (String)
+* **valid** -- true/false if valid/invalid request (String)
+* **version** -- PCR API version (String)
+
+The most useful way to think about Courses is as a collection of Section objects.
+
+### 'Sections' in pcr-ruby ###
+
+In pcr-ruby, Sections are single offerings of a Course.  Each Section is associated with a certain Course -- think of a Section as the individual classes under the umbrella of the Course.  Sections in the PCR API are treated similarly.
+
+To retrieve a Section:
+```ruby
+require 'pcr-ruby'
+pcr = PCR.new(API_TOKEN)
+course_history = pcr.coursehistory(course_code)
+recent_sections = course_history.courses.last.sections
+single_recent_section = recent_sections.first
+```
+
+Sections have the following instance variables:
+* **aliases** -- crosslistings of the Section (Array)
+* **course** -- a hash containing info of the parent course (Hash)
+* **group** -- 
+* **id** -- the PCR API ID of the section (String)
+* **instructors** -- a hash of info on each of the section's instructors (Hash)
+* **meetingtimes** -- an array of hashes that contain info on each of the meeting times of the section (Array)
+* **name** -- the plain-English name of the section (String)
+* **path** -- the PCR API URL path of the section (String)
+* **reviews** -- an array of hashes which each contain the review data for the section (usually only one review hash) (Array)
+* **sectionnum** -- the number of the section (e.g. "001") (String)
+* **retrieved** -- date/time retrieved (String)
+* **valid** -- true/false if query valid/invalid (String)
+* **version** -- PCR API version (String)
+
+### 'Instructors' in pcr-ruby ###
+
+(New version of instructors coming soon)
+
+## pcr-ruby Usage Examples ##
+
+Here are some (hopefully very simple and intuitive) usage examples for pcr-ruby:
+
+### Get average course quality rating ###
+Let's say we want to find the average course quality rating for Introduction to International Relations, PSCI-150:
+
+```ruby
+require 'pcr-ruby'
+course_code = "PSCI-150"
+pcr = PCR.new(API_TOKEN)
+psci150 = pcr.coursehistory(course_code)
+puts psci150.average("rCourseQuality") #=> 3.041
+```
+
+Or, even more briefly:
+
+```ruby
+require 'pcr-ruby'
+pcr = PCR.new(API_TOKEN)
+puts pcr.coursehistory("PSCI-150").average("rCourseQuality")
+#=> 3.041
+```
+
+### Get most recent course difficulty rating ###
+Finding the most recent section's course difficulty rating is just as easy:
+
+```ruby
+require 'pcr-ruby'
+course_code = "PSCI-150"
+pcr = PCR.new(API_TOKEN)
+psci150 = pcr.coursehistory(course_code)
+puts psci150.recent("rDifficulty") #=> 2.59
+```
+
+### Get the course quality rating for a specific course/semester ###
+```ruby
+require 'pcr-ruby'
+course_code = "PSCI-150"
+pcr = PCR.new(API_TOKEN)
+psci150 = pcr.coursehistory(course_code)
+psci150_course = psci150.courses[3]
+puts psci150_course.semester #=> "2003C"
+puts psci150_course.average("rDifficulty") #=> 2.98
+```
+
+
+## TODO ##
+* Implement refactored Instructor object
+* Implement stricter checks on course code arguments
+*	Implement search by professor last/first name rather than by ID.  ID is unintuitive.  Will probably need to see if I can make a lookup method, or simply pull down a database of all instructors and do a search on that database.

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/classes/course.rb

@@ -0,0 +1,59 @@
+require 'classes/resource'
+require 'classes/section'
+
+module PCR
+  class Course
+    include Comparable
+    include PCR::Resource
+    attr_reader :aliases, :credits, :description, :history, :id, 
+                  :name, :path, :reviews, :sections, :semester, 
+                  :retrieved, :valid, :version
+
+    def initialize(path, semester)
+      #TODO: Don't need to pass in semester
+      @path, @semester = path, semester
+
+      # Hit api
+      json = PCR.get_json(path)
+
+      # List of sections
+      @sections = json['result']['sections']['values'].map do |section|
+        Section.new(section['path'])
+      end
+
+      # Assign attrs
+      attrs = %w(aliases credits description history id name reviews 
+                 retrieved valid version)
+      set_attrs(attrs, json)
+    end
+
+    def <=>(other)
+      #TODO: Throw error if not same course
+      return year <=> other.year unless year == other.year
+      season <=> other.season
+    end
+
+    def average(metric)
+      # Aggregate ratings across all sections
+      total, num = 0, 0
+      #TODO: inject
+      self.sections.each do |section|
+        section.reviews.each do |review|
+          total += review.send(metric).to_f
+          num += 1
+        end
+      end
+
+      # Return average value across all sections
+      (total / num)
+    end
+
+    def year
+      @semester[0..3].to_i
+    end
+
+    def season
+      @semester[4]
+    end
+  end
+end

data/lib/classes/coursehistory.rb

@@ -0,0 +1,65 @@
+require 'classes/resource'
+require 'classes/course'
+
+module PCR
+  class CourseHistory
+    include PCR::Resource
+    attr_reader :course_code, :courses, :id, :path, :retrieved, :valid, :version
+    
+    def initialize(course_code)
+      @course_code = course_code
+      
+      # Read JSON from PCR API
+      json = PCR.get_json("coursehistories/#{self.course_code}")
+      
+      # List of courses in coursehistory
+      @courses = json['result']['courses'].map do |course|
+        Course.new(course['path'], course['semester'])
+      end
+
+      # Sort course list by semester
+      @courses.sort!
+      
+      # Assign rest of attrs
+      attrs = %w(id path reviews retrieved valid version)
+      set_attrs(attrs, json)
+    end
+    
+    def recent(metric)
+      # Select most recent course
+      course = @courses[-1]
+      
+      # Aggregate ratings for metric
+      total, num = 0, 0
+      course.sections.each do |section|
+        section.reviews.each do |review|
+          total += review.send(metric).to_f
+          num += 1
+        end
+      end
+      
+      # Return average value across most recent sections
+      (total / num)
+    end
+  
+    def average(metric)
+      # Aggregate ratings across all sections
+      total, num = 0, 0
+      courses.each do |course|
+        course.sections.each do |section|
+          section.reviews.each do |review|
+            total += review.send(metric).to_f
+            num += 1
+          end
+        end
+      end
+      
+      # Return average value across all sections
+      total / num
+    end
+    
+    def name
+      self.courses.last.name
+    end
+  end
+end

data/lib/classes/resource.rb

@@ -0,0 +1,9 @@
+module PCR
+  module Resource
+    def set_attrs(attrs, json)
+      attrs.each do |attr|
+        self.instance_variable_set("@#{attr}", json['result'][attr] || json[attr])
+      end
+    end
+  end
+end

data/lib/classes/review.rb

@@ -0,0 +1,27 @@
+require 'classes/resource'
+
+module PCR
+  class Review
+    include PCR::Resource
+    attr_reader :instructor, :num_reviewers, :num_students, :retrieved,
+                :comments, :id
+
+    def initialize(path)
+      @path = path
+
+      # Hit api
+      json = PCR.get_json(path)
+
+      # Assign attrs
+      attrs = %w(instructor num_reviewers num_students amount_learned comments
+                retrieved id)
+      set_attrs(attrs, json)
+
+      # Assign ratings
+      json['result']['ratings'].each do |name, val|
+        self.instance_variable_set("@#{name}", val)
+        self.class.send(:attr_accessor, name)
+      end
+    end
+  end
+end

data/lib/classes/section.rb

@@ -0,0 +1,29 @@
+require 'classes/resource'
+require 'classes/review'
+
+module PCR
+  class Section
+    include PCR::Resource
+    attr_reader :aliases, :course, :group, :id, :instructors, 
+                  :meetingtimes, :name, :path, :reviews, 
+                  :sectionnum, :retrieved, :valid, :version
+
+    def initialize(path)
+      @path = path
+
+      # Hit api
+      json = PCR.get_json(path)
+
+      # Get reviews
+      # Usually one, but may be > 1
+      @reviews = json['result']['reviews']['values'].map do |review|
+        Review.new(review['path'])
+      end
+
+      # Assign attrs
+      attrs = %w(aliases course group id instructors meetingtimes name 
+                 sectionnum retrieved valid version)
+      set_attrs(attrs, json)
+    end
+  end
+end

data/lib/pcr.rb

@@ -0,0 +1,50 @@
+require 'json'
+require 'open-uri'
+require 'classes/coursehistory'
+
+#PCR class handles token and api url, so both are easily changed
+module PCR
+  class Client
+    attr_reader :token
+
+    def initialize(token, api_endpt = "http://api.penncoursereview.com/v1/")
+      @token = token
+      @api_endpt = api_endpt
+    end
+
+    def get_json(path)
+      #TODO: Error handling for bad/no token
+      JSON.parse(open("#{@api_endpt + path}?token=#{@token}").read)
+    end
+
+    def coursehistory(course_code)
+      CourseHistory.new(course_code)
+    end
+
+    def instructor(id)
+      raise NotImplementedError.new("Instructors have not yet been implemented.")
+    end
+
+    def dept(code)
+      raise NotImplementedError.new("Departments have not yet been implemented.")
+    end
+  end
+
+  class << self
+    attr_accessor :token
+
+    def client
+      @client = PCR::Client.new(token) unless @client && token == @client.token
+      @client
+    end
+
+    def respond_to_missing?(method_name, include_private=false); client.respond_to?(method_name, include_private); end if RUBY_VERSION >= "1.9"
+    def respond_to?(method_name, include_private=false); client.respond_to?(method_name, include_private) || super; end if RUBY_VERSION < "1.9"
+
+    private
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+  end
+end

data/lib/pcr/version.rb

@@ -0,0 +1,5 @@
+module PCR
+  module Ruby
+    VERSION = "0.5"
+  end
+end

data/pcr.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/pcr/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = "Matt Parmett, Greg Terrono"
+  gem.email         = "terronogr@gmail.com"
+  gem.description   = %q{Ruby wrapper for the Penn Course Review API}
+  gem.summary       = %q{Ruby wrapper for the Penn Course Review API}
+  gem.homepage      = "https://github.com/gterrono/pcr-ruby"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "pcr"
+  gem.require_paths = ["lib"]
+  gem.version       = PCR::Ruby::VERSION
+  
+  gem.add_dependency "json"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: pcr
+version: !ruby/object:Gem::Version
+  version: '0.5'
+  prerelease: 
+platform: ruby
+authors:
+- Matt Parmett, Greg Terrono
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby wrapper for the Penn Course Review API
+email: terronogr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/classes/course.rb
+- lib/classes/coursehistory.rb
+- lib/classes/resource.rb
+- lib/classes/review.rb
+- lib/classes/section.rb
+- lib/pcr.rb
+- lib/pcr/version.rb
+- pcr.gemspec
+homepage: https://github.com/gterrono/pcr-ruby
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for the Penn Course Review API
+test_files: []