82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# Cantaloupe Downloader — Agent Guide
|
|
|
|
CLI tool for exporting machine list data (Excel .xlsx) from mycantaloupe.com. Used as the upstream data source for the Canteen asset tracking pipeline.
|
|
|
|
## Stack
|
|
|
|
- **Python** 3.11+, **click** (CLI framework)
|
|
- **httpx** (async HTTP client with anti-forgery token handling)
|
|
- **playwright** (browser automation fallback for JS challenges)
|
|
- **openpyxl** (Excel file reading)
|
|
- **respx** / **pytest** (testing)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
cantaloupe/
|
|
__init__.py
|
|
__main__.py # Entry: python -m cantaloupe
|
|
cli.py # Click CLI: export, diff, configure commands
|
|
config.py # Config file management (~/.cantaloupe.env)
|
|
diff.py # Compare two Excel exports
|
|
|
|
src/
|
|
auth.py # Login: httpx anti-forgery token or Playwright fallback
|
|
download.py # Export POST → save .xlsx
|
|
|
|
tests/
|
|
test_auth.py
|
|
test_cli.py
|
|
test_diff.py
|
|
test_download.py
|
|
|
|
API.md # API investigation notes
|
|
README.md
|
|
requirements.txt
|
|
```
|
|
|
|
## How to Run
|
|
|
|
```bash
|
|
# Export machines list
|
|
python -m cantaloupe export
|
|
|
|
# With scheduled-output path
|
|
python -m cantaloupe export --scheduled
|
|
|
|
# Compare two exports
|
|
python -m cantaloupe diff file1.xlsx file2.xlsx
|
|
|
|
# Configure credentials
|
|
python -m cantaloupe configure
|
|
```
|
|
|
|
## Key Architecture
|
|
|
|
- **Two auth strategies:**
|
|
1. **Primary:** httpx — anti-forgery token extraction from HTML, form-based login
|
|
2. **Fallback:** Playwright — full browser automation for JS challenges
|
|
- Config stored in `~/.cantaloupe.env` (credentials)
|
|
- Exports go to `~/cantaloupe-exports/` with manifest tracking via `manifest.json`
|
|
- `diff` command compares two exports cell-by-cell
|
|
|
|
## Production
|
|
|
|
- **CLI tool only** — no server, no systemd
|
|
- Triggered via cron: `cantaloupe-sync.sh` runs every 6 hours
|
|
- Part of the Canteen pipeline: Cantaloupe → downloader → sync API
|
|
|
|
## Environment Variables
|
|
|
|
| Var | Description |
|
|
|-----|-------------|
|
|
| CANTALOUPE_EMAIL | Login email |
|
|
| CANTALOUPE_PASSWORD | Login password |
|
|
| CANTALOUPE_OTP_SECRET | Optional TOTP secret for 2FA |
|
|
|
|
## Pitfalls
|
|
|
|
- Cantaloupe may show JS challenges — Playwright fallback handles this but requires browser binaries (`playwright install chromium`)
|
|
- Export format may change on Cantaloupe's side (they're a third-party SaaS) — `diff.py` detects structural changes
|
|
- Auth tokens expire; each run re-authenticates
|