hutool-python 1.0.0__py3-none-any.whl

hutool/core/util/enum_util.py

@@ -0,0 +1,94 @@
+from enum import Enum
+from typing import Any, Callable, List, Optional, Type
+
+
+class EnumUtil:
+    """枚举工具类
+
+    提供对Python枚举类型的常用操作方法，包括获取名称、值、查找等。
+    """
+
+    @staticmethod
+    def get_names(enum_class: Type[Enum]) -> List[str]:
+        """获取所有枚举名称
+
+        :param enum_class: 枚举类
+        :return: 枚举名称列表
+        """
+        return [member.name for member in enum_class]
+
+    @staticmethod
+    def get_values(enum_class: Type[Enum]) -> list:
+        """获取所有枚举值
+
+        :param enum_class: 枚举类
+        :return: 枚举值列表
+        """
+        return [member.value for member in enum_class]
+
+    @staticmethod
+    def get_items(enum_class: Type[Enum]) -> dict:
+        """获取所有枚举项为字典
+
+        :param enum_class: 枚举类
+        :return: 以枚举名称为键、枚举值为值的字典
+        """
+        return {member.name: member.value for member in enum_class}
+
+    @staticmethod
+    def contains(enum_class: Type[Enum], value: Any) -> bool:
+        """是否包含指定值
+
+        :param enum_class: 枚举类
+        :param value: 待检查的值
+        :return: 是否包含该值
+        """
+        try:
+            enum_class(value)
+            return True
+        except ValueError:
+            return False
+
+    @staticmethod
+    def of(enum_class: Type[Enum], name: str) -> Optional[Enum]:
+        """根据名称获取枚举
+
+        :param enum_class: 枚举类
+        :param name: 枚举成员名称
+        :return: 对应的枚举成员，未找到返回None
+        """
+        try:
+            return enum_class[name]
+        except KeyError:
+            return None
+
+    @staticmethod
+    def of_value(enum_class: Type[Enum], value: Any) -> Optional[Enum]:
+        """根据值获取枚举
+
+        :param enum_class: 枚举类
+        :param value: 枚举成员的值
+        :return: 对应的枚举成员，未找到返回None
+        """
+        try:
+            return enum_class(value)
+        except ValueError:
+            return None
+
+    @staticmethod
+    def get_by_func(
+        enum_class: Type[Enum], func: Callable[[Enum], bool], default: Optional[Enum] = None
+    ) -> Optional[Enum]:
+        """通过自定义函数查找枚举
+
+        遍历所有枚举成员，返回第一个使函数返回True的成员。
+
+        :param enum_class: 枚举类
+        :param func: 接收枚举成员并返回布尔值的函数
+        :param default: 未找到时的默认值，默认为None
+        :return: 匹配的枚举成员，未找到返回default
+        """
+        for member in enum_class:
+            if func(member):
+                return member
+        return default

hutool/core/util/escape_util.py

@@ -0,0 +1,97 @@
+import html
+from urllib.parse import quote, unquote
+
+
+class EscapeUtil:
+    """转义工具类，对应 Java cn.hutool.core.util.EscapeUtil"""
+
+    # HTML特殊字符映射
+    _HTML_ESCAPE_MAP = {
+        "&": "&",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    }
+    _HTML_UNESCAPE_MAP = {v: k for k, v in _HTML_ESCAPE_MAP.items()}
+
+    @staticmethod
+    def escape_html(content: str) -> str:
+        """HTML转义，将 & < > " ' 转义为HTML实体
+
+        :param content: 待转义的字符串
+        :return: 转义后的字符串
+        """
+        if not content:
+            return content
+        # 先转义 & 避免二次转义
+        result = content.replace("&", "&amp;")
+        result = result.replace("<", "&lt;")
+        result = result.replace(">", "&gt;")
+        result = result.replace('"', "&quot;")
+        result = result.replace("'", "&#39;")
+        return result
+
+    @staticmethod
+    def unescape_html(content: str) -> str:
+        """HTML反转义，将HTML实体还原为原始字符
+
+        :param content: 待反转义的字符串
+        :return: 反转义后的字符串
+        """
+        if not content:
+            return content
+        return html.unescape(content)
+
+    @staticmethod
+    def escape_xml(content: str) -> str:
+        """XML转义（同HTML转义）
+
+        :param content: 待转义的字符串
+        :return: 转义后的字符串
+        """
+        return EscapeUtil.escape_html(content)
+
+    @staticmethod
+    def unescape_xml(content: str) -> str:
+        """XML反转义（同HTML反转义）
+
+        :param content: 待反转义的字符串
+        :return: 反转义后的字符串
+        """
+        return EscapeUtil.unescape_html(content)
+
+    @staticmethod
+    def escape_sql(content: str) -> str:
+        """SQL转义，将单引号转为两个单引号
+
+        :param content: 待转义的字符串
+        :return: 转义后的字符串
+        """
+        if not content:
+            return content
+        return content.replace("'", "''")
+
+    @staticmethod
+    def escape_url(url: str, charset: str = "utf-8") -> str:
+        """URL编码
+
+        :param url: 待编码的URL字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 编码后的URL字符串
+        """
+        if not url:
+            return url
+        return quote(url, encoding=charset, safe="")
+
+    @staticmethod
+    def unescape_url(url: str, charset: str = "utf-8") -> str:
+        """URL解码
+
+        :param url: 待解码的URL字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 解码后的URL字符串
+        """
+        if not url:
+            return url
+        return unquote(url, encoding=charset)

hutool/core/util/hash_util.py

@@ -0,0 +1,243 @@
+"""哈希工具类"""
+
+
+class HashUtil:
+    """哈希工具类，对应 Java cn.hutool.core.util.HashUtil
+
+    提供多种非加密哈希算法的纯Python实现。
+    所有算法结果通过 & 0xFFFFFFFF 限制为32位无符号整数。
+    """
+
+    @staticmethod
+    def fnv1(data: bytes) -> int:
+        """FNV-1 哈希算法
+
+        :param data: 字节数组
+        :return: 32位哈希值
+        """
+        if data is None:
+            return 0
+        FNV_OFFSET = 0x811C9DC5
+        FNV_PRIME = 0x01000193
+        hash_val = FNV_OFFSET
+        for b in data:
+            hash_val = (hash_val * FNV_PRIME) & 0xFFFFFFFF
+            hash_val ^= b
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def fnv1a(data: bytes) -> int:
+        """FNV-1a 哈希算法（与FNV-1的区别在于异或和乘法的顺序相反）
+
+        :param data: 字节数组
+        :return: 32位哈希值
+        """
+        if data is None:
+            return 0
+        FNV_OFFSET = 0x811C9DC5
+        FNV_PRIME = 0x01000193
+        hash_val = FNV_OFFSET
+        for b in data:
+            hash_val ^= b
+            hash_val = (hash_val * FNV_PRIME) & 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def bkdr_hash(string: str) -> int:
+        """BKDR 哈希算法
+
+        由Brian Kernighan与Dennis Ritchie提出，种子数为131。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        seed = 131
+        hash_val = 0
+        for ch in string:
+            hash_val = (hash_val * seed + ord(ch)) & 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def ap_hash(string: str) -> int:
+        """AP 哈希算法
+
+        由Arash Partow提出，具有很好的分布效果。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0xAAAAAAAA
+        for i, ch in enumerate(string):
+            if (i & 1) == 0:
+                hash_val ^= (hash_val << 7) ^ ord(ch) ^ (hash_val >> 3)
+            else:
+                hash_val ^= ~((hash_val << 11) ^ ord(ch) ^ (hash_val >> 5))
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def djb_hash(string: str) -> int:
+        """DJB 哈希算法
+
+        由Daniel J. Bernstein提出，使用初始值5381。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 5381
+        for ch in string:
+            hash_val = ((hash_val << 5) + hash_val + ord(ch)) & 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def js_hash(string: str) -> int:
+        """JS 哈希算法
+
+        Justin Sobel提出的哈希算法。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0x4E67C6A7
+        for ch in string:
+            hash_val ^= (hash_val << 5) + ord(ch) + (hash_val >> 2)
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def rs_hash(string: str) -> int:
+        """RS 哈希算法
+
+        Robert Sedgwicks提出的哈希算法。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        a = 63689
+        b = 378551
+        hash_val = 0
+        for ch in string:
+            hash_val = (hash_val * a + ord(ch)) & 0xFFFFFFFF
+            a = (a * b) & 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def sdbm_hash(string: str) -> int:
+        """SDBM 哈希算法
+
+        开源数据库SDBM使用的哈希算法。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0
+        for ch in string:
+            hash_val = ord(ch) + (hash_val << 6) + (hash_val << 16) - hash_val
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def elf_hash(string: str) -> int:
+        """ELF 哈希算法
+
+        UNIX系统ELF文件格式中使用的哈希算法。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0
+        x = 0
+        for ch in string:
+            hash_val = (hash_val << 4) + ord(ch)
+            x = hash_val & 0xF0000000
+            if x != 0:
+                hash_val ^= x >> 24
+            hash_val &= ~x
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def dek_hash(string: str) -> int:
+        """DEK 哈希算法
+
+        由Donald E. Knuth提出。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = len(string)
+        for ch in string:
+            hash_val = ((hash_val << 5) ^ (hash_val >> 27) ^ ord(ch)) & 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def bp_hash(string: str) -> int:
+        """BP 哈希算法
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0
+        for ch in string:
+            hash_val = (hash_val << 7) ^ ord(ch)
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def pjw_hash(string: str) -> int:
+        """PJW 哈希算法
+
+        Peter J. Weinberger提出的哈希算法，常用于编译器符号表。
+
+        :param string: 输入字符串
+        :return: 32位哈希值
+        """
+        if string is None:
+            return 0
+        hash_val = 0
+        for ch in string:
+            hash_val = (hash_val << 4) + ord(ch)
+            high_bits = hash_val & 0xF0000000
+            if high_bits != 0:
+                hash_val ^= high_bits >> 24
+                hash_val &= ~high_bits
+            hash_val &= 0xFFFFFFFF
+        return hash_val
+
+    @staticmethod
+    def java_hash_code(string: str) -> int:
+        """Java String.hashCode() 兼容实现
+
+        使用 Java 的 s*31+c 算法，结果与Java完全一致。
+        Java的hashCode使用有符号32位整数，此方法返回无符号表示。
+
+        算法: h = h * 31 + char[i]
+
+        :param string: 输入字符串
+        :return: 32位哈希值（无符号表示，范围与Java有符号int一一对应）
+        """
+        if string is None:
+            return 0
+        h = 0
+        for ch in string:
+            h = (31 * h + ord(ch)) & 0xFFFFFFFF
+        return h

hutool/core/util/hex_util.py

@@ -0,0 +1,140 @@
+"""十六进制工具类"""
+
+
+class HexUtil:
+    """十六进制工具类，对应 Java cn.hutool.core.util.HexUtil"""
+
+    # 十六进制字符表（大写和小写）
+    _DIGITS_UPPER = "0123456789ABCDEF"
+    _DIGITS_LOWER = "0123456789abcdef"
+
+    @staticmethod
+    def encode_hex_str(data: bytes, lower_case: bool = False) -> str:
+        """字节数组转十六进制字符串
+
+        :param data: 字节数组
+        :param lower_case: 是否使用小写，默认大写
+        :return: 十六进制字符串
+        """
+        if data is None:
+            return ""
+        digits = HexUtil._DIGITS_LOWER if lower_case else HexUtil._DIGITS_UPPER
+        result = []
+        for b in data:
+            result.append(digits[(b >> 4) & 0x0F])
+            result.append(digits[b & 0x0F])
+        return "".join(result)
+
+    @staticmethod
+    def decode_hex(hex_str: str) -> bytes:
+        """十六进制字符串转字节数组
+
+        :param hex_str: 十六进制字符串（允许含空格等分隔符，自动去除）
+        :return: 字节数组
+        :raises ValueError: 当输入包含非法十六进制字符时抛出
+        """
+        if hex_str is None or len(hex_str) == 0:
+            return b""
+        # 去除常见分隔符（空格、冒号、短横线）
+        hex_str = hex_str.replace(" ", "").replace(":", "").replace("-", "")
+        length = len(hex_str)
+        if length % 2 != 0:
+            raise ValueError(f"十六进制字符串长度必须为偶数，当前长度为 {length}")
+        result = bytearray(length // 2)
+        for i in range(0, length, 2):
+            high = int(hex_str[i], 16)
+            low = int(hex_str[i + 1], 16)
+            result[i // 2] = (high << 4) | low
+        return bytes(result)
+
+    @staticmethod
+    def to_hex(number: int) -> str:
+        """数字转十六进制字符串（不带0x前缀）
+
+        :param number: 整数
+        :return: 十六进制字符串（大写）
+        """
+        if number == 0:
+            return "0"
+        # 处理负数：取其二进制补码表示
+        if number < 0:
+            # 转为无符号表示，取足够位数
+            number = number & 0xFFFFFFFFFFFFFFFF
+        result = []
+        while number > 0:
+            digit = number & 0x0F
+            result.append(HexUtil._DIGITS_UPPER[digit])
+            number >>= 4
+        result.reverse()
+        return "".join(result)
+
+    @staticmethod
+    def hex_to_int(hex_str: str) -> int:
+        """十六进制字符串转int
+
+        :param hex_str: 十六进制字符串（可选0x/0X前缀）
+        :return: 对应的整数值
+        """
+        if hex_str is None or len(hex_str) == 0:
+            raise ValueError("十六进制字符串不能为空")
+        hex_str = hex_str.strip()
+        if hex_str.startswith("0x") or hex_str.startswith("0X"):
+            hex_str = hex_str[2:]
+        return int(hex_str, 16)
+
+    @staticmethod
+    def encode_color_str(color: tuple) -> str:
+        """RGB元组转十六进制颜色字符串
+
+        :param color: RGB元组，如 (255, 128, 0)
+        :return: 十六进制颜色字符串，如 '#FF8000'
+        """
+        if color is None or len(color) < 3:
+            raise ValueError("颜色元组必须包含至少3个元素（R, G, B）")
+        r, g, b = color[0], color[1], color[2]
+        if not (0 <= r <= 255 and 0 <= g <= 255 and 0 <= b <= 255):
+            raise ValueError("RGB值必须在0-255范围内")
+        return f"#{r:02X}{g:02X}{b:02X}"
+
+    @staticmethod
+    def decode_color(color_str: str) -> tuple:
+        """十六进制颜色字符串转RGB元组
+
+        :param color_str: 十六进制颜色字符串，如 '#FF8000' 或 'FF8000'
+        :return: RGB元组，如 (255, 128, 0)
+        """
+        if color_str is None or len(color_str) == 0:
+            raise ValueError("颜色字符串不能为空")
+        color_str = color_str.strip().lstrip("#")
+        if len(color_str) == 6:
+            r = int(color_str[0:2], 16)
+            g = int(color_str[2:4], 16)
+            b = int(color_str[4:6], 16)
+            return (r, g, b)
+        elif len(color_str) == 3:
+            # 短格式如 #F80 -> #FF8800
+            r = int(color_str[0] * 2, 16)
+            g = int(color_str[1] * 2, 16)
+            b = int(color_str[2] * 2, 16)
+            return (r, g, b)
+        else:
+            raise ValueError(f"非法的颜色字符串长度：{len(color_str)}，期望6位或3位")
+
+    @staticmethod
+    def format_hex(hex_str: str, delimiter: str = " ", group_size: int = 2) -> str:
+        """格式化十六进制字符串，添加分隔符
+
+        :param hex_str: 十六进制字符串
+        :param delimiter: 分隔符，默认为空格
+        :param group_size: 每组字符数，默认为2
+        :return: 格式化后的十六进制字符串，如 '4A:3F:2B'
+        """
+        if hex_str is None or len(hex_str) == 0:
+            return ""
+        hex_str = hex_str.replace(" ", "").replace(":", "").replace("-", "")
+        if group_size <= 0:
+            raise ValueError("group_size 必须大于 0")
+        groups = []
+        for i in range(0, len(hex_str), group_size):
+            groups.append(hex_str[i : i + group_size].upper())
+        return delimiter.join(groups)