ErisPulse.runtime.file_watcher 模块
模块概述
文件变更监控
提供文件系统变更检测能力
提示
- 通过定期比较 .py 文件的 mtime 检测变更
- 接口与 watchdog.observers.Observer 保持一致 (schedule/start/stop/join)
- 供运行时插件热重载(runtime/plugin_reload)与 CLI 热重载(CLI/commands/run)共用
- 默认忽略 .venv/.git 等目录(FILE_WATCHER_IGNORED_DIRS),可经 ignore_dirs 覆盖
类列表
class FileSystemEventHandler
文件事件处理器基类
子类可覆写 on_modified 等回调以响应文件变更事件。
示例:
class MyHandler(FileSystemEventHandler):
def on_modified(self, event):
print(f"changed: {event.src_path}")
方法列表
on_modified(event: 'FileChangeEvent') -> None
文件修改事件回调
- event (
FileChangeEvent): 文件变更事件
on_created(event: 'FileChangeEvent') -> None
文件创建事件回调
- event (
FileChangeEvent): 文件变更事件
on_deleted(event: 'FileChangeEvent') -> None
文件删除事件回调
- event (
FileChangeEvent): 文件变更事件
on_moved(event: 'FileChangeEvent') -> None
文件移动事件回调
提示 轮询实现(PollingObserver)基于 mtime 比较,不触发本回调——移动 表现为旧路径
on_deleted+ 新路径on_created。
- event (
FileChangeEvent): 文件变更事件
class FileChangeEvent
文件变更事件
- src_path (
str): 发生变更的文件路径 - event_type (
str): 事件类型("modified" / "created" / "deleted")
方法列表
__init__(src_path: str, event_type: str = 'modified')
初始化文件变更事件
- src_path (
str): 发生变更的文件路径 - event_type (
str): 事件类型("modified" / "created" / "deleted")
class PollingObserver
纯 Python 轮询文件监控器
通过定期遍历目录并比较 .py 文件的 mtime 检测变更
提示
- 接口与 watchdog.observers.Observer 一致 (schedule/start/stop/join)
- 轮询运行在后台守护线程,不会阻止进程退出
- 仅监控 .py 文件的变更,避免不必要的开销
- 忽略目录按目录名在任意层级剪枝;键统一「绝对化 + normcase」规范化 ——Windows 大小写不同的路径写法、以及以相对路径调度的监控目录 (如默认的
plugins或.)都不会产生虚假删除/创建事件, 删除检测的前缀匹配在任意调度路径写法下均成立- 单个 handler 回调抛异常只记 warning,不会杀死轮询线程
interval (
float): 轮询间隔(秒) (默认: FILE_WATCH_POLL_INTERVAL_SECS)ignore_dirs (
Iterable[str): | None] 忽略的目录名集合;None = 使用内置默认清单(FILE_WATCHER_IGNORED_DIRS), 显式传入列表 = 整体替换(空列表 = 不忽略任何目录)
示例:
observer = PollingObserver()
observer.schedule(MyHandler(), ".", recursive=True)
observer.start()
方法列表
__init__(interval: float = FILE_WATCH_POLL_INTERVAL_SECS, ignore_dirs: Iterable[str] | None = None)
初始化轮询监控器
interval (
float): 轮询间隔(秒) (默认: FILE_WATCH_POLL_INTERVAL_SECS)ignore_dirs (
Iterable[str): | None] 忽略的目录名集合(None = 内置默认清单;显式列表 = 整体替换)
is_running -> bool(property)
轮询线程是否仍在运行
返回值: 是否运行中
schedule(event_handler: FileSystemEventHandler, path: str, recursive: bool = False) -> None
注册事件处理器与监控目录
- event_handler (
FileSystemEventHandler): 文件事件处理器 - path (
str): 要监控的目录路径 - recursive (
bool): 是否递归监控子目录 (默认: False)
start() -> None
记录初始快照后启动后台轮询线程
stop() -> None
请求停止轮询线程
join(timeout: float | None = None) -> None
等待轮询线程结束
timeout: 最长等待秒数;None = 一直等到线程退出。轮询线程
为守护线程,超时返回后线程仍会随
stop()自行退出,不会 阻塞调用方(事件循环线程内停止监控时传入有限超时)
_walk_py(path: str, recursive: bool)
遍历目录下的 .py 文件(跳过忽略目录)
内部方法
- path (
str): 目录路径 - recursive (
bool): 是否递归子目录
返回值 (Generator): .py 文件路径生成器
_key(path: str) -> str(staticmethod)
路径归一键:绝对化 + normcase
内部方法
监控目录允许以相对路径调度(默认 plugins / CLI 的 .),
键必须与删除检测的前缀(同为绝对化归一)在同一坐标系比较,
否则相对调度路径下删除事件永不触发;绝对化同时保证重叠 watch
("." 与 "plugins")的跨 watch 去重键一致。
_dispatch(handler: FileSystemEventHandler, method: str, event_type: str, src_path: str) -> None(staticmethod)
派发单个事件到 handler,回调异常只记 warning(轮询线程不因此死亡)
内部方法
_snapshot() -> None
记录所有 .py 文件的当前 mtime,作为变更比较基准
内部方法
_run() -> None
轮询主循环:比较 mtime 并在变更时回调处理器
除修改外补发创建 / 删除事件:本轮新出现的文件回调 on_created,
stat 失败(已删除)的文件回调 on_deleted。移动 = 旧路径删除 +
新路径创建(on_moved 在轮询实现下不触发)。
内部方法