fileflow-cli 0.1.0__tar.gz → 0.2.1__tar.gz

fileflow_cli-0.2.1/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: fileflow-cli
+Version: 0.2.1
+Summary: 🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具
+Author-email: Yuluo <lingeryuluo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Linger668/fileflow
+Project-URL: Repository, https://github.com/Linger668/fileflow
+Project-URL: Issues, https://github.com/Linger668/fileflow/issues
+Keywords: file-organization,file-management,cli,productivity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Desktop Environment :: File Managers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == "watch"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 🧹 FileFlow CLI
+
+**智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具**
+
+[![PyPI version](https://img.shields.io/pypi/v/fileflow-cli?style=flat-square&logo=pypi&logoColor=white&color=blue)](https://pypi.org/project/fileflow-cli/)
+[![Python Version](https://img.shields.io/pypi/pyversions/fileflow-cli?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fileflow-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/fileflow-cli?style=flat-square&color=brightgreen)](https://pypi.org/project/fileflow-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg?style=flat-square)](https://github.com/astral-sh/ruff)
+[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=flat-square&logo=github)](https://github.com/Linger668/fileflow)
+
+---
+
+<p align="center">
+  <b>🇬🇧 English</b> · <a href="README_zh.md">🇨🇳 简体中文</a>
+</p>
+
+---
+
+</div>
+
+## ✨ 一分钟上手
+
+```bash
+# 1. 安装
+pip install fileflow-cli
+
+# 2. 进入乱糟糟的下载目录
+cd ~/Downloads
+
+# 3. 生成配置文件
+fileflow init
+
+# 4. 预览整理效果（安全，不会动你的文件）
+fileflow run .
+
+# 5. 确认后执行整理
+fileflow run . --force
+```
+
+**搞定！** 你的文件被自动分类到 `Pictures/`、`Documents/`、`Code/`、`Videos/`、`Audio/` 等目录。
+
+---
+
+## 🎯 解决什么问题？
+
+> **你的 Downloads 文件夹是不是像这样？**
+
+```
+📁 Downloads/
+├── IMG_2024.jpg
+├── project_report.pdf
+├── meeting_notes.docx
+├── screenshot.png
+├── vacation_photo.jpg
+├── budget_2024.xlsx
+├── app.py
+├── style.css
+├── video.mp4
+├── song.mp3
+├── archive.zip
+├── another_doc.pdf
+├── script.js
+├── logo.svg
+├── photo_from_2019.jpg
+...
+```
+
+**整理后 →**
+
+```
+📁 Downloads/
+├── 📁 Pictures/jpg/vacation_photo.jpg
+│               png/screenshot.png
+│               svg/logo.svg
+├── 📁 Documents/pdf/project_report.pdf
+│                 docx/meeting_notes.docx
+│                 xlsx/budget_2024.xlsx
+├── 📁 Code/py/app.py
+│             css/style.css
+│             js/script.js
+├── 📁 Videos/mp4/video.mp4
+├── 📁 Audio/mp3/song.mp3
+├── 📁 Archives/zip/archive.zip
+```
+
+**干净、有序、一目了然。**
+
+---
+
+## 🚀 功能特性
+
+| 特性 | 说明 |
+|------|------|
+| 🎯 **YAML 规则引擎** | 声明式配置，想怎么分就怎么分 |
+| 🔍 **预览模式** | 先看效果再执行，安全无副作用 |
+| 📂 **6 种匹配方式** | 扩展名/通配符/正则/文件名包含/文件大小/组合 AND |
+| 📦 **文件操作** | 移动/复制/删除，自动创建目录 |
+| ⚡ **冲突处理** | 跳过/重命名/覆盖，策略可选 |
+| ⏪ **支持撤销** | `fileflow undo` 一键回退 |
+| 📊 **统计功能** | `fileflow stats` 查看整理记录 |
+| 🔌 **可扩展** | 匹配器和操作都支持插件式注册 |
+| 🎨 **终端美化** | Rich 进度条 + 彩色表格 |
+| 🪶 **轻量依赖** | 只需 typer + rich + pyyaml |
+
+---
+
+## 📖 详细用法
+
+### 命令一览
+
+```bash
+fileflow init          # 🚀 生成默认 .fileflow.yaml
+fileflow run .         # 🔍 预览整理效果
+fileflow run . --force # 📦 执行整理
+fileflow validate      # ✅ 验证配置文件
+fileflow list-rules    # 📋 查看规则列表
+fileflow stats         # 📊 查看统计信息
+fileflow undo          # ⏪ 撤销最近操作
+fileflow --help        # 📖 查看帮助
+```
+
+### 常用选项
+
+| 选项 | 说明 |
+|------|------|
+| `--config, -c` | 指定配置文件 |
+| `--dry-run, -n` | 仅预览模式 |
+| `--force, -f` | 跳过预览，直接执行 |
+| `--yes, -y` | 跳过所有确认提示 |
+| `--no-recursive` | 不扫描子目录 |
+| `--no-progress` | 不显示进度条 |
+| `--verbose, -v` | 详细输出 |
+| `--version, -V` | 显示版本 |
+
+### 示例
+
+```bash
+# 整理桌面
+fileflow run ~/Desktop
+
+# 使用自定义配置
+fileflow run . --config ~/my-rules.yaml
+
+# 不递归子目录
+fileflow run . --force --no-recursive
+
+# 只预览，不确认
+fileflow run . --dry-run -y
+
+# 撤销最近 3 次操作
+fileflow undo --steps 3
+
+# 撤销所有操作
+fileflow undo --all
+```
+
+---
+
+## 📝 配置文件 (.fileflow.yaml)
+
+```yaml
+version: "1.0"
+
+settings:
+  dry_run_by_default: true   # 默认预览模式
+  on_conflict: "skip"        # skip | rename | overwrite
+  create_target_dirs: true
+
+rules:
+  - name: "整理图片"
+    description: "按扩展名分类图片"
+    match:
+      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg", ".bmp"]
+    action: move
+    target: "Pictures/{ext_no_dot}/{filename}"
+
+  - name: "整理文档"
+    match:
+      extensions: [".pdf", ".doc", ".docx", ".xls", ".xlsx"]
+      max_size_mb: 50         # 忽略超过 50MB 的文件
+    action: move
+    target: "Documents/{ext_no_dot}/{filename}"
+
+  - name: "清理旧日志"
+    match:
+      extensions: [".log"]
+      min_size_mb: 100        # 只处理超过 100MB 的日志
+    action: delete
+    enabled: false            # 默认禁用，需手动启用
+```
+
+### 📂 路径模板变量
+
+| 变量 | 说明 | 示例值 |
+|------|------|--------|
+| `{filename}` | 完整文件名 | `report.pdf` |
+| `{name}` | 文件名（无扩展名） | `report` |
+| `{ext_no_dot}` | 扩展名（无点，推荐目录用） | `pdf` |
+| `{ext}` | 扩展名（含点） | `.pdf` |
+| `{year}` | 4 位年份 | `2026` |
+| `{month}` | 2 位月份 | `07` |
+| `{day}` | 2 位日期 | `13` |
+
+> **推荐使用 `{ext_no_dot}` 作为目录名**，如 `Documents/pdf/report.pdf`，而不是 `Documents/.pdf/report.pdf`。
+
+---
+
+## 🏗 项目架构
+
+```
+fileflow/
+├── src/fileflow/
+│   ├── cli.py        # CLI 命令 (Typer)
+│   ├── config.py     # YAML 配置加载 & 验证
+│   ├── engine.py     # 核心引擎 (扫描→匹配→执行)
+│   ├── history.py    # 操作历史 & Undo
+│   ├── rules.py      # 规则数据模型
+│   ├── matchers.py   # 匹配器注册表 + 6 种内置匹配器
+│   ├── actions.py    # 文件操作注册表 (move/copy/delete)
+│   ├── templates.py  # 路径模板变量解析
+│   └── report.py     # Rich 终端美化输出
+├── tests/            # 76 项单元测试
+├── .github/          # CI/CD 自动化
+└── pyproject.toml    # 项目配置
+```
+
+### 🧩 设计亮点
+
+**匹配器注册表模式** — 新增匹配器只需注册，无需修改其他代码：
+
+```python
+@register("my_matcher")
+class MyMatcher(Matcher):
+    def __call__(self, path: Path) -> bool:
+        return path.suffix == ".xyz"
+```
+
+---
+
+## 🧪 开发 & 测试
+
+```bash
+git clone https://github.com/Linger668/fileflow.git
+cd fileflow
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 代码检查
+ruff check src/
+ruff format src/
+mypy src/
+```
+
+---
+
+## 🤝 贡献
+
+欢迎提交 [Issue](https://github.com/Linger668/fileflow/issues) 和 [PR](https://github.com/Linger668/fileflow/pulls)！
+
+**新手友好** 👉 查看 [good first issues](https://github.com/Linger668/fileflow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+
+---
+
+## 📄 许可证
+
+[MIT](LICENSE) © 2026 Yuluo
+
+---
+
+<div align="center">
+
+**如果 FileFlow 帮到了你，请给它 ⭐ 支持一下！** 🌟
+
+[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=social)](https://github.com/Linger668/fileflow)
+
+</div>

fileflow_cli-0.2.1/README.md

@@ -0,0 +1,281 @@
+<div align="center">
+
+# 🧹 FileFlow CLI
+
+**智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具**
+
+[![PyPI version](https://img.shields.io/pypi/v/fileflow-cli?style=flat-square&logo=pypi&logoColor=white&color=blue)](https://pypi.org/project/fileflow-cli/)
+[![Python Version](https://img.shields.io/pypi/pyversions/fileflow-cli?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fileflow-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/fileflow-cli?style=flat-square&color=brightgreen)](https://pypi.org/project/fileflow-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg?style=flat-square)](https://github.com/astral-sh/ruff)
+[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=flat-square&logo=github)](https://github.com/Linger668/fileflow)
+
+---
+
+<p align="center">
+  <b>🇬🇧 English</b> · <a href="README_zh.md">🇨🇳 简体中文</a>
+</p>
+
+---
+
+</div>
+
+## ✨ 一分钟上手
+
+```bash
+# 1. 安装
+pip install fileflow-cli
+
+# 2. 进入乱糟糟的下载目录
+cd ~/Downloads
+
+# 3. 生成配置文件
+fileflow init
+
+# 4. 预览整理效果（安全，不会动你的文件）
+fileflow run .
+
+# 5. 确认后执行整理
+fileflow run . --force
+```
+
+**搞定！** 你的文件被自动分类到 `Pictures/`、`Documents/`、`Code/`、`Videos/`、`Audio/` 等目录。
+
+---
+
+## 🎯 解决什么问题？
+
+> **你的 Downloads 文件夹是不是像这样？**
+
+```
+📁 Downloads/
+├── IMG_2024.jpg
+├── project_report.pdf
+├── meeting_notes.docx
+├── screenshot.png
+├── vacation_photo.jpg
+├── budget_2024.xlsx
+├── app.py
+├── style.css
+├── video.mp4
+├── song.mp3
+├── archive.zip
+├── another_doc.pdf
+├── script.js
+├── logo.svg
+├── photo_from_2019.jpg
+...
+```
+
+**整理后 →**
+
+```
+📁 Downloads/
+├── 📁 Pictures/jpg/vacation_photo.jpg
+│               png/screenshot.png
+│               svg/logo.svg
+├── 📁 Documents/pdf/project_report.pdf
+│                 docx/meeting_notes.docx
+│                 xlsx/budget_2024.xlsx
+├── 📁 Code/py/app.py
+│             css/style.css
+│             js/script.js
+├── 📁 Videos/mp4/video.mp4
+├── 📁 Audio/mp3/song.mp3
+├── 📁 Archives/zip/archive.zip
+```
+
+**干净、有序、一目了然。**
+
+---
+
+## 🚀 功能特性
+
+| 特性 | 说明 |
+|------|------|
+| 🎯 **YAML 规则引擎** | 声明式配置，想怎么分就怎么分 |
+| 🔍 **预览模式** | 先看效果再执行，安全无副作用 |
+| 📂 **6 种匹配方式** | 扩展名/通配符/正则/文件名包含/文件大小/组合 AND |
+| 📦 **文件操作** | 移动/复制/删除，自动创建目录 |
+| ⚡ **冲突处理** | 跳过/重命名/覆盖，策略可选 |
+| ⏪ **支持撤销** | `fileflow undo` 一键回退 |
+| 📊 **统计功能** | `fileflow stats` 查看整理记录 |
+| 🔌 **可扩展** | 匹配器和操作都支持插件式注册 |
+| 🎨 **终端美化** | Rich 进度条 + 彩色表格 |
+| 🪶 **轻量依赖** | 只需 typer + rich + pyyaml |
+
+---
+
+## 📖 详细用法
+
+### 命令一览
+
+```bash
+fileflow init          # 🚀 生成默认 .fileflow.yaml
+fileflow run .         # 🔍 预览整理效果
+fileflow run . --force # 📦 执行整理
+fileflow validate      # ✅ 验证配置文件
+fileflow list-rules    # 📋 查看规则列表
+fileflow stats         # 📊 查看统计信息
+fileflow undo          # ⏪ 撤销最近操作
+fileflow --help        # 📖 查看帮助
+```
+
+### 常用选项
+
+| 选项 | 说明 |
+|------|------|
+| `--config, -c` | 指定配置文件 |
+| `--dry-run, -n` | 仅预览模式 |
+| `--force, -f` | 跳过预览，直接执行 |
+| `--yes, -y` | 跳过所有确认提示 |
+| `--no-recursive` | 不扫描子目录 |
+| `--no-progress` | 不显示进度条 |
+| `--verbose, -v` | 详细输出 |
+| `--version, -V` | 显示版本 |
+
+### 示例
+
+```bash
+# 整理桌面
+fileflow run ~/Desktop
+
+# 使用自定义配置
+fileflow run . --config ~/my-rules.yaml
+
+# 不递归子目录
+fileflow run . --force --no-recursive
+
+# 只预览，不确认
+fileflow run . --dry-run -y
+
+# 撤销最近 3 次操作
+fileflow undo --steps 3
+
+# 撤销所有操作
+fileflow undo --all
+```
+
+---
+
+## 📝 配置文件 (.fileflow.yaml)
+
+```yaml
+version: "1.0"
+
+settings:
+  dry_run_by_default: true   # 默认预览模式
+  on_conflict: "skip"        # skip | rename | overwrite
+  create_target_dirs: true
+
+rules:
+  - name: "整理图片"
+    description: "按扩展名分类图片"
+    match:
+      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg", ".bmp"]
+    action: move
+    target: "Pictures/{ext_no_dot}/{filename}"
+
+  - name: "整理文档"
+    match:
+      extensions: [".pdf", ".doc", ".docx", ".xls", ".xlsx"]
+      max_size_mb: 50         # 忽略超过 50MB 的文件
+    action: move
+    target: "Documents/{ext_no_dot}/{filename}"
+
+  - name: "清理旧日志"
+    match:
+      extensions: [".log"]
+      min_size_mb: 100        # 只处理超过 100MB 的日志
+    action: delete
+    enabled: false            # 默认禁用，需手动启用
+```
+
+### 📂 路径模板变量
+
+| 变量 | 说明 | 示例值 |
+|------|------|--------|
+| `{filename}` | 完整文件名 | `report.pdf` |
+| `{name}` | 文件名（无扩展名） | `report` |
+| `{ext_no_dot}` | 扩展名（无点，推荐目录用） | `pdf` |
+| `{ext}` | 扩展名（含点） | `.pdf` |
+| `{year}` | 4 位年份 | `2026` |
+| `{month}` | 2 位月份 | `07` |
+| `{day}` | 2 位日期 | `13` |
+
+> **推荐使用 `{ext_no_dot}` 作为目录名**，如 `Documents/pdf/report.pdf`，而不是 `Documents/.pdf/report.pdf`。
+
+---
+
+## 🏗 项目架构
+
+```
+fileflow/
+├── src/fileflow/
+│   ├── cli.py        # CLI 命令 (Typer)
+│   ├── config.py     # YAML 配置加载 & 验证
+│   ├── engine.py     # 核心引擎 (扫描→匹配→执行)
+│   ├── history.py    # 操作历史 & Undo
+│   ├── rules.py      # 规则数据模型
+│   ├── matchers.py   # 匹配器注册表 + 6 种内置匹配器
+│   ├── actions.py    # 文件操作注册表 (move/copy/delete)
+│   ├── templates.py  # 路径模板变量解析
+│   └── report.py     # Rich 终端美化输出
+├── tests/            # 76 项单元测试
+├── .github/          # CI/CD 自动化
+└── pyproject.toml    # 项目配置
+```
+
+### 🧩 设计亮点
+
+**匹配器注册表模式** — 新增匹配器只需注册，无需修改其他代码：
+
+```python
+@register("my_matcher")
+class MyMatcher(Matcher):
+    def __call__(self, path: Path) -> bool:
+        return path.suffix == ".xyz"
+```
+
+---
+
+## 🧪 开发 & 测试
+
+```bash
+git clone https://github.com/Linger668/fileflow.git
+cd fileflow
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 代码检查
+ruff check src/
+ruff format src/
+mypy src/
+```
+
+---
+
+## 🤝 贡献
+
+欢迎提交 [Issue](https://github.com/Linger668/fileflow/issues) 和 [PR](https://github.com/Linger668/fileflow/pulls)！
+
+**新手友好** 👉 查看 [good first issues](https://github.com/Linger668/fileflow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
+
+---
+
+## 📄 许可证
+
+[MIT](LICENSE) © 2026 Yuluo
+
+---
+
+<div align="center">
+
+**如果 FileFlow 帮到了你，请给它 ⭐ 支持一下！** 🌟
+
+[![GitHub Stars](https://img.shields.io/github/stars/Linger668/fileflow?style=social)](https://github.com/Linger668/fileflow)
+
+</div>

{fileflow_cli-0.1.0 → fileflow_cli-0.2.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fileflow-cli"
-version = "0.1.0"
+version = "0.2.1"
 description = "🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具"
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "MIT" }
+license = "MIT"
 authors = [
     { name = "Yuluo", email = "lingeryuluo@gmail.com" },
 ]
@@ -18,7 +18,6 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Intended Audience :: End Users/Desktop",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
@@ -72,6 +71,11 @@ python_version = "3.10"
 exclude = ["tests/"]
 ignore_missing_imports = true
 
+# Typer decorators don't have type stubs
+[[tool.mypy.overrides]]
+module = "fileflow.cli"
+disable_error_code = ["untyped-decorator"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]

{fileflow_cli-0.1.0 → fileflow_cli-0.2.1}/src/fileflow/__init__.py

@@ -1,3 +1,3 @@
 """FileFlow — 智能文件整理器."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

{fileflow_cli-0.1.0 → fileflow_cli-0.2.1}/src/fileflow/actions.py

@@ -9,9 +9,9 @@
 from __future__ import annotations
 
 import shutil
+from collections.abc import Callable
 from enum import Enum
 from pathlib import Path
-from typing import Callable
 
 from .templates import resolve_path