libfilewatcher

Cross-platform file system watcher for real-time monitoring

Install

pip install libfilewatcher

Usage

from libfilewatcher import FileWatcher, FileWatcherEvent

watcher = FileWatcher(root_dir="/path/to/watch")

def on_file_change(event: FileWatcherEvent):
    print(f"File {event.event_type}: {event.file}")

watcher.add_callback(on_file_change)
watcher.start()

# Or use async
import asyncio
event = await watcher.get_event(timeout=5.0)

API

FileWatcherEvent

Dataclass representing a file system event.

• file: str — Absolute path to the file
• event_type: str — One of "add", "change", "unlink"

FileWatcher

Main class for watching file system changes.

FileWatcher(
    root_dir: str | None = None,
    ignore_patterns: list[str] | None = None,
    enabled: bool = True,
)

Methods:

• start() — Start watching
• stop() — Stop watching
• add_callback(callback) — Add event callback
• remove_callback(callback) — Remove callback
• async get_event(timeout) — Get next event
• is_running — Property checking if watcher is active

FileWatcherManager

Manage multiple watchers.

manager = FileWatcherManager()
watcher = manager.create_watcher("name", root_dir="...")
manager.start_all()
manager.stop_all()

CLI

# Watch current directory
libfilewatcher watch

# Watch specific directory
libfilewatcher watch /path/to/directory

# Watch with ignore patterns
libfilewatcher watch /path/to/directory --ignore "*.log" --ignore "*.tmp"

Development

git clone https://github.com/daedalus/libfilewatcher.git
cd libfilewatcher
pip install -e ".[test]"

# run tests
pytest

# format
ruff format src/ tests/

# lint
ruff check src/ tests/

# type check
mypy src/