Calendar subscription api

• Python 3.10+
• FastAPI
• Typer
• Uvicorn / Hypercorn
• Pydantic Settings
• uv
• pytest, Ruff, mypy, pre-commit

uv sync

Copy .env.example to .env only for local development. Never commit .env or real credentials.

uv run ical-api-server

pip install git+https://github.com/qsoyq/ical-api.git

uv run pytest -q

Run the full local validation suite:

uv run pre-commit run --all-files
uv run ruff check .
uv run ruff format --check .
uv run mypy ical_api tests

GitHub integration tests require the optional test_github_token, test_github_owner, and test_github_repo values in .env. They are skipped when those values are absent.

External network integration tests are disabled by default because they depend on third-party site availability and page structure. Run them explicitly with:

RUN_EXTERNAL_INTEGRATION_TESTS=1 uv run pytest -q

To run only the external site tests:

RUN_EXTERNAL_INTEGRATION_TESTS=1 uv run pytest -q tests/routes_test.py::test_vlrgg tests/routes_test.py::test_gofans

To run only the GitHub issues integration test after configuring the required .env values:

uv run pytest -q tests/routes_test.py::test_github_issues

uv build

1. Confirm main is green in CI.
2. Update pyproject.toml version.
3. Record validation evidence and rollback notes in docs/release/.
4. Tag the release from main.

Rollback is handled by reverting the release commit or deploying the previous known-good tag.

This repository uses GitHub Flow:

• main is the protected integration branch.
• Work happens on issue-linked branches named <type>/<issue-id>-<short-description>.
• Pull requests require CI, review, and a complete PR template before merge.

• CONTRIBUTING.md: development workflow and validation.
• SECURITY.md: vulnerability reporting and secret handling.
• docs/decisions/: architecture and process decisions.
• docs/release/: release and rollback notes.
• docs/postmortems/: incident reviews.

Maintained by @qsoyq.

Runtime settings are read from environment variables and local .env files through Pydantic Settings.

Common variables:

basic_auth_username
basic_auth_password
vlrgg_fetch_match_time_semaphore
vlrgg_fetch_timeout
http_host
http_port
http_reload
log_level