annie.core.logbook

Central event log — a dated file plus an in-memory store for the Log tab (infra).

Errors that happen in the background (lazy decode, render workers, the conversion batch, NiceGUI’s own callbacks) used to escape to the terminal and were easy to miss. The log book gives them one home:

• every event is appended to an in-memory ring buffer the Log tab reads, and

• mirrored to a per-session file named after the session database (e.g. annie_2026-01-02_09-00-00.log beside …/sessions/annie_…​.db) so a session’s log and its review DB are paired; renaming the DB renames the log (see LogBook.retarget()), keeping their names in lockstep.

The store is event-sourced: each event has a monotonic seq so a per-client poller can fetch only what is new (for toasts) without re-rendering everything. It is pure stdlib and thread-safe, so render/convert worker threads can report too.

Attributes

LEVELS	The levels an event can carry, most severe first.
MAX_MESSAGE_CHARS	Longest message shown in a toast or a Log tab row; the rest goes to the details.
LOG	The process-wide event log.

Classes

LogEvent	One recorded event.
LogBook	A thread-safe, bounded event store mirrored to a dated log file.

Functions

report(→ LogEvent)	Record an event on the global LOG.
report_exception(→ LogEvent)	Record an error event whose details are exc's formatted traceback.

Module Contents

annie.core.logbook.LEVELS: tuple[str, ...] = ('error', 'warning', 'info')

The levels an event can carry, most severe first.

class annie.core.logbook.LogEvent

One recorded event.

seq

Monotonic sequence number (for incremental polling).

timestamp

When it was recorded.

level

One of LEVELS.

message

Short, one-line summary.

details

Optional long text (e.g. a traceback) for the expandable view.

property time_text: str

The timestamp formatted as YYYY-MM-DD HH:MM:SS.

as_clipboard() → str

The event rendered as plain text for the Copy button.

annie.core.logbook.MAX_MESSAGE_CHARS = 200

Longest message shown in a toast or a Log tab row; the rest goes to the details.

class annie.core.logbook.LogBook(capacity: int = 2000)

A thread-safe, bounded event store mirrored to a dated log file.

Create an empty store.

Parameters:

capacity – Maximum number of events kept in memory (oldest dropped).

attach_file(log_dir: str | pathlib.Path, name: str) → pathlib.Path

Mirror events to <log_dir>/<name>.log and return the file path.

Parameters:

• log_dir – Directory to write the log file into (created if needed).

• name – Base filename (no suffix) — the session database’s stem, so the log and its review DB share a name and can be found together.

Returns:

The log file path.

retarget(db_path: str | pathlib.Path) → pathlib.Path | None

Rename the active log file to match a (renamed) session database.

The log and its review DB are paired session data, so when the DB is renamed the log follows: the current log file’s content moves to <logs_dir>/<db_stem>.log and the file handler re-points there. If a log by that name already exists (e.g. switching to a previously used DB), events are appended to it rather than clobbering it.

Parameters:

db_path – The new active database path; its stem names the log.

Returns:

The new log path, or None if no log file is attached yet.

add(level: str, message: str, details: str = '') → LogEvent

Record an event (and mirror it to the file, if attached).

A long or multi-line message (e.g. one that embeds an exception’s text, which for torchcodec runs to 150 lines) is cut to its first line for the toast and the Log tab row; the full text moves to the top of details, so nothing is lost.

Parameters:

• level – One of LEVELS.

• message – One-line summary.

• details – Optional long text.

Returns:

The stored LogEvent.

events() → list[LogEvent]

Return a snapshot of all stored events, oldest first.

since(seq: int) → tuple[list[LogEvent], int]

Return events newer than seq and the latest sequence number.

Parameters:

seq – The last sequence number the caller has already seen.

Returns:

A (new_events, latest_seq) pair.

latest_seq() → int

Return the most recent sequence number (0 when empty).

clear() → None

Drop all in-memory events (the file is untouched).

annie.core.logbook.LOG

The process-wide event log.

annie.core.logbook.report(message: str, *, level: str = 'error', details: str = '') → LogEvent

Record an event on the global LOG.

Parameters:

• message – One-line summary.

• level – One of LEVELS.

• details – Optional long text.

Returns:

The stored LogEvent.

annie.core.logbook.report_exception(message: str, exc: BaseException | None) → LogEvent

Record an error event whose details are exc’s formatted traceback.

Parameters:

• message – One-line summary.

• exc – The exception to format into the details, or None.

Returns:

The stored LogEvent.