pyfileindex.watcher.FileSystemWatcher

class pyfileindex.watcher.FileSystemWatcher(path: str)

Bases: object

Runs watchfiles in a background thread to collect file system change events for a path, so callers can drain already-collected changes instead of repeatedly rescanning the file system.

watchfiles is an optional dependency of pyfileindex: importing this module never requires it, only start() does.

Callers that hold a watcher alive for the lifetime of the process (e.g. via a path-keyed singleton cache) may never trigger its __del__ during normal execution – it would only run during interpreter shutdown, by which point CPython may already be tearing down the modules and C-API state that the background thread’s native extension depends on, which can crash the process instead of cleanly joining the thread. start() therefore registers stop() with atexit, so every watcher is joined while the interpreter is still fully intact, before that teardown begins.

Parameters:

path (str) – file system path to watch

__init__(path: str) → None

Methods

__init__(path)
drain_pending_changes([timeout])	Atomically take the file system changes collected since the last call.
start()	Start the background file system watcher.
stop()	Stop the background file system watcher.

Attributes

thread

drain_pending_changes(timeout: float = 0.0) → set

Atomically take the file system changes collected since the last call.

A change made on disk is not visible immediately: it takes a small amount of time for the OS to report it and for the background thread to pick it up. If timeout is 0, whatever has arrived so far is returned right away, which may be nothing even though a change just happened. Passing a small timeout instead waits for that change to arrive (or for the timeout to elapse) before returning, without blocking any longer than necessary.

Unrelated changes collected by an earlier, undrained call already leave the “changes available” signal set, which would otherwise let a caller’s wait return immediately even though the change it is actually waiting for is still in flight. The signal is therefore cleared before waiting, so a timeout > 0 always gives the background thread a real chance to deliver the latest change.

Parameters:

timeout (float) – max time in seconds to wait for a pending change to arrive if none is available yet (optional)

Returns:

set of (watchfiles.Change, path) tuples

Return type:

set

start() → None

Start the background file system watcher.

watchfiles.watch() only registers the underlying OS-level watch the first time the generator is advanced, which otherwise happens lazily inside the background thread. To avoid missing changes made right after construction, the generator is advanced once synchronously here before the background thread takes over.

stop() → None

Stop the background file system watcher. Safe to call even if no watcher is running.