hutool-python 1.0.0__py3-none-any.whl

hutool/core/exceptions.py

@@ -0,0 +1,66 @@
+"""异常类定义，对应 Java cn.hutool.core.exceptions。"""
+
+
+class UtilException(Exception):
+    """工具类通用异常。
+
+    对应 Java cn.hutool.core.exceptions.UtilException。
+    支持 format 风格的消息格式化。
+    """
+
+    def __init__(self, message: str, *args):
+        if args:
+            message = message.format(*args)
+        super().__init__(message)
+
+
+class IORuntimeException(UtilException):
+    """IO 运行时异常。
+
+    对应 Java cn.hutool.core.exceptions.IORuntimeException。
+    """
+
+    def __init__(self, message: str, *args):
+        super().__init__(message, *args)
+
+
+class StatefulException(UtilException):
+    """有状态的异常，可携带额外状态信息。"""
+
+    def __init__(self, message: str, *args):
+        super().__init__(message, *args)
+
+
+class NotInitedException(UtilException):
+    """未初始化异常。"""
+
+    def __init__(self, message: str = "Not initialized", *args):
+        super().__init__(message, *args)
+
+
+class NullPointerException(UtilException):
+    """空指针异常。"""
+
+    def __init__(self, message: str = "Null pointer", *args):
+        super().__init__(message, *args)
+
+
+class IllegalArgumentException(UtilException):
+    """非法参数异常。"""
+
+    def __init__(self, message: str, *args):
+        super().__init__(message, *args)
+
+
+class IllegalStateException(UtilException):
+    """非法状态异常。"""
+
+    def __init__(self, message: str, *args):
+        super().__init__(message, *args)
+
+
+class UnsupportedOperationException(UtilException):
+    """不支持的操作异常。"""
+
+    def __init__(self, message: str = "Unsupported operation", *args):
+        super().__init__(message, *args)

hutool/core/io/data_size_util.py

@@ -0,0 +1,79 @@
+"""数据大小工具模块"""
+
+import re
+from typing import Dict
+
+
+class DataSizeUtil:
+    """数据大小工具类"""
+
+    _UNITS: Dict[str, int] = {
+        "B": 1,
+        "KB": 1024,
+        "MB": 1024**2,
+        "GB": 1024**3,
+        "TB": 1024**4,
+        "PB": 1024**5,
+    }
+
+    # 用于匹配 "数字 + 可选空格 + 单位" 的正则
+    _SIZE_PATTERN = re.compile(
+        r"^\s*(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB|PB)\s*$",
+        re.IGNORECASE,
+    )
+
+    @staticmethod
+    def parse(size_str: str) -> int:
+        """解析数据大小字符串为字节数
+
+        支持的单位（不区分大小写）: B, KB, MB, GB, TB, PB
+
+        示例::
+
+            DataSizeUtil.parse("10KB")   -> 10240
+            DataSizeUtil.parse("1.5GB")  -> 1610612736
+            DataSizeUtil.parse("512 B")  -> 512
+
+        :param size_str: 数据大小字符串，如 "10KB"、"1.5 GB"
+        :return: 对应的字节数（int）
+        :raises ValueError: 无法解析时抛出
+        """
+        match = DataSizeUtil._SIZE_PATTERN.match(size_str)
+        if not match:
+            raise ValueError(f"无法解析数据大小字符串: '{size_str}'")
+        number = float(match.group(1))
+        unit = match.group(2).upper()
+        multiplier = DataSizeUtil._UNITS[unit]
+        return int(number * multiplier)
+
+    @staticmethod
+    def format_size(size: int) -> str:
+        """将字节数格式化为可读字符串
+
+        自动选择最合适的单位，保留两位小数并去除末尾的零。
+
+        示例::
+
+            DataSizeUtil.format_size(10240)       -> "10KB"
+            DataSizeUtil.format_size(1073741824)   -> "1GB"
+            DataSizeUtil.format_size(512)          -> "512B"
+
+        :param size: 字节数
+        :return: 格式化后的字符串
+        """
+        if size < 0:
+            return "-" + DataSizeUtil.format_size(-size)
+
+        if size < DataSizeUtil._UNITS["KB"]:
+            return f"{size}B"
+
+        # 从大到小尝试匹配合适的单位
+        for unit in ("PB", "TB", "GB", "MB", "KB"):
+            unit_size = DataSizeUtil._UNITS[unit]
+            if size >= unit_size:
+                value = size / unit_size
+                # 保留两位小数，去除末尾多余的零和小数点
+                formatted = f"{value:.2f}".rstrip("0").rstrip(".")
+                return f"{formatted}{unit}"
+
+        return f"{size}B"

hutool/core/io/file_name_util.py

@@ -0,0 +1,111 @@
+"""文件名工具模块"""
+
+import os
+import re
+from typing import List
+
+
+class FileNameUtil:
+    """文件名工具类"""
+
+    # 文件名中不允许出现的字符（Windows + 通用）
+    _INVALID_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+    @staticmethod
+    def get_name(path: str) -> str:
+        """获取文件名（含扩展名）
+
+        :param path: 文件路径
+        :return: 文件名，如 "document.txt"
+        """
+        return os.path.basename(path)
+
+    @staticmethod
+    def get_prefix(path: str) -> str:
+        """获取文件名前缀（不含扩展名）
+
+        :param path: 文件路径
+        :return: 文件名前缀，如 "document"
+        """
+        name = os.path.basename(path)
+        dot_index = name.rfind(".")
+        if dot_index <= 0:
+            return name
+        return name[:dot_index]
+
+    @staticmethod
+    def get_suffix(path: str) -> str:
+        """获取扩展名（不含点）
+
+        :param path: 文件路径
+        :return: 扩展名，如 "txt"；无扩展名时返回空字符串
+        """
+        name = os.path.basename(path)
+        dot_index = name.rfind(".")
+        if dot_index < 0 or dot_index == len(name) - 1:
+            return ""
+        return name[dot_index + 1 :]
+
+    @staticmethod
+    def main_name(path: str) -> str:
+        """获取主文件名（等同于 get_prefix）
+
+        :param path: 文件路径
+        :return: 主文件名
+        """
+        return FileNameUtil.get_prefix(path)
+
+    @staticmethod
+    def ext_name(path: str) -> str:
+        """获取扩展名（同 get_suffix）
+
+        :param path: 文件路径
+        :return: 扩展名
+        """
+        return FileNameUtil.get_suffix(path)
+
+    @staticmethod
+    def normalize(path: str) -> str:
+        """标准化文件名路径
+
+        将路径中的反斜杠统一替换为正斜杠，并去除多余分隔符。
+
+        :param path: 文件路径
+        :return: 标准化后的路径
+        """
+        normalized = path.replace("\\", "/")
+        # 去除连续的斜杠（保留开头的 ./ 或协议部分）
+        parts = normalized.split("/")
+        result_parts: List[str] = []
+        for part in parts:
+            if part == "" and result_parts:
+                continue
+            result_parts.append(part)
+        return "/".join(result_parts)
+
+    @staticmethod
+    def clean_invalid(name: str) -> str:
+        """清理文件名中的非法字符
+
+        移除 Windows 及通用文件系统中不允许出现的字符。
+
+        :param name: 原始文件名
+        :return: 清理后的合法文件名
+        """
+        cleaned = FileNameUtil._INVALID_CHARS.sub("", name)
+        # 去除首尾空格和点（Windows 不允许）
+        cleaned = cleaned.strip(" .")
+        return cleaned if cleaned else "unnamed"
+
+    @staticmethod
+    def is_type(path: str, ext: str) -> bool:
+        """检查文件扩展名是否匹配
+
+        比较时忽略大小写。
+
+        :param path: 文件路径
+        :param ext: 期望的扩展名（不含点，如 "txt"）
+        :return: 匹配返回 True，否则 False
+        """
+        actual = FileNameUtil.get_suffix(path)
+        return actual.lower() == ext.lower().lstrip(".")