sdpy-kit 0.1.0__py3-none-any.whl

kit/file_kit.py

@@ -0,0 +1,429 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-08-22
+"""文件工具类，提供文件读写、移动、复制等跨平台操作功能
+
+重构说明（破坏性内部、外部零风险）：
+- 用 `_ROOT_PATH is None` 语义替代 `_INITIALIZED` 布尔标记，收敛初始化逻辑。
+- 修正 `_get_root_path` 返回类型（不再返回可能为 None 的值却标注为 Path）。
+- 补全 `walk_dir` 缺失的返回类型标注。
+- 公开方法名、签名与语义不变。
+"""
+
+from collections.abc import Iterator
+from pathlib import Path
+from shutil import copy2, copytree, move, rmtree
+
+from kit.config.kit_config import get_settings
+from kit.config.log_config import get_default_logger
+
+settings = get_settings()
+logger = get_default_logger(__name__)
+
+
+class FileKit:
+    """文件工具类，提供文件读写、移动、复制等跨平台操作功能
+
+    配置：
+    - 根文件存储路径通过配置文件 FILE_STORAGE_ROOT 获取
+    - 使用统一的 get_settings() 进行配置管理
+    - 使用统一的 get_default_logger() 进行日志记录
+    - 支持跨平台路径处理（Windows/Linux）
+
+    所有方法均处理路径分隔符，确保跨平台兼容性。
+    """
+
+    # None 表示尚未初始化（未调用 configure，也未被惰性初始化）
+    _ROOT_PATH: Path | None = None
+
+    @classmethod
+    def _ensure_initialized(cls) -> None:
+        """惰性初始化根文件存储路径（首次使用时从配置读取）"""
+        if cls._ROOT_PATH is not None:
+            return
+
+        root_path_str = settings.FILE_STORAGE_ROOT
+        if not root_path_str:
+            raise RuntimeError("配置项 FILE_STORAGE_ROOT 未设置，请设置文件存储根路径")
+
+        root_path = cls._normalize_path(root_path_str)
+
+        if not root_path.exists():
+            raise RuntimeError(f"根路径不存在: {root_path}")
+        if not root_path.is_dir():
+            raise RuntimeError(f"根路径不是有效目录: {root_path}")
+
+        cls._ROOT_PATH = root_path
+        logger.info(f"✅ FileKit 已初始化，根路径: {root_path}")
+
+    @staticmethod
+    def _normalize_path(path: str) -> Path:
+        """规范化路径，处理跨平台路径分隔符"""
+        return Path(path).resolve()
+
+    @classmethod
+    def configure(cls, root_path: str) -> None:
+        """手动配置根文件存储路径
+
+        Args:
+            root_path: 文件存储根路径
+
+        Raises:
+            ValueError: 路径不存在或不是目录时抛出
+        """
+        normalized = cls._normalize_path(root_path)
+
+        if not normalized.exists():
+            raise ValueError(f"根路径不存在: {normalized}")
+        if not normalized.is_dir():
+            raise ValueError(f"根路径不是有效目录: {normalized}")
+
+        cls._ROOT_PATH = normalized
+
+    @classmethod
+    def read_file(cls, relative_path: str, encoding: str = "utf-8") -> str:
+        """读取文件内容
+
+        Args:
+            relative_path: 相对于根路径的文件路径
+            encoding: 文件编码，默认 utf-8
+
+        Returns:
+            str: 文件内容字符串
+        """
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"文件不存在: {full_path}")
+
+        try:
+            return full_path.read_text(encoding=encoding)
+        except UnicodeDecodeError as e:
+            raise UnicodeDecodeError(
+                e.encoding,
+                e.object,
+                e.start,
+                e.end,
+                f"文件编码错误，请尝试使用其他编码读取: {e}",
+            )
+
+    @classmethod
+    def write_file(
+        cls,
+        relative_path: str,
+        content: str,
+        mode: str = "overwrite",
+        encoding: str = "utf-8",
+    ) -> bool:
+        """写入文件内容
+
+        Args:
+            relative_path: 相对于根路径的文件路径
+            content: 要写入的内容
+            mode: 写入模式，"overwrite"（覆盖）或 "append"（追加）
+            encoding: 文件编码，默认 utf-8
+
+        Returns:
+            bool: 写入成功返回 True
+        """
+        if mode not in ("overwrite", "append"):
+            raise ValueError(
+                f"无效的写入模式: {mode}，支持的模式: 'overwrite', 'append'"
+            )
+
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+        parent_dir = full_path.parent
+
+        if not parent_dir.exists():
+            parent_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            if mode == "append":
+                with full_path.open("a", encoding=encoding) as f:
+                    f.write(content)
+            else:
+                full_path.write_text(content, encoding=encoding)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"写入文件失败: {e}")
+
+    @classmethod
+    def move_file(cls, src_relative_path: str, dest_relative_path: str) -> bool:
+        """移动文件（重命名）
+
+        Args:
+            src_relative_path: 源文件相对于根路径的路径
+            dest_relative_path: 目标文件相对于根路径的路径
+
+        Returns:
+            bool: 移动成功返回 True
+        """
+        cls._ensure_initialized()
+
+        src_path = cls._get_full_path(src_relative_path)
+        dest_path = cls._get_full_path(dest_relative_path)
+
+        if not src_path.exists():
+            raise FileNotFoundError(f"源文件不存在: {src_path}")
+
+        dest_parent = dest_path.parent
+        if dest_parent and not dest_parent.exists():
+            dest_parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            move(src_path, dest_path)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"移动文件失败: {e}")
+
+    @classmethod
+    def copy_file(cls, src_relative_path: str, dest_relative_path: str) -> bool:
+        """复制文件
+
+        Args:
+            src_relative_path: 源文件相对于根路径的路径
+            dest_relative_path: 目标文件相对于根路径的路径
+
+        Returns:
+            bool: 复制成功返回 True
+        """
+        cls._ensure_initialized()
+
+        src_path = cls._get_full_path(src_relative_path)
+        dest_path = cls._get_full_path(dest_relative_path)
+
+        if not src_path.exists():
+            raise FileNotFoundError(f"源文件不存在: {src_path}")
+
+        dest_parent = dest_path.parent
+        if dest_parent and not dest_parent.exists():
+            dest_parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            copy2(src_path, dest_path)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"复制文件失败: {e}")
+
+    @classmethod
+    def delete_file(cls, relative_path: str) -> bool:
+        """删除文件
+
+        Args:
+            relative_path: 要删除的文件相对于根路径的路径
+
+        Returns:
+            bool: 删除成功返回 True
+        """
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"文件不存在: {full_path}")
+
+        try:
+            full_path.unlink()
+            return True
+        except Exception as e:
+            raise RuntimeError(f"删除文件失败: {e}")
+
+    @classmethod
+    def file_exists(cls, relative_path: str) -> bool:
+        """检查文件是否存在"""
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+        return full_path.is_file()
+
+    @classmethod
+    def get_full_path(cls, relative_path: str) -> Path:
+        """获取文件的完整路径"""
+        cls._ensure_initialized()
+        return cls._get_full_path(relative_path)
+
+    @classmethod
+    def _get_full_path(cls, relative_path: str) -> Path:
+        """内部方法：获取完整路径"""
+        assert cls._ROOT_PATH is not None
+        return cls._ROOT_PATH / relative_path
+
+    @classmethod
+    def get_root_path(cls) -> str:
+        """获取当前配置的根路径"""
+        return str(cls._get_root_path())
+
+    @classmethod
+    def _get_root_path(cls) -> Path:
+        """获取根文件存储路径"""
+        cls._ensure_initialized()
+        assert cls._ROOT_PATH is not None
+        return cls._ROOT_PATH
+
+    @staticmethod
+    def generate_unique_id() -> str:
+        """生成唯一 ID（字符串类型）"""
+        from kit.common_kit import CommonKit
+
+        return CommonKit.generate_timestamp_id()
+
+    @staticmethod
+    def generate_filename(prefix: str = "", extension: str = "") -> str:
+        """生成带有时间戳的唯一文件名
+
+        Args:
+            prefix: 文件名前缀（可选），如 "log_"
+            extension: 文件扩展名（可选），如 "txt"，可不带点
+
+        Returns:
+            str: 生成的文件名
+        """
+        from kit.common_kit import CommonKit
+
+        unique_id = CommonKit.generate_timestamp_id()
+        if extension:
+            if not extension.startswith("."):
+                extension = "." + extension
+            return f"{prefix}{unique_id}{extension}"
+        return f"{prefix}{unique_id}"
+
+    @classmethod
+    def move_dir(cls, src_relative_path: str, dest_relative_path: str) -> bool:
+        """移动目录
+
+        Args:
+            src_relative_path: 源目录相对于根路径的路径
+            dest_relative_path: 目标目录相对于根路径的路径
+
+        Returns:
+            bool: 移动成功返回 True
+        """
+        cls._ensure_initialized()
+
+        src_path = cls._get_full_path(src_relative_path)
+        dest_path = cls._get_full_path(dest_relative_path)
+
+        if not src_path.exists():
+            raise FileNotFoundError(f"源目录不存在: {src_path}")
+        if not src_path.is_dir():
+            raise ValueError(f"源路径不是目录: {src_path}")
+
+        try:
+            move(src_path, dest_path)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"移动目录失败: {e}")
+
+    @classmethod
+    def delete_dir(cls, relative_path: str) -> bool:
+        """删除目录（递归删除）
+
+        Args:
+            relative_path: 要删除的目录相对于根路径的路径
+
+        Returns:
+            bool: 删除成功返回 True
+        """
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"目录不存在: {full_path}")
+        if not full_path.is_dir():
+            raise ValueError(f"路径不是目录: {full_path}")
+
+        try:
+            rmtree(full_path)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"删除目录失败: {e}")
+
+    @classmethod
+    def copy_dir(cls, src_relative_path: str, dest_relative_path: str) -> bool:
+        """复制目录（递归复制）
+
+        Args:
+            src_relative_path: 源目录相对于根路径的路径
+            dest_relative_path: 目标目录相对于根路径的路径
+
+        Returns:
+            bool: 复制成功返回 True
+        """
+        cls._ensure_initialized()
+
+        src_path = cls._get_full_path(src_relative_path)
+        dest_path = cls._get_full_path(dest_relative_path)
+
+        if not src_path.exists():
+            raise FileNotFoundError(f"源目录不存在: {src_path}")
+        if not src_path.is_dir():
+            raise ValueError(f"源路径不是目录: {src_path}")
+
+        try:
+            copytree(src_path, dest_path)
+            return True
+        except Exception as e:
+            raise RuntimeError(f"复制目录失败: {e}")
+
+    @classmethod
+    def walk_dir(
+        cls,
+        relative_path: str = "",
+        top_down: bool = True,
+        on_error: str | None = None,
+    ) -> Iterator[tuple[Path, list[str], list[str]]]:
+        """遍历目录树（使用 Path.walk 方法）
+
+        Args:
+            relative_path: 要遍历的目录相对于根路径的路径，空字符串表示根目录
+            top_down: 遍历顺序，True 为自顶向下，False 为自底向上
+            on_error: 错误处理方式，None 或 "ignore" 或 "report"
+
+        Yields:
+            (root: Path, dirs: list[str], files: list[str]) 元组
+        """
+        cls._ensure_initialized()
+
+        full_path = cls._get_full_path(relative_path)
+        root_path = cls._get_root_path()
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"目录不存在: {full_path}")
+        if not full_path.is_dir():
+            raise ValueError(f"路径不是目录: {full_path}")
+
+        def error_handler(os_error: OSError) -> None:
+            if on_error == "report":
+                raise os_error
+
+        for root, dirs, files in full_path.walk(
+            top_down=top_down,
+            on_error=error_handler if on_error in ("ignore", "report") else None,
+        ):
+            yield (
+                root.relative_to(root_path) if root != root_path else Path("."),
+                dirs,
+                files,
+            )