1 min read
pyssg.watch.watcher
Native, event-driven filesystem watcher.
This is the ONLY module allowed to import watchdog. It wraps
watchdog.observers.Observer (the OS-native backend: inotify/FSEvents/
ReadDirectoryChangesW/kqueue) and normalises raw watchdog events into neutral
:class:~pyssg.watch.events.FsEvent instances.
Polling is forbidden: the constructor refuses a
PollingObserver and, if the native backend is unavailable, fails loudly
instead of silently degrading. Debouncing is a timer driven by the event stream
(a :class:threading.Timer reset on each event), never a periodic FS scan.
class FsWatcher
Native event-driven watcher with stream-debounced batching.
Parameters
| Name | Type | Description |
|---|---|---|
roots | Directories to watch recursively (content/layout/config dirs). | |
ignore | Extra ignore globs from config; combined with the always-on editor/VCS/output noise (see :mod:`pyssg.watch.ignore`). | |
debounce_ms | Quiet period in milliseconds; a burst is flushed once no new event has arrived for this long. Must be positive. |
Raises
| Type | Description |
|---|---|
RuntimeError | If the resolved observer is a ``PollingObserver`` or the native backend is otherwise unavailable. |
FsWatcher.__init__(self, roots: list[str], ignore: list[str], debounce_ms: int = 80) -> None
FsWatcher.observer_name(self) -> str
Class name of the resolved observer (for regression assertions).
FsWatcher.run(self, on_batch: Callablelist[FsEvent, None]) -> None
Start watching; flush coalesced bursts to on_batch.
The observer runs on its own thread. This call only schedules and starts
it; it returns immediately so the caller owns the main thread. Use
:meth:stop to tear down.
Parameters
| Name | Type | Description |
|---|---|---|
on_batch | Invoked once per quiet burst with the coalesced events. |
Raises
| Type | Description |
|---|---|
RuntimeError | If called more than once on the same watcher. |
FsWatcher.stop(self) -> None
Stop the observer and cancel any pending debounce timer.
Safe to call even if :meth:run was never called or already stopped.