2 min read

pyssg.watch.events

Neutral filesystem events and pure coalescing.

This module is deliberately free of any third-party dependency and of any IO or clock access: it defines the backend-neutral :class:FsEvent that the incremental engine consumes and the pure :func:coalesce debounce merge. Keeping it pure makes the merge rules exhaustively unit-testable and lets the engine stay unaware that watchdog exists at all.

class FsEvent

A backend-neutral filesystem change.

The incremental engine only ever sees :class:FsEvent; the concrete watcher backend (watchdog) is hidden behind pyssg/watch so the backend can be swapped without touching core.

Attributes

kind: The change kind. path: For add/modify/delete the affected path; for move the source path. dest: Only set for move: the destination path. None otherwise.

coalesce(events: list[FsEvent]) -> list[FsEvent]

Merge a burst of events into the minimal equivalent set.

Within a single debounce window the same path may emit several raw events; collapsing them avoids redundant rebuild work. The function is pure: it has no IO and no clock, so it is fully deterministic and exhaustively testable.

Merge rules (per path, by final net effect):

• multiple modify -> a single modify;
• add then modify -> add (the file is still new, just edited);
• modify then delete -> delete (the edit no longer matters);
• add then delete -> dropped entirely (the file never settled);
• delete then add -> modify (the file was replaced in place, documented here so the engine treats a delete+recreate the same as an editor's atomic save);
• move events are preserved verbatim and never merged away, to keep the rename identity. A move's path (source) and dest (destination) are independent keys, so a later edit on the destination is tracked separately from the move itself.

Ordering: the result preserves the order in which each path first appears in events. This gives a stable, deterministic batch for downstream seeding.

Parameters

Returns