shawn/cantaloupe-downloader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add diff tracking documentation

Shawn
2026-05-21 18:55:51 -04:00
parent 58e221a0f5
commit 1e52721ddb
1 changed files with 32 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Home.md
+32 -3
@@ -4,10 +4,11 @@ Automation for exporting machine data from mycantaloupe.com.
**Repo:** [shawn/cantaloupe-downloader](https://gitea.ourpad.casa/shawn/cantaloupe-downloader)
**Local:** `~/projects/cantaloupe-downloader/`
**Latest commit:** `e408867`
## Purpose
CLI tool to authenticate with mycantaloupe.com and download the Machine List Excel export via direct HTTP (httpx) — no browser automation needed.
CLI tool to authenticate with mycantaloupe.com and download the Machine List Excel export via direct HTTP (httpx) — no browser automation needed. Built-in diff tracking compares exports across runs.
## Architecture
@@ -15,8 +16,9 @@ CLI tool to authenticate with mycantaloupe.com and download the Machine List Exc
- **`src/download.py`** — Export download automation
- Authenticate → verify access → POST `/cs4/VueMachineList/ExcelExport` → save .xlsx
- **`cantaloupe/`** — Click CLI wrapper (`python -m cantaloupe export`)
- `cantaloupe/cli.py` — export + configure commands
- `cantaloupe/cli.py` — export + diff + configure commands
- `cantaloupe/config.py` — credential management (`~/.cantaloupe.env`)
- `cantaloupe/diff.py` — diff engine comparing xlsx by Asset ID, manifest tracking
## Quick Start
@@ -34,6 +36,12 @@ export CANTALOUPE_PASSWORD="your-password"
# Download export
python -m cantaloupe export --output ./exports/
# Download + auto-compare with previous export
python -m cantaloupe export --diff
# Compare two exports
python -m cantaloupe diff --from old.xlsx --to new.xlsx
# Cron/scheduled mode
python -m cantaloupe export --scheduled --output /data/exports/
```
@@ -43,6 +51,7 @@ python -m cantaloupe export --scheduled --output /data/exports/
| Command | Description |
|---|---|
| `python -m cantaloupe export` | Download machine list Excel |
| `python -m cantaloupe diff` | Compare two exports and show changes |
| `python -m cantaloupe configure` | Save credentials to `~/.cantaloupe.env` |
### Export Options
@@ -52,9 +61,29 @@ python -m cantaloupe export --scheduled --output /data/exports/
| `-o, --output PATH` | Output directory or file path |
| `--headless / --visible` | Browser mode for Playwright fallback |
| `--scheduled` | Non-interactive cron mode |
| `--diff / --no-diff` | Auto-compare with previous export after download |
| `--email TEXT` | Override account email |
| `--password TEXT` | Override account password |
### Diff Options
| Flag | Description |
|---|---|
| `--from PATH` | Older xlsx file (default: auto from manifest) |
| `--to PATH` | Newer xlsx file (default: auto from manifest) |
| `--id-column NAME` | Column to use as unique key (auto-detected) |
| `--json` | Output machine-readable JSON |
## Diff Tracking
Compares two Excel exports keyed on **Asset ID** (auto-detected, case-insensitive).
Reports:
- 🟢 New machines added
- 🔴 Machines removed
- 🟡 Machines with changed fields
Manifest at `~/.cantaloupe-exports/manifest.json` tracks export history for auto-diff.
## Credential Priority
1. `CANTALOUPE_EMAIL` / `CANTALOUPE_PASSWORD` environment variables
@@ -71,7 +100,7 @@ See [API Investigation](https://gitea.ourpad.casa/shawn/cantaloupe-downloader/wi
## Test Status
86 tests passing (27 auth + 20 download + 39 CLI) as of commit `9c3d3ef`.
130 tests passing (27 auth + 20 download + 39 CLI + 44 diff) as of commit `e408867`.
## Environment Variables