rubyuw 0.99.1

data/.gitignore

@@ -0,0 +1,4 @@
+pkg/*
+test/password.rb
+.yardoc
+doc/*

data/README.md

@@ -0,0 +1,81 @@
+# RubyUW: Ruby Interface to MyUW
+
+__RubyUW is NOT supported in any way by the University of Washington__
+
+RubyUW provides a programmable interface to MyUW, University
+of Washington's student web portal. 
+
+## Why?
+
+It's a fun project and it was really a proof of concept more than
+anything. I don't plan on officially supporting this library or
+promising updates in case any features break. Its a good example
+for any Ruby developer on the uses of mechanize and the ability
+to scrape content or simulate a human at a browser.
+
+It is also a useful library to create MyUW automation tools
+with. I do not support this.
+
+## How does it work?
+
+RubyUW functions by emulating a human in an actual browser. It hunts
+down buttons to click, fields to fill in, etc. It is programmed
+using the Ruby Mechanize library to achieve this level of human
+simulation.
+
+Of course this also means that even minor tweaks to the MyUW layout
+could potentially "break" the RubyUW library.
+
+## Installing
+
+    # Install the gem
+    sudo gem sources -a http://gems.github.com
+    sudo gem install mitchellh-rubyuw
+
+## Using RubyUW
+
+It's easy to get started with RubyUW. Below is a basic example
+but you can also read the comprehensive documentation, check out
+the section below this, titled "Documentation."
+
+The following is a quick and simple example:
+
+    require 'rubyuw'
+    RubyUW::Base.authenticate("netid", "password") or raise("Login Failed")
+    
+    # Get SLN information
+    sln_info = RubyUW::SLN.find(14153, "AUT+2009")
+
+## Documentation
+
+You may view all documentation [at the following URL](http://mitchellh.github.com/RubyUW/):
+
+http://mitchellh.github.com/RubyUW/
+
+## Testing
+
+RubyUW includes a comprehensive test suite included both live and
+mocked testing. Mocked testing uses "mocked" HTML pages and a lot
+of object stubbing to simulate a real environment and to force
+certain events to occur (such as strange HTML in a request) in order
+to completely test the library. Mock testing can be run straight
+"out of the box" via a rake task:
+
+    rake test:run_mock
+
+RubyUW also includes "live" testing which uses a real UW NetID and
+password to conduct live tests. To run this, see test/password.rb.sample
+and modify it to include your credentials, then save it as password.rb.
+Following this, run another rake task:
+
+    rake test:run_live
+
+Note: Live testing is very very slow. On my machine with the current
+suite it takes about a minute to run all the tests (though this is
+highly dependent on your internet connection).
+
+Note: Also, live testing DOES NOT test registration since that actually
+affects your MyUW account in a significant way. To test registration,
+run the registration test directly:
+
+    cd test/live && ruby registration_test.rb

data/Rakefile

@@ -0,0 +1,45 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "rubyuw"
+    gemspec.summary = "Library which provides a ruby interface to the University of Washington student portal."
+    gemspec.email = "mitchell.hashimoto@gmail.com"
+    gemspec.homepage = "http://github.com/mitchellh/rubyuw"
+    gemspec.description = "Library which provides a ruby interface to the University of Washington student portal."
+    gemspec.authors = ["Mitchell Hashimoto"]
+    
+    gemspec.add_dependency('tenderlove-mechanize', '>= 0.9.3.20090623142847')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+def run_tests(files)
+  files.each { |f| require f }
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  desc "Generate YARD documentation."
+  task :yardoc do
+    puts "Yard is not available. Install with: sudo gem install yard"
+  end
+end
+
+namespace :test do
+  desc "Run all the tests" 
+  task :run => [:run_mock, :run_live]
+  
+  desc "Run the library test on fixtured data"
+  task :run_mock do
+    run_tests(Dir[File.join(File.dirname(__FILE__), 'test', 'mocked', '**', '*.rb')])
+  end
+  
+  desc "Run the library tests on live data (requires password.rb file). NOTE: This method is very slow."
+  task :run_live do
+    run_tests(Dir[File.join(File.dirname(__FILE__), 'test', 'live', '**', '*.rb')])
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.99.1

data/lib/rubyuw.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'mechanize'
+require 'nokogiri'
+require 'rubyuw/errors'
+require 'rubyuw/base'
+require 'rubyuw/connection'
+require 'rubyuw/sln'
+require 'rubyuw/curriculum_enrollment'
+require 'rubyuw/schedule'

data/lib/rubyuw/base.rb

@@ -0,0 +1,122 @@
+module RubyUW
+  # The base class for RubyUW. As a developer using RubyUW, you'll
+  # most likely only use this class to authenticate a connection to 
+  # MyUW and to verify the connection.
+  #
+  # The base connection is shared by all other portions of RubyUW.
+  # Therefore, it a connection is not established first, you'll
+  # probably see a NotLoggedInError from other areas of RubyUW.
+  #
+  # == Usage Example
+  #
+  # @example Authenticating with MyUW
+  #   require 'rubyuw'
+  #   RubyUW::Base.authenticate("uwnetid", "password")
+  class Base
+    @@connection = nil
+
+    class <<self
+      # Authenticate with MyUW. This method sets up and verifies
+      # a session with MyUW. Every feature of RubyUW which requires
+      # authentication (as of writing this documentation this is
+      # every feature), will require that this authentication is
+      # completed first.
+      #
+      # @param [String] UW NetID
+      # @param [String] Password for the UW NetID
+      # @return [nil]
+      def authenticate(netid, password)
+        # Clear pre-existing session information first
+        logout
+        
+        # Log in
+        results = connection.goto("http://myuw.washington.edu").
+                    verify("//input[@type='submit' and @value='Log in with your UW NetID']").
+                    submit_form('f').
+                    submit_form('relay').
+                    submit_form('query', {
+                      :user => netid,
+                      :pass => password
+                    }).
+                    execute!
+        
+        relay_form = results.form_with(:name => 'relay')
+        return false unless results.form_with(:name => 'query').nil?
+        relay_form.submit()
+        
+        true
+      end
+      
+      # Checks whether authentication is still valid. This method
+      # goes to the MyUW portal and checks to verify that the
+      # previous authentication is valid. If no authentication was
+      # ever done, this will return false.
+      #
+      # @return [Boolean]
+      def authenticated?
+        results = connection.goto("http://myuw.washington.edu").
+                            submit_form('f').
+                            execute!
+        
+        !results.search("//div[@class='main_search']").empty?
+      end
+      
+      # Log out from MyUW. This method clears the cookies of the
+      # connection, also cleraing out any session data. This effectively
+      # logs a user out of anything.
+      def logout
+        connection.cookie_jar.clear!
+      end
+      
+      # Returns the connection object. Used by other portions of RubyUW
+      # to browse the pages, authenticate, and more. This method will
+      # typically *never* be called by non-internal systems.
+      #
+      # @return [WWW::Mechanize] A WWW::Mechanize object.
+      def connection
+        @@connection ||= RubyUW::Connection.new do |browser|
+          browser.user_agent_alias = 'Mac Safari'
+          browser.follow_meta_refresh = true
+
+          # Workaround to avoid frozen object error SSL pages
+          browser.keep_alive = false
+
+          # Do not keep any history, which is otherwise a 
+          # surefire way to grow memory usage without bound.
+          browser.max_history = 0
+          
+          # Force parsing with Nokogiri. Strange bug introduced
+          # in 0.9.3 of WWW::Mechanize defaults to nil.
+          # http://github.com/tenderlove/mechanize/issues#issue/5
+          browser.html_parser = Nokogiri::HTML
+        end
+      end
+      
+      # Resets the connection by clearing out the old. This way,
+      # when connection is next called, it will recreate the object.
+      def reset_connection!
+        @@connection = nil
+        self
+      end
+      
+      # Runs an xpath on a page, mapping the results to a hash map.
+      # This method should never have to be called outside the core library
+      # code. It is purely a conveniance method supplied to other parts
+      # of the library since this functionality is repeated a few times
+      # in different areas.
+      def extract(page, xpath, keys)
+        nodes = page.search(xpath)
+        return nil if nodes.empty?
+
+        data = {}
+        nodes.each_with_index do |node, i|
+          # If we have no keys left, break out of the loop.
+          break if i >= keys.length
+          data[keys[i]] = node.inner_text.strip.gsub("\302\240", "") unless keys[i].nil?
+        end
+        
+        data
+      end
+    end
+  end
+end

data/lib/rubyuw/connection.rb

@@ -0,0 +1,145 @@
+module RubyUW
+  # Represents a connection to the MyUW portal. Outside developers
+  # will most likely not use this class, and will almost certainly
+  # not instantiate this class alone. However, for documentation
+  # purposes for myself and for potential contributors to RubyUW,
+  # this class is documented to the full extent.
+  #
+  # This class is mostly
+  # a fancy wrapper around WWW::Mechanize to provide nifty features
+  # such as chaining a workflow to get to a certain result and so on.
+  #
+  # == Page Flow Representation
+  #
+  # The main focus of this class is to provide a flexible way for
+  # the various pieces of RubyUW to represent and execute web flows.
+  # By "web flow" I mean the process of executing a task within a
+  # web site. WWW::Mechanize on its own is very good at getting/posting
+  # web pages and storing cookies and so on. But it has no good way (yet)
+  # of representing advanced multi-page actions. This is where
+  # this class comes in.
+  #
+  # If at any point a step in the process fails (link was not found,
+  # for example) then a RubyUW::InvalidPageError is thrown with details
+  # on what occured. 
+  #
+  # Below is a simple example of a three-step web flow which simulates
+  # logging into a fake website.
+  #
+  #   connection = RubyUW::Connection.new
+  #   connection.goto("http://fakewebsite.com").
+  #             click_link("Log In").
+  #             submit_form('login', :username => "foo", :password => "baz").
+  #             execute!
+  #
+  # In RubyUW, more advanced features were necessary to verify that the
+  # page being visited is in fact valid to what we're looking for (to
+  # protected against potential changes in the MyUW system). The example
+  # below shows how this works. The verify method accepts any valid xpath
+  # and fails if the xpath fails to return any matches. 
+  # Just like any other step, if the verification
+  # fails, a simple RubyUW::InvalidPageError is thrown.
+  #
+  #   connection = RubyUW::Connection.new
+  #   connection.goto("http://fakewebsite.com").
+  #             verify("//input[@type='submit' and @value='Log in with your UW NetID']").
+  #             click_submit("Log in with your UW NetID").
+  #             execute!
+  #
+  # == Thread Safety
+  #
+  # The RubyUW::Connection object is *NOT* thread-safe at all. If multiple
+  # threads are attempting to do web flows concurrently, the results are
+  # unspecified.
+  class Connection < WWW::Mechanize
+    # Flow item: Go to a specific URL. Calling this method will
+    # attach a task to the current flow to go to a specific URL.
+    #
+    # @param [String] URL to go to (must respond to #to_s)
+    # @return self
+    def goto(url)
+      current_flow.push([:goto, url])
+      self
+    end
+    
+    # Flow item: Submit a form. Attaches a task to the curernt flow to
+    # submit a form specified by the given form name. Optionally, data
+    # parameters may be given as the second argument to be filled into
+    # the form.
+    #
+    # @param [String] Name of the form.
+    # @param [Hash] Parameters to pass through to the form.
+    # @return self
+    def submit_form(name, parameters={})
+      current_flow.push([:submit_form, name, parameters])
+      self
+    end
+    
+    # Flow item: Verify the existence of an element or elements. Attaches
+    # a task to verify that the given XPath string matches at least one
+    # element.
+    #
+    # @param [String] XPath of the element(s) to verify existence of.
+    # @return self
+    def verify(xpath)
+      current_flow.push([:verify, xpath])
+      self
+    end
+    
+    # Execute the current web flow. This task will execute the flow
+    # (in order of course) that has been built up and will clear out the
+    # flow for future usage. It will return the last executed task.
+    def execute!
+      # The context variable provides contextual information to the
+      # execute_* task. It is merely the result of the last execute
+      # task.
+      context = nil
+      
+      current_flow.each do |command, *params|
+        # The context becomes the first parameter
+        params.unshift(context)
+        
+        # Send to the special execution method
+        context = send("execute_#{command}!", *params)
+      end
+      
+      @current_flow = []
+      context
+    end
+
+    # Returns the internal representation of the current web flow.
+    def current_flow
+      @current_flow ||= []
+    end
+    
+    protected
+    
+    # Executes the 'goto' web flow task by simply GETting the
+    # url specified. Returns the get result.
+    def execute_goto!(context, url)
+      self.get(url)
+    end
+    
+    # Executes the 'verify' web flow task by checking the
+    # context with the xpath. Raises an InvalidPageError if no
+    # elements match.
+    def execute_verify!(context, xpath)
+      results = context.search(xpath)
+      raise Errors::InvalidPageError.new(context, "Failed verify step in web flow.") if results.empty?
+      
+      context
+    end
+    
+    # Executes the 'submit_form' task. Submits a form given by finding
+    # it on the previous page and submitting it.
+    def execute_submit_form!(context, name, parameters = {})
+      form = context.form_with(:name => name)
+      raise Errors::InvalidPageError.new(context, "Failed to find form on submit_form: #{name}") if form.nil?
+      
+      # The #to_s is necessary here to avoid strange exceptions being
+      # thrown by WWW::Mechanize. Unit tested.
+      parameters.each { |k,v| form[k.to_s] = v.to_s }
+      form.submit()
+    end
+  end
+end

data/lib/rubyuw/curriculum_enrollment.rb

@@ -0,0 +1,75 @@
+module RubyUW
+  # RubyUW::CurriculumEnrollment is used to extract SLN information
+  # for an entire "curriculum" of courses (whic is how MyUW refers
+  # to it). If you have multiple SLNs within the same curriculum
+  # (chemistry, computer science, history, etc.), it is more efficient
+  # to use the CurriculumEnrollment class rather than SLN.
+  #
+  # <b>Requires authentication with RubyUW::Base prior to use!</b>
+  #
+  # == Usage Examples
+  #
+  #   require 'rubyuw'
+  #   RubyUW::Base.authenticate("netid", "password")
+  #   curriculum = RubyUW::CurriculumEnrollment.find("HIST")
+  #   curriculum["12345"] # RubyUW::SLN object. Use it like one!
+  #
+  # After using {RubyUW::CurriculumEnrollment} to grab the SLNs of a
+  # specific curriculum, you can access the individual SLNs using
+  # the array access notation common to ruby. This access returns
+  # a {RubyUW::SLN} object.
+  class CurriculumEnrollment
+    class <<self
+      # Pulls data about a specific curriculum. The SLN data is pulled
+      # directly from the MyUW curriculum information page. Authentication
+      # is required prior to use.
+      #
+      # @param [String] Curriculum to search for.
+      # @param [String] The term (quarter) to search in.
+      def find(curriculum, term)
+        raise Errors::NotLoggedInError.new unless Base.authenticated?
+
+        page = Base.connection.get("https://sdb.admin.washington.edu/timeschd/uwnetid/tsstat.asp?QTRYR=#{term}&CURRIC=#{curriculum}")
+        raise Errors::CurriculumDoesNotExistError.new if !curriculum_exists?(page)
+        
+        extract_courses(page, term)
+      rescue WWW::Mechanize::ResponseCodeError
+        raise Errors::CurriculumDoesNotExistError.new
+      end
+      
+      protected
+
+      def curriculum_exists?(page)
+        !(page.body.to_s =~ /No sections found for (.+?)/i)
+      end
+      
+      def extract_courses(page, term)
+        course_nodes = page.search('//table//tr[count(th)>1 and @bgcolor="#d0d0d0"]//following-sibling::tr')
+        
+        results = {}
+        course_nodes.each { |node| 
+          sln, data = extract_course(node)
+          results[sln] = RubyUW::SLN.new(sln, term, data)
+        }
+        
+        results
+      end
+      
+      def extract_course(node)
+        data_keys = [:sln, :course, :section, :type, :title, :current_enrollment, :limit_enrollment,
+            :room_capacity, :space_available, nil, :notes]
+
+        results = Base.extract(node, 'td', data_keys)
+        results[:sln].gsub!(/^>/, '') # Strips leading '>' off of quiz sections
+        
+        [results[:sln], results]
+      end
+    end
+  end
+  
+  module Errors
+    # An error indicating that the curriclum requesting does not
+    # exist.
+    class CurriculumDoesNotExistError < Exception; end
+  end
+end