Canvas Mastery Toolkit

This repository contains a toolkit to support implementations of the learning mastery gradebook on Canvas.

Requirements

• MATLAB: 2023a or later¹
• Python: 3.8 or later²

Python dependencies

• bullet
• canvasapi
• click
• console-menu
• keyring
• numpy
• pandas
• python-dateutil

Installation

To install the Python package, run, in the cloned repository:

pip install -e .

Then, to install the toolkit console, run:

canvas install

This will prompt for the base URL of the institution's Canvas site, such as https://canvas.cornell.edu.

If the above fails because the command canvas was not found, there may be issues with the Python PATH.

Configuration

The toolkit is primarily configured through a file in the user's home directory named .canvas-toolkit-config. This file is generated by the installation steps above.

To configure Canvas course entries, which are needed to use the toolkit console, run:

canvas courses add <course_name> <canvas_id>

where <course_name> is a short name of choice for the course, such as "sandbox" or "diffeq", and <canvas_id> is the corresponding Canvas ID, usually found in the course's Canvas URL.

To list all configured course entries, run:

canvas courses list

To remove a course entry, run:

canvas courses remove <course_name>

To change individual configuration values, run:

canvas config <address> <value>

where <address> is a unique entry address or identifier, such as canvas_url or sandbox.canvas_course_id, and <value> is the new value to set.

To recall configuration values, run:

canvas config <address>

Note that ~/.canvas-toolkit-config can be edited directly with a text or code editor, but it is critical not to modify the structure of this file. Only configuration values should be adjusted.

Environment

The toolkit uses an environmental variable to define the connection between MATLAB and Python. To get started, copy .env.example to .env and open in a text or code editor of choice. Then, set PYTHON_COMMAND to the system's Python executable, which can be found on Mac and Linux by running which python or which python3.

Documentation

For details on usage and syntax, see the information provided in docs/.

Footnotes

1. MATLAB 2023a introduced support for environmental variables, which the toolkit leverages in order to decouple user-dependent configuration values from version-controlled code. ↩

2. Python 3.8 is the minimum version supported by the pandas package, which is central to several features in the toolkit. Additionally, Python 3.8 introduced support for assignment expressions, which help write clearer, well-intentioned list and dictionary comprehensions and are used throughout the toolkit. ↩