开发工具【免费下载链接】watchdogPython library and shell utilities to monitor filesystem events.项目地址https://gitcode.com/gh_mirrors/wa/watchdog点击查看免费下载本文是 watchdog 项目的入门技术指南。watchdog 是一个纯 Python 编写的文件系统事件监控库提供跨平台 API 与配套 shell 工具watchmedo。读完本文你将掌握 watchdog 的安装方式、Observer EventHandler 核心编程模型、事件类型体系、跨平台底层实现原理inotify / FSEvents / kqueue / ReadDirectoryChangesW / 轮询回退并了解如何通过 watchmedo 在命令行中响应目录变化。本文以仓库文档 docs/source/index.rst、docs/source/quickstart.rst、docs/source/installation.rst 为主体结合 src/watchdog 源码与测试进行佐证。一、watchdog 是什么watchdog 是 Python API library and shell utilities to monitor file system events——一个用于监控文件系统事件的 Python API 库同时附带命令行 shell 工具。它的核心定位是目录监控变得简单主要体现在两点跨平台 API同一套 Python 接口在 Windows、Linux、macOS、BSD 上都能工作底层自动选择各平台原生机制shell 工具提供 watchmedo 命令行工具可以在目录发生变化时直接触发命令执行无需编写 Python 代码。watchdog 要求Python 3.9 及以上版本。仓库当前版本号可在 src/watchdog/version.py 中确认VERSION_MAJOR / VERSION_MINOR / VERSION_BUILD构成__version__文档版本定义见 docs/source/global.rst.inc。二、安装 watchdog2.1 使用 pip 从 PyPI 安装推荐$ python -m pip install -U watchdog如果只需要核心监控库上面的命令就够了。若还想使用watchmedo命令行工具需要安装额外依赖主要依赖 PyYAML安装方式如下$ python -m pip install -U watchdog[watchmedo]2.2 从源码 tar 包安装$ wget -c https://pypi.python.org/packages/source/w/watchdog/watchdog-版本.tar.gz $ tar zxvf watchdog-版本.tar.gz $ cd watchdog-版本 $ python -m pip install -e .同样地需要 watchmedo 时改为$ python -m pip install -e .[watchmedo]2.3 从代码仓库安装$ git clone --recursive git://github.com/gorakhargosh/watchdog.git $ cd watchdog $ python -m pip install -e .需要 watchmedo 时同样使用-e .[watchmedo]。其中--recursive用于拉取仓库的递归子模块当前仓库包含 C 扩展源码 src/watchdog_fsevents.c可作参考。2.4 依赖说明watchdog 核心库依赖极少各平台差异主要体现在系统级组件上操作系统WindowsLinux 2.6macOS DarwinBSDXCode——是—使用watchmedo工具时所有平台都需要额外依赖操作系统WindowsLinux 2.6macOS DarwinBSDPyYAML是是是是详细说明见 docs/source/installation.rst 的 Dependencies 一节。三、快速上手监控当前目录的变化3.1 四个核心步骤官方 Quickstart 给出了使用 watchdog API 的标准流程创建 Observer 线程实例watchdog.observers.Observer实现事件处理器继承watchdog.events.FileSystemEventHandler的子类调度监控路径用 observer 实例调度schedule若干路径并绑定事件处理器启动 observer 线程让它在后台持续产生事件且不阻塞主线程。注意默认情况下一个Observer实例不会监控子目录。只有在对Observer.schedule()传入recursiveTrue时才会递归监控整棵目录树。3.2 一个可运行的完整示例下面的程序递归监控当前目录把发生的文件系统变化打印到控制台import time from watchdog.events import FileSystemEvent, FileSystemEventHandler from watchdog.observers import Observer class MyEventHandler(FileSystemEventHandler): def on_any_event(self, event: FileSystemEvent) - None: print(event) event_handler MyEventHandler() observer Observer() observer.schedule(event_handler, ., recursiveTrue) observer.start() try: while True: time.sleep(1) finally: observer.stop() observer.join()运行后按Control-C即可停止程序。仓库还提供了更完整的演示脚本 docs/source/examples/simple.py它接收命令行参数作为待监控路径path sys.argv[1]配置了logging.basicConfig(levellogging.DEBUG)并逐一覆写了on_moved、on_created、on_deleted、on_modified、on_closed、on_closed_no_write、on_opened等回调方法可通过python examples/simple.py /path/to/watch方式运行。3.3 为什么主循环要 sleepobserver.start()启动的是后台线程基于BaseThread主线程需要保持存活否则进程会退出。示例中while True: time.sleep(1)即用于维持主线程finally块保证退出时优雅地调用observer.stop()停止线程、observer.join()等待线程真正结束。从源码 src/watchdog/observers/api.py 可以看到 observer 的线程模型EventEmitter生产者线程调用queue_events(timeout)周期性读取文件系统事件并放入EventQueuesrc/watchdog/observers/api.py 中EventQueue继承自SkipRepeatsQueue可跳过连续重复的相同事件EventDispatcher消费者线程通过dispatch_events()从队列取出事件并分发给对应 watch 上注册的 handlersBaseObserver.dispatch_eventsBaseObserver维护_watches、_handlers、_emitters三组集合schedule()在已有 emitter 时才创建新 emitter否则复用。默认超时时间在 src/watchdog/observers/api.py 中定义为DEFAULT_EMITTER_TIMEOUT 1.0秒和DEFAULT_OBSERVER_TIMEOUT 1.0秒。四、类型注解注意事项Observer 并非类如果你使用类型注解需要特别注意一点watchdog.observers.Observer实际上不是一个类而是一个变量它持有你当前平台上最好的 observer 类。这是因为 src/watchdog/observers/init.py 中的_get_observer_cls()会在导入时按平台选择实现Linux →watchdog.observers.inotify.InotifyObservermacOS → 优先watchdog.observers.fsevents.FSEventsObserver导入失败则回退到KqueueObserver再失败则回退到轮询并给出警告Windows →watchdog.observers.read_directory_changes.WindowsApiObserver失败则回退轮询BSD →KqueueObserver其他平台 →PollingObserver最后通过Observer _get_observer_cls()把最佳实现赋给Observer这个名字。因此为了正确地对你的代码做类型标注应使用watchdog.observers.api.BaseObserver这一真实基类例如from watchdog.observers import Observer from watchdog.observers.api import BaseObserver def my_func(obs: BaseObserver) - None: # Do something with obs pass observer: BaseObserver Observer() my_func(observer)BaseObserver定义在 src/watchdog/observers/api.py 中继承自EventDispatcher提供了schedule()、add_handler_for_watch()、remove_handler_for_watch()、unschedule()、unschedule_all()、start()、stop()、join()等核心接口。五、事件与事件处理器体系5.1 事件类型watchdog 把所有文件系统变化抽象为统一的FileSystemEvent对象定义于 src/watchdog/events.py它是不可变immutable数据类型可作为字典键或加入集合。事件对象携带src_path源路径、dest_path目标路径移动事件使用、event_type和is_directory等属性。具体事件类包括事件类含义FileCreatedEvent/DirCreatedEvent文件 / 目录创建FileModifiedEvent/DirModifiedEvent文件 / 目录修改FileDeletedEvent/DirDeletedEvent文件 / 目录删除FileMovedEvent/DirMovedEvent基类FileSystemMovedEvent文件 / 目录移动或重命名FileOpenedEvent文件被打开FileClosedEvent打开用于写入的文件被关闭FileClosedNoWriteEvent打开用于读取的文件被关闭在 src/watchdog/events.py 中可以看到event_type常量定义moved、deleted、created、modified、closed、closed_no_write、opened以及is_synthetic字段——它标记那些不是操作系统直接广播、而是根据其他真实事件推断出来的合成事件例如整个目录被移动后为目录内部文件补充生成的移动事件见generate_sub_moved_events/generate_sub_created_events。5.2 事件处理器处理器基类是FileSystemEventHandlersrc/watchdog/events.py其dispatch(event)方法先调用on_any_event(event)兜底处理器再根据event.event_type动态分派到对应方法。可覆写的方法包括on_any_event(event)所有事件的兜底回调on_moved(event)文件或目录被移动 / 重命名on_created(event)文件或目录被创建on_deleted(event)文件或目录被删除on_modified(event)文件或目录被修改on_closed(event)写入模式打开的文件被关闭on_closed_no_write(event)只读打开的文件被关闭on_opened(event)文件被打开。仓库还内置了三个可直接使用的处理器子类PatternMatchingEventHandler按 glob 模式匹配事件路径内部使用pathlib的PurePath.match()构造函数参数为patterns、ignore_patterns、ignore_directories、case_sensitiveRegexMatchingEventHandler按正则表达式匹配事件路径内部使用re模块参数为regexes、ignore_regexes、ignore_directories、case_sensitive默认为大小写不敏感即re.IGNORECASELoggingEventHandler将各类事件以 info 级别写入日志例如 Created file: ...、Moved directory: from ... to ...。六、跨平台原理与注意事项watchdog 的原则是尽可能使用操作系统原生 API仅在原生 API 不可用时回退到周期性轮询磁盘、比较目录快照的方式。各平台实现如下完整说明见 docs/source/installation.rst 的 Supported Platforms (and Caveats) 一节。6.1 Linux 2.6inotifyLinux 2.6 及以后内核提供名为inotify(7)的 API 用于监控文件系统事件watchdog 的实现位于 src/watchdog/observers/inotify.py另有带 C 扩展路径的 src/watchdog/observers/inotify_c.py 与带缓冲区的 src/watchdog/observers/inotify_buffer.py。注意多数系统上每个用户可创建的 watch 数量上限为8192而 watchdog 监控每个目录就需要一个 watch。要修改此限制编辑/etc/sysctl.conf并添加fs.inotify.max_user_watches163846.2 macOSFSEvents 与 kqueueDarwin 内核 / OS X API 提供两种目录监控机制kqueue(2)FSEventswatchdog 可用两者中的任一个优先使用 FSEventsmacOS 实现见 src/watchdog/observers/fsevents.py 和 src/watchdog/observers/fsevents2.pyC 扩展见 src/watchdog_fsevents.c。kqueue(2)使用打开的文件描述符做监控当前实现遵循 macOS 文件系统监控性能指南来打开描述符——只为了监控事件而打开从而允许 OS X 在不锁定被监控卷的情况下卸载它们。kqueue 实现见 src/watchdog/observers/kqueue.py。关于 watchdog 如何使用kqueue(2)的更多信息见下文 BSD Unix variants其中大部分内容同样适用于 macOS。6.3 BSD 变体kqueueBSD 变体自带kqueue(2)程序可用它监控打开文件描述符的变化。由于kqueue(2)的工作方式watchdog 需要以只读、非阻塞模式打开这些文件和目录并持续记录它们。watchdog 会自动为所有新创建的文件/目录打开文件描述符并在删除后关闭它们。注意操作系统的单进程打开文件描述符数量上限可能阻碍 watchdog 的监控能力。应确保该限制至少为1024或一个适合你使用场景的值。把下面这行追加到你的~/.profile配置文件中即可ulimit -n 10246.4 Windows Vista 及以后ReadDirectoryChangesWWindows API 提供ReadDirectoryChangesWwatchdog 当前包含一个同步方式的实现需要 Windows Vista 及以后版本才具备的附加 API 功能实现见 src/watchdog/observers/read_directory_changes.py相关辅助模块 src/watchdog/observers/winapi.py。需要注意两点平台差异注意在 Windows 上重命名rename与移动move不是同一个操作watchdog 会尽力把重命名转换为移动事件。同时由于ReadDirectoryChangesW会在底层 I/O 完成前就返回目录的重命名/移动事件watchdog 可能无法完全扫描被移动的目录从而无法成功为其中的文件与子目录排队生成移动事件。注意Windows API 不提供对象是文件还是目录的信息因此目录的删除事件可能被报告为文件删除事件。6.5 与操作系统无关的回退方案轮询watchdog 还内置了一个跨平台回退实现通过周期性地比较目录树快照来检测变化。实现位于 src/watchdog/observers/polling.pyPollingEmitter在启动时on_thread_start用DirectorySnapshot建立初始快照之后每次queue_events()会重新生成新快照通过DirectorySnapshotDiff(old, new)计算差异并据此产生FileDeletedEvent、FileModifiedEvent、FileCreatedEvent、FileMovedEvent及对应的目录事件PollingObserver与PollingObserverVFS是可直接使用的 observer 类。快照与差异计算工具位于 src/watchdog/utils/dirsnapshot.py。从 src/watchdog/observers/polling.py 的注释可以看到轮询 emitter 的timeout参数实际上充当轮询间隔——We dont want to hit the disk continuously即避免持续访问磁盘。七、API 参考与命令行工具7.1 API 参考概览仓库文档 docs/source/api.rst 列出了完整 API 参考主要包括watchdog.events事件类与事件处理器类watchdog.observers.api面向 observer 实现者的基础类包括ObservedWatch一次调度的 watch包含 path、recursive、event_filter、follow_symlink 等属性、EventQueue、EventEmitter、EventDispatcher、BaseObserverwatchdog.observers平台选择器Observer与各平台 observer 类watchdog.observers.polling轮询实现watchdog.utilsdirsnapshot等工具模块watchdog.tricks高级技巧tricks如 docs/source/examples/logger.py、docs/source/examples/patterns.py、docs/source/examples/tricks.yaml 中演示的用法。7.2 watchmedo命令行触发命令除了 APIwatchdog 还提供 shell 工具watchmedo实现于 src/watchdog/watchmedo.pyWindows 批处理入口见 tools/watchmedo.bat。它的作用是在目录变化时运行命令例如配合tricks.yaml配置文件定义响应动作。安装时使用watchdog[watchmedo]即可获得该工具及 PyYAML 依赖。典型的命令行形态以监控目录并触发命令为例为$ watchmedo shell-command --patterns*.py --recursive --commandecho ${watch_event_type} ${watch_src_path} .具体命令参数与子命令如shell-command、tricks、log等可通过运行watchmedo --help查看也可阅读 src/watchdog/watchmedo.py 中的 argparse 定义确认。八、参与贡献与进一步阅读若你发现 bug 或想为 watchdog 添加新特性可以参考文档 docs/source/hacking.rst 了解贡献代码或文档的规范。仓库的测试用例如 tests/test_observer.py、tests/test_events.py、tests/test_observers_polling.py展示了各模块的预期行为是深入理解内部实现的绝佳入口。后续可继续阅读docs/source/quickstart.rst快速上手示例docs/source/installation.rst安装与平台注意事项docs/source/api.rst完整 API 参考docs/source/examples/simple.py可直接运行的监控示例脚本src/watchdog/events.py事件与处理器源码src/watchdog/observers/api.pyObserver 核心实现源码。赞分享开发工具【免费下载链接】watchdogPython library and shell utilities to monitor filesystem events.项目地址https://gitcode.com/gh_mirrors/wa/watchdog点击查看免费下载相关推荐终极指南3步让老旧Mac免费升级到最新macOS系统终极指南3步让老旧Mac免费升级到最新macOS系统 你是否还在为苹果官方放弃支持的老旧Mac而烦恼想象一下你的2015年MacBook Air依然性能不操作系统固件驱动开发Watchdog终极指南Python文件系统事件监控的完整解决方案 Watchdog终极指南Python文件系统事件监控的完整解决方案 想要实时监控文件系统的变化吗Watchdog是Python开发者必备的文件系统事件开发工具Python Watchdog完全指南10分钟学会文件系统监控Python Watchdog完全指南10分钟学会文件系统监控 想要实时监控文件系统变化却不知从何入手Python Watchdog库是你的终极解决方案这开发工具上一篇Jetson Containers 项目教程下一篇Colab-SSH 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
watchdog 入门指南：用 Python 跨平台监控文件系统事件
开发工具【免费下载链接】watchdogPython library and shell utilities to monitor filesystem events.项目地址https://gitcode.com/gh_mirrors/wa/watchdog点击查看免费下载本文是 watchdog 项目的入门技术指南。watchdog 是一个纯 Python 编写的文件系统事件监控库提供跨平台 API 与配套 shell 工具watchmedo。读完本文你将掌握 watchdog 的安装方式、Observer EventHandler 核心编程模型、事件类型体系、跨平台底层实现原理inotify / FSEvents / kqueue / ReadDirectoryChangesW / 轮询回退并了解如何通过 watchmedo 在命令行中响应目录变化。本文以仓库文档 docs/source/index.rst、docs/source/quickstart.rst、docs/source/installation.rst 为主体结合 src/watchdog 源码与测试进行佐证。一、watchdog 是什么watchdog 是 Python API library and shell utilities to monitor file system events——一个用于监控文件系统事件的 Python API 库同时附带命令行 shell 工具。它的核心定位是目录监控变得简单主要体现在两点跨平台 API同一套 Python 接口在 Windows、Linux、macOS、BSD 上都能工作底层自动选择各平台原生机制shell 工具提供 watchmedo 命令行工具可以在目录发生变化时直接触发命令执行无需编写 Python 代码。watchdog 要求Python 3.9 及以上版本。仓库当前版本号可在 src/watchdog/version.py 中确认VERSION_MAJOR / VERSION_MINOR / VERSION_BUILD构成__version__文档版本定义见 docs/source/global.rst.inc。二、安装 watchdog2.1 使用 pip 从 PyPI 安装推荐$ python -m pip install -U watchdog如果只需要核心监控库上面的命令就够了。若还想使用watchmedo命令行工具需要安装额外依赖主要依赖 PyYAML安装方式如下$ python -m pip install -U watchdog[watchmedo]2.2 从源码 tar 包安装$ wget -c https://pypi.python.org/packages/source/w/watchdog/watchdog-版本.tar.gz $ tar zxvf watchdog-版本.tar.gz $ cd watchdog-版本 $ python -m pip install -e .同样地需要 watchmedo 时改为$ python -m pip install -e .[watchmedo]2.3 从代码仓库安装$ git clone --recursive git://github.com/gorakhargosh/watchdog.git $ cd watchdog $ python -m pip install -e .需要 watchmedo 时同样使用-e .[watchmedo]。其中--recursive用于拉取仓库的递归子模块当前仓库包含 C 扩展源码 src/watchdog_fsevents.c可作参考。2.4 依赖说明watchdog 核心库依赖极少各平台差异主要体现在系统级组件上操作系统WindowsLinux 2.6macOS DarwinBSDXCode——是—使用watchmedo工具时所有平台都需要额外依赖操作系统WindowsLinux 2.6macOS DarwinBSDPyYAML是是是是详细说明见 docs/source/installation.rst 的 Dependencies 一节。三、快速上手监控当前目录的变化3.1 四个核心步骤官方 Quickstart 给出了使用 watchdog API 的标准流程创建 Observer 线程实例watchdog.observers.Observer实现事件处理器继承watchdog.events.FileSystemEventHandler的子类调度监控路径用 observer 实例调度schedule若干路径并绑定事件处理器启动 observer 线程让它在后台持续产生事件且不阻塞主线程。注意默认情况下一个Observer实例不会监控子目录。只有在对Observer.schedule()传入recursiveTrue时才会递归监控整棵目录树。3.2 一个可运行的完整示例下面的程序递归监控当前目录把发生的文件系统变化打印到控制台import time from watchdog.events import FileSystemEvent, FileSystemEventHandler from watchdog.observers import Observer class MyEventHandler(FileSystemEventHandler): def on_any_event(self, event: FileSystemEvent) - None: print(event) event_handler MyEventHandler() observer Observer() observer.schedule(event_handler, ., recursiveTrue) observer.start() try: while True: time.sleep(1) finally: observer.stop() observer.join()运行后按Control-C即可停止程序。仓库还提供了更完整的演示脚本 docs/source/examples/simple.py它接收命令行参数作为待监控路径path sys.argv[1]配置了logging.basicConfig(levellogging.DEBUG)并逐一覆写了on_moved、on_created、on_deleted、on_modified、on_closed、on_closed_no_write、on_opened等回调方法可通过python examples/simple.py /path/to/watch方式运行。3.3 为什么主循环要 sleepobserver.start()启动的是后台线程基于BaseThread主线程需要保持存活否则进程会退出。示例中while True: time.sleep(1)即用于维持主线程finally块保证退出时优雅地调用observer.stop()停止线程、observer.join()等待线程真正结束。从源码 src/watchdog/observers/api.py 可以看到 observer 的线程模型EventEmitter生产者线程调用queue_events(timeout)周期性读取文件系统事件并放入EventQueuesrc/watchdog/observers/api.py 中EventQueue继承自SkipRepeatsQueue可跳过连续重复的相同事件EventDispatcher消费者线程通过dispatch_events()从队列取出事件并分发给对应 watch 上注册的 handlersBaseObserver.dispatch_eventsBaseObserver维护_watches、_handlers、_emitters三组集合schedule()在已有 emitter 时才创建新 emitter否则复用。默认超时时间在 src/watchdog/observers/api.py 中定义为DEFAULT_EMITTER_TIMEOUT 1.0秒和DEFAULT_OBSERVER_TIMEOUT 1.0秒。四、类型注解注意事项Observer 并非类如果你使用类型注解需要特别注意一点watchdog.observers.Observer实际上不是一个类而是一个变量它持有你当前平台上最好的 observer 类。这是因为 src/watchdog/observers/init.py 中的_get_observer_cls()会在导入时按平台选择实现Linux →watchdog.observers.inotify.InotifyObservermacOS → 优先watchdog.observers.fsevents.FSEventsObserver导入失败则回退到KqueueObserver再失败则回退到轮询并给出警告Windows →watchdog.observers.read_directory_changes.WindowsApiObserver失败则回退轮询BSD →KqueueObserver其他平台 →PollingObserver最后通过Observer _get_observer_cls()把最佳实现赋给Observer这个名字。因此为了正确地对你的代码做类型标注应使用watchdog.observers.api.BaseObserver这一真实基类例如from watchdog.observers import Observer from watchdog.observers.api import BaseObserver def my_func(obs: BaseObserver) - None: # Do something with obs pass observer: BaseObserver Observer() my_func(observer)BaseObserver定义在 src/watchdog/observers/api.py 中继承自EventDispatcher提供了schedule()、add_handler_for_watch()、remove_handler_for_watch()、unschedule()、unschedule_all()、start()、stop()、join()等核心接口。五、事件与事件处理器体系5.1 事件类型watchdog 把所有文件系统变化抽象为统一的FileSystemEvent对象定义于 src/watchdog/events.py它是不可变immutable数据类型可作为字典键或加入集合。事件对象携带src_path源路径、dest_path目标路径移动事件使用、event_type和is_directory等属性。具体事件类包括事件类含义FileCreatedEvent/DirCreatedEvent文件 / 目录创建FileModifiedEvent/DirModifiedEvent文件 / 目录修改FileDeletedEvent/DirDeletedEvent文件 / 目录删除FileMovedEvent/DirMovedEvent基类FileSystemMovedEvent文件 / 目录移动或重命名FileOpenedEvent文件被打开FileClosedEvent打开用于写入的文件被关闭FileClosedNoWriteEvent打开用于读取的文件被关闭在 src/watchdog/events.py 中可以看到event_type常量定义moved、deleted、created、modified、closed、closed_no_write、opened以及is_synthetic字段——它标记那些不是操作系统直接广播、而是根据其他真实事件推断出来的合成事件例如整个目录被移动后为目录内部文件补充生成的移动事件见generate_sub_moved_events/generate_sub_created_events。5.2 事件处理器处理器基类是FileSystemEventHandlersrc/watchdog/events.py其dispatch(event)方法先调用on_any_event(event)兜底处理器再根据event.event_type动态分派到对应方法。可覆写的方法包括on_any_event(event)所有事件的兜底回调on_moved(event)文件或目录被移动 / 重命名on_created(event)文件或目录被创建on_deleted(event)文件或目录被删除on_modified(event)文件或目录被修改on_closed(event)写入模式打开的文件被关闭on_closed_no_write(event)只读打开的文件被关闭on_opened(event)文件被打开。仓库还内置了三个可直接使用的处理器子类PatternMatchingEventHandler按 glob 模式匹配事件路径内部使用pathlib的PurePath.match()构造函数参数为patterns、ignore_patterns、ignore_directories、case_sensitiveRegexMatchingEventHandler按正则表达式匹配事件路径内部使用re模块参数为regexes、ignore_regexes、ignore_directories、case_sensitive默认为大小写不敏感即re.IGNORECASELoggingEventHandler将各类事件以 info 级别写入日志例如 Created file: ...、Moved directory: from ... to ...。六、跨平台原理与注意事项watchdog 的原则是尽可能使用操作系统原生 API仅在原生 API 不可用时回退到周期性轮询磁盘、比较目录快照的方式。各平台实现如下完整说明见 docs/source/installation.rst 的 Supported Platforms (and Caveats) 一节。6.1 Linux 2.6inotifyLinux 2.6 及以后内核提供名为inotify(7)的 API 用于监控文件系统事件watchdog 的实现位于 src/watchdog/observers/inotify.py另有带 C 扩展路径的 src/watchdog/observers/inotify_c.py 与带缓冲区的 src/watchdog/observers/inotify_buffer.py。注意多数系统上每个用户可创建的 watch 数量上限为8192而 watchdog 监控每个目录就需要一个 watch。要修改此限制编辑/etc/sysctl.conf并添加fs.inotify.max_user_watches163846.2 macOSFSEvents 与 kqueueDarwin 内核 / OS X API 提供两种目录监控机制kqueue(2)FSEventswatchdog 可用两者中的任一个优先使用 FSEventsmacOS 实现见 src/watchdog/observers/fsevents.py 和 src/watchdog/observers/fsevents2.pyC 扩展见 src/watchdog_fsevents.c。kqueue(2)使用打开的文件描述符做监控当前实现遵循 macOS 文件系统监控性能指南来打开描述符——只为了监控事件而打开从而允许 OS X 在不锁定被监控卷的情况下卸载它们。kqueue 实现见 src/watchdog/observers/kqueue.py。关于 watchdog 如何使用kqueue(2)的更多信息见下文 BSD Unix variants其中大部分内容同样适用于 macOS。6.3 BSD 变体kqueueBSD 变体自带kqueue(2)程序可用它监控打开文件描述符的变化。由于kqueue(2)的工作方式watchdog 需要以只读、非阻塞模式打开这些文件和目录并持续记录它们。watchdog 会自动为所有新创建的文件/目录打开文件描述符并在删除后关闭它们。注意操作系统的单进程打开文件描述符数量上限可能阻碍 watchdog 的监控能力。应确保该限制至少为1024或一个适合你使用场景的值。把下面这行追加到你的~/.profile配置文件中即可ulimit -n 10246.4 Windows Vista 及以后ReadDirectoryChangesWWindows API 提供ReadDirectoryChangesWwatchdog 当前包含一个同步方式的实现需要 Windows Vista 及以后版本才具备的附加 API 功能实现见 src/watchdog/observers/read_directory_changes.py相关辅助模块 src/watchdog/observers/winapi.py。需要注意两点平台差异注意在 Windows 上重命名rename与移动move不是同一个操作watchdog 会尽力把重命名转换为移动事件。同时由于ReadDirectoryChangesW会在底层 I/O 完成前就返回目录的重命名/移动事件watchdog 可能无法完全扫描被移动的目录从而无法成功为其中的文件与子目录排队生成移动事件。注意Windows API 不提供对象是文件还是目录的信息因此目录的删除事件可能被报告为文件删除事件。6.5 与操作系统无关的回退方案轮询watchdog 还内置了一个跨平台回退实现通过周期性地比较目录树快照来检测变化。实现位于 src/watchdog/observers/polling.pyPollingEmitter在启动时on_thread_start用DirectorySnapshot建立初始快照之后每次queue_events()会重新生成新快照通过DirectorySnapshotDiff(old, new)计算差异并据此产生FileDeletedEvent、FileModifiedEvent、FileCreatedEvent、FileMovedEvent及对应的目录事件PollingObserver与PollingObserverVFS是可直接使用的 observer 类。快照与差异计算工具位于 src/watchdog/utils/dirsnapshot.py。从 src/watchdog/observers/polling.py 的注释可以看到轮询 emitter 的timeout参数实际上充当轮询间隔——We dont want to hit the disk continuously即避免持续访问磁盘。七、API 参考与命令行工具7.1 API 参考概览仓库文档 docs/source/api.rst 列出了完整 API 参考主要包括watchdog.events事件类与事件处理器类watchdog.observers.api面向 observer 实现者的基础类包括ObservedWatch一次调度的 watch包含 path、recursive、event_filter、follow_symlink 等属性、EventQueue、EventEmitter、EventDispatcher、BaseObserverwatchdog.observers平台选择器Observer与各平台 observer 类watchdog.observers.polling轮询实现watchdog.utilsdirsnapshot等工具模块watchdog.tricks高级技巧tricks如 docs/source/examples/logger.py、docs/source/examples/patterns.py、docs/source/examples/tricks.yaml 中演示的用法。7.2 watchmedo命令行触发命令除了 APIwatchdog 还提供 shell 工具watchmedo实现于 src/watchdog/watchmedo.pyWindows 批处理入口见 tools/watchmedo.bat。它的作用是在目录变化时运行命令例如配合tricks.yaml配置文件定义响应动作。安装时使用watchdog[watchmedo]即可获得该工具及 PyYAML 依赖。典型的命令行形态以监控目录并触发命令为例为$ watchmedo shell-command --patterns*.py --recursive --commandecho ${watch_event_type} ${watch_src_path} .具体命令参数与子命令如shell-command、tricks、log等可通过运行watchmedo --help查看也可阅读 src/watchdog/watchmedo.py 中的 argparse 定义确认。八、参与贡献与进一步阅读若你发现 bug 或想为 watchdog 添加新特性可以参考文档 docs/source/hacking.rst 了解贡献代码或文档的规范。仓库的测试用例如 tests/test_observer.py、tests/test_events.py、tests/test_observers_polling.py展示了各模块的预期行为是深入理解内部实现的绝佳入口。后续可继续阅读docs/source/quickstart.rst快速上手示例docs/source/installation.rst安装与平台注意事项docs/source/api.rst完整 API 参考docs/source/examples/simple.py可直接运行的监控示例脚本src/watchdog/events.py事件与处理器源码src/watchdog/observers/api.pyObserver 核心实现源码。赞分享开发工具【免费下载链接】watchdogPython library and shell utilities to monitor filesystem events.项目地址https://gitcode.com/gh_mirrors/wa/watchdog点击查看免费下载相关推荐终极指南3步让老旧Mac免费升级到最新macOS系统终极指南3步让老旧Mac免费升级到最新macOS系统 你是否还在为苹果官方放弃支持的老旧Mac而烦恼想象一下你的2015年MacBook Air依然性能不操作系统固件驱动开发Watchdog终极指南Python文件系统事件监控的完整解决方案 Watchdog终极指南Python文件系统事件监控的完整解决方案 想要实时监控文件系统的变化吗Watchdog是Python开发者必备的文件系统事件开发工具Python Watchdog完全指南10分钟学会文件系统监控Python Watchdog完全指南10分钟学会文件系统监控 想要实时监控文件系统变化却不知从何入手Python Watchdog库是你的终极解决方案这开发工具上一篇Jetson Containers 项目教程下一篇Colab-SSH 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
