philiprehberger-file-watcher 0.3.0

Filesystem event watcher with decorator-based callbacks

philiprehberger-file-watcher

Filesystem event watcher with decorator-based callbacks.

Installation

pip install philiprehberger-file-watcher

Usage

Basic Watching

from philiprehberger_file_watcher import Watcher

watcher = Watcher("./src")

@watcher.on("created", pattern="*.py")
def on_new_python_file(event):
    print(f"New file: {event.path}")

@watcher.on("modified", pattern="*.css")
def on_css_change(event):
    print(f"CSS changed: {event.path}")

@watcher.on("any")
def on_anything(event):
    print(f"{event.type}: {event.path}")

# Blocking
watcher.start()

# Or background mode
watcher.start(background=True)
# ... do other work ...
watcher.stop()

Batch Event Collection

watcher = Watcher("./uploads")

def handle_batch(events):
    print(f"Received {len(events)} files at once")
    for event in events:
        print(f"  {event.path}")

# Fire callback when 50 events collected or after 3 seconds
watcher.on_batch("created", handle_batch, batch_size=50, timeout=3.0)

watcher.start(background=True)

Stopping watches and introspection

watcher = Watcher("./src")
watcher.start(background=True)

# Inspect currently-watched paths
print(watcher.watched_paths())  # ['/abs/path/to/src']

# Stop watching a specific path
removed = watcher.unwatch("./src")  # True if the path was being watched
print(watcher.watched_paths())  # []

Event Types

"created", "modified", "deleted", "moved", "any"

API

Function / Class	Description
Watcher(path, recursive, debounce)	Watch a directory for filesystem changes with decorator-based event handlers
FileEvent	A filesystem event with type, path, is_directory, and dest_path fields
Watcher.on(event_type, pattern)	Decorator to register a single-event callback
Watcher.add_listener(event_type, callback, pattern)	Programmatically add an event listener
Watcher.on_batch(event_type, callback, batch_size, timeout)	Register a batch callback that fires on size or timeout
Watcher.start(background)	Start watching (blocking or background)
Watcher.stop()	Stop watching
Watcher.unwatch(path)	Stop watching a specific path; returns True if the path was being watched
Watcher.watched_paths()	Return a snapshot list of currently-watched paths

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT