Reminders — API reference¶

CLI¶

main()

connection(db_path: Path | None = None)

Context manager that opens and closes a reminders database connection.

ensure_schema(conn: Connection) -> None

Apply any pending migrations to the database.

Safe to call on every connection open — checks a single integer and returns immediately if the schema is current.

PARAMETER	DESCRIPTION
`conn`	Open reminders database connection. TYPE: `Connection`

get_connection(db_path: Path | None = None) -> Connection

Open a reminders database connection.

The connection has WAL journal mode enabled (for concurrent reads) and the current schema applied via migrations.

PARAMETER	DESCRIPTION
`db_path`	Override the database path (defaults to `{data_dir}/reminders.db`). TYPE: `Path \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Connection`	A `sqlite3.Connection` ready for use. The caller must close it.

get_data_dir() -> Path

Return the mait-code data directory, creating it if needed.

get_db_path() -> Path

Return the reminders database path.

active_reminders(
    conn: Connection, *, now: datetime | None = None
) -> tuple[list[dict], list[dict]]

Return the active reminders split into (overdue, upcoming).

Both lists are ordered by due date. A reminder is overdue when its due time is at or before now (default: the current UTC time).

dismissed_reminders(conn: Connection) -> list[dict]

Return dismissed reminders, ordered by due date.

overdue_reminders(
    conn: Connection, *, now: datetime | None = None
) -> list[dict]

Return only the overdue active reminders, ordered by due date.