Python Watchdogライブラリ入門:ファイル・ディレクトリのリアルタイム監視ガイド

Python tutorial - IT technology blog
Python tutorial - IT technology blog

永遠の課題:サーバーを疲弊させる無限ループ

自動化パイプラインを構築するシーンを想像してみてください。毎朝、経理部門から共有ディレクトリ /data/incoming に500件のレポートPDFが出力されます。あなたのタスクは、そこから数値を抽出してPostgreSQLに投入することです。最も直感的な解決策は何でしょうか? おそらく while True: time.sleep(10) でスクリプトを回し、フォルダをポーリング(定期監視)し続けることでしょう。

しかしこの方法は、配達員が来たかどうかを確かめるために5秒おきに玄関を開けに行くようなものです。無駄にCPU使用率が15〜20%まで跳ね上がり、SSDは1日何千回もの読み取りI/Oで酷使されます。さらに厄介なのは、50MBのPDFファイルがまだ20%しか書き込まれていないタイミングで読み込んでしまい、システムが即座にクラッシュしてしまうリスクです。

よりスマートなアプローチは、いわば「呼び鈴」を取り付けることです。ディレクトリに新しいファイルが入ってきた瞬間に、OS側からPythonに通知を送ってもらう仕組みを作ります。これこそが、Watchdogライブラリの果たす役割です。

動作の仕組み:OS層のAPIを直接活用する

Watchdogは無駄なポーリングを繰り返しません。Linuxの inotify、macOSの FSEvents、Windowsの ReadDirectoryChangesW といったカーネルレベルの監視APIに直接フックします。そのため、スクリプトは普段スリープ状態で待機し、実際のイベントが発生したときだけ起動します。

Watchdogのアーキテクチャは、主に3つの要素で構成されています:

  • Observer: 指定したディレクトリの変更をバックグラウンドスレッドで監視する門番のような存在。
  • Event Handler: 変更が検知された際のアクション(ファイルの読み込み、データ圧縮、アラート送信など)を実装するハンドラー。
  • Events: OSから発行されるイベント群。代表的なものに created、modified、deleted、moved があります。

実践:自動化パイプラインの構築

pip経由でライブラリをインストールします:

pip install watchdog

1. 基本的なディレクトリ監視

以下のコードは、./incoming ディレクトリ内のあらゆる変更を監視します:

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

class FileMonitorHandler(FileSystemEventHandler):
    def on_created(self, event):
        if not event.is_directory:
            print(f"[作成] {event.src_path}")

    def on_modified(self, event):
        if not event.is_directory:
            print(f"[変更] {event.src_path}")

    def on_deleted(self, event):
        if not event.is_directory:
            print(f"[削除] {event.src_path}")

if __name__ == "__main__":
    path_to_watch = "./incoming"
    event_handler = FileMonitorHandler()
    observer = Observer()
    # recursive=Trueでサブディレクトリも再帰的に監視
    observer.schedule(event_handler, path=path_to_watch, recursive=True)
    
    print(f"監視を開始しました: {path_to_watch}...")
    observer.start()
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()

2. PatternMatchingEventHandlerによる拡張子フィルタリング

実運用では、.tmp や .DS_Store のような一時ファイルまで処理したくありません。自前で if-else を書いて拡張子を判定する代わりに、PatternMatchingEventHandler を活用しましょう:

from watchdog.events import PatternMatchingEventHandler

class InvoiceHandler(PatternMatchingEventHandler):
    def __init__(self):
        super().__init__(
            patterns=["*.pdf", "*.xlsx"],
            ignore_patterns=["*.tmp", "*~*"],
            ignore_directories=True,
            case_sensitive=False
        )

    def on_created(self, event):
        print(f"対象ファイルを受信しました: {event.src_path}")

3. 実践ノウハウ:スケール時のパイプライン停止を防ぐ

初期の200行程度のコードは検証環境では軽快に動きます。しかし、大量のトラフィックを抱える本番環境へデプロイすると、次の2つの落とし穴に直面します:

  • 書き込み途中ファイルの読み込み(Partial Write)の罠: SFTP経由で300MBのCSVファイルをダウンロードする場合、最初の1バイトが書き込まれた時点で on_created が発火します。即座に読み込もうとすると、データが途中で切れたり、Permission Deniedエラーが発生したりします。対策として、1〜2秒間待機してファイルサイズに変化がないことを確認してから処理を開始します。
  • 重いロジックによるObserverのブロッキング: on_created 内にOCR処理やDBへのインサート、Telegram通知などを直接詰め込むのは典型的なアンチパターンです。処理に3秒かかっている間に20ファイルが一気に届いた場合、Observerはイベントを取りこぼして(ドロップして)しまいます。正攻法は、ハンドラー側ではファイルパスをキュー(Queue)に積むだけにとどめ、重い処理はワーカースレッドに任せることです。
import time
import os
from queue import Queue
from threading import Thread
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

job_queue = Queue()

def worker():
    while True:
        file_path = job_queue.get()
        if file_path is None:
            break
        
        # ディスクへのファイル書き込み完了を待機
        last_size = -1
        while True:
            try:
                current_size = os.path.getsize(file_path)
                if current_size == last_size and current_size > 0:
                    break
                last_size = current_size
                time.sleep(1)
            except FileNotFoundError:
                break
        
        print(f"[処理開始] 安全にパースを開始します: {file_path}")
        job_queue.task_done()

class AsyncHandler(FileSystemEventHandler):
    def on_created(self, event):
        if not event.is_directory:
            # キューにタスクを追加して即座に復帰し、Observerをブロックしない
            job_queue.put(event.src_path)

if __name__ == "__main__":
    # キューを処理するバックグラウンドワーカーを2基起動
    for _ in range(2):
        Thread(target=worker, daemon=True).start()
        
    observer = Observer()
    observer.schedule(AsyncHandler(), path="./incoming", recursive=False)
    observer.start()
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()

まとめ

Watchdogは、手動のポーリングループを完全に置き換える洗練されたソリューションです。ファイル監視をOSカーネルに委ねることで、メモリ消費を抑えつつ、変更に対して即座に応答できるようになります。「イベントを検知するスレッド」と「重い処理を実行するスレッド」を分離するという鉄則を守ることで、堅牢で安定したシステム運用が実現できます。

Share: