File System Watcher

Monitor directory changes using platform-native APIs for real-time file system events

75 min

Advanced

CGoPython

Choose Implementation Language

Setup Instructions (Python)

Install Python 3.7+

Install watchdog library: pip install watchdog

Create project directory

Set up virtual environment (recommended)

1. Import Required Libraries

First, we need to import all the necessary libraries for file system watching.

import time
import os
import sys
from pathlib import Path
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

Key Points Explained

• `time` - For adding delays in our event loop
• `os` - For operating system interface functions
• `sys` - For system-specific parameters and functions
• `pathlib.Path` - For object-oriented filesystem paths
• `Observer` - The main watcher class from watchdog
• `FileSystemEventHandler` - Base class for handling file events

2. Create Event Handler Class

This class will handle all file system events that occur in the watched directory.

class FileChangeHandler(FileSystemEventHandler):
    """Handler for file system events"""

    def __init__(self, filters=None):
        super().__init__()
        self.filters = filters or []
        self.event_count = 0

    def should_process_file(self, file_path):
        """Check if file should be processed based on filters"""
        if not self.filters:
            return True

        file_name = os.path.basename(file_path)
        return any(file_name.endswith(f) for f in self.filters)

Key Points Explained

• `__init__` - Initialize the handler with optional file filters
• `self.filters` - List of file extensions to watch (e.g., ['.py', '.txt'])
• `self.event_count` - Counter to track total number of events
• `should_process_file()` - Helper method to check if a file matches our filters
• `os.path.basename()` - Extract just the filename from the full path
• `any()` - Returns True if any filter matches the file extension

3. Implement Event Methods

These methods are called automatically when different types of file events occur.

    def on_created(self, event):
        if not event.is_directory and self.should_process_file(event.src_path):
            self.event_count += 1
            print(f"[{self.event_count}] 📄 Created: {event.src_path}")

    def on_modified(self, event):
        if not event.is_directory and self.should_process_file(event.src_path):
            self.event_count += 1
            print(f"[{self.event_count}] ✏️  Modified: {event.src_path}")

    def on_deleted(self, event):
        if not event.is_directory and self.should_process_file(event.src_path):
            self.event_count += 1
            print(f"[{self.event_count}] 🗑️  Deleted: {event.src_path}")

    def on_moved(self, event):
        if not event.is_directory and self.should_process_file(event.src_path):
            self.event_count += 1
            print(f"[{self.event_count}] 📦 Moved: {event.src_path} -> {event.dest_path}")

Key Points Explained

• `on_created()` - Called when a new file is created
• `on_modified()` - Called when a file is modified
• `on_deleted()` - Called when a file is deleted
• `on_moved()` - Called when a file is moved or renamed
• `event.is_directory` - Check if the event is for a directory
• `event.src_path` - The source path of the file
• `event.dest_path` - The destination path (for move events)

Usage Examples

python file_watcher.py

python file_watcher.py /path/to/watch

python file_watcher.py --filter .py --filter .txt

python file_watcher.py ~/Documents --recursive

Key Features

Cross-Platform Support

Works on Linux (inotify), macOS (kqueue), and Windows (ReadDirectoryChangesW)

Efficient Event Notifications

Uses native OS APIs for minimal CPU overhead and instant notifications

Recursive Directory Watching

Monitor entire directory trees including subdirectories

Configurable Event Filters

Filter events by file extensions, patterns, or custom criteria

Graceful Error Handling

Robust error handling with proper resource cleanup

Real-time Performance

Low latency event detection suitable for production use

Common Use Cases

🔄 Build Systems

Automatically rebuild projects when source files change

📡 Live Reloading

Refresh web applications during development

📋 File Synchronization

Sync files between directories or systems

🛡️ Security Monitoring

Monitor sensitive directories for unauthorized changes

📊 Log Processing

Process log files as they're written

💾 Backup Systems

Trigger backups when files are modified

Performance Tips & Best Practices

🚀 Optimization

• Use file extension filters to reduce event noise
• Implement debouncing for rapid file changes
• Limit recursive depth for large directory trees
• Batch process multiple events when possible

⚠️ Common Pitfalls

• Watch for symlink loops in recursive mode
• Handle temporary files created by editors
• Be aware of OS-specific event limitations
• Always properly close file descriptors

Concepts Covered

File System EventsEvent-Driven ProgrammingCross-Platform APIsSystem Programming

Implementation Steps

1. Environment Setup

Install required dependencies and set up development environment

2. Create Project Structure

Set up the basic project files and directory structure

3. Implement Core Logic

Write the main file watching functionality

4. Add Event Handling

Handle different types of file system events

5. Test & Run

Test the implementation and run the file watcher