uiuc-api

uiuc-api provides a simple, high-level interface for working with the University of Illinois at Urbana Champaign’s REST API’s catalog module. Note that it is still under development and may be slightly buggy.

API Reference

class uiuc_api.Course(subject, number, hours, label, description, schedule_info, prereqs, coreqs, constraints, raw)

__init__(subject, number, hours, label, description, schedule_info, prereqs, coreqs, constraints, raw)

Parameters

• subject (str) – the name of the course’s subject (like ‘CS’)

• number (int) – the course number (like 421)

• hours (Optional[int]) – the number of credit hours the course is

• label (Optional[str]) – the course label (like ‘Programming Languages & Compilers’)

• description (Optional[str]) – the course description

• schedule_info (Optional[str]) – info about course scheduling

• prereqs (List[frozenset]) – prerequisite requirements

• coreqs (List[frozenset]) – corequisite requirements

• constraints (List[str]) – additional constraints on taking the course

• raw (Element) – a lxml.etree.Element object with the raw XML course data

serialize()

Generates YAML representation of course.

Return type

str

Returns

YAML dict with the course’s name as the single key and its attributes as the value

uiuc_api.get_course(course_name, year=None, quarter=None, redirect=False)

Returns parsed Course object.

Parameters

• year (Optional[str]) – year to get catalog from

• quarter (Optional[str]) – one of {'fall', 'spring', 'winter', 'summer'} (any case, defaults to spring)

• course_name (str) – valid course name (like ‘CS 225’, ‘cs225’, etc.)

• redirect (bool) – if True, courses that are the same will redirect to the root course (for instance, MATH 213 will simply return the Course object for CS 173)

Return type

Course

Returns

a Course object

Prerequsities, Corequsities, and Constraints

Prerequsites (Course.prereqs) are reprsented as a list of frozen sets, where each frozen set contains one or more options, one of which must be satisifed. For instance: [{CS 125}, {CS 173, MATH 213}] means “CS 125 and one of CS 173, MATH 213.” Corequsities (Course.coreqs) are represented the same way. Additional data that cannot be parsed into these forms is put into Course.constraints as a list of strings. Please note that there may not be 100% accuracy in parsing course data, as course descriptions are highly varried, and it is difficult to write an all-inclusive grammar.

Credit Hours

Credit hours are parsed by taking the first integer from the text of the creditHours XML attribute. This has the consequence that for courses that are “X or Y” hours, Course.credit_hours is only X. If you want to get the raw credit hour data use Course.raw.find("creditHours").

uiuc_api.get_courses(course_name_iterator, year=None, quarter=None, max_workers=None)

Wrapper function around get_course that uses concurrent.futures.ThreadPoolExecutor to fetch data concurrently.

Parameters

• course_name_iterator (Iterator[str]) – iterator of course names

• year (Optional[str]) – year to get catalog from

• quarter (Optional[str]) – one of {'fall', 'spring', 'winter', 'summer'} (any case, defaults to spring)

• max_workers (Optional[int]) – number of workers to use (defaults to os.cpu_count() + 4)

Return type

List[Course]

Returns

list of Course objects

How to Use get_courses

Each call to get_course is slow as get_course calls fetch which has to query the XML data. As with most IO bound tasks, this can be streamlined via multithreading. As get_courses takes in an iterable of course names, not a single course name, and makes use of concurrency, it is more performant than multiple synchronous calls to get_course if max_workers is set to an appropriate amount. More workers translates to more initial overhead but will generally result in more courses fetched / second. If the number of courses is high, it is reccomended to set this signifigantly higher than the default, though this is heavily dependent on hardware. If you want to do something like get the entire course catalog, you may want to benchmark and figure out the ideal value for max_workers first.

uiuc_api.subject_iterator(year=None, quarter=None)

Gets an iterator of subject names.

Parameters

• year (Optional[str]) – year to get catalog (defaults to current year)

• quarter (Optional[str]) – one of {'fall', 'spring', 'winter', 'summer'} (any case, defaults to spring)

Return type

Iterator[str]

Returns

generator yielding abbreviated subject names

uiuc_api.course_iterator(subjects=None, max_workers=32)

Gets an iterator of courses, high volume of https requests is streamlined through concurrency.

Parameters

• subjects (Optional[Iterator[str]]) – iterator of subject names, intended to be output of get_subjects() (defaults to all subjects)

• max_workers (int) – max number of worker threads to use

Return type

Iterator[str]

Returns

generator yielding course names: ('AAS 100', 'AAS 105', 'AAS 120'..).

uiuc_api.fetch(year=None, quarter=None, subject=None, number=None)

Queries official xml api with given parameters.

Parameters

• year (Optional[str]) – year to get catalog from (defaults to current year)

• quarter (Optional[str]) – one of {'fall', 'spring', 'winter', 'summer'} (any case, defaults to spring)

• subject (Optional[str]) – subject abbreviation

• number (Optional[str]) – 3 digit course number

Return type

Element

Returns

appropriate lxml.etree.Element object

When to Use fetch

fetch is a lower level function that directly gets XML data. For the most part, you should be using get_course or get_courses instead. You can also access the lxml.etree.Element object directly via Course.raw. The output of fetch is dependent on what default arguments are passed. If no subject is passed, the data for the subject catalog is returned. If a subject but no course number is specified, it gets the catalog data for that subject. If a course number is also specified, it gets the catalog entry for that course.