Metadata-Version: 2.4
Name: course-dl
Version: 0.3.3
Summary: Download Blackboard course exports from Curtin University's LMS
Author: Michael Borck
Author-email: Michael Borck <michael@borck.dev>
License-Expression: MIT
Requires-Dist: playwright
Requires-Dist: python-dotenv
Requires-Dist: rapidfuzz
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/michael-borck/course-dl
Project-URL: Source, https://github.com/michael-borck/course-dl
Description-Content-Type: text/markdown

# course-dl

Download Blackboard course exports from Curtin University's LMS as Common Cartridge
packages, useful for migrating courses to Canvas or other LMS platforms.

## Installation

```bash
uv tool install course-dl
playwright install chromium
```

Or install from source:

```bash
git clone https://github.com/michael-borck/course-dl.git
cd course-dl
uv sync
uv run playwright install chromium
```

## Usage

Exporting is a **two-step process** because Blackboard takes 15–30 minutes to
build each Common Cartridge package.

### Step 1: Trigger builds

```bash
# Trigger builds for specific courses (fuzzy-matched)
course-dl build COMP1000 "Data Structures"

# Trigger builds for all courses
course-dl build --all

# Only courses from a specific teaching period
course-dl build --term "Semester 1 2025"
course-dl build --term 2025 --all

# Interactive picker — no args, select from a list
course-dl build
```

Blackboard queues the export and confirms with "This action has been queued."
You can trigger builds for many courses at once — they build in parallel on the
server.

### Step 2: Download packages

Wait 15–30 minutes, then download with the **same search terms**:

```bash
# Download matching courses
course-dl download COMP1000 "Data Structures"

# Download all
course-dl download --all

# Interactive picker
course-dl download
```

Courses with no package ready yet will show "not ready" — just run the command
again later.

### Typical batch workflow

```bash
# 1. Trigger all builds
course-dl build --all

# 2. Wait 15-30 minutes...

# 3. Download everything
course-dl download --all -o exports/
```

### Common options

```
course-dl [OPTIONS] {build,download}

Options (before subcommand):
  -u, --username STR    Curtin username
  -p, --password STR    Curtin password
  --visible             Show the browser window (default: headless)
  --timeout INT         Navigation timeout in ms (default: 60000)

Subcommand options:
  SEARCH...             Search terms (fuzzy-matched against course titles)
  -f, --file PATH       File with search terms (one per line)
  --all                 Select all courses
  --term STR            Teaching period to select (e.g. 'Semester 1 2025')
  --match-threshold INT Fuzzy match score 0-100 (default: 60)

Download-only options:
  -o, --output-dir PATH Output directory (default: ./exports/)
  --overwrite           Re-download courses that already exist locally
```

### Fuzzy matching

Course titles in Blackboard are long. You don't need the full title:

```bash
course-dl build COMP1000              # matches by unit code
course-dl build "Unix and C"          # matches by partial name
course-dl build "Data Structures"     # matches by topic
```

### Interactive picker

When no search terms are provided, a numbered selection prompt is shown.
Enter numbers separated by commas or spaces, with optional ranges:

```
Selection: 1          # just the first course
Selection: 1,3-5      # first course plus courses 3 to 5
Selection: all        # everything
Selection:            # (empty) cancel
```

### Older year/semester courses

Blackboard's course page has a teaching-period dropdown that filters which
courses are shown. The CLI drives the same dropdown:

- **Interactive mode** (`course-dl build` with no args) shows a numbered
  teaching-period menu first, then the course picker for that period.
- **`--term`** picks it automatically:

```bash
course-dl build --term "Semester 1 2025"
course-dl download --term 2024 --all -o exports/
```

If Blackboard doesn't render a period dropdown, `--term` falls back to
filtering course titles.

Other selection methods work within the chosen period — search terms
(`course-dl build ISAD1000`) or a file of unit codes/names, one per line:

```bash
cat my-units.txt
ISAD1000
"Unix and C"
course-dl build -f my-units.txt
```

Note: only courses still in your Blackboard enrolment list can be exported.
If Curtin removed you from an old site, it won't appear in any period.

### Skip behaviour

`course-dl download` skips courses that already have a `.zip` or `.imscc` file
in the output directory matching the unit code. Use `--overwrite` to force
re-download.

When only one package exists on Blackboard, it is deleted after download
(since we created it). When multiple packages exist, none are deleted and the
tool logs which one was downloaded.

## Credentials

Credentials are resolved in order:

1. CLI flags (`-u`, `-p`)
2. Environment variables (`CDL_USERNAME`, `CDL_PASSWORD`)
3. `.env` file (searched in order):
   - `~/.config/course-dl/.env`
   - `~/.course-dl.env`
   - `./.env`
4. Interactive prompt

Copy `.env.example` to one of the above locations:

```bash
cp .env.example ~/.config/course-dl/.env
```

## License

MIT
