Metadata-Version: 2.4
Name: canvaslms
Version: 6.22
Summary: Command-line interface to Canvas LMS
License-Expression: MIT
License-File: LICENSE
Author: Daniel Bosk
Author-email: daniel@bosk.se
Maintainer: Daniel Bosk
Maintainer-email: dbosk@kth.se
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Utilities
Provides-Extra: diff
Provides-Extra: llm
Requires-Dist: appdirs (>=1.4.4)
Requires-Dist: argcomplete (>=2,<4)
Requires-Dist: arrow (>=1.2.3)
Requires-Dist: cachetools (>=5.3.1)
Requires-Dist: canvasapi (>=3.4.0,<4.0.0)
Requires-Dist: keyring (>=24.2,<26.0)
Requires-Dist: llm (>=0.36) ; extra == "llm"
Requires-Dist: llm-anthropic (>=0.19,<1.0) ; extra == "llm"
Requires-Dist: llm-azure (>=1.1,<3.0) ; extra == "llm"
Requires-Dist: llm-gemini (>=0.26.1,<1.0) ; extra == "llm"
Requires-Dist: llm-github-copilot (>=0.3.1,<1.0.0) ; extra == "llm"
Requires-Dist: llm-openai-plugin (>=0.7,<1.0) ; extra == "llm"
Requires-Dist: llm-openai-via-codex (>=0.1a0) ; extra == "llm"
Requires-Dist: llm-python (>=0.1,<1.0) ; extra == "llm"
Requires-Dist: patiencediff (>=0.2.18,<0.3.0) ; extra == "diff"
Requires-Dist: pdfminer.six (>=20231228)
Requires-Dist: pypandoc (>=1.11)
Requires-Dist: pytorial (>=0.10.0,<1.0)
Requires-Dist: pyyaml (>=5.1)
Requires-Dist: rich (>=13,<16)
Project-URL: Bug Tracker, https://github.com/dbosk/canvaslms/issues
Project-URL: Documentation, https://github.com/dbosk/canvaslms/releases
Project-URL: Repository, https://github.com/dbosk/canvaslms
Description-Content-Type: text/markdown

# canvaslms: A CLI to Canvas LMS.

This program provides a command-line interface for Canvas. The command
is `canvaslms` and it has several subcommands in the same style as Git.
`canvaslms` provides output in a format useful for POSIX tools, this
makes automating tasks much easier.

## Getting started

Start by login to your Canvas server

```bash
pipx install canvaslms
canvaslms login
```

Then let the built-in tutorials walk you through the commands against your
own courses. Each step opens a shell, tells you what to type, and checks what
you did; progress is saved between runs.

```bash
canvaslms tutorial list
canvaslms tutorial run getting-started
```

The first tutorial covers logging in and listing courses and users. Later
ones cover assignments and grading, course content, and letting a coding
agent such as Claude Code run `canvaslms` for you through the skills in
[dbosk/claude-skills](https://github.com/dbosk/claude-skills).

You can also use the package directly from Python.
This lets scripts and other CLI tools import `canvaslms` and reuse the same
authentication, configuration, and encrypted cache as the `canvaslms`
command-line tool.
The top-level `canvaslms.canvas` object is lazy-loaded, restored from the same
encrypted cache as the CLI, and saved automatically at process exit.

```python
import canvaslms

for course in canvaslms.canvas.get_courses():
    print(course.name)
```

Let's consider how to grade students logging into the student-shell SSH
server. We store the list of students' Canvas and KTH IDs in a file.

```bash
canvaslms users -sc DD1301 | cut -f 1,2 > students.csv
```

Then we check who has logged into student-shell.
```bash
ssh student-shell.sys.kth.se last | cut -f 1 -d " " | sort | uniq \
  > logged-in.csv
```

Finally, we check who of our students logged in.
We can set their grade to P and add the comment "Well done!" in
Canvas. We set the grades for the two assignments whose titles match the
regular expression `(Preparing the terminal|The terminal)`.
```bash
for s in $(cut -f 2 students.csv); do
  grep $s logged-in.csv && \
    canvaslms grade -c DD1301 -a "(Preparing the terminal|The terminal)" \
      -u $(grep $s students.csv | cut -f 1) \
      -g P -m "Well done!"
done
```

### Analyzing Quiz/Survey Results

The `quizzes analyse` command helps you analyze Canvas quiz or survey evaluation data. 
Download the Student Analysis Report CSV from Canvas and run:

```bash
# Markdown output (default, rendered with rich)
canvaslms quizzes analyse --csv survey_results.csv

# LaTeX output (for PDF compilation)
canvaslms quizzes analyse --csv survey_results.csv --format latex > report.tex
```

This will provide:
- Statistical summaries for quantitative questions (ratings, multiple choice)
- Proper handling of multi-select questions (comma-separated options)
- All individual responses for qualitative questions (free text)
- AI-generated summaries of qualitative responses (requires `llm`, install with `canvaslms[llm]`)

If you installed with the `[llm]` extra, configure your API keys:
```bash
llm keys set openai  # or another provider
```

### Managing Quiz Content

Quizzes written elsewhere, for example with `text2qti`, can be imported as
QTI 1.2 packages. First list your courses and their IDs, then replace `12345`
below with your course ID to upload a generated Classic quiz. Run the last
command after regenerating the ZIP to replace its questions. Replacing keeps
the quiz's ID and settings, requires an unpublished quiz without student
attempts, and writes a backup that `quizzes edit -f` can restore.

```bash
canvaslms courses --all --id
quiz_id=$(canvaslms quizzes import -c '^12345$' -f quiz.qti.zip --id-only)
canvaslms quizzes import -c '^12345$' -f quiz.qti.zip -a "^$quiz_id$" --replace-items
```

Add `--type new` to import as a New Quiz instead (fresh imports only), and
`canvaslms quizzes list -c '^12345$' -i` to list quizzes with their IDs.

View and edit quiz content directly from the command line:

```bash
# View quiz questions rendered as markdown
canvaslms quizzes view -c "Course" -a "Quiz Name"

# Edit quiz content interactively
canvaslms quizzes edit -c "Course" -a "Quiz Name"

# Export quiz items for backup or migration
canvaslms quizzes items export -c "Course" -a "Quiz Name" --importable

# Add questions to a quiz bank (use --example to see question formats)
canvaslms quizzes items add -c "Course" -a "Quiz Name" --example
```

### Editing Announcements and Discussions

Edit existing announcements using the same workflow as pages:

```bash
# Edit interactively (opens in editor)
canvaslms discussions edit -c "Course" -t "Announcement Title"

# Edit from a markdown file with YAML front matter
canvaslms discussions edit -c "Course" -t "Announcement Title" -f announcement.md
```

## Installation

Install the PyPI package using `pip` or `pipx`:
```bash
# Basic installation (Python 3.10+)
python3 -m pip install canvaslms
# or
pipx install canvaslms # recommended

# With optional LLM support for AI summaries (Python 3.10+)
python3 -m pip install canvaslms[llm]
# or
pipx install canvaslms[llm] # recommended
```

The `[llm]` extra includes the `llm` package and various LLM provider plugins (OpenAI, Anthropic, Gemini, Azure) for AI-powered features like quiz analysis summaries.

The Python API uses the same credential sources as the command-line tool:
system keyring, `CANVAS_SERVER`/`CANVAS_TOKEN`, or the config file.

Some subcommands use `pandoc`, so you will likely have to [install 
pandoc][pandoc] on your system manually.

[pandoc]: https://pandoc.org/installing.html

## Development

This project uses literate programming with [noweb](https://www.cs.tufts.edu/~nr/noweb/). 
The source code is written in `.nw` files which combine documentation and code.

### GitHub Copilot Setup

This repository includes GitHub Copilot configuration files:
- `.github/copilot-instructions.md`: Project context and coding guidelines
- `.copilotignore`: Files to exclude from Copilot context

The configuration helps Copilot understand the literate programming approach, 
Canvas LMS domain, and project-specific patterns.

