filepulse 0.1.0__tar.gz

filepulse-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: filepulse
+Version: 0.1.0
+Summary: 文件监控与归档同步工具 — 轮询检测文件变化并自动同步，支持 zip 归档自动解压处理
+Author: songwupei
+License: MIT
+Project-URL: Homepage, https://codeberg.org/songwupei/filepulse
+Project-URL: Repository, https://codeberg.org/songwupei/filepulse
+Project-URL: Issues, https://codeberg.org/songwupei/filepulse/issues
+Keywords: file-sync,monitor,polling,archive,zip,backup
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+
+# filepulse — 文件监控与归档同步工具
+
+轮询检测源文件变化并自动同步到目标位置，支持 zip 归档自动解压处理。
+
+## 功能特性
+
+- 📁 监控文件变化（时间戳、大小、哈希），自动同步到目标位置
+- 📦 监控压缩包（zip），自动解压并分发到多个目标目录
+- 🔀 支持扁平化复制（丢弃子目录，文件直达目标）
+- 🪝 前后置钩子脚本（sync/archive 处理前后执行自定义逻辑）
+- 💾 自动备份功能
+- 🔄 可配置的检查间隔
+- 📊 运行状态统计
+- 🎯 支持简单和复杂映射配置
+
+## 系统要求
+
+- Python ≥ 3.10
+- pip install 自动安装依赖 (tomli, tomli-w, click)
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+pip install filepulse
+```
+
+### 2. 初始化
+
+```bash
+filepulse init    # 创建 config.toml, 日志和备份目录
+```
+
+### 3. 配置监控文件
+
+编辑 `config.toml`：
+
+```toml
+[monitor]
+interval = 2.0
+
+[files]
+"source/path/file.txt" = "target/path/file.txt"
+```
+
+### 4. 启动监控
+
+```bash
+# 文件同步
+filepulse sync run config.toml              # 前台持续监控
+filepulse sync run --daemon config.toml     # 后台运行
+filepulse sync once config.toml             # 一次性同步
+
+# 归档处理
+filepulse archive run config.toml           # 前台持续扫描
+filepulse archive run --daemon config.toml  # 后台运行
+filepulse archive once config.toml          # 一次性处理
+filepulse archive check config.toml         # 干跑：列出待处理 zip
+
+# 守护进程管理
+filepulse daemon status                      # 查看状态
+filepulse daemon stop                        # 停止
+filepulse daemon logs 50                     # 查看日志
+filepulse daemon reload                      # 重载配置
+```
+
+## 命令参考
+
+### 文件同步 (`filepulse sync`)
+
+| 命令 | 说明 |
+|---|---|
+| `sync run <config>` | 前台持续监控 |
+| `sync run --daemon <config>` | 后台持续监控 |
+| `sync once <config>` | 一次性同步所有变更文件 |
+| `sync check <FILE> <config>` | 检查单个文件状态 |
+| `sync stats <config>` | 列出配置的文件映射 |
+
+### 归档处理 (`filepulse archive`)
+
+| 命令 | 说明 |
+|---|---|
+| `archive run <config>` | 前台持续扫描 zip |
+| `archive run --daemon <config>` | 后台持续扫描 |
+| `archive once <config>` | 一次性处理待处理 zip |
+| `archive check <config>` | 干跑：列出待处理 zip |
+
+### 守护进程 (`filepulse daemon`)
+
+| 命令 | 说明 |
+|---|---|
+| `daemon status` | 查看所有后台进程 |
+| `daemon stop` | 停止所有后台进程 |
+| `daemon logs [N]` | 查看最近 N 行日志 |
+| `daemon reload` | 停止后重新启动 |
+
+### 工具
+
+```bash
+filepulse clean               # 清理旧日志和备份
+filepulse treasury-run        # 运行司库日报流程
+filepulse --version           # 版本信息
+```
+
+### Just 别名（可选）
+
+如果安装了 [Just](https://just.systems)，可使用快捷别名：
+
+```bash
+just daemon         # → filepulse sync run --daemon config.toml
+just foreground     # → filepulse sync run config.toml
+just status         # → filepulse daemon status
+just stop           # → filepulse daemon stop
+just logs           # → filepulse daemon logs 50
+```
+
+## 配置说明
+
+### 文件同步配置
+
+**简单格式**：
+```toml
+[files]
+"源文件路径" = "目标文件路径"
+```
+
+**详细格式（带钩子）**：
+```toml
+[files.my_entry]
+source = "/path/to/source.xlsx"
+target = "/path/to/target.xlsx"
+on_before_sync = ""   # 前置钩子脚本
+on_after_sync = ""    # 后置钩子脚本
+```
+
+**监控选项** (`[monitor]`)：
+- `interval`: 检查间隔（秒，默认 2.0）
+- `check_size`: 检查文件大小变化（默认 true）
+- `check_mtime`: 检查修改时间变化（默认 true）
+- `check_hash`: 检查文件哈希变化（默认 false）
+- `create_backup`: 同步前创建备份（默认 true）
+- `backup_dir`: 备份文件目录（默认 "backup"）
+
+### 归档处理配置
+
+```toml
+[archive_monitor]
+interval = 10.0                    # 检查间隔（秒）
+extract_temp = "/tmp/sync_extract" # 解压临时目录
+base_dir = "/path/to/base"         # 源文件扫描根目录
+
+[[archives]]
+name = "任务名"
+source_pattern = "inbox/通道-*/data-*.zip"  # glob 模式（相对于 base_dir）
+target_dirs = ["/path/to/output1", "/path/to/output2"]  # 多目标（推荐）
+flatten_targets = ["/path/to/output2"]  # 扁平化目标（丢弃子目录）
+rename_to = ""                     # 解压后重命名顶层目录
+archive_dir = "/path/to/processed" # 已处理 zip 归档位置
+on_before_process = ""             # 前置钩子脚本
+on_after_process = ""              # 后置钩子脚本
+```
+
+### 钩子环境变量
+
+| 变量 | 文件同步 | 归档处理 |
+|---|---|---|
+| `MONITOR_TYPE` | `file_sync` | `archive` |
+| `MONITOR_EVENT` | `before_sync` / `after_sync` | `before_process` / `after_process` |
+| `MONITOR_SOURCE` | 源文件路径 | zip 文件路径 |
+| `MONITOR_TARGET` | 目标文件路径 | 目标目录 |
+| `MONITOR_TASK` | file_id | 任务名 |
+| `MONITOR_EXTRACTED` | — | 目标目录（仅后置钩子） |
+
+### 状态文件与路径
+
+filepulse 遵循 XDG 规范存储运行时数据：
+
+- 状态文件: `~/.local/share/filepulse/` (或 `$XDG_DATA_HOME/filepulse/`)
+- 日志文件: `~/.cache/filepulse/` (或 `$XDG_CACHE_HOME/filepulse/`)
+- PID 文件: `~/.local/share/filepulse/`
+
+可通过环境变量覆盖：`FILEPULSE_DATA_DIR`, `FILEPULSE_CACHE_DIR`
+
+## 迁移指南
+
+从旧 `monitor.py` 迁移：
+
+| 旧 | 新 |
+|---|---|
+| `python monitor.py config.toml --foreground` | `filepulse sync run config.toml` |
+| `python monitor.py config.toml --daemon` | `filepulse sync run --daemon config.toml` |
+| `python monitor.py config.toml --sync-all` | `filepulse sync once config.toml` |
+| `python monitor.py config.toml --check <F>` | `filepulse sync check <F> config.toml` |
+| `python monitor.py config.toml --stats` | `filepulse sync stats config.toml` |
+| `python monitor.py config.toml --archive-foreground` | `filepulse archive run config.toml` |
+| `python monitor.py config.toml --archive-daemon` | `filepulse archive run --daemon config.toml` |
+| `python monitor.py config.toml --archive-sync` | `filepulse archive once config.toml` |
+| `python monitor.py config.toml --archive-check` | `filepulse archive check config.toml` |
+
+配置文件 100% 向后兼容。
+
+## 故障排除
+
+- **导入错误** → `pip install filepulse` 会自动安装依赖
+- **文件未同步** → `filepulse daemon logs 50` 查看日志
+- **归档 zip 未处理** → `filepulse archive check config.toml` 干跑
+- **前台调试** → `filepulse archive run config.toml` 前台运行查看实时输出

filepulse-0.1.0/README.md

@@ -0,0 +1,208 @@
+# filepulse — 文件监控与归档同步工具
+
+轮询检测源文件变化并自动同步到目标位置，支持 zip 归档自动解压处理。
+
+## 功能特性
+
+- 📁 监控文件变化（时间戳、大小、哈希），自动同步到目标位置
+- 📦 监控压缩包（zip），自动解压并分发到多个目标目录
+- 🔀 支持扁平化复制（丢弃子目录，文件直达目标）
+- 🪝 前后置钩子脚本（sync/archive 处理前后执行自定义逻辑）
+- 💾 自动备份功能
+- 🔄 可配置的检查间隔
+- 📊 运行状态统计
+- 🎯 支持简单和复杂映射配置
+
+## 系统要求
+
+- Python ≥ 3.10
+- pip install 自动安装依赖 (tomli, tomli-w, click)
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+pip install filepulse
+```
+
+### 2. 初始化
+
+```bash
+filepulse init    # 创建 config.toml, 日志和备份目录
+```
+
+### 3. 配置监控文件
+
+编辑 `config.toml`：
+
+```toml
+[monitor]
+interval = 2.0
+
+[files]
+"source/path/file.txt" = "target/path/file.txt"
+```
+
+### 4. 启动监控
+
+```bash
+# 文件同步
+filepulse sync run config.toml              # 前台持续监控
+filepulse sync run --daemon config.toml     # 后台运行
+filepulse sync once config.toml             # 一次性同步
+
+# 归档处理
+filepulse archive run config.toml           # 前台持续扫描
+filepulse archive run --daemon config.toml  # 后台运行
+filepulse archive once config.toml          # 一次性处理
+filepulse archive check config.toml         # 干跑：列出待处理 zip
+
+# 守护进程管理
+filepulse daemon status                      # 查看状态
+filepulse daemon stop                        # 停止
+filepulse daemon logs 50                     # 查看日志
+filepulse daemon reload                      # 重载配置
+```
+
+## 命令参考
+
+### 文件同步 (`filepulse sync`)
+
+| 命令 | 说明 |
+|---|---|
+| `sync run <config>` | 前台持续监控 |
+| `sync run --daemon <config>` | 后台持续监控 |
+| `sync once <config>` | 一次性同步所有变更文件 |
+| `sync check <FILE> <config>` | 检查单个文件状态 |
+| `sync stats <config>` | 列出配置的文件映射 |
+
+### 归档处理 (`filepulse archive`)
+
+| 命令 | 说明 |
+|---|---|
+| `archive run <config>` | 前台持续扫描 zip |
+| `archive run --daemon <config>` | 后台持续扫描 |
+| `archive once <config>` | 一次性处理待处理 zip |
+| `archive check <config>` | 干跑：列出待处理 zip |
+
+### 守护进程 (`filepulse daemon`)
+
+| 命令 | 说明 |
+|---|---|
+| `daemon status` | 查看所有后台进程 |
+| `daemon stop` | 停止所有后台进程 |
+| `daemon logs [N]` | 查看最近 N 行日志 |
+| `daemon reload` | 停止后重新启动 |
+
+### 工具
+
+```bash
+filepulse clean               # 清理旧日志和备份
+filepulse treasury-run        # 运行司库日报流程
+filepulse --version           # 版本信息
+```
+
+### Just 别名（可选）
+
+如果安装了 [Just](https://just.systems)，可使用快捷别名：
+
+```bash
+just daemon         # → filepulse sync run --daemon config.toml
+just foreground     # → filepulse sync run config.toml
+just status         # → filepulse daemon status
+just stop           # → filepulse daemon stop
+just logs           # → filepulse daemon logs 50
+```
+
+## 配置说明
+
+### 文件同步配置
+
+**简单格式**：
+```toml
+[files]
+"源文件路径" = "目标文件路径"
+```
+
+**详细格式（带钩子）**：
+```toml
+[files.my_entry]
+source = "/path/to/source.xlsx"
+target = "/path/to/target.xlsx"
+on_before_sync = ""   # 前置钩子脚本
+on_after_sync = ""    # 后置钩子脚本
+```
+
+**监控选项** (`[monitor]`)：
+- `interval`: 检查间隔（秒，默认 2.0）
+- `check_size`: 检查文件大小变化（默认 true）
+- `check_mtime`: 检查修改时间变化（默认 true）
+- `check_hash`: 检查文件哈希变化（默认 false）
+- `create_backup`: 同步前创建备份（默认 true）
+- `backup_dir`: 备份文件目录（默认 "backup"）
+
+### 归档处理配置
+
+```toml
+[archive_monitor]
+interval = 10.0                    # 检查间隔（秒）
+extract_temp = "/tmp/sync_extract" # 解压临时目录
+base_dir = "/path/to/base"         # 源文件扫描根目录
+
+[[archives]]
+name = "任务名"
+source_pattern = "inbox/通道-*/data-*.zip"  # glob 模式（相对于 base_dir）
+target_dirs = ["/path/to/output1", "/path/to/output2"]  # 多目标（推荐）
+flatten_targets = ["/path/to/output2"]  # 扁平化目标（丢弃子目录）
+rename_to = ""                     # 解压后重命名顶层目录
+archive_dir = "/path/to/processed" # 已处理 zip 归档位置
+on_before_process = ""             # 前置钩子脚本
+on_after_process = ""              # 后置钩子脚本
+```
+
+### 钩子环境变量
+
+| 变量 | 文件同步 | 归档处理 |
+|---|---|---|
+| `MONITOR_TYPE` | `file_sync` | `archive` |
+| `MONITOR_EVENT` | `before_sync` / `after_sync` | `before_process` / `after_process` |
+| `MONITOR_SOURCE` | 源文件路径 | zip 文件路径 |
+| `MONITOR_TARGET` | 目标文件路径 | 目标目录 |
+| `MONITOR_TASK` | file_id | 任务名 |
+| `MONITOR_EXTRACTED` | — | 目标目录（仅后置钩子） |
+
+### 状态文件与路径
+
+filepulse 遵循 XDG 规范存储运行时数据：
+
+- 状态文件: `~/.local/share/filepulse/` (或 `$XDG_DATA_HOME/filepulse/`)
+- 日志文件: `~/.cache/filepulse/` (或 `$XDG_CACHE_HOME/filepulse/`)
+- PID 文件: `~/.local/share/filepulse/`
+
+可通过环境变量覆盖：`FILEPULSE_DATA_DIR`, `FILEPULSE_CACHE_DIR`
+
+## 迁移指南
+
+从旧 `monitor.py` 迁移：
+
+| 旧 | 新 |
+|---|---|
+| `python monitor.py config.toml --foreground` | `filepulse sync run config.toml` |
+| `python monitor.py config.toml --daemon` | `filepulse sync run --daemon config.toml` |
+| `python monitor.py config.toml --sync-all` | `filepulse sync once config.toml` |
+| `python monitor.py config.toml --check <F>` | `filepulse sync check <F> config.toml` |
+| `python monitor.py config.toml --stats` | `filepulse sync stats config.toml` |
+| `python monitor.py config.toml --archive-foreground` | `filepulse archive run config.toml` |
+| `python monitor.py config.toml --archive-daemon` | `filepulse archive run --daemon config.toml` |
+| `python monitor.py config.toml --archive-sync` | `filepulse archive once config.toml` |
+| `python monitor.py config.toml --archive-check` | `filepulse archive check config.toml` |
+
+配置文件 100% 向后兼容。
+
+## 故障排除
+
+- **导入错误** → `pip install filepulse` 会自动安装依赖
+- **文件未同步** → `filepulse daemon logs 50` 查看日志
+- **归档 zip 未处理** → `filepulse archive check config.toml` 干跑
+- **前台调试** → `filepulse archive run config.toml` 前台运行查看实时输出

filepulse-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "filepulse"
+version = "0.1.0"
+description = "文件监控与归档同步工具 — 轮询检测文件变化并自动同步，支持 zip 归档自动解压处理"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "songwupei"},
+]
+keywords = ["file-sync", "monitor", "polling", "archive", "zip", "backup"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Archiving",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "tomli>=2.0",
+    "tomli-w>=1.0",
+    "click>=8.1",
+]
+
+[project.scripts]
+filepulse = "filepulse.cli:main"
+
+[project.urls]
+Homepage = "https://codeberg.org/songwupei/filepulse"
+Repository = "https://codeberg.org/songwupei/filepulse"
+Issues = "https://codeberg.org/songwupei/filepulse/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

filepulse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

filepulse-0.1.0/src/filepulse/__init__.py

@@ -0,0 +1,3 @@
+"""filepulse — 文件监控与归档同步工具."""
+
+__version__ = "0.1.0"

filepulse-0.1.0/src/filepulse/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m filepulse``."""
+
+from .cli import main
+
+main()