qsr_ics

Convert QSR schedule .eml files into weekly .ics calendar files (RFC 5545). Runs locally as a Python CLI; no network services.

Requirements

• Python 3.13+

Install

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate

pip install .
cp .env.example .env
# Edit .env: at least TIMEZONE; DATABASE_PATH/LOG_DIR optional (see runbook)

Configuration

• Copy .env.example to .env and set at least:
  • TIMEZONE — IANA name (e.g. America/Los_Angeles) for correct export times
• Optional (omit for default per-user data layout; see docs/public/runbook.md):
  • DATABASE_PATH — path to the SQLite file
  • LOG_DIR — where JSONL logs are written
  • APP_ROOT or QSR_APP_ROOT — override the resolved data root
• Retention: RETENTION_DAYS_SCHEDULE / RETENTION_DAYS_LOGS (see .env.example).

Usage

# Interactive menu: locations, employees, view schedule, Inbox scan, settings, optional export
python -m qsr_ics

# Ingest one or more .eml files or a directory of direct-child .eml files
python -m qsr_ics --eml path/to/schedule.eml
python -m qsr_ics --eml path/to/dir

# Location aliases (ICS SUMMARY)
python -m qsr_ics alias list
python -m qsr_ics alias set

iOS: Send the .ics as a file attachment (Messages, Mail, Files). Do not open an https:// link to the file — iOS may treat it as a subscription calendar. Exported files use CRLF, omit METHOD on VCALENDAR, and include iOS-friendly STATUS / SEQUENCE / TRANSP on events.

Operator steps (install, data folders, Inbox, uninstall) are summarized in docs/public/runbook.md when this repository (or a release bundle) includes that file.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the LICENSE file in this repository for the full text.