fileflow-cli 0.1.0__py3-none-any.whl

fileflow/templates.py

@@ -0,0 +1,124 @@
+"""模板路径变量解析引擎.
+
+支持以下变量（在 target 路径中使用）:
+  {name}      — 文件名（不含扩展名）
+  {ext}       — 扩展名，例如 .jpg, .pdf（含点）
+  {ext_no_dot} — 扩展名不带点
+  {filename}  — 完整文件名
+  {year}      — 4 位年份
+  {month}     — 2 位月份（01-12）
+  {month:02d} — 同上，始终 2 位
+  {day}       — 2 位日期（01-31）
+  {day:02d}   — 同上，始终 2 位
+  {hour}      — 2 位小时
+  {minute}    — 2 位分钟
+"""
+
+from __future__ import annotations
+
+import string
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+class TemplateError(Exception):
+    """模板解析错误."""
+
+
+@dataclass
+class TemplateContext:
+    """模板变量上下文."""
+
+    filename: str
+    name: str
+    ext: str
+    ext_no_dot: str
+    year: str
+    month: str
+    day: str
+    hour: str
+    minute: str
+
+    @classmethod
+    def from_path(cls, path: Path) -> TemplateContext:
+        """根据文件路径和当前时间构建上下文."""
+        now = datetime.now()
+        return cls(
+            filename=path.name,
+            name=path.stem,
+            ext=path.suffix,
+            ext_no_dot=path.suffix.lstrip("."),
+            year=str(now.year),
+            month=f"{now.month:02d}",
+            day=f"{now.day:02d}",
+            hour=f"{now.hour:02d}",
+            minute=f"{now.minute:02d}",
+        )
+
+
+class TemplateFormatter(string.Formatter):
+    """自定义格式化器，支持 {month:02d} 等格式."""
+
+    def get_field(self, field_name: str, args: Any, kwargs: Any) -> Any:
+        return super().get_field(field_name, args, kwargs)
+
+
+_formatter = TemplateFormatter()
+_ALLOWED_VARS = {
+    "filename", "name", "ext", "ext_no_dot",
+    "year", "month", "day", "hour", "minute",
+}
+
+
+def render(template: str, path: Path) -> str:
+    """渲染目标路径模板.
+
+    Args:
+        template: 模板字符串，如 "Pictures/{ext}/{filename}"
+        path: 源文件路径.
+
+    Returns:
+        渲染后的路径字符串（相对路径，不含源文件根目录）.
+
+    Raises:
+        TemplateError: 模板包含未知变量.
+    """
+    ctx = TemplateContext.from_path(path)
+    try:
+        result = _formatter.vformat(template, (), ctx.__dict__)
+    except KeyError as e:
+        raise TemplateError(f"未知的模板变量: {e}") from e
+
+    # 检查是否有未识别的变量
+    for unresolved in _find_unresolved_braces(result):
+        raise TemplateError(f"未解析的模板变量: {{{unresolved}}}")
+
+    return result
+
+
+def _find_unresolved_braces(text: str) -> list[str]:
+    """查找未解析的 {var} 模式."""
+    import re
+
+    return re.findall(r"\{(\w+)\}", text)
+
+
+def resolve_path(target_template: str, source_path: Path, base_dir: Path) -> Path:
+    """将目标模板解析为绝对路径.
+
+    如果 target_template 是绝对路径，直接使用；
+    否则拼接在 base_dir 下。
+
+    Returns:
+        目标绝对路径.
+
+    Raises:
+        TemplateError: 模板变量错误.
+    """
+    rendered = render(target_template, source_path)
+    dest = Path(rendered)
+    if dest.is_absolute():
+        return dest
+    return (base_dir / dest).resolve()

fileflow_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+fileflow/__init__.py,sha256=p9sKzFor4MSLHEJGL4Y_LHG2ReYWPgoGMJB1r2slbW8,65
+fileflow/__main__.py,sha256=0j6YkleysZiA9zUxOdSOB0VLE4RJAOVa2e8xwsHJIYg,100
+fileflow/actions.py,sha256=xVKdnwCOU7EU6QAgKX82cUQx-yoEcWDI_f9qsgRuR38,4710
+fileflow/cli.py,sha256=kXW9zeaA93metNp6cI1cc0p4X8XgIU-YPBqwJJJxzh8,5357
+fileflow/config.py,sha256=xo2ukKyAxGC5ruNl6cCWXObDtrAaxUBFOP8bxdMIrOk,5226
+fileflow/engine.py,sha256=Tb37W0JbpMSJ3QP2k570DUduMKGBJC0idlgveGkPc6I,5096
+fileflow/matchers.py,sha256=q4v_jSAhR80MCfXLaaSP-u6XwXyoDZa6k5XezuHmRxQ,6352
+fileflow/report.py,sha256=BK44CWfamyqpZT_Vzoahmi4ihbBnUS_-ppimGJlmf0c,5310
+fileflow/rules.py,sha256=K_u9MOtCFzgDPbcfh62CC322tv1hgLwfmYVC8XvSuHE,2669
+fileflow/templates.py,sha256=VH-UGQqKNr6nQotKlSTtT0RlXYCUhzne_v4i63lMfsc,3267
+fileflow_cli-0.1.0.dist-info/licenses/LICENSE,sha256=hNx-ECYdfwssDGwJr1LV-rFwAjyYoTc8XQs4HEWkx4c,1062
+fileflow_cli-0.1.0.dist-info/METADATA,sha256=TFFmMsMm45f_qYuY6xOC9B6LxIPSl3aLEmjb6BGQFEI,5963
+fileflow_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+fileflow_cli-0.1.0.dist-info/entry_points.txt,sha256=G7wG0F-rGKahrDqANcAvvPyYeanLMlPkr-ruyazH5WA,46
+fileflow_cli-0.1.0.dist-info/top_level.txt,sha256=dqhg2RJdWiHT_o-4y5CgIhJV2vsJQHr3GS4Uo3zVENY,9
+fileflow_cli-0.1.0.dist-info/RECORD,,

fileflow_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fileflow_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fileflow = fileflow.cli:app

fileflow_cli-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+fileflow