fileflow-cli 0.1.0__py3-none-any.whl

fileflow/engine.py

@@ -0,0 +1,167 @@
+"""核心编排引擎：扫描 → 匹配 → 执行."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .actions import (
+    ConflictStrategy,
+    ActionResult,
+    get_action,
+)
+from .config import load_config
+from .matchers import matches
+from .report import format_results, print_summary
+from .rules import Rule, RuleSet
+
+
+class EngineResult:
+    """一次引擎运行的结果."""
+
+    def __init__(
+        self,
+        source_dir: Path,
+        results: list[ActionResult],
+        dry_run: bool,
+        rule_matches: dict[str, int],
+    ) -> None:
+        self.source_dir = source_dir
+        self.results = results
+        self.dry_run = dry_run
+        self.rule_matches = rule_matches
+
+    @property
+    def success_count(self) -> int:
+        return sum(1 for r in self.results if r.success and not r.skipped)
+
+    @property
+    def skipped_count(self) -> int:
+        return sum(1 for r in self.results if r.skipped)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for r in self.results if not r.success)
+
+    def print(self) -> None:
+        """打印结果到终端."""
+        print_summary(self)
+
+
+def run(
+    source_dir: str | Path,
+    config_path: str | Path | None = None,
+    dry_run: bool | None = None,
+    force: bool = False,
+    recursive: bool = True,
+) -> EngineResult:
+    """运行文件整理.
+
+    1. 加载配置
+    2. 扫描源目录
+    3. 对每个文件匹配规则
+    4. 执行操作（或预览）
+
+    Args:
+        source_dir: 要整理的目录路径.
+        config_path: 配置文件路径，None 则自动搜索.
+        dry_run: 是否仅预览；None 则使用配置中的 dry_run_by_default.
+        force: 如果 True 且 dry_run 未明确设置，则 dry_run=False.
+        recursive: 是否递归扫描子目录.
+    """
+    source = Path(source_dir).resolve()
+    if not source.is_dir():
+        raise ValueError(f"源路径不是目录: {source}")
+
+    config = load_config(config_path)
+    settings = config.get("settings", {})
+
+    # 确定 dry-run 模式
+    if dry_run is None:
+        dry_run = settings.get("dry_run_by_default", True)
+
+    if force and dry_run is None:
+        dry_run = False
+
+    conflict_str = ConflictStrategy(settings.get("on_conflict", "skip"))
+    create_dirs = settings.get("create_target_dirs", True)
+
+    rule_set = RuleSet.load_from_yaml(config.get("rules", []))
+
+    # 扫描文件
+    files = _scan_files(source, recursive)
+    results: list[ActionResult] = []
+    rule_matches: dict[str, int] = {}
+    unmatched_count = 0
+
+    for file_path in files:
+        matched = False
+        for rule in rule_set.active_rules:
+            if matches(file_path, rule):
+                matched = True
+                rule_matches[rule.name] = rule_matches.get(rule.name, 0) + 1
+
+                if dry_run:
+                    # 预览模式：只记录不执行
+                    from .templates import resolve_path
+
+                    try:
+                        dest = resolve_path(rule.target, file_path, source)
+                        results.append(
+                            ActionResult(
+                                file_path,
+                                target=dest,
+                                success=True,
+                                action=f"[dry-run] {rule.action}",
+                            )
+                        )
+                    except Exception as e:
+                        results.append(
+                            ActionResult(
+                                file_path,
+                                error=str(e),
+                                success=False,
+                                action=rule.action,
+                            )
+                        )
+                else:
+                    # 执行模式
+                    action_func = get_action(rule.action)
+                    result = action_func(
+                        file_path,
+                        rule.target,
+                        source,
+                        create_dirs=create_dirs,
+                        conflict=conflict_str,
+                    )
+                    results.append(result)
+                break  # 一个文件只匹配第一条规则
+
+        if not matched:
+            unmatched_count += 1
+
+    return EngineResult(
+        source_dir=source,
+        results=results,
+        dry_run=dry_run,
+        rule_matches=rule_matches,
+    )
+
+
+def _scan_files(directory: Path, recursive: bool) -> list[Path]:
+    """扫描目录中的普通文件（忽略隐藏文件）. """
+    files: list[Path] = []
+
+    if recursive:
+        # 排除隐藏目录（以 . 开头）
+        for entry in directory.rglob("*"):
+            if entry.is_file() and not any(
+                part.startswith(".") for part in entry.relative_to(directory).parts
+            ):
+                files.append(entry)
+    else:
+        for entry in directory.iterdir():
+            if entry.is_file() and not entry.name.startswith("."):
+                files.append(entry)
+
+    return sorted(files)

fileflow/matchers.py

@@ -0,0 +1,214 @@
+"""匹配器注册表和内置匹配器.
+
+匹配器是一个可调用对象: (Path) -> bool
+注册表模式使新增匹配器只需注册，无需修改其他代码。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .rules import Rule
+
+# 类型: 匹配器函数签名
+MatcherFunc = Callable[[Path], bool]
+
+
+# ── 匹配器注册表 ──────────────────────────────────────────
+
+_matchers: dict[str, type[Matcher]] = {}
+
+
+def register(name: str) -> Callable[[type[Matcher]], type[Matcher]]:
+    """装饰器：在注册表中注册一个匹配器类."""
+
+    def wrapper(cls: type[Matcher]) -> type[Matcher]:
+        _matchers[name] = cls
+        return cls
+
+    return wrapper
+
+
+def get_matcher(name: str) -> type[Matcher]:
+    """按名称获取匹配器类."""
+    if name not in _matchers:
+        raise KeyError(f"未知的匹配器: {name!r}，可选: {list(_matchers.keys())}")
+    return _matchers[name]
+
+
+def list_matchers() -> list[str]:
+    """列出所有注册的匹配器名称."""
+    return list(_matchers.keys())
+
+
+# ── 基类 ────────────────────────────────────────────────
+
+
+class Matcher:
+    """匹配器基类.
+
+    子类需实现 __call__(path) -> bool。
+    构造时接收匹配条件值（字符串或列表）。
+    """
+
+    def __init__(self, value: Any) -> None:
+        self.value = value
+
+    def __call__(self, path: Path) -> bool:
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.value!r})"
+
+
+# ── 内置匹配器 ────────────────────────────────────────────
+
+
+@register("extensions")
+class ExtensionsMatcher(Matcher):
+    """按文件扩展名匹配."""
+
+    def __init__(self, value: list[str]) -> None:
+        # 统一处理：确保 . 开头、小写
+        self.extensions = {
+            e.lower() if e.startswith(".") else f".{e.lower()}"
+            for e in value
+        }
+
+    def __call__(self, path: Path) -> bool:
+        if not path.is_file():
+            return False
+        return path.suffix.lower() in self.extensions
+
+
+@register("patterns")
+class PatternsMatcher(Matcher):
+    """按文件名通配符模式匹配（如 *.txt, data_*.csv）. """
+
+    def __init__(self, value: list[str]) -> None:
+        import fnmatch
+
+        self._fnmatch = fnmatch
+        self.patterns = value
+
+    def __call__(self, path: Path) -> bool:
+        name = path.name
+        return any(self._fnmatch.fnmatch(name, p) for p in self.patterns)
+
+
+@register("name_contains")
+class NameContainsMatcher(Matcher):
+    """按文件名包含子串匹配."""
+
+    def __init__(self, value: list[str]) -> None:
+        self.substrings = value
+
+    def __call__(self, path: Path) -> bool:
+        name = path.name.lower()
+        return any(s.lower() in name for s in self.substrings)
+
+
+@register("name_regex")
+class NameRegexMatcher(Matcher):
+    """按文件名正则表达式匹配."""
+
+    def __init__(self, value: list[str]) -> None:
+        self.patterns = [re.compile(p, re.IGNORECASE) for p in value]
+
+    def __call__(self, path: Path) -> bool:
+        name = path.name
+        return any(p.search(name) is not None for p in self.patterns)
+
+
+@register("min_size_mb")
+@register("max_size_mb")
+class SizeMatcher(Matcher):
+    """按文件大小匹配.
+
+    支持 min_size_mb / max_size_mb / min_size_bytes / max_size_bytes。
+    值由 Rule 对象直接提供，本匹配器不直接构造。
+    """
+
+    def __init__(self, value: float | int) -> None:
+        self.limit = value
+
+    @classmethod
+    def from_rule(cls, rule: Rule) -> SizeMatcher | None:
+        """从 Rule 构建大小匹配器（合并所有大小条件）."""
+        min_bytes = None
+        max_bytes = None
+
+        if rule.min_size_mb is not None:
+            min_bytes = int(rule.min_size_mb * 1024 * 1024)
+        if rule.min_size_bytes is not None:
+            min_bytes = rule.min_size_bytes
+        if rule.max_size_mb is not None:
+            max_bytes = int(rule.max_size_mb * 1024 * 1024)
+        if rule.max_size_bytes is not None:
+            max_bytes = rule.max_size_bytes
+
+        if min_bytes is None and max_bytes is None:
+            return None
+
+        sm = cls(0)
+        sm.min_bytes = min_bytes
+        sm.max_bytes = max_bytes
+        return sm
+
+    def __call__(self, path: Path) -> bool:
+        if not path.is_file():
+            return False
+        try:
+            size = path.stat().st_size
+        except OSError:
+            return False
+
+        min_b = getattr(self, "min_bytes", None)
+        max_b = getattr(self, "max_bytes", None)
+
+        if min_b is not None and size < min_b:
+            return False
+        if max_b is not None and size > max_b:
+            return False
+        return True
+
+
+# ── 规则匹配引擎 ──────────────────────────────────────────
+
+
+def build_matchers(rule: Rule) -> list[MatcherFunc]:
+    """从一条规则构建所有匹配器函数列表.
+
+    返回值是一个可调用函数列表，每个接受 Path 返回 bool。
+    """
+    matchers: list[MatcherFunc] = []
+
+    if rule.extensions:
+        matchers.append(ExtensionsMatcher(rule.extensions))
+    if rule.patterns:
+        matchers.append(PatternsMatcher(rule.patterns))
+    if rule.name_contains:
+        matchers.append(NameContainsMatcher(rule.name_contains))
+    if rule.name_regex:
+        matchers.append(NameRegexMatcher(rule.name_regex))
+
+    size_matcher = SizeMatcher.from_rule(rule)
+    if size_matcher is not None:
+        matchers.append(size_matcher)
+
+    return matchers
+
+
+def matches(path: Path, rule: Rule) -> bool:
+    """判断一个文件是否匹配一条规则.
+
+    - 如果规则没有任何匹配条件，返回 False（不会匹配所有文件）
+    - 多个匹配条件是 AND 关系：文件必须满足所有条件
+    """
+    checkers = build_matchers(rule)
+    if not checkers:
+        return False
+    return all(check(path) for check in checkers)

fileflow/report.py

@@ -0,0 +1,164 @@
+"""Rich 终端格式化输出."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .actions import ActionResult
+
+if TYPE_CHECKING:
+    from .engine import EngineResult
+
+console = Console()
+
+
+def print_banner() -> None:
+    """打印 FileFlow 启动横幅."""
+    banner = Text()
+    banner.append("🧹 FileFlow", style="bold cyan")
+    banner.append(" v", style="dim")
+    banner.append("0.1.0", style="bold yellow")
+    banner.append(" — 智能文件整理器", style="dim")
+    console.print(banner)
+
+
+def print_config_preview(config: dict[str, Any]) -> None:
+    """打印配置预览."""
+    rules = config.get("rules", [])
+    table = Table(
+        title="📋 规则列表",
+        box=box.ROUNDED,
+        header_style="bold cyan",
+    )
+    table.add_column("名称", style="bold")
+    table.add_column("操作", style="yellow")
+    table.add_column("目标路径", style="green")
+    table.add_column("条件", style="dim")
+    table.add_column("状态")
+
+    for rule in rules:
+        match = rule.get("match", {})
+        conditions = []
+        if match.get("extensions"):
+            conditions.append(f"ext: {', '.join(match['extensions'])}")
+        if match.get("patterns"):
+            conditions.append(f"pattern: {', '.join(match['patterns'])}")
+        if match.get("name_contains"):
+            conditions.append(f"name contains: {', '.join(match['name_contains'])}")
+        if match.get("max_size_mb"):
+            conditions.append(f"< {match['max_size_mb']}MB")
+
+        status = "[green]✓ 启用[/]" if rule.get("enabled", True) else "[red]✗ 禁用[/]"
+        table.add_row(
+            rule.get("name", ""),
+            rule.get("action", "move"),
+            rule.get("target", ""),
+            "\n".join(conditions) or "[dim]无[/]",
+            status,
+        )
+
+    console.print(table)
+
+
+def format_results(results: list[ActionResult]) -> None:
+    """格式化输出操作结果列表."""
+    for result in results:
+        style = "green" if result.success else "red"
+        icon = "✓" if result.success else "✗"
+        if result.skipped:
+            style = "yellow"
+            icon = "–"
+        if result.error:
+            console.print(f"  [{style}]{icon} {result.source.name}[/]  [red]{result.error}[/]")
+        elif result.skipped:
+            console.print(f"  [{style}]{icon} {result.source.name}[/]  (已存在)")
+        else:
+            target = result.target or ""
+            console.print(f"  [{style}]{icon} {result.source.name}[/]  →  {target}")
+
+
+def print_summary(result: EngineResult) -> None:
+    """打印引擎运行摘要."""
+    header = "[bold cyan]🔍 预览结果[/]" if result.dry_run else "[bold green]📦 整理完成[/]"
+    console.print()
+
+    # 匹配统计
+    table = Table(box=box.SIMPLE, header_style="bold")
+    table.add_column("规则", style="bold")
+    table.add_column("匹配数", justify="right")
+
+    for rule_name, count in sorted(result.rule_matches.items()):
+        table.add_row(rule_name, str(count))
+
+    if table.row_count > 0:
+        console.print(Panel(table, title=header))
+
+    # 汇总信息
+    total = len(result.results)
+    success = result.success_count
+    skipped = result.skipped_count
+    errors = result.error_count
+
+    summary = Text()
+    summary.append(f"\n  共处理 {total} 个文件", style="bold")
+    if success:
+        summary.append(f"  ✅ {success} 成功", style="green")
+    if skipped:
+        summary.append(f"  ⏭ {skipped} 跳过", style="yellow")
+    if errors:
+        summary.append(f"  ❌ {errors} 失败", style="red")
+
+    console.print(summary)
+
+    # 打印详细信息
+    if result.results:
+        console.print("\n[bold]详细信息:[/]")
+        format_results(result.results)
+
+    if not result.dry_run and result.success_count > 0:
+        console.print("\n[dim]💡 提示: 使用 fileflow undo 可撤销本次操作[/]")
+
+    console.print()
+
+
+def print_rule_list(rules: list[dict[str, Any]], verbose: bool = False) -> None:
+    """打印规则列表."""
+    table = Table(
+        title="📋 规则配置",
+        box=box.ROUNDED,
+        header_style="bold cyan",
+    )
+    table.add_column("#", justify="right")
+    table.add_column("名称", style="bold")
+    table.add_column("描述", style="dim")
+    table.add_column("操作", style="yellow")
+    table.add_column("目标")
+    table.add_column("状态")
+
+    for i, rule in enumerate(rules, 1):
+        status = "[green]启用[/]" if rule.get("enabled", True) else "[red]禁用[/]"
+        table.add_row(
+            str(i),
+            rule.get("name", ""),
+            rule.get("description", ""),
+            rule.get("action", "move"),
+            rule.get("target", ""),
+            status,
+        )
+
+        if verbose and "match" in rule:
+            match = rule["match"]
+            details = []
+            for k, v in match.items():
+                details.append(f"    {k}: {v}")
+            if details:
+                table.add_row("", "", "", "", "", "")
+                # 使用 add_row 的 extra 特性要小心，我们直接用 panel
+    console.print(table)

fileflow/rules.py

@@ -0,0 +1,86 @@
+"""规则数据模型."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Rule:
+    """一条整理规则."""
+
+    name: str
+    description: str = ""
+    action: str = "move"
+    target: str = ""
+    enabled: bool = True
+
+    # 匹配条件
+    extensions: list[str] = field(default_factory=list)
+    patterns: list[str] = field(default_factory=list)
+    name_contains: list[str] = field(default_factory=list)
+    name_regex: list[str] = field(default_factory=list)
+    min_size_mb: float | None = None
+    max_size_mb: float | None = None
+    min_size_bytes: int | None = None
+    max_size_bytes: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Rule:
+        """从 YAML 字典构建规则."""
+        match: dict[str, Any] = data.get("match", {})
+
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            action=data.get("action", "move"),
+            target=data.get("target", ""),
+            enabled=data.get("enabled", True),
+            extensions=match.get("extensions", []),
+            patterns=match.get("patterns", []),
+            name_contains=match.get("name_contains", []),
+            name_regex=match.get("name_regex", []),
+            min_size_mb=match.get("min_size_mb"),
+            max_size_mb=match.get("max_size_mb"),
+            min_size_bytes=match.get("min_size_bytes"),
+            max_size_bytes=match.get("max_size_bytes"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为可序列化字典（用于历史记录等）. """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "action": self.action,
+            "target": self.target,
+            "enabled": self.enabled,
+        }
+
+
+class RuleSet:
+    """一组规则的集合，支持启用/禁用过滤."""
+
+    def __init__(self, rules: list[Rule] | None = None) -> None:
+        self.rules = rules or []
+
+    @classmethod
+    def load_from_yaml(cls, data: list[dict[str, Any]]) -> RuleSet:
+        """从 YAML 解析的列表加载规则集."""
+        return cls([Rule.from_dict(item) for item in data])
+
+    @property
+    def active_rules(self) -> list[Rule]:
+        """仅返回启用的规则."""
+        return [r for r in self.rules if r.enabled]
+
+    def add_rule(self, rule: Rule) -> None:
+        """添加一条规则."""
+        self.rules.append(rule)
+
+    def __len__(self) -> int:
+        return len(self.rules)
+
+    def __getitem__(self, index: int) -> Rule:
+        return self.rules[index]