uw_learn 1.0.0.pre → 1.0.1

data/lib/uw_learn.rb

@@ -1,15 +1,28 @@
 require 'mechanize'
 require 'hpricot'
-require 'awesome_print'
 require 'open-uri'
 require 'httparty'
 require 'rainbow'
 
-require './lib/uw_learn/grade'
-require './lib/uw_learn/course'
+require 'uw_learn/grade'
+require 'uw_learn/course'
 
+##
+# The UW Learn gem is a tiny web crawler for University of Waterloo students.
+# It grabs their grades, and prints them out in the terminal.
+# 
+# @author Gaurav Mali <hello@gauravmali.com>
+# @version 1.0.1
+# 
 class Uwlearn
-
+  
+  ##
+  # Creates a new instance of UW Learn account.
+  # Proceeds to login and scrape grades.
+  #
+  # @param [String] The student username
+  # @param [String] The student password
+  #
   def initialize(login, password)
     @user_login = login
     @user_passw = password
@@ -24,20 +37,38 @@ class Uwlearn
     start
   end
 
+  ##
+  # @!method login
+  #   The username that the account was logged in with
+  #   @return [String] The username
+  #   
   def login
     @user_login
   end
 
+  ##
+  # @!method print_courses
+  #   Prints out the names of all the courses
+  #  
   def print_courses
     @learn_courses.each do |course|
       puts course.name.foreground(:yellow)
     end
   end
 
+  ##
+  # @!method courses
+  #   The array of the user's courses in string format
+  #   @return [Array] The user's courses
+  #  
   def courses
     @learn_courses
   end
 
+  ##
+  # @!method print_grades
+  #   Prints out every course's name and the grades registered with it
+  #  
   def print_grades
     @learn_grades.each do |grade|
       puts grade.which_course?.foreground(:yellow) + ": ".foreground(:yellow)
@@ -45,43 +76,82 @@ class Uwlearn
     end
   end
 
+  ##
+  # @!method grades
+  #   The array of user's grades in string format
+  #   @return [Array] The user's grades
+  #  
   def grades
     @learn_grades
   end
 
   private
 
+  ##
+  # learn_url
+  #   Holding on to the learn URL for easy change. You may try simply changing this URL to a different University's URL.
+  #   But remember, this is a hacky scrape job. Don't be surprised if things break.
+  #  
   def learn_url
     "http://learn.uwaterloo.ca"
   end 
 
+  ##
+  # course_url
+  #   Just in case if D2L decides to change their markup, you know where to look for (hopefully) a quick fix.
+  #  
   def course_url
     "/d2l/lp/ouHome/home.d2l?ou="
   end
 
+  ##
+  # course_html
+  #   Just in case if D2L decides to change their markup, you know where to look for (hopefully) a quick fix.
+  #  
   def course_html
-    "//ul[@id='z_bl']//div[@class='dco_c']//a"
+    "//ul[@id='z_w']//div[@class='dco_c']//a"
+  end
+
+  ##
+  # error_html
+  #   Just in case if D2L decides to change their markup, you know where to look for (hopefully) a quick fix.
+  #  
+  def error_html
+    "//div[@class='error']"
   end
 
+  ##
+  # start
+  #   The starting point of crawling. Calls the authentication and scraping methods.
+  #
   def start
+    # Very important object. Don't lose or overwrite it. Required for scraping.
     agent = Mechanize.new
 
     begin
+      # Authenticates in this method call.
       links = authenticate agent
+      # Scrapes in this method call.
       acquire links, agent
+
       puts "Grades acquired.".foreground(:cyan)
     rescue Exception => e
-      puts e.message  
-      #puts e.backtrace.inspect
+      puts e.message
     rescue Mechanize::ResponseCodeError, Net::HTTPNotFound
       puts "Looks like the website has changed. Contact the developer to fix this issue.".foreground(:red)
     end
 
   end
 
+  ##
+  # authenticate
+  #   Logs in using the user credentials.
+  #   Returns an array of anchor(<a href=""></a>) elements of course links.
+  #
   def authenticate(agent)
     puts "Authenticating ".foreground(:cyan) + @user_login.foreground(:cyan) + "...".foreground(:cyan)
 
+    # Login form submission
     page = agent.get learn_url
     form = page.forms.first
     form.username = @user_login
@@ -89,13 +159,23 @@ class Uwlearn
     page = agent.submit form
 
     course_links = page.search course_html
-    if course_links.empty?
+    login_error = page.search error_html
+
+    if login_error.empty? and course_links.empty?
+      raise "D2l has changed. Please contact the developer.".foreground(:red)
+    elsif !login_error.empty?
       raise "Couldn't authenticate. Please try again.".foreground(:red)
     end
     
     course_links
   end
 
+  ##
+  # acquire
+  #   Extracts the course name and code for further scraping of grades.
+  #   The scraping occurs in the initialization of the grade objects.
+  #   Stores the grades and courses in two different arrays: @learn_courses and @learn_grades.
+  #
   def acquire(links, agent)
     puts "Acquiring data...".foreground(:cyan)
 
@@ -115,4 +195,4 @@ class Uwlearn
     end 
   end
 
-end
+end # Uwlearn

data/lib/uw_learn/course.rb

@@ -0,0 +1,40 @@
+##
+# The course object represents a typical course a student would register for.
+# 
+# @todo Add more featuers such as course news and dates
+# 
+# @author Gaurav Mali <hello@gauravmali.com>
+# @version 1.0.1
+# 
+
+class Course
+  ##
+  # @!attribute [r] name
+  #   @return [String] the course name
+  attr_reader :name
+
+  ##
+  # @!attribute [r] code
+  #   @return [String] the course code
+  attr_reader :code
+
+  ##
+  # @!attribute [r] grade
+  #   @return [Object] the grades of the particular course
+  attr_reader :grade
+
+  ##
+  # Creates a new instance of a course object.
+  # Simply holds on to string values and the grade object.
+  #
+  # @param [String] The course name
+  # @param [String] The course code
+  # @param [Object] The course grades
+  #
+  def initialize(name, code, grade)
+    @name = name
+    @code = code
+    @grade = grade
+  end
+
+end # Course

data/lib/uw_learn/grade.rb

@@ -0,0 +1,116 @@
+require 'mechanize'
+require 'hpricot'
+require 'open-uri'
+
+##
+# The grade object scrapes and holds on the grades of a particular course
+# 
+# @todo Store the grades in a hash with key as a string and value as a number of some sort
+# 
+# @author Gaurav Mali <hello@gauravmali.com>
+# @version 1.0.1
+# 
+class Grade
+  
+  ##
+  # Creates a new instance of a course grade.
+  # Proceeds to scrape grades and store it in @grades.
+  #
+  # @param [String] The course name
+  # @param [String] The course code
+  # @param [Object] The Mechanize object for scraping
+  #
+  def initialize(name, code, agent)
+    @course_name = name
+    @course_code = code
+    @grades = Array.new
+    
+    get_grades agent
+  end
+  
+  ##
+  # @!method which_course?
+  #   A way to find out which course a grade belongs to.
+  #   @return [String] The course name
+  # 
+  def which_course?
+    @course_name
+  end
+
+  ##
+  # @!method summary
+  #   Returns a summary of grades for this particular course.
+  #   If no grades were uploaded, user is notified so.
+  #   
+  #   @return [Array] The grades in string format.
+  # 
+  def summary
+    if @grades.empty?
+      ("Sorry the instructor for " + @course_name + " has not uploaded any marks yet").foreground(:red)
+    else
+      @grades
+    end
+  end
+
+  private
+
+  ##
+  # grades_url
+  #   Just in case if D2L decides to change their markup, you know where to look for (hopefully) a quick fix.
+  # 
+  def grades_url
+    "https://learn.uwaterloo.ca/d2l/lms/grades/my_grades/main.d2l?ou=" + @course_code
+  end
+
+  ##
+  # grades?
+  #   Are there any grades for this course?
+  #   Returns true(yes) or false(no)
+  # 
+  def grades?(report)
+    report.xpath("//td[@class='d_gempty']").to_s == ""
+  end
+
+  ##
+  # has_mark?
+  #   Are there any marks in this table of grades?
+  #   We don't want rows with no data in them.
+  #   
+  #   Returns true(yes) or false(no)
+  # 
+  def has_mark?(row)
+    # Why didn't !(row/"label").blank? work?
+    (row/"label").to_s != ""
+  end
+
+  ##
+  # get_grades
+  #   More scraping.
+  # 
+  def get_grades(agent)
+    page = agent.get grades_url
+    report = page.parser
+    
+    # Search for all rows that have both 'strong' and 'label' elements
+    if grades? report 
+      rows = report.xpath("//table[@id='z_c']/tr")
+
+      if rows.empty?
+        raise "ERROR: Failed parsing at the rows. Please contact the developer.".foreground(:red)
+      end
+      
+      rows.each do |row|
+        if has_mark? row
+          mark = (row/"label").last.inner_html.to_s
+          category = (row/"strong").inner_html.to_s
+    
+          # Storing it as a string for now. Future releases will be different.
+          @grades << (category + " => " + mark)
+        end      
+      end
+
+    end
+
+  end
+
+end # Grade

metadata

@@ -1,17 +1,161 @@
 --- !ruby/object:Gem::Specification
 name: uw_learn
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre
-  prerelease: 6
+  version: 1.0.1
+  prerelease: 
 platform: ruby
 authors:
 - Gaurav Mali
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-24 00:00:00.000000000 Z
-dependencies: []
-description: Gets student grades from University of Waterloo's D2L website.
+date: 2012-09-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  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'
+- !ruby/object:Gem::Dependency
+  name: hpricot
+  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'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  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'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  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'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: turn
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Displays student grades from D2l in the terminal.
 email: hello@gauravmali.com
 executables:
 - uw_learn
@@ -19,6 +163,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/uw_learn.rb
+- lib/uw_learn/grade.rb
+- lib/uw_learn/course.rb
 - bin/uw_learn
 homepage: https://github.com/GMali/uw_learn
 licenses: []
@@ -26,6 +172,7 @@ post_install_message:
 rdoc_options: []
 require_paths:
 - lib
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -35,13 +182,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Tiny web crawler for University of Waterloo students
+summary: Tiny web crawler for University of Waterloo students.
 test_files: []