Watchdog

Watchdog is a Python library for monitoring filesystem events - file/directory creation, deletion, modification, and moves - using each platform’s native notification mechanism: inotify on Linux, FSEvents on macOS, kqueue on BSD, and ReadDirectoryChangesW on Windows, with a polling fallback everywhere else. It exposes both an Observer/EventHandler API for embedding filesystem watching directly in Python applications and a watchmedo shell utility for triggering shell commands or auto-restarting processes on file changes, making it a common building block behind live-reload tooling, build watchers, and sync utilities.

What You Get

• A unified Observer class that dispatches filesystem events to registered EventHandler subclasses regardless of the underlying OS notification API
• Native backend implementations for inotify (Linux), FSEvents (macOS), kqueue (BSD), and the Win32 ReadDirectoryChangesW API, plus a portable polling observer as a fallback
• Pattern-matching event handlers (PatternMatchingEventHandler, RegexMatchingEventHandler) for filtering events by filename glob or regex without writing dispatch logic by hand
• The watchmedo command-line utility for running shell commands, auto-restarting a process, or logging events whenever matched files change, with no Python code required
• A DirectorySnapshot/DirectorySnapshotDiff API for polling-based change detection when native OS events aren’t available or desired

Common Use Cases

• Building a live-reload development server that restarts or refreshes when source files change
• Triggering an incremental build, test run, or sync job automatically whenever files in a watched directory are modified
• Implementing a file-sync or backup tool that reacts to filesystem changes in near real time instead of polling on a timer
• Using the watchmedo CLI to wire an arbitrary shell command to file-change events without writing any Python

Under The Hood

Architecture Watchdog centers on src/watchdog/observers, which contains one module per platform backend (inotify.py/inotify_c.py wrapping Linux’s inotify via ctypes, fsevents.py for macOS’s FSEvents, kqueue.py for BSD, read_directory_changes.py/winapi.py for Windows) all conforming to a common BaseObserver interface defined in observers/api.py; the Observer class chosen at import time is simply an alias for whichever backend matches the running platform. Events flow from the backend thread into EventQueue, which dispatches to registered EventHandler subclasses (in src/watchdog/events.py), decoupling event production from consumption. src/watchdog/tricks builds the watchmedo CLI’s shell-command and process-restart behaviors on top of the same handler interface. Polling-based detection (observers/polling.py) uses DirectorySnapshot/DirectorySnapshotDiff to diff directory state between scans as a portable fallback. Tech Stack Python with a thin C extension/ctypes layer for the Linux inotify backend and platform-specific optional dependencies (pyobjc for FSEvents on macOS); packaged via setuptools with cibuildwheel for building platform wheels. Type checking is enforced via a strict mypy configuration (disallow_untyped_defs, warn_unused_ignores) in pyproject.toml. Code Quality The tests/ directory contains 26 test modules exercising each observer backend plus the pattern-matching handlers and directory-snapshot diffing; coverage is tracked via tool.coverage.report config excluding type-checking-only branches. The long single-maintainer-plus-contributors history (gorakhargosh holds the majority of commits, with steady community contributions) reflects a mature, incrementally hardened codebase. API Design The Observer/EventHandler pattern is a small, well-documented surface: subclass EventHandler, override the on_* callbacks you care about, schedule it against a path, and start the observer — this requires little boilerplate for the common case. The pattern-matching handler subclasses (PatternMatchingEventHandler) further reduce boilerplate for the common case of filtering by filename pattern, though users needing to differentiate platform-specific event nuances (e.g. move-event semantics differing between inotify and FSEvents) must dig into backend-specific docs.