fileflow-cli 0.1.0__tar.gz

fileflow_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuluo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fileflow_cli-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: fileflow-cli
+Version: 0.1.0
+Summary: 🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具
+Author-email: Yuluo <lingeryuluo@gmail.com>
+License: 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: License :: OSI Approved :: MIT License
+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
+
+# 🧹 FileFlow
+
+> 智能文件整理器 — 基于 YAML 规则引擎的 CLI 文件分类/移动/清理工具
+
+[![PyPI version](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/fileflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+## ✨ 功能
+
+- 📝 **YAML 规则引擎** — 声明式配置，一目了然
+- 🔍 **预览模式** — 先看效果再执行，安全无副作用
+- 📂 **多种匹配方式** — 扩展名/通配符/正则/文件名/大小
+- 🎯 **智能文件移动** — 自动创建目录，冲突策略可选
+- ⏪ **支持撤销** — 操作历史可追溯（即将推出）
+- 🎨 **Rich 终端美化** — 彩色表格，清晰直观
+- 🔌 **可扩展架构** — 匹配器和操作都支持注册表模式
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+pip install fileflow
+```
+
+### 1. 初始化配置
+
+在要整理的目录下生成配置文件：
+
+```bash
+cd ~/Downloads
+fileflow init
+```
+
+这会生成 `.fileflow.yaml`，内置了图片/文档/视频/代码等常用规则。
+
+### 2. 预览效果
+
+```bash
+fileflow run .
+```
+
+以预览模式运行，会展示每个文件将被如何整理，**不会真正移动文件**。
+
+### 3. 执行整理
+
+```bash
+fileflow run . --force
+```
+
+确认无误后，使用 `--force` 真正执行。
+
+### 一键完成（跳过确认）
+
+```bash
+fileflow run . --force --yes
+```
+
+## 📖 使用指南
+
+### 命令概览
+
+```bash
+fileflow init          # 生成默认配置文件
+fileflow run           # 运行整理（默认预览）
+fileflow validate      # 验证配置文件
+fileflow list-rules    # 查看规则列表
+fileflow --help        # 查看全部命令
+```
+
+### 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--config, -c` | 指定配置文件路径 |
+| `--dry-run, -n` | 仅预览模式 |
+| `--force, -f` | 跳过预览直接执行 |
+| `--yes, -y` | 自动确认，跳过交互提示 |
+| `--no-recursive` | 不递归扫描子目录 |
+| `--verbose, -v` | 详细输出 |
+| `--version, -V` | 显示版本 |
+
+### 配置示例
+
+```yaml
+# .fileflow.yaml
+version: "1.0"
+
+settings:
+  dry_run_by_default: true   # 默认预览模式
+  on_conflict: "skip"        # skip | rename | overwrite | ask
+  create_target_dirs: true
+
+rules:
+  - name: "整理图片"
+    match:
+      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg"]
+    action: move
+    target: "Pictures/{ext}/{filename}"
+
+  - name: "清理旧日志"
+    match:
+      extensions: [".log"]
+      modified_before_days: 30
+    action: delete
+    enabled: false  # 默认禁用
+```
+
+### 📂 模板变量
+
+目标路径 `target` 支持以下变量：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `{filename}` | 完整文件名 | `report.pdf` |
+| `{name}` | 文件名（不含扩展名） | `report` |
+| `{ext}` | 扩展名（含点，推荐用于文件名） | `.pdf` |
+| `{ext_no_dot}` | 扩展名（不含点，推荐用于目录名） | `pdf` |
+| `{year}` | 4 位年份 | `2026` |
+| `{month}` | 2 位月份 | `07` |
+| `{day}` | 2 位日期 | `13` |
+| `{hour}` | 2 位小时 | `14` |
+| `{minute}` | 2 位分钟 | `30` |
+
+## 🏗 项目架构
+
+```
+fileflow/
+├── src/fileflow/
+│   ├── cli.py        # CLI 命令定义 (Typer)
+│   ├── config.py     # YAML 配置加载 & 验证
+│   ├── engine.py     # 核心编排引擎
+│   ├── rules.py      # 规则数据模型
+│   ├── matchers.py   # 匹配器注册表 & 内置匹配器
+│   ├── actions.py    # 文件操作 (move/copy/delete)
+│   ├── templates.py  # 路径模板变量解析
+│   ├── report.py     # Rich 终端输出
+│   └── watcher.py    # 实时监控（可选）
+├── tests/            # 全模块测试覆盖
+└── pyproject.toml    # 项目配置
+```
+
+## 🧪 运行测试
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+查看测试覆盖率：
+
+```bash
+pytest --cov --cov-report=html
+```
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 PR！详情见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 📄 许可证
+
+[MIT](LICENSE) © 2026 Yuluo

fileflow_cli-0.1.0/README.md

@@ -0,0 +1,165 @@
+# 🧹 FileFlow
+
+> 智能文件整理器 — 基于 YAML 规则引擎的 CLI 文件分类/移动/清理工具
+
+[![PyPI version](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/fileflow/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+## ✨ 功能
+
+- 📝 **YAML 规则引擎** — 声明式配置，一目了然
+- 🔍 **预览模式** — 先看效果再执行，安全无副作用
+- 📂 **多种匹配方式** — 扩展名/通配符/正则/文件名/大小
+- 🎯 **智能文件移动** — 自动创建目录，冲突策略可选
+- ⏪ **支持撤销** — 操作历史可追溯（即将推出）
+- 🎨 **Rich 终端美化** — 彩色表格，清晰直观
+- 🔌 **可扩展架构** — 匹配器和操作都支持注册表模式
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+pip install fileflow
+```
+
+### 1. 初始化配置
+
+在要整理的目录下生成配置文件：
+
+```bash
+cd ~/Downloads
+fileflow init
+```
+
+这会生成 `.fileflow.yaml`，内置了图片/文档/视频/代码等常用规则。
+
+### 2. 预览效果
+
+```bash
+fileflow run .
+```
+
+以预览模式运行，会展示每个文件将被如何整理，**不会真正移动文件**。
+
+### 3. 执行整理
+
+```bash
+fileflow run . --force
+```
+
+确认无误后，使用 `--force` 真正执行。
+
+### 一键完成（跳过确认）
+
+```bash
+fileflow run . --force --yes
+```
+
+## 📖 使用指南
+
+### 命令概览
+
+```bash
+fileflow init          # 生成默认配置文件
+fileflow run           # 运行整理（默认预览）
+fileflow validate      # 验证配置文件
+fileflow list-rules    # 查看规则列表
+fileflow --help        # 查看全部命令
+```
+
+### 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--config, -c` | 指定配置文件路径 |
+| `--dry-run, -n` | 仅预览模式 |
+| `--force, -f` | 跳过预览直接执行 |
+| `--yes, -y` | 自动确认，跳过交互提示 |
+| `--no-recursive` | 不递归扫描子目录 |
+| `--verbose, -v` | 详细输出 |
+| `--version, -V` | 显示版本 |
+
+### 配置示例
+
+```yaml
+# .fileflow.yaml
+version: "1.0"
+
+settings:
+  dry_run_by_default: true   # 默认预览模式
+  on_conflict: "skip"        # skip | rename | overwrite | ask
+  create_target_dirs: true
+
+rules:
+  - name: "整理图片"
+    match:
+      extensions: [".jpg", ".jpeg", ".png", ".gif", ".svg"]
+    action: move
+    target: "Pictures/{ext}/{filename}"
+
+  - name: "清理旧日志"
+    match:
+      extensions: [".log"]
+      modified_before_days: 30
+    action: delete
+    enabled: false  # 默认禁用
+```
+
+### 📂 模板变量
+
+目标路径 `target` 支持以下变量：
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `{filename}` | 完整文件名 | `report.pdf` |
+| `{name}` | 文件名（不含扩展名） | `report` |
+| `{ext}` | 扩展名（含点，推荐用于文件名） | `.pdf` |
+| `{ext_no_dot}` | 扩展名（不含点，推荐用于目录名） | `pdf` |
+| `{year}` | 4 位年份 | `2026` |
+| `{month}` | 2 位月份 | `07` |
+| `{day}` | 2 位日期 | `13` |
+| `{hour}` | 2 位小时 | `14` |
+| `{minute}` | 2 位分钟 | `30` |
+
+## 🏗 项目架构
+
+```
+fileflow/
+├── src/fileflow/
+│   ├── cli.py        # CLI 命令定义 (Typer)
+│   ├── config.py     # YAML 配置加载 & 验证
+│   ├── engine.py     # 核心编排引擎
+│   ├── rules.py      # 规则数据模型
+│   ├── matchers.py   # 匹配器注册表 & 内置匹配器
+│   ├── actions.py    # 文件操作 (move/copy/delete)
+│   ├── templates.py  # 路径模板变量解析
+│   ├── report.py     # Rich 终端输出
+│   └── watcher.py    # 实时监控（可选）
+├── tests/            # 全模块测试覆盖
+└── pyproject.toml    # 项目配置
+```
+
+## 🧪 运行测试
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+查看测试覆盖率：
+
+```bash
+pytest --cov --cov-report=html
+```
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 PR！详情见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 📄 许可证
+
+[MIT](LICENSE) © 2026 Yuluo

fileflow_cli-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fileflow-cli"
+version = "0.1.0"
+description = "🧹 智能文件整理器 — YAML 规则引擎驱动的 CLI 文件分类/移动/清理工具"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Yuluo", email = "lingeryuluo@gmail.com" },
+]
+keywords = ["file-organization", "file-management", "cli", "productivity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Desktop Environment :: File Managers",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+watch = ["watchdog>=4.0.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Linger668/fileflow"
+Repository = "https://github.com/Linger668/fileflow"
+Issues = "https://github.com/Linger668/fileflow/issues"
+
+[project.scripts]
+fileflow = "fileflow.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "SIM"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+exclude = ["tests/"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=fileflow --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["fileflow"]

fileflow_cli-0.1.0/setup.cfg

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

fileflow_cli-0.1.0/src/fileflow/__init__.py

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

fileflow_cli-0.1.0/src/fileflow/__main__.py

@@ -0,0 +1,6 @@
+"""支持 python -m fileflow 运行."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

fileflow_cli-0.1.0/src/fileflow/actions.py

@@ -0,0 +1,164 @@
+"""文件操作：移动、复制、删除等.
+
+支持冲突策略：
+- skip: 跳过目标已存在的文件
+- rename: 自动添加后缀 (1), (2)...
+- overwrite: 覆盖目标文件
+"""
+
+from __future__ import annotations
+
+import shutil
+from enum import Enum
+from pathlib import Path
+from typing import Callable
+
+from .templates import resolve_path
+
+
+class ConflictStrategy(str, Enum):
+    """文件冲突处理策略."""
+
+    SKIP = "skip"
+    RENAME = "rename"
+    OVERWRITE = "overwrite"
+
+
+class ActionResult:
+    """一次文件操作的结果."""
+
+    def __init__(
+        self,
+        source: Path,
+        target: Path | None = None,
+        success: bool = True,
+        action: str = "move",
+        skipped: bool = False,
+        error: str | None = None,
+    ) -> None:
+        self.source = source
+        self.target = target
+        self.success = success
+        self.action = action
+        self.skipped = skipped
+        self.error = error
+
+    @property
+    def summary(self) -> str:
+        if self.error:
+            return f"[red]✗ {self.action}: {self.source.name}[/] → {self.error}"
+        if self.skipped:
+            return f"[yellow]– 跳过: {self.source.name}[/] (目标已存在)"
+        return f"[green]✓ {self.action}: {self.source.name}[/] → {self.target}"
+
+
+def resolve_target_path(
+    target_template: str,
+    source: Path,
+    base_dir: Path,
+    conflict: ConflictStrategy = ConflictStrategy.SKIP,
+) -> Path:
+    """解析目标路径，并根据冲突策略处理.
+
+    Returns:
+        最终的目标路径（可能已根据冲突策略调整）.
+    """
+    dest = resolve_path(target_template, source, base_dir)
+
+    if conflict == ConflictStrategy.RENAME and dest.exists():
+        dest = _find_available_name(dest)
+
+    return dest
+
+
+def _find_available_name(dest: Path) -> Path:
+    """找到一个不存在的路径，如 file (1).txt, file (2).txt."""
+    parent = dest.parent
+    stem = dest.stem
+    suffix = dest.suffix
+    counter = 1
+    while True:
+        new_name = f"{stem} ({counter}){suffix}"
+        candidate = parent / new_name
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def move_file(
+    source: Path,
+    target_template: str,
+    base_dir: Path,
+    create_dirs: bool = True,
+    conflict: ConflictStrategy = ConflictStrategy.SKIP,
+) -> ActionResult:
+    """移动文件."""
+    try:
+        dest = resolve_target_path(target_template, source, base_dir, conflict)
+        if dest == source:
+            return ActionResult(source, dest, success=True, action="move")
+
+        if dest.exists() and conflict == ConflictStrategy.SKIP:
+            return ActionResult(source, dest, skipped=True, action="move")
+
+        if create_dirs:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+        shutil.move(str(source), str(dest))
+        return ActionResult(source, dest, success=True, action="move")
+    except OSError as e:
+        return ActionResult(source, error=str(e), success=False, action="move")
+
+
+def copy_file(
+    source: Path,
+    target_template: str,
+    base_dir: Path,
+    create_dirs: bool = True,
+    conflict: ConflictStrategy = ConflictStrategy.SKIP,
+) -> ActionResult:
+    """复制文件."""
+    try:
+        dest = resolve_target_path(target_template, source, base_dir, conflict)
+        if dest.exists() and conflict == ConflictStrategy.SKIP:
+            return ActionResult(source, dest, skipped=True, action="copy")
+
+        if create_dirs:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+        shutil.copy2(str(source), str(dest))
+        return ActionResult(source, dest, success=True, action="copy")
+    except OSError as e:
+        return ActionResult(source, error=str(e), success=False, action="copy")
+
+
+def delete_file(source: Path) -> ActionResult:
+    """删除文件."""
+    try:
+        source.unlink()
+        return ActionResult(source, success=True, action="delete")
+    except OSError as e:
+        return ActionResult(source, error=str(e), success=False, action="delete")
+
+
+# ── 操作注册表 ─────────────────────────────────────────────
+
+ActionFunc = Callable[..., ActionResult]
+
+_actions: dict[str, ActionFunc] = {
+    "move": move_file,
+    "copy": copy_file,
+    "delete": delete_file,
+}
+
+
+def get_action(name: str) -> ActionFunc:
+    """按名称获取操作函数."""
+    if name not in _actions:
+        raise KeyError(f"未知操作: {name!r}，可选: {list(_actions.keys())}")
+    return _actions[name]
+
+
+def list_actions() -> list[str]:
+    """列出所有注册的操作名称."""
+    return list(_actions.keys())