Введение

Во многих сценариях важно отслеживать изменения в файловой системе: появление новых файлов, удаление, переименование, изменение содержимого. Такие задачи возникают при построении логеров, CI/CD-систем, утилит резервного копирования, автоматизации и даже при работе с системами безопасности.

Библиотека Watchdog в Python предоставляет кроссплатформенный, надёжный и расширяемый способ мониторинга изменений в файловой системе с минимальными накладными расходами. В этой статье мы разберем все возможности этой библиотеки, от базовых до продвинутых, и покажем, как внедрять её в реальные проекты.

Основная часть

Установка Watchdog

pip install watchdog

Работает на Windows, Linux, macOS. Использует разные механизмы наблюдения (inotify, FSEvents, ReadDirectoryChangesW) в зависимости от платформы.

Основные компоненты

Watchdog построен вокруг следующих ключевых элементов:

• Observer — запускает мониторинг

• EventHandler — обработчик событий (например, изменение файла)

• Event — объект события (содержит путь, тип и время)

Пример минимального кода

import time
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class MyHandler(FileSystemEventHandler):
    def on_modified(self, event):
        print(f"Изменено: {event.src_path}")

observer = Observer()
observer.schedule(MyHandler(), path=".", recursive=True)
observer.start()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    observer.stop()
observer.join()

Типы событий

on_created(event)

Вызывается при создании нового файла или папки

on_deleted(event)

Вызывается при удалении

on_modified(event)

При изменении содержимого файла или метаданных

on_moved(event)

При перемещении/переименовании

def on_moved(self, event):
    print(f"Перемещено: {event.src_path} → {event.dest_path}")

Расширенные возможности

Рекурсивное наблюдение

Параметр recursive=True позволяет отслеживать изменения во всех подпапках.

Фильтрация расширений

class TxtHandler(FileSystemEventHandler):
    def on_created(self, event):
        if event.src_path.endswith(".txt"):
            print(f"Новый TXT-файл: {event.src_path}")

Запуск команд по событию

import os
class AutoRunner(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith("script.py"):
            os.system("python script.py")

Watchdog + Asyncio

Для асинхронных приложений можно использовать watchdog[watchmedo] или объединить с asyncio через отдельный поток.

Интеграция в проекты

CI/CD

• Автозапуск тестов при изменении кода

• Отслеживание конфигураций в pipeline

Data Engineering

• Мониторинг входных данных

• Запуск ETL по появлению файлов

DevOps

• Отслеживание логов

• Автосборка/обновление конфигов

Производительность и масштабирование

• Watchdog работает быстро и эффективно на системах с менее 10000 файлов.

• Для крупных проектов рекомендуется:

  • Исключать временные каталоги

  • Использовать фильтрацию событий

  • Переводить наблюдателей в отдельные процессы

Альтернативы и сравнение

Инструмент	Язык	Поддержка ОС	Поддержка событий	Асинхронность
Watchdog	Python	Windows/Linux/macOS	Да	Через поток
inotify	C	Только Linux	Да	Да
fswatch	C++	macOS/Linux	Частично	Нет
chokidar	Node.js	Все платформы	Да	Да

Особенности и ограничения

• Не поддерживает нативно асинхронный API

• Зависит от платформы (разное поведение на Windows и Linux)

• Уязвим к временным файлам и частым автосохранениям (в IDE)

Лучшие практики

• Использовать конкретные расширения для отслеживания

• Разделять обработку событий по типам (через разные методы)

• Добавлять логи и дебаг-режим

• Заворачивать наблюдение в try/except

• Останавливать наблюдатель корректно (через stop() и join())

Основные классы и функции Watchdog

1. Observer()

Главный класс, который запускает и останавливает мониторинг.

Методы:

---

schedule(handler, path, recursive=True)

Добавляет обработчик событий для указанного пути.

• handler: экземпляр класса-наследника от FileSystemEventHandler

• path: путь к папке

• recursive: отслеживать ли подкаталоги

Пример:

---

start()

Запускает наблюдение (асинхронно, в отдельном потоке).

---

stop()

Останавливает наблюдение.

---

join(timeout=None)

Блокирует выполнение, пока наблюдатель работает. Можно указать таймаут.

---

2. FileSystemEventHandler

Базовый обработчик событий. Нужно наследоваться от него и переопределять методы.

Методы:

---

on_created(event)

Вызывается при создании файла или папки.

---

on_deleted(event)

Вызывается при удалении файла или папки.

---

on_modified(event)

Вызывается при изменении файла или папки.

---

on_moved(event)

Вызывается при перемещении файла или папки.

---

dispatch(event)

Маршрутизирует событие к нужному методу (например, on_created и т.п.). Переопределяется редко.

---

3. События (FileSystemEvent и его подклассы)

Все события, передающиеся в обработчики, имеют структуру:

Общие атрибуты:

• event.src_path — путь к объекту

• event.is_directory — True если это папка

Типы событий:

• FileCreatedEvent

• FileDeletedEvent

• FileModifiedEvent

• FileMovedEvent

---

4. PatternMatchingEventHandler

Расширение FileSystemEventHandler, позволяющее фильтровать события по шаблонам (например, только .txt файлы).

Параметры:

• patterns: список шаблонов (например, ["*.txt"])

• ignore_patterns: что исключить

• ignore_directories: исключать папки

• case_sensitive: чувствительность к регистру

Пример:

---

Методы: те же (on_created, on_deleted, и т.д.), но работают только с подходящими файлами.

---

5. LoggingEventHandler

Готовый обработчик, который логирует все события через модуль logging.

Пример:

---

6. PollingObserver()

Альтернатива Observer, основанная не на системных событиях, а на периодическом опросе файловой системы. Используется, если обычный Observer не поддерживается (например, на некоторых файловых системах или в сетевых хранилищах).

---

7. watchdog.observers.Observer.schedule(handler, path, recursive=True)

Добавляет обработчик к Observer (описано выше, дублируется в интерфейсе Observer).

---

Полный пример использования:

Заключение

Watchdog — универсальное решение для мониторинга файловой системы на Python. С его помощью можно реализовать гибкие сценарии наблюдения, автоматизировать рутинные задачи, обеспечить контроль за важными файлами и интегрировать его в любые пайплайны или DevOps-инструменты. Он легко расширяется, стабилен в работе и активно используется как в скриптах, так и в продакшене.