Overview

Parse one or more ICS calendar files, merge their events, sort by start time, and print the result in several formats.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Basic usage

--filepath is required and may be repeated. Paths are read in order; events from every file are combined and sorted by start time.

ics_render --filepath calendar-a.ics --filepath calendar-b.ics

Without an output flag, ics_render prints a text table to stdout.

Output modes

Output format flags are mutually exclusive. Pick one per run.

Default text table

Sorted columns: Start, Duration, Name.

ics_render --filepath tests/fixtures/early.ics --filepath tests/fixtures/late.ics

Start                      Duration    Name
-------------------------  ----------  ----------------
2024-06-01T09:00:00+00:00  0:30:00     Morning standup
2024-06-10                 1 day       All-day planning
2024-06-15T14:00:00+00:00  1:00:00     Release review

JSON Lines (--jsonl)

Each event is one JSON object on its own line. Keys are lower-case, underscore-separated names taken from the original VEVENT properties (summary, start, end, and so on). Timestamp values use ISO 8601.

ics_render --jsonl --filepath tests/fixtures/early.ics --filepath tests/fixtures/late.ics

{"summary": {"parameters": {}, "value": "Morning standup"}, "start": {"parameters": {}, "value": "2024-06-01T09:00:00+00:00"}, "end": {"parameters": {}, "value": "2024-06-01T09:30:00+00:00"}, "uid": {"parameters": {}, "value": "early-1@example"}, "description": {"parameters": {}, "value": "Daily team sync"}}
{"summary": {"parameters": {}, "value": "All-day planning"}, "start": {"parameters": {"value": "DATE"}, "value": "2024-06-10"}, "end": {"parameters": {"value": "DATE"}, "value": "2024-06-11"}, "uid": {"parameters": {}, "value": "late-2@example"}}
{"summary": {"parameters": {}, "value": "Release review"}, "start": {"parameters": {}, "value": "2024-06-15T14:00:00+00:00"}, "end": {"parameters": {}, "value": "2024-06-15T15:00:00+00:00"}, "uid": {"parameters": {}, "value": "late-1@example"}}

Redirect to a file:

ics_render --jsonl --filepath calendar.ics > events.jsonl

HTML month grid (--html)

A self-contained HTML page with a traditional calendar layout: weeks as rows, days as columns (Sunday first), events listed inside each day cell. Timed events show HH:MM before the name.

When events span more than one month, a Month drop-down at the top switches between month grids. The visible grid stays in sync with the selection after refresh.

Click an event to open a detail modal (start, stop, duration, description). Use Copy beside the description to copy it to the clipboard; a Copied toast confirms success.

ics_render --html --filepath tests/fixtures/early.ics --filepath tests/fixtures/late.ics > calendar.html

Open in a browser:

xdg-open calendar.html

HTML table (--html-table)

A self-contained HTML page: one table row per event with Start, Stop, Duration, and Name. Hover the name to see the description as a tooltip.

ics_render --html-table --filepath tests/fixtures/early.ics --filepath tests/fixtures/late.ics > calendar-table.html

HTML list (--html-list)

A self-contained HTML page: each event is a spaced block with name, start, stop, duration, and the full description at the bottom (newlines rendered as line breaks).

ics_render --html-list --filepath tests/fixtures/early.ics --filepath tests/fixtures/late.ics > calendar-list.html

Tests

python -m pytest -q

Regenerating README screenshots

Screenshots under asset/screenshots/ are produced from the test fixtures using Brave in headless mode:

./make_screenshots

Requires brave (or adjust the browser command in the script). Intermediate .html files in asset/screenshots/ are updated at the same time. Text table and JSONL examples in this README are sample output from the same fixtures.