fileflow-cli 0.1.0__py3-none-any.whl

fileflow/__init__.py

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

fileflow/__main__.py

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

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())

fileflow/cli.py

@@ -0,0 +1,193 @@
+"""FileFlow CLI 命令入口.
+
+使用 Typer 构建，支持自动补全和 --help。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich import print as rprint
+
+from . import __version__
+from .config import (
+    ConfigError,
+    find_config,
+    generate_default_config,
+    load_config,
+)
+from .engine import run
+from .report import (
+    print_banner,
+    print_config_preview,
+    print_rule_list,
+    console,
+)
+
+app = typer.Typer(
+    name="fileflow",
+    help="🧹 智能文件整理器 — 基于 YAML 规则引擎自动分类整理文件",
+    add_completion=True,
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        rprint(f"[bold cyan]FileFlow[/] [yellow]v{__version__}[/]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", "-V",
+        help="显示版本号并退出",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """FileFlow 智能文件整理器."""
+    pass
+
+
+@app.command(name="run")
+def run_command(
+    source_dir: str = typer.Argument(
+        ".", help="要整理的目录路径（默认当前目录）",
+    ),
+    config: Optional[str] = typer.Option(
+        None, "--config", "-c",
+        help="配置文件路径（默认自动搜索 .fileflow.yaml）",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f",
+        help="跳过 dry-run 确认，直接执行",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n",
+        help="仅预览不执行（覆盖配置中的 dry_run_by_default）",
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y",
+        help="自动确认，跳过交互提示",
+    ),
+    no_recursive: bool = typer.Option(
+        False, "--no-recursive",
+        help="不递归扫描子目录",
+    ),
+) -> None:
+    """运行文件整理（默认先预览）."""
+    print_banner()
+
+    try:
+        config_path = Path(config) if config else None
+        is_dry_run = dry_run or None  # None 表示使用配置默认值
+        if force:
+            is_dry_run = False
+
+        result = run(
+            source_dir=source_dir,
+            config_path=config_path,
+            dry_run=is_dry_run,
+            force=force,
+            recursive=not no_recursive,
+        )
+    except ConfigError as e:
+        console.print(f"[red]配置错误:[/] {e}")
+        raise typer.Exit(code=1)
+    except ValueError as e:
+        console.print(f"[red]错误:[/] {e}")
+        raise typer.Exit(code=1)
+
+    result.print()
+
+    # Dry-run 模式下询问是否要执行
+    if result.dry_run and result.results and not yes:
+        proceed = typer.confirm(
+            "\n[bold]是否要执行以上操作?[/]",
+            default=False,
+        )
+        if proceed:
+            result = run(
+                source_dir=source_dir,
+                config_path=config_path,
+                dry_run=False,
+                force=False,
+                recursive=not no_recursive,
+            )
+            result.print()
+
+
+@app.command()
+def init(
+    global_config: bool = typer.Option(
+        False, "--global", "-g",
+        help="在当前目录生成默认配置",
+    ),
+) -> None:
+    """在当前目录生成默认配置文件 .fileflow.yaml."""
+    target = Path.cwd() / ".fileflow.yaml"
+    if target.exists():
+        overwrite = typer.confirm(
+            f"[yellow]{target} 已存在，是否覆盖?[/]",
+            default=False,
+        )
+        if not overwrite:
+            console.print("[yellow]已取消[/]")
+            raise typer.Exit()
+
+    content = generate_default_config()
+    target.write_text(content, encoding="utf-8")
+    console.print(f"[green]✅ 已生成配置文件:[/] {target}")
+    console.print("\n[dim]现在你可以:\n  1. 编辑 {target.name} 自定义规则\n  2. 运行 [bold]fileflow run .[/bold] 预览效果\n  3. 加 [bold]--force[/bold] 执行整理[/dim]")
+
+
+@app.command()
+def validate(
+    config: Optional[str] = typer.Option(
+        None, "--config", "-c",
+        help="配置文件路径",
+    ),
+) -> None:
+    """验证配置文件语法和规则."""
+    try:
+        config_path = Path(config) if config else None
+        data = load_config(config_path)
+        console.print("[green]✅ 配置文件验证通过[/]")
+        print_config_preview(data)
+    except ConfigError as e:
+        console.print(f"[red]❌ 配置验证失败:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def list_rules(
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v",
+        help="显示详细的匹配条件",
+    ),
+    config: Optional[str] = typer.Option(
+        None, "--config", "-c",
+        help="配置文件路径",
+    ),
+) -> None:
+    """列出当前配置中的所有规则."""
+    try:
+        config_path = Path(config) if config else None
+        data = load_config(config_path)
+        rules = data.get("rules", [])
+        if not rules:
+            console.print("[yellow]⚠ 配置中没有定义任何规则[/]")
+            raise typer.Exit()
+
+        print_rule_list(rules, verbose=verbose)
+    except ConfigError as e:
+        console.print(f"[red]错误:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

fileflow/config.py

@@ -0,0 +1,183 @@
+"""配置文件加载、解析和验证."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .rules import RuleSet
+
+
+DEFAULT_CONFIG = {
+    "version": "1.0",
+    "settings": {
+        "history_file": ".fileflow_history.json",
+        "dry_run_by_default": True,
+        "create_target_dirs": True,
+        "on_conflict": "skip",
+    },
+    "rules": [],
+}
+
+
+class ConfigError(Exception):
+    """配置相关错误."""
+
+
+def find_config(path: Path | str | None = None) -> Path | None:
+    """查找配置文件。
+
+    搜索顺序：
+    1. 用户指定的路径
+    2. 当前目录下的 .fileflow.yaml
+    3. 当前目录下的 .fileflow.yml
+    """
+    if path:
+        p = Path(path)
+        if p.exists():
+            return p.resolve()
+        raise ConfigError(f"配置文件不存在: {path}")
+
+    cwd = Path.cwd()
+    for name in (".fileflow.yaml", ".fileflow.yml"):
+        candidate = cwd / name
+        if candidate.exists():
+            return candidate.resolve()
+
+    return None
+
+
+def load_config(path: Path | str | None = None) -> dict[str, Any]:
+    """加载 YAML 配置文件.
+
+    Args:
+        path: 配置文件路径，为 None 时自动搜索.
+
+    Returns:
+        完整的配置字典（合并了默认值）.
+
+    Raises:
+        ConfigError: 文件不存在或格式错误.
+    """
+    resolved = find_config(path)
+    if resolved is None:
+        msg = (
+            "未找到 .fileflow.yaml 配置文件。\n"
+            "请先在目标目录运行: fileflow init"
+        )
+        raise ConfigError(msg)
+
+    try:
+        raw = resolved.read_text(encoding="utf-8")
+        data: dict[str, Any] = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"YAML 解析错误: {e}") from e
+    except OSError as e:
+        raise ConfigError(f"读取文件失败: {e}") from e
+
+    config = _merge_defaults(data)
+    validate_config(config)
+    return config
+
+
+def _merge_defaults(data: dict[str, Any]) -> dict[str, Any]:
+    """将用户配置与默认值合并."""
+    merged = DEFAULT_CONFIG.copy()
+    merged.update(data)
+
+    # 合并 settings
+    if "settings" in data and isinstance(data["settings"], dict):
+        merged_settings = merged["settings"].copy()
+        merged_settings.update({
+            k: v for k, v in data["settings"].items()
+            if v is not None
+        })
+        merged["settings"] = merged_settings
+
+    return merged
+
+
+def validate_config(config: dict[str, Any]) -> None:
+    """验证配置合法性."""
+    settings = config.get("settings", {})
+    valid_conflicts = {"skip", "rename", "overwrite", "ask"}
+    on_conflict = settings.get("on_conflict", "skip")
+    if on_conflict not in valid_conflicts:
+        raise ConfigError(
+            f"无效的 on_conflict 值: {on_conflict!r}。"
+            f" 可选: {', '.join(valid_conflicts)}"
+        )
+
+    rules = config.get("rules", [])
+    if not isinstance(rules, list):
+        raise ConfigError("'rules' 必须是列表")
+
+    for i, rule in enumerate(rules):
+        if not isinstance(rule, dict):
+            raise ConfigError(f"rules[{i}] 必须是对象")
+        if "name" not in rule:
+            raise ConfigError(f"rules[{i}] 缺少 'name' 字段")
+        if "match" not in rule:
+            raise ConfigError(f"规则 '{rule['name']}' 缺少 'match' 字段")
+        if "target" not in rule and rule.get("action", "move") in ("move", "copy"):
+            raise ConfigError(f"规则 '{rule['name']}' 缺少 'target' 路径")
+
+
+def generate_default_config() -> str:
+    """生成默认配置文件内容."""
+    return """# FileFlow 配置文件
+# 运行 `fileflow run` 会自动读取此文件
+
+version: "1.0"
+
+settings:
+  history_file: ".fileflow_history.json"
+  dry_run_by_default: true
+  create_target_dirs: true
+  on_conflict: "skip"          # skip | rename | overwrite | ask
+
+rules:
+  - name: "整理图片"
+    description: "按扩展名整理图片文件"
+    match:
+      extensions: [".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".bmp"]
+    action: move
+    target: "Pictures/{ext_no_dot}/{filename}"
+
+  - name: "整理文档"
+    description: "归类 Office 和 PDF 文件"
+    match:
+      extensions: [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"]
+    action: move
+    target: "Documents/{ext_no_dot}/{filename}"
+
+  - name: "整理视频"
+    description: "归类视频文件"
+    match:
+      extensions: [".mp4", ".avi", ".mkv", ".mov", ".wmv", ".flv"]
+    action: move
+    target: "Videos/{ext_no_dot}/{filename}"
+
+  - name: "整理音频"
+    description: "归类音频文件"
+    match:
+      extensions: [".mp3", ".wav", ".flac", ".aac", ".ogg", ".wma"]
+    action: move
+    target: "Audio/{ext_no_dot}/{filename}"
+
+  - name: "整理压缩包"
+    description: "归类压缩文件"
+    match:
+      extensions: [".zip", ".rar", ".7z", ".tar", ".gz", ".bz2"]
+    action: move
+    target: "Archives/{ext_no_dot}/{filename}"
+
+  - name: "整理代码文件"
+    description: "归类代码和文本文件"
+    match:
+      extensions: [".py", ".js", ".ts", ".html", ".css", ".json", ".xml", ".md", ".txt"]
+    action: move
+    target: "Code/{ext_no_dot}/{filename}"
+"""