larzwatch

Portable, poll-based file & directory watching. Pure Python, zero dependencies.

Detect when files are created, modified, or deleted, and react. It works by comparing snapshots of modification times, so it has no native dependencies and behaves identically on every OS (where watchdog needs platform backends). Run a blocking loop, a background thread, or - crucially for tests - call poll() yourself and inspect the changes.

from larzwatch import Watcher

w = Watcher("src", patterns=["*.py"])
w.on_change(lambda c: print(c.type, c.path))   # 'created' / 'modified' / 'deleted'
w.watch(interval=1)          # blocking; or w.start() for a background thread

Why

• No native backends. watchdog is great but ships OS-specific extensions; larzwatch is pure Python and works the same everywhere - handy for CI, weird filesystems, and locked-down environments. Polling is perfectly fine for reload-on-change, build triggers, and config reloading.
• Testable. poll() returns the exact list of Change(type, path) since the last call, so you unit-test file-change logic without threads or sleeps.
• Filtered & recursive. patterns=["*.py", "*.toml"] and recursive=True/False.
• Zero dependencies.

Install

pip install larzwatch

Usage

from larzwatch import Watcher

w = Watcher("config", patterns=["*.yaml"])
w.on_change(reload_config)

# blocking loop
w.watch(interval=0.5)

# or background + your own loop
w.start(interval=0.5)
...
w.stop()

# or drive it yourself (tests, cron)
for change in w.poll():
    print(change.type, change.path)

Tests

python -m unittest discover -s tests -v   # 9 tests incl. create/modify/delete + background

The Larz stack

One of 30+ pure-Python, zero-dependency libraries at github.com/larz-scripter.

License

MIT (c) larz-scripter