First Occurrences
A terminal book for the first time each year something happens (first frost, the swallows). You enter a date against an event with uv run firsts.py add first swallow, or paste the years you remember with uv run firsts.py backfill, and uv run firsts.py prints one column per year with a colophon under it, like the last page of a printed book. It runs on Python's standard library through uv and needs nothing else. Its only input is what you type or paste, the real clock, and one plain text file that is only ever added to: $FIRSTS_FILE if set, otherwise ~/firsts.txt. The first entry for an event and a year is final; a correction goes in as an erratum line below it.
Install once, so it can be called firsts from anywhere:
ln -s "$PWD/firsts.py" ~/.local/bin/firsts
Commands
firsts add EVENT... [--date YYYY-MM-DD] [--recalled] [--note TEXT]
firsts backfill [--seen] one "YYYY-MM-DD event | note" per line, then Ctrl-D
firsts erratum EVENT... YEAR TEXT...
firsts [table [--from YEAR] [--days]]
The file
# First occurrences. One line per entry. A line is never changed.
# Opened 2026-03-11.
2026-03-11 | seen | swallow | over the mill pond
2025-04-02 | recalled | swallow | about the second week, I think
erratum | 2026 | swallow | filed 2026-04-02 | the 11th was a house martin; the first swallow was the 14th
Fields are separated by | . Basis is seen or recalled. The note is the rest of the line. The file is yours and may be edited by hand; the tool reads it leniently, reports what it cannot read, and only ever appends.
Checks
NO_COLOR=1 uv run python -m unittest
uv run python e2e.py # Linux with tmux; the full acceptance run, log in out/e2e.log
Colophon
Catalogue number 54 of 100. Set in the terminal's own typeface, one colour held in reserve. The example above is the grammar, not a record. This edition has changed no line.
normal is dead
Files
- README.md
- e2e.py
- firsts.py
- out/e2e.log
- out/term/add-80.html
- out/term/add-80.txt
- out/term/backfill-80.html
- out/term/backfill-80.txt
- out/term/days-80.html
- out/term/days-80.txt
- out/term/empty-80.html
- out/term/empty-80.txt
- out/term/erratum-80.html
- out/term/erratum-80.txt
- out/term/from-40-plain.html
- out/term/from-40-plain.txt
- out/term/help-80.html
- out/term/help-80.txt
- out/term/refusal-80.html
- out/term/refusal-80.txt
- out/term/table-40-plain.html
- out/term/table-40-plain.txt
- out/term/table-40.html
- out/term/table-40.txt
- out/term/table-80-plain.html
- out/term/table-80-plain.txt
- out/term/table-80.html
- out/term/table-80.txt
- test_firsts.py