hutool-python 1.0.0__py3-none-any.whl

hutool/core/io/io_util.py

@@ -0,0 +1,133 @@
+"""IO工具模块"""
+
+from typing import IO, List, Optional, Union
+
+
+class IoUtil:
+    """IO工具类"""
+
+    @staticmethod
+    def read(stream: IO, charset: str = "utf-8") -> str:
+        """从流中读取字符串
+
+        :param stream: 输入流（需支持 read 方法）
+        :param charset: 字符编码，默认 utf-8
+        :return: 读取到的字符串内容
+        """
+        raw = stream.read()
+        if isinstance(raw, bytes):
+            return raw.decode(charset)
+        return raw
+
+    @staticmethod
+    def read_bytes(stream: IO) -> bytes:
+        """从流中读取字节数组
+
+        :param stream: 输入流（需支持 read 方法）
+        :return: 读取到的字节数组
+        """
+        data = stream.read()
+        if isinstance(data, str):
+            return data.encode("utf-8")
+        return data
+
+    @staticmethod
+    def read_lines(stream: IO, charset: str = "utf-8") -> List[str]:
+        """从流中读取行列表
+
+        :param stream: 输入流（需支持 read 或 readlines 方法）
+        :param charset: 字符编码，默认 utf-8
+        :return: 行列表
+        """
+        raw = stream.read()
+        if isinstance(raw, bytes):
+            raw = raw.decode(charset)
+        return raw.splitlines(keepends=False)
+
+    @staticmethod
+    def write(stream: IO, data: Union[str, bytes], charset: str = "utf-8") -> int:
+        """写入数据到流
+
+        :param stream: 输出流（需支持 write 方法）
+        :param data: 要写入的数据（str 或 bytes）
+        :param charset: 当 data 为 str 时使用的编码，默认 utf-8
+        :return: 写入的字节数
+        """
+        if isinstance(data, str):
+            encoded = data.encode(charset)
+        elif isinstance(data, (bytes, bytearray)):
+            encoded = bytes(data)
+        else:
+            encoded = str(data).encode(charset)
+        return stream.write(encoded)
+
+    @staticmethod
+    def write_bytes(stream: IO, data: bytes) -> int:
+        """写入字节数组到流
+
+        :param stream: 输出流（需支持 write 方法）
+        :param data: 要写入的字节数组
+        :return: 写入的字节数
+        """
+        if isinstance(data, bytearray):
+            data = bytes(data)
+        return stream.write(data)
+
+    @staticmethod
+    def copy(
+        input_stream: IO,
+        output_stream: IO,
+        buffer_size: int = 8192,
+    ) -> int:
+        """拷贝流数据
+
+        :param input_stream: 输入流
+        :param output_stream: 输出流
+        :param buffer_size: 缓冲区大小，默认 8192 字节
+        :return: 拷贝的总字节数
+        """
+        total = 0
+        while True:
+            chunk = input_stream.read(buffer_size)
+            if not chunk:
+                break
+            if isinstance(chunk, str):
+                chunk = chunk.encode("utf-8")
+            output_stream.write(chunk)
+            total += len(chunk)
+        return total
+
+    @staticmethod
+    def close(closable: Optional[IO]) -> None:
+        """安全关闭可关闭对象
+
+        如果对象为 None 或已关闭，则不做任何操作。
+
+        :param closable: 可关闭对象（如文件流），可以为 None
+        """
+        if closable is None:
+            return
+        try:
+            closable.close()
+        except Exception:
+            pass
+
+    @staticmethod
+    def to_bytes(obj: Union[str, bytes, bytearray, memoryview]) -> bytes:
+        """将对象转为 bytes
+
+        支持 str / bytes / bytearray / memoryview 类型。
+
+        :param obj: 待转换的对象
+        :return: 字节数组
+        :raises TypeError: 不支持的对象类型
+        """
+        if isinstance(obj, bytes):
+            return obj
+        if isinstance(obj, str):
+            return obj.encode("utf-8")
+        if isinstance(obj, bytearray):
+            return bytes(obj)
+        if isinstance(obj, memoryview):
+            return obj.tobytes()
+        raise TypeError(f"不支持的对象类型: {type(obj).__name__}")

hutool/core/io/path_util.py

@@ -0,0 +1,247 @@
+"""路径工具模块"""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Callable, List, Optional, Union
+
+
+class PathUtil:
+    """路径工具类"""
+
+    @staticmethod
+    def get_path_separator() -> str:
+        """获取当前操作系统的路径分隔符
+
+        :return: 路径分隔符字符串（Windows 为 '\\'，Linux/macOS 为 '/'）
+        """
+        return os.sep
+
+    @staticmethod
+    def normalize(path: Union[str, Path]) -> str:
+        """标准化路径
+
+        解析符号链接、去除冗余分隔符和上级引用（..），返回绝对路径。
+
+        :param path: 原始路径
+        :return: 标准化后的路径字符串
+        """
+        return str(Path(path).resolve())
+
+    @staticmethod
+    def get_parent(path: Union[str, Path]) -> str:
+        """获取父目录路径
+
+        :param path: 文件或目录路径
+        :return: 父目录的路径字符串
+        """
+        return str(Path(path).parent)
+
+    @staticmethod
+    def get_name(path: Union[str, Path]) -> str:
+        """获取路径中的文件名或最后一级目录名
+
+        :param path: 文件或目录路径
+        :return: 文件名或目录名
+        """
+        return Path(path).name
+
+    @staticmethod
+    def sub_path(path: Union[str, Path], from_index: int, to_index: int) -> str:
+        """获取路径的子段
+
+        按路径层级截取子路径。索引从 0 开始。
+
+        :param path: 原始路径
+        :param from_index: 起始索引（含）
+        :param to_index: 结束索引（不含）
+        :return: 子路径字符串
+        :raises ValueError: 索引越界时抛出
+        """
+        p = Path(path)
+        parts = p.parts
+        if from_index < 0 or to_index > len(parts) or from_index > to_index:
+            raise ValueError(f"无效的索引范围: [{from_index}, {to_index})，路径共 {len(parts)} 层")
+        sub_parts = parts[from_index:to_index]
+        return str(Path(*sub_parts))
+
+    @staticmethod
+    def is_absolute(path: Union[str, Path]) -> bool:
+        """判断路径是否为绝对路径
+
+        :param path: 文件路径
+        :return: 是绝对路径返回 True
+        """
+        return Path(path).is_absolute()
+
+    @staticmethod
+    def exists(path: Union[str, Path]) -> bool:
+        """判断路径是否存在
+
+        :param path: 文件或目录路径
+        :return: 存在返回 True
+        """
+        return Path(path).exists()
+
+    @staticmethod
+    def mkdir(path: Union[str, Path]) -> Path:
+        """创建目录（包括所有必要的父目录）
+
+        如果目录已存在则不做任何操作。
+
+        :param path: 目录路径
+        :return: 创建的目录 Path 对象
+        """
+        p = Path(path)
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @staticmethod
+    def mk_parent_dirs(path: Union[str, Path]) -> Path:
+        """创建文件的父目录
+
+        :param path: 文件路径
+        :return: 父目录的 Path 对象
+        """
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return p.parent
+
+    @staticmethod
+    def loop_files(
+        path: Union[str, Path],
+        file_filter: Optional[Callable[[Path], bool]] = None,
+    ) -> List[Path]:
+        """递归遍历目录下的所有文件
+
+        :param path: 目录路径
+        :param file_filter: 可选的过滤函数，接受 Path 参数，返回 True 表示保留
+        :return: 文件 Path 列表
+        :raises FileNotFoundError: 路径不存在时抛出
+        """
+        p = Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"路径不存在: {path}")
+        if p.is_file():
+            files = [p]
+        else:
+            files = sorted(p.rglob("*"))
+            files = [f for f in files if f.is_file()]
+        if file_filter is not None:
+            files = [f for f in files if file_filter(f)]
+        return files
+
+    @staticmethod
+    def copy(
+        src: Union[str, Path],
+        dest: Union[str, Path],
+        is_override: bool = True,
+    ) -> Path:
+        """复制文件或目录
+
+        :param src: 源路径
+        :param dest: 目标路径
+        :param is_override: 是否覆盖已存在的目标，默认 True
+        :return: 目标路径的 Path 对象
+        :raises FileExistsError: 目标已存在且 is_override 为 False 时抛出
+        :raises FileNotFoundError: 源路径不存在时抛出
+        """
+        src_p = Path(src)
+        dest_p = Path(dest)
+        if not src_p.exists():
+            raise FileNotFoundError(f"源路径不存在: {src}")
+        if dest_p.exists() and not is_override:
+            raise FileExistsError(f"目标路径已存在: {dest}")
+        if src_p.is_dir():
+            if dest_p.exists() and is_override:
+                shutil.rmtree(dest_p)
+            shutil.copytree(src_p, dest_p)
+        else:
+            dest_p.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_p, dest_p)
+        return dest_p
+
+    @staticmethod
+    def move(
+        src: Union[str, Path],
+        dest: Union[str, Path],
+        is_override: bool = True,
+    ) -> Path:
+        """移动文件或目录
+
+        :param src: 源路径
+        :param dest: 目标路径
+        :param is_override: 是否覆盖已存在的目标，默认 True
+        :return: 目标路径的 Path 对象
+        :raises FileExistsError: 目标已存在且 is_override 为 False 时抛出
+        :raises FileNotFoundError: 源路径不存在时抛出
+        """
+        src_p = Path(src)
+        dest_p = Path(dest)
+        if not src_p.exists():
+            raise FileNotFoundError(f"源路径不存在: {src}")
+        if dest_p.exists():
+            if not is_override:
+                raise FileExistsError(f"目标路径已存在: {dest}")
+            if dest_p.is_dir():
+                shutil.rmtree(dest_p)
+            else:
+                dest_p.unlink()
+        dest_p.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src_p), str(dest_p))
+        return dest_p
+
+    @staticmethod
+    def del_path(path: Union[str, Path]) -> bool:
+        """删除文件或目录
+
+        目录将递归删除。如果路径不存在则返回 False。
+
+        :param path: 文件或目录路径
+        :return: 删除成功返回 True，路径不存在返回 False
+        """
+        p = Path(path)
+        if not p.exists():
+            return False
+        if p.is_dir():
+            shutil.rmtree(p)
+        else:
+            p.unlink()
+        return True
+
+    @staticmethod
+    def equals(
+        path1: Union[str, Path],
+        path2: Union[str, Path],
+    ) -> bool:
+        """比较两个路径是否指向同一位置
+
+        通过解析后的绝对路径进行比较。
+
+        :param path1: 第一个路径
+        :param path2: 第二个路径
+        :return: 相等返回 True
+        """
+        return Path(path1).resolve() == Path(path2).resolve()
+
+    @staticmethod
+    def starts_with(path: Union[str, Path], prefix: str) -> bool:
+        """判断路径是否以指定前缀开头
+
+        :param path: 文件路径
+        :param prefix: 路径前缀
+        :return: 匹配返回 True
+        """
+        normalized_path = PathUtil.normalize(path)
+        normalized_prefix = PathUtil.normalize(prefix)
+        return normalized_path.startswith(normalized_prefix)
+
+    @staticmethod
+    def ends_with(path: Union[str, Path], suffix: str) -> bool:
+        """判断路径是否以指定后缀结尾
+
+        :param path: 文件路径
+        :param suffix: 路径后缀
+        :return: 匹配返回 True
+        """
+        return str(path).replace("\\", "/").endswith(suffix.replace("\\", "/"))

hutool/core/io/resource_util.py

@@ -0,0 +1,137 @@
+"""资源工具模块"""
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import IO, List
+
+
+class ResourceUtil:
+    """资源工具类"""
+
+    # 默认资源搜索路径列表，可通过 add_resource_path 扩展
+    _resource_paths: List[str] = []
+
+    @classmethod
+    def add_resource_path(cls, path: str) -> None:
+        """添加资源搜索路径
+
+        :param path: 资源目录的绝对或相对路径
+        """
+        abs_path = os.path.abspath(path)
+        if abs_path not in cls._resource_paths:
+            cls._resource_paths.append(abs_path)
+
+    @staticmethod
+    def get_resource(path: str) -> str:
+        """获取资源的绝对路径
+
+        按以下顺序查找资源:
+        1. 绝对路径直接返回
+        2. 当前工作目录
+        3. 已注册的资源搜索路径
+
+        :param path: 资源的相对或绝对路径
+        :return: 资源的绝对路径
+        :raises FileNotFoundError: 资源不存在时抛出
+        """
+        # 如果是绝对路径且存在，直接返回
+        if os.path.isabs(path) and os.path.exists(path):
+            return os.path.abspath(path)
+
+        # 在当前工作目录查找
+        cwd_path = os.path.join(os.getcwd(), path)
+        if os.path.exists(cwd_path):
+            return os.path.abspath(cwd_path)
+
+        # 在已注册的资源路径中查找
+        for res_dir in ResourceUtil._resource_paths:
+            candidate = os.path.join(res_dir, path)
+            if os.path.exists(candidate):
+                return os.path.abspath(candidate)
+
+        raise FileNotFoundError(f"资源不存在: {path}")
+
+    @staticmethod
+    def get_resource_bytes(path: str) -> bytes:
+        """读取资源为字节数组
+
+        :param path: 资源的相对或绝对路径
+        :return: 资源内容的字节数组
+        :raises FileNotFoundError: 资源不存在时抛出
+        """
+        abs_path = ResourceUtil.get_resource(path)
+        with open(abs_path, "rb") as f:
+            return f.read()
+
+    @staticmethod
+    def get_resource_str(path: str, charset: str = "utf-8") -> str:
+        """读取资源为字符串
+
+        :param path: 资源的相对或绝对路径
+        :param charset: 字符编码，默认 utf-8
+        :return: 资源内容的字符串
+        :raises FileNotFoundError: 资源不存在时抛出
+        """
+        abs_path = ResourceUtil.get_resource(path)
+        with open(abs_path, encoding=charset) as f:
+            return f.read()
+
+    @staticmethod
+    def get_resource_stream(path: str) -> IO:
+        """获取资源的文件流
+
+        调用方负责关闭返回的文件流。
+
+        :param path: 资源的相对或绝对路径
+        :return: 可读的文件对象
+        :raises FileNotFoundError: 资源不存在时抛出
+        """
+        abs_path = ResourceUtil.get_resource(path)
+        return open(abs_path, "rb")
+
+    @staticmethod
+    def get_resources(pattern: str) -> List[str]:
+        """根据模式匹配获取资源列表
+
+        支持通配符模式（如 "*.txt"、"data/*.csv"）。
+        在当前工作目录和已注册的资源搜索路径中搜索。
+
+        :param pattern: 文件名匹配模式（支持 * 和 ? 通配符）
+        :return: 匹配的资源绝对路径列表
+        """
+        results: List[str] = []
+
+        # 在当前工作目录中搜索
+        cwd = os.getcwd()
+        ResourceUtil._search_in_dir(cwd, pattern, results)
+
+        # 在已注册的资源路径中搜索
+        for res_dir in ResourceUtil._resource_paths:
+            ResourceUtil._search_in_dir(res_dir, pattern, results)
+
+        # 去重并排序
+        return sorted(set(results))
+
+    @staticmethod
+    def _search_in_dir(base_dir: str, pattern: str, results: List[str]) -> None:
+        """在指定目录中递归搜索匹配的文件
+
+        :param base_dir: 基础搜索目录
+        :pattern: 文件名匹配模式
+        :param results: 结果列表（原地修改）
+        """
+        base = Path(base_dir)
+        if not base.is_dir():
+            return
+
+        # 如果 pattern 包含路径分隔符，按路径层级匹配
+        if os.sep in pattern or "/" in pattern:
+            for match in base.glob(pattern):
+                if match.is_file():
+                    results.append(str(match.resolve()))
+        else:
+            # 只按文件名匹配，递归搜索所有子目录
+            for file_path in base.rglob("*"):
+                if file_path.is_file() and fnmatch.fnmatch(file_path.name, pattern):
+                    results.append(str(file_path.resolve()))