Metadata-Version: 2.4
Name: canvas_downloader
Version: 0.1.1
Summary: A fast, safe, and customizable CLI tool to download course content from Canvas.
Project-URL: Homepage, https://github.com/jamubc/Canvas_Downloader
Project-URL: Issues, https://github.com/jamubc/Canvas_Downloader/issues
Author: jamubc
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: pathvalidate>=3.2.0
Requires-Dist: pdfkit>=1.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tqdm>=4.66.0
Description-Content-Type: text/markdown

# Canvas_Downloader 
![Open Source](https://img.shields.io/badge/Open_Source-brightgreen?style=flat-square) ![Educational](https://img.shields.io/badge/Educational-blue?style=flat-square) ![Canvas LMS](https://img.shields.io/badge/Canvas_LMS-red?style=flat-square&logo=canvas)

![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue?style=flat-square&logo=python&logoColor=white)
![PyPI Version](https://img.shields.io/badge/pypi-v0.1.1-blue?style=flat-square&logo=pypi&logoColor=white)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)
![CLI Tool](https://img.shields.io/badge/CLI-Tool-green?style=flat-square&logo=windowsterminal)
![PyPI - Downloads](https://img.shields.io/pypi/dm/canvas-downloader?style=flat-square)


A fast, safe, and customizable tool to download course content from Canvas (Instructure).

---
<img width="1280" height="720" alt="canvas_downloader_image-2" src="https://github.com/user-attachments/assets/6346efe3-f2c9-434b-b7c9-49d4a8e966eb" />

---

**Features:**
- **Safe:** Strictly read-only. Never modifies, deletes, or uploads any data.
- **Cross-Platform:** Works on macOS, Windows, and Linux.
- **Optimized:** Uses parallel downloading and smart rate-limiting to be fast without getting blocked.
- **Complete:** Can download Files, Modules, Pages, and Assignments (including attached solutions/descriptions).
- **Flexible:** download everything in structured folders, or flatten it; ignore specific files; pick specific courses.

**Why?**
- I was tired of downloading course content manually
- I wanted to have a backup of my courses
- I wanted to be able to access my courses offline
- I want to feed the downloaded content into a LLM
- I want to turn my courses into a searchable database
- I want to turn my courses into a quiz or practice test
---

## ⚡ Quick Start

### Recommended easiest usage:
1. **Install pipx** (if you don't have it):
   ```bash
   brew install pipx
   pipx ensurepath
   pipx install canvas_downloader
   canvas-downloader --help
   ```

### Option 1: Install via Pip (Fastest) - 📦 [![PyPI - Version](https://img.shields.io/pypi/v/canvas_downloader?style=flat-square)](https://pypi.org/project/canvas_downloader/)
This is the easiest way to use the tool. Get it directly from [PyPI](https://pypi.org/project/canvas_downloader/).
```bash
pip install canvas_downloader
```
Then run it anywhere:
```bash
canvas-downloader --help
```

### Option 2: Run from Source (with `uv`)
1. **Install uv** (if needed): `brew install uv` (macOS) or `pip install uv` (others).
    - (For more help see [uv docs](https://github.com/astral-sh/uv))
2. **Clone the repo:**
   ```bash
   git clone https://github.com/jamubc/Canvas_Downloader.git
   cd Canvas_Downloader
   ```
3. **Setup environment:**
   ```bash
   uv venv
   uv pip install -r requirements.txt
   ```
4. **Run:**
   ```bash
   uv run python downloader.py --help
   ```

---

## 🛠️ The Command Builder (Recommended)

Don't want to mess around with typing complex Terminal commands? We have a **built-in web UI** to click and configure your custom command!

**If you installed via pipx or pip:**
```bash
canvas-downloader --builder
```

**If running from source:**
```bash
uv run python downloader.py --builder
```

This will automatically open a local web server where you can drop in your API Token, Course ID, and check off any settings you want. Once you click "Copy Command", simply paste it back into your terminal to run it!

---

### Manual Basic Usage (Without Builder)
If you prefer not to use the builder, copy the text below into a text editor, replace your values, paste into terminal, and run. 
```bash
canvas-downloader \
    --api-token YOUR_API_TOKEN \
    --course-id YOUR_COURSE_ID \
    --output-dir ./my_course_download \
    --canvas-url https://canvas.instructure.com
```
*(Replace `YOUR_API_TOKEN`, `YOUR_COURSE_ID` with real values. Use your school's URL for `--canvas-url`)*

*For more information see [Canvas API Documentation](https://canvas.instructure.com/doc/api/courses.html)*

---

## 🛠️ Advanced Flags

If you are using the Web Builder, these options are available as easy-to-use checkboxes. If you are typing the command manually, you can customize the download by adding these flags:

| Flag | Description |
| :--- | :--- |
| `--include-assignments` | **Recommended.** Downloads assignment instructions and attached files (solutions, starter code, etc.) into an `Assignments/` folder. |
| `--include-submissions` | Download your own submissions (e.g. uploaded files, graded PDFs) into `Assignments/{Name}/Submissions/`. |
| `--no-structure` | Flattens all files into a single directory instead of organizing them by Module/Week. |
| `--ignore-pattern "*.ext"` | Skips files matching the pattern. Can be used multiple times. <br> *Example:* `--ignore-pattern "*.zip" --ignore-pattern "*.m"` |
| `--no-optimize` | Disables parallel downloading and smart rate-limiting. Use this if you encounter errors or want a strictly sequential, slower download. |
| `--force` | Force redownload of all files, ignoring any existing files (bypassing sync logic). |
| `--canvas-url URL` | Base URL of your Canvas instance. Defaults to `https://canvas.instructure.com`. <br> *Example:* `https://canvas.ubc.ca` |

### Example Usage:
```bash
uv run python downloader.py \
    --api-token <TOKEN> \
    --course-id 123456 \
    --output-dir ./Fall2024_Backup \
    --canvas-url https://canvas.ubc.ca \
    --include-assignments \
    --ignore-pattern "*.mp4" 
```

---

## 🔄 Re-running
To download new content later, just run the same command again. The script is safe to run multiple times; it will overwrite existing files with the latest versions from Canvas.

## 🙋 Common Questions (FAQ)

**Q: How do I download all my Canvas course contents at once?**
A: This tool is built exactly for that. It iterates through your entire course (Modules, Files, Assignments, Pages) and saves everything to your local computer in one go.

**Q: Can I backup my Canvas courses before I lose access?**
A: Yes! Use this tool at the end of the semester to create a permanent, offline archive of your materials (PDFs, PPTXs, Videos, etc).

**Q: Does this download videos and quiz content?**
A: It downloads files and assignment descriptions. Video support and specific quiz capture are currently being worked on (see Upcoming Features).

## Issues with usage?
*Im happy to help, please open an issue on GitHub.*

## Upcoming Features
-  Downloading Video files (currently unhandled)
- AI [Embedding](https://www.ibm.com/think/topics/embedding)
- Plug in usage for '[canvas-mcp-tool](https://github.com/jamubc/canvas-mcp-tool)' (please reach out if you are interested in testing it!)
- [Repomix](https://github.com/yamadashy/repomix) integration

## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
