Rudaux API Documentation

If you need more direct control over rudaux, the Python API is preferred over the CLI. For some examples of how to use these functions, please see Examples.

Rudaux's has two primary classes: Course and Assignment.

Course

Course object for manipulating an entire Canvas/JupyterHub/nbgrader course

from rudaux import Course

Instantiation

Course(
  course_dir=None,
  auto=False
)
Parameters
course_dir - str

The course directory containing your course configuration files. (rudaux_config.py and/or nbgrader_config.py) This should also be your nbgrader directory. Currently, it is assumed that this is your private instructors' repository. If none is provided, defaults to the current working directory.

Default: os.getcwd()

auto - bool

Suppress all prompts, automatically answering yes.

Default: False

Returns - Course

A Course object for manipulating an entire Canvas/JupyterHub/nbgrader course.

Methods

.get_external_tool_id() → Course
Find the ID of the external tool created in Canvas that represents your JupyterHub server.
This is necessary to link your LTI launch keys to assignment links created in Canvas.
.get_students_from_canvas() → Course

Get the course student list from Canvas.

.sync_nbgrader() → Course

Sync student and assignment lists between nbgrader and Canvas.

  • Add students into nbgrader gradebook that are present in Canvas.
  • Remove students from nbgrader gradebook that are not present in Canvas.
  • Add assignments to gradebook which are present in config, but not in gradebook.
  • Remove assignments from gradebook which are no longer present in config.
.assign(assignments, overwrite) → Course   Commits   Pushes

Assign assignments for a course.

Parameters
assignments - Union[List[str], str]
The name or names of the assignments you wish to assign.
Defaults to all assignments.
overwrite - bool

Bypass overwrite prompts and nuke preexisting directories.

Default: False

.create_canvas_assignments() → Course

Create assignments in Canvas.

.schedule_grading() → Course

Schedule auto-grading cron jobs for all assignments.

Assignment

Assignment object for manipulating individual assignments.

from rudaux import Assignment

Instantiation

Assignment(
  name,
  duedate=None,
  duetime='23:59:59',
  points=1,
  manual=False,
  course=None
)
Parameters
name - str

The assignment's name.
This should be compatible with nbgrader's file naming convention.

Required. Example: 'homework_1'

duedate - str

The assignment's due date.

Required. Example: '2019-03-14'

duetime - str

The assignment's due time.

Default: '23:59:59'

points - int

The number of points the assignment is worth.

Default: 1

manual - bool

Is manual grading required?

Default: False

course - Course

The course the assignment belongs to.

Optional. Recommended usage is to subclass Assignment with the course as a class variable.

Returns - Assignment

An assignment object for performing different operations on a given assignment.

Methods

.update_or_create_canvas_assignment() → str

Search for an assignment in Canvas by assignment name.
If an assignment is found, update it. If not, create it.

Returns

A reporting status, whether the assignment was updated or created.

.schedule_grading() → Dict[str, str]

Schedule grading of an assignment by adding cron jobs to initialize auto-grading.
The job will be scheduled to run at the assignment's due datetime.

  • If no auto-grading job for that assignment exists in cron, create a job.
  • If an auto-grading job for that assignment is already scheduled in cron, update the job.

The job takes the following format:

  1. Initialize SSH agent
  2. Add instructors & students SSH-keys to SSH agent
  3. Run `rudaux grade` with output redirected to a log file in the instructors' repository
Returns

A status reporting dictionary with the keys 'close_time' and 'action'.

.collect() → Assignment   Commits   Pushes

Collect student copies an assignment.

Copy your students' notebooks from the fileserver into the instructors repo submitted/ directory. This also creates a submission in the gradebook on behalf of each student, which is necessary for nbgrader to record grades in the gradebook.

If the student fileserver is a ZFS filesystem, the closest snapshot that occurred after the due date will be used. This requires c.JupyterHub.zfs_regex and c.JupyterHub.zfs_datetime_pattern to be set in the course configuration.

.grade() → Assignment   Commits   Pushes

Auto-grade an assignment within a docker container.

.feedback() → Assignment   Commits   Pushes

Generate feedback reports for student assignments.

.submit() → Assignment   Commits   Pushes

Upload students' grades to Canvas.

Note: The functionality to upload generated feedback is the only piece of rudaux that has yet to be implemented. Currently, .submit() only uploads the student's grade to Canvas.