minervac
is a CLI client for Minerva's course registration facilities. The program can be run either without a Minerva login to:
- search for course information,
Or with a Minerva login to:
-
display your current course schedule, final exam schedule, or transcript, and register for courses by CRN or course code.
-
Course schedules can be formatted with custom reports, conflicts are detected, and HTML timetables, as well as importable calendar files, can be produced.
Previously registered courses are recorded and minervac
will only attempt registration for the remaining courses on each run.
The program is implemented in Python and currently is very hacky. Pull requests welcome. If you have ideas for features or have found a bug, please open an issue.
- A departmental or faculty advisor. Link valid as of 6th June, 2018
- [Last Known Update April 11th, 2018] When choosing courses, you may find the
McGill Enhanced
Chrome extension useful: https://tinyurl.com/McGillEnhancedFeatures - [Deprecated/Offline] If you don't need to make changes to your registration, look into
Minervabot
instead. Its source code could be insightful: https://github.com/zafarali/minerva-bot - [It's a bit old] The website Simplify McGill is great as an informational resource if you're a first year, good not only for course registration, but also for surviving at McGill in general
- [Be careful] If you haven't already found it there's also a subreddit for McGill if you have any genearl questions.
Features to be added in the future include:
- (Library) Documentation to make this a proper API for more reusability and other spin-off projects like a full website, maybe Android/iOS apps
- (CLI/Library) Create commands to alter settings that config.py contains, implement
ConfigParser
module - (CLI/Library) Integrate the scripts from extras/ into the main package, either as part of the library or as a Command Line Tool
- (CLI) Streamline interactive shell, and provide comprehensive help messages and documentation
- (CLI) Implement caching feature to store data/info on courses from eCalendar
- (CLI) Submit Mercury Evaluation Survey (seems risky/tricky?)
- (CLI) Enhance the requisite courses extraction feature of the eCalendar parser
Features to be added in the NEAR future include:
- (CLI) Integrate eCalendar features into command line tool
- (CLI/Library) VSB schedule integration features
- (CLI/Library) Connect to Docuum
- (CLI/Library) Data Visualization tools for the Mercury Evaluations
- (CLI) Allow username and password entry as arguments in native command line tool
- (Library) Data analysis tools on the Mercury Evaluations
- (Library) Improve Mercury Instructor Search (suggestions? multiple results?)
- eCalendar scraping added to library
- Scrape Course eCalendar page for Overview, Title, Notes, Faculty, Instructors, Terms
- Requisite Courses Extraction (WIP)
- Tool to convert typical term code to an eCalendar school year code
- Includes tool to print the information of the all the available courses of a given subject
- Remembering of Minerva credentials in native terminal/console. Implemented
keyring
module for secure credentials storage in system keyring.- Made usage of 'keyring' an extra that will be installable by pip via
pip install minervaclient[cli_features]
- Made usage of 'keyring' an extra that will be installable by pip via
- Minerva search function now accepts course codes case insensitive (always converts to uppercase)
- Mercury Evaluation scraping tools added to library
- Search for Instructors based on either a given name or ID number, can be partial, and obtain full name and ID number
- Obtain the list of evaluation reports on a specific instructor, or on a specific course
- Obtain the information from an evaluation report given a report ID number (ID is found in reports listings, and is temporary)
- The original minervac script has been moved to the
__main__
module for cross-platform compatibility - main function in
__main__
module now accepts arguments in its parameters, that overrides its usage as a command line tool, and is now scriptable html5lib
is now no longer a required package, however its usage is highly recommended for full functionality- Performed the
futurize
script on package, overhauled all the code to be compatible with Python 3, preliminary tests show that it works in both now (Python 2.7 and Python 3.5+).
- Fixed visual schedule creation missing file error
- Fixed inputting string into keyring data storing
- Several indentation inconsistencies were corrected
- Public Search is now case insensitive to course codes
- An interactive shell feature, so that commands can be run one after the other without repeated Minerva logons.
- Login credentials are retained for the duration that the shell runs
- Separate commands for setting/changing login credentials, and for removing credentials/logging out
- Added some helpful login related functions to the library
- Added backwards compatibility for
reg
andsched
(They still work) - Added more help messages to the interpreter
- Fixed some bugs involving installations via pip
- Changed the subcommands
reg
andsched
=>register
andschedule
for human readability - Fixed login-help bug present in the interpreter
- Updated the installation methods, now any form of installation has the same functionality
- Implement an on-screen login when running features that require Minerva login
- Converted original project by nicholaspaun into an installable pip package that will be added to the PyPi system for easier installation
- Added support for automatically installing the dependencies for this project such as
requests
,beautifulsoup4
, andurllib5
- Added an explicit feature,
minervac search
in the command line app, for querying Minerva for course information on CRNs, instructors, times, dates, waitlists, and general availability - the only command that works now is
minervac
which should replace the previous iteration'smnvc
andminervaclient
- Updated the installation methods, but the majority of features only work if installing via build from source. See note
-
- You can now view your final exam schedule (
minervac schedule -E
)
- You can now view your final exam schedule (
-
- You can now query your transcript (
minervac transcript
)
- You can now query your transcript (
-
- A visual timetable feature has been implemented. (-V).
- Calendar export is now available (vCalendar format only). (-C)
-
- The command-line interface won't be modified anymore, only extended. Configuration format is still in flux.
- Displaying course schedule information with custom reports.
The goals of this project are to create a simple and high-quality interface for the most-used features of Minerva. The user interface will be designed in accordance with UNIX priciples, thus, minervac
will be easily programmable. Additionally, minervac
will clearly explain how it is connecting to Minerva and provide a starting point for other projects that attempt to use the Minerva "API". This project is free and open-source. Forks and projects that use this should try to be open-source as well.
- Download the source code.
minervac
uses therequests
,beautifulsoup4
, andhtml5lib
modules for Python.
- A good way to install them is probably with
pip
:sudo pip install requests beautifulsoup4 html5lib
- Edit
config.py
to setup various settings - Run
python setup.py install
orsudo python setup.py install
- You may now run
minervac -h
for help information. This just works for Unix/Linux but it's iffy for Windows. You might need some bash command prompt for it to work on Windows ex. Git Bash, Cygwin
- Run
pip install minervaclient
orsudo pip install minervaclient
- Use
minervac -h
to get help information.
NOTE: At the time of this writing, all features of the application should work, now that login occurs everytime the application is run
It's way simpler than actually using Minerva!
NOTE: Any minervaclient
or mnvc
command should be replaced with minervac
in this new version!
-
Interactive Shell:
minervac shell
- commands should involve using
search
, `register
- commands should involve using
-
Course Information Search:
minervac search
- To retrieve the information from all the sections of a course:
minervac search -t 201809 COMP-202 MATH-133
(Fall 2018) - To retrieve the information from just one section:
minervac search -t 201901 POLI-200-002
(Winter 2019) - To retrieve just availability from classes:
minervac search -A -t 201805 CCOM-206 FRSL-100-001 MATH-133-018
(Summer 2018) - To retrieve just Lectures:
minervac search -L -t 201809 COMP-202
- To retrieve just Tutorials:
minervac search -T -t 201809 COMP-202
- NOTE: Minerva Credentials are not required for this feature and therefore is the most secure in the sense you don't expose your passwords to any hackers or children that find their way onto your computer...
- ALSO NOTE: Waitlist/Availability information can get kinda weird so if it says 0/0 it's probably completely full but check Minerva for these weird things.
- To retrieve the information from all the sections of a course:
-
Registration:
minervac register
- To register for a set of courses:
minervac register -t FALL2016 COMP-251-001 MATH-240-001
- To register by CRN (faster):
minervac register -t 2016-FALL 814 30302 30
- To save previously-registered courses and only register for what remains:
minervac register -j compstuff -t 2016-FALL COMP-273-002 COMP-396-001
- NOTE: An option to search without logging in is provided. However, only waitlist information can be determined in this way, and its quality may be poor.
- To register for a set of courses:
-
Scheduling:
minervac schedule
- To display your schedule:
minervac schedule -t WINTER2017
- To display more details (
-l
), or less (-s
):minervac schedule -lt SUMMER-2017
orminervac schedule -st 2016WINTER-SUP
- To use a custom report (edit
config.py
):minervac schedule -t WINTER2017 -r magicreport
- To export your timetable to a HTML file:
minervac schedule -t 2016SUMMER -V > ~/summer-schedule.html
- Edit
config.py
to change the way courses are formatted andsched_timetable.css
to adjust the styling. - Hint: Click on a building name to get directions. Hover over courses to see an explanation of the color code.
- Edit
- To export your course schedule to an iCalendar file:
minervac schedule -Ct 2017-WINTER > mcgill-winter-2017.ics
- You can also export your final exam schedule, like this:
minervac schedule -ECt FALL2016 > mcgill-fall-2016-finals.ics
. - The resulting file can be imported into your favorite calendar application (Google Calendar, and the Mac OS X Calendar work.)
- This format may also be called ICS or vCalendar.
- You can also export your final exam schedule, like this:
- To display your final exam schedule:
minervac schedule -t FALL2016 -E
- To display your schedule:
-
Transcripts:
minervac transcript
- To display your transcript:
minervac transcript
- The term argument is optional, and more than one term can be specified:
minervac transcript -t FALL2016,2017-SUMMER
- Reports (
-r
) and the long (-l
) and short (-s
) shortcuts can be used. (See Scheduling above.) - To display only your program information (
-S
) and GPA (-C
):minervac transcript -SC
- To display some miscellaneous transcript information as well (
-P
):minervac transcript -P
- To display your transcript:
-
For a full description of available options:
minervac -h
-
A few useful extra scripts are included in the
extras/
folder:- Note: These tools are more experimental than
minervac
itself and might not work so well. grablrs.py
: Downloads LRS lecture recordings.transcript-monitor.sh
: Allows you to monitor your unofficial transcript for new grades.
- Note: These tools are more experimental than
- Put it in your
crontab
. This way, theminervac
will automatically be run at the time interval you choose, and you will receive an email indicating the status of your course registration job.- If you don't have
cron
, you may need to write a long-running loop or use your OS' job scheduling facility. Oh, and by the way, your OS sucks.
- If you don't have
- An example crontab line:
00 * * * * minervac -dj compstuff -t 2016FALL 814 20620 33
. - Some ideas:
- Set the
MAILTO
option to your email address, or pipe the output tomail
. - You can receive this information as a SMS text message. Look up the email-to-SMS gateway for your cellular carrier. For example,
MAILTO=2505551234@msg.telus.com
- Set the
- Displaying degree evaluation reports.
- Won't implement: While it would be trivial to support dropping courses, I am worried that this may mess up people's schedules as Minerva does not perform truly atomic transactions. Furthermore, it may mess up my own schedule and so I don't want to test it. If you're braver than I am, please send me a pull request.
Extra Features to look into:
- Support output formatters and more control over what this program prints.
- Allow querying for courses from the CLI, and use a SQL database to allow for fancy queries.
- Integrate the course selection satisfiability solver to recommend what you can register for.
- Prerequisite/Corequisite Information
- Mercury Course Evaluations
- Link to course syllabuses
- Program Outlines for different Majors/Minors
-
You are solely responsible for deciding if
minervac
is compliant with McGill's policies, and if you want to assume this risk.- Start reading here: McGill Policy on the Responsible Use of IT Resources, but there are most definitely more policies that may be applicable to this program and its use.
-
minervac
might mess up your course schedule in a very bad sort of way. -
The final exam data might be unpleasantly wrong, as it is generated from a
messed uppretty high-quality PDF. Progress at McGill! -
minervac
might suddenly stop working if Minerva is changed. -
Minerva is a horrible, horrible system and trying to extend this program may lead to a horrible headache.
-
This program was badly written, in a rush, and might have some serious design flaws.
-
May give CS hipsters a headache.
Minerva is a Banner installation (Release 8.7, to be precise), so you may be able to adapt the program to work for your university or college. Try to edit minerva_common.py
with the correct URL to your student information system. A quick way to check if you've got Banner is to Google for "bwckgens" and your institution's name.