hutool-python 1.0.0__py3-none-any.whl

hutool/crypto/secure_util.py

@@ -0,0 +1,311 @@
+import os
+from typing import Optional, Tuple, Union
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives import padding as sym_padding
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+class SecureUtil:
+    """加密工具类
+
+    提供常用对称/非对称加密算法封装：
+    - AES（CBC/ECB/CTR）
+    - DES（CBC/ECB）
+    - RSA（加密/解密/签名/验签）
+    """
+
+    # ------------------------------------------------------------------ #
+    #  内部辅助
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _ensure_bytes(data: Union[str, bytes]) -> bytes:
+        """将输入统一转为 bytes"""
+        if isinstance(data, str):
+            return data.encode("utf-8")
+        return data
+
+    # ------------------------------------------------------------------ #
+    #  AES
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def generate_aes_key(key_size: int = 128) -> bytes:
+        """生成AES密钥
+
+        :param key_size: 密钥位数，支持 128、192、256
+        :return: 随机密钥 bytes
+        """
+        if key_size not in (128, 192, 256):
+            raise ValueError("AES密钥长度必须为128、192或256位")
+        return os.urandom(key_size // 8)
+
+    @staticmethod
+    def encrypt_aes(data: bytes, key: bytes, mode: str = "CBC", iv: Optional[bytes] = None) -> bytes:
+        """AES加密
+
+        :param data: 待加密数据（明文）
+        :param key: AES密钥（16/24/32字节）
+        :param mode: 加密模式，支持 CBC / ECB / CTR
+        :param iv: 初始化向量（CBC/CTR模式必填，ECB模式忽略）
+        :return: 密文 bytes（CBC/CTR模式前16字节为IV）
+        """
+        if len(key) not in (16, 24, 32):
+            raise ValueError("AES密钥长度必须为16、24或32字节")
+
+        mode_upper = mode.upper()
+        if mode_upper == "CBC":
+            if iv is None:
+                iv = os.urandom(16)
+            cipher_mode = modes.CBC(iv)
+        elif mode_upper == "ECB":
+            iv = b""
+            cipher_mode = modes.ECB()
+        elif mode_upper == "CTR":
+            if iv is None:
+                iv = os.urandom(16)
+            cipher_mode = modes.CTR(iv)
+        else:
+            raise ValueError(f"不支持的AES模式: {mode}")
+
+        # PKCS7 填充（CTR模式无需填充）
+        if mode_upper != "CTR":
+            padder = sym_padding.PKCS7(128).padder()
+            data = padder.update(data) + padder.finalize()
+
+        cipher = Cipher(algorithms.AES(key), cipher_mode, backend=default_backend())
+        encryptor = cipher.encryptor()
+        ciphertext = encryptor.update(data) + encryptor.finalize()
+
+        # 将IV/nonce拼接在密文前（ECB模式除外）
+        if mode_upper == "ECB":
+            return ciphertext
+        return iv + ciphertext
+
+    @staticmethod
+    def decrypt_aes(data: bytes, key: bytes, mode: str = "CBC", iv: Optional[bytes] = None) -> bytes:
+        """AES解密
+
+        :param data: 密文 bytes（如果未提供iv，CBC/CTR模式会从前16字节读取IV）
+        :param key: AES密钥
+        :param mode: 加密模式，支持 CBC / ECB / CTR
+        :param iv: 初始化向量（可选，不提供时从密文前缀读取）
+        :return: 解密后的明文 bytes
+        """
+        if len(key) not in (16, 24, 32):
+            raise ValueError("AES密钥长度必须为16、24或32字节")
+
+        mode_upper = mode.upper()
+        if mode_upper == "CBC":
+            if iv is None:
+                iv, data = data[:16], data[16:]
+            cipher_mode = modes.CBC(iv)
+        elif mode_upper == "ECB":
+            cipher_mode = modes.ECB()
+        elif mode_upper == "CTR":
+            if iv is None:
+                iv, data = data[:16], data[16:]
+            cipher_mode = modes.CTR(iv)
+        else:
+            raise ValueError(f"不支持的AES模式: {mode}")
+
+        cipher = Cipher(algorithms.AES(key), cipher_mode, backend=default_backend())
+        decryptor = cipher.decryptor()
+        plaintext = decryptor.update(data) + decryptor.finalize()
+
+        # 去除PKCS7填充（CTR模式无需去除）
+        if mode_upper != "CTR":
+            unpadder = sym_padding.PKCS7(128).unpadder()
+            plaintext = unpadder.update(plaintext) + unpadder.finalize()
+
+        return plaintext
+
+    # ------------------------------------------------------------------ #
+    #  DES
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def generate_des_key() -> bytes:
+        """生成DES密钥（8字节）"""
+        return os.urandom(8)
+
+    @staticmethod
+    def encrypt_des(data: bytes, key: bytes, mode: str = "CBC", iv: Optional[bytes] = None) -> bytes:
+        """DES加密
+
+        :param data: 待加密数据
+        :param key: DES密钥（8字节）
+        :param mode: 加密模式，支持 CBC / ECB
+        :param iv: 初始化向量（CBC模式必填或自动生成）
+        :return: 密文 bytes（CBC模式前8字节为IV）
+        """
+        if len(key) != 8:
+            raise ValueError("DES密钥长度必须为8字节")
+
+        mode_upper = mode.upper()
+        if mode_upper == "CBC":
+            if iv is None:
+                iv = os.urandom(8)
+            cipher_mode = modes.CBC(iv)
+        elif mode_upper == "ECB":
+            iv = b""
+            cipher_mode = modes.ECB()
+        else:
+            raise ValueError(f"不支持的DES模式: {mode}")
+
+        # PKCS7 填充（DES块大小64位=8字节）
+        padder = sym_padding.PKCS7(64).padder()
+        data = padder.update(data) + padder.finalize()
+
+        cipher = Cipher(algorithms.TripleDES(key * 3 if len(key) == 8 else key), cipher_mode, backend=default_backend())
+        encryptor = cipher.encryptor()
+        ciphertext = encryptor.update(data) + encryptor.finalize()
+
+        if mode_upper == "ECB":
+            return ciphertext
+        return iv + ciphertext
+
+    @staticmethod
+    def decrypt_des(data: bytes, key: bytes, mode: str = "CBC", iv: Optional[bytes] = None) -> bytes:
+        """DES解密
+
+        :param data: 密文 bytes（如果未提供iv，CBC模式会从前8字节读取IV）
+        :param key: DES密钥（8字节）
+        :param mode: 加密模式，支持 CBC / ECB
+        :param iv: 初始化向量（可选）
+        :return: 解密后的明文 bytes
+        """
+        if len(key) != 8:
+            raise ValueError("DES密钥长度必须为8字节")
+
+        mode_upper = mode.upper()
+        if mode_upper == "CBC":
+            if iv is None:
+                iv, data = data[:8], data[8:]
+            cipher_mode = modes.CBC(iv)
+        elif mode_upper == "ECB":
+            cipher_mode = modes.ECB()
+        else:
+            raise ValueError(f"不支持的DES模式: {mode}")
+
+        cipher = Cipher(algorithms.TripleDES(key * 3 if len(key) == 8 else key), cipher_mode, backend=default_backend())
+        decryptor = cipher.decryptor()
+        plaintext = decryptor.update(data) + decryptor.finalize()
+
+        unpadder = sym_padding.PKCS7(64).unpadder()
+        plaintext = unpadder.update(plaintext) + unpadder.finalize()
+
+        return plaintext
+
+    # ------------------------------------------------------------------ #
+    #  RSA
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def generate_rsa_key_pair(key_size: int = 2048) -> Tuple[bytes, bytes]:
+        """生成RSA密钥对
+
+        :param key_size: 密钥位数，默认2048
+        :return: (public_key_pem, private_key_pem) 元组
+        """
+        private_key = rsa.generate_private_key(
+            public_exponent=65537,
+            key_size=key_size,
+            backend=default_backend(),
+        )
+        public_key = private_key.public_key()
+
+        public_pem = public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        return public_pem, private_pem
+
+    @staticmethod
+    def encrypt_rsa(data: bytes, public_key_pem: bytes) -> bytes:
+        """RSA公钥加密
+
+        :param data: 待加密数据（长度受密钥大小限制）
+        :param public_key_pem: PEM格式公钥
+        :return: 密文 bytes
+        """
+        public_key = serialization.load_pem_public_key(public_key_pem, backend=default_backend())
+        ciphertext = public_key.encrypt(
+            data,
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+        return ciphertext
+
+    @staticmethod
+    def decrypt_rsa(data: bytes, private_key_pem: bytes) -> bytes:
+        """RSA私钥解密
+
+        :param data: 密文 bytes
+        :param private_key_pem: PEM格式私钥
+        :return: 明文 bytes
+        """
+        private_key = serialization.load_pem_private_key(private_key_pem, password=None, backend=default_backend())
+        plaintext = private_key.decrypt(
+            data,
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+        return plaintext
+
+    @staticmethod
+    def sign_with_rsa(data: bytes, private_key_pem: bytes) -> bytes:
+        """RSA私钥签名
+
+        :param data: 待签名数据
+        :param private_key_pem: PEM格式私钥
+        :return: 签名 bytes
+        """
+        private_key = serialization.load_pem_private_key(private_key_pem, password=None, backend=default_backend())
+        signature = private_key.sign(
+            data,
+            padding.PSS(
+                mgf=padding.MGF1(hashes.SHA256()),
+                salt_length=padding.PSS.MAX_LENGTH,
+            ),
+            hashes.SHA256(),
+        )
+        return signature
+
+    @staticmethod
+    def verify_with_rsa(data: bytes, signature: bytes, public_key_pem: bytes) -> bool:
+        """RSA公钥验签
+
+        :param data: 原始数据
+        :param signature: 签名 bytes
+        :param public_key_pem: PEM格式公钥
+        :return: 验签是否通过
+        """
+        public_key = serialization.load_pem_public_key(public_key_pem, backend=default_backend())
+        try:
+            public_key.verify(
+                signature,
+                data,
+                padding.PSS(
+                    mgf=padding.MGF1(hashes.SHA256()),
+                    salt_length=padding.PSS.MAX_LENGTH,
+                ),
+                hashes.SHA256(),
+            )
+            return True
+        except Exception:
+            return False

hutool/crypto/sign_util.py

@@ -0,0 +1,74 @@
+from typing import Dict
+
+from .digest_util import DigestUtil
+
+
+class SignUtil:
+    """签名工具类
+
+    提供常用的参数签名算法，适用于接口签名、防篡改等场景。
+    签名流程：
+    1. 将参数按 key 的字典序排序
+    2. 拼接为 key1=value1&key2=value2&secret=xxx 格式
+    3. 使用指定算法计算摘要
+    """
+
+    # 支持的算法映射
+    _ALGORITHM_MAP = {
+        "md5": (DigestUtil.md5_hex, False),
+        "sha1": (DigestUtil.sha1_hex, False),
+        "sha256": (DigestUtil.sha256_hex, False),
+        "hmac_md5": (DigestUtil.hmac_md5_hex, True),
+        "hmac_sha1": (DigestUtil.hmac_sha1_hex, True),
+        "hmac_sha256": (DigestUtil.hmac_sha256_hex, True),
+    }
+
+    @staticmethod
+    def sign_params(params: Dict[str, str], secret: str, algorithm: str = "md5") -> str:
+        """对参数进行签名
+
+        签名步骤：
+        1. 将参数按 key 字典序升序排序
+        2. 拼接为 key1=value1&key2=value2&secret=xxx 形式
+        3. 用指定算法计算摘要并返回十六进制字符串
+
+        :param params: 待签名的参数字典
+        :param secret: 密钥
+        :param algorithm: 签名算法，支持 md5 / sha1 / sha256 / hmac_md5 / hmac_sha1 / hmac_sha256
+        :return: 签名后的十六进制字符串
+        :raises ValueError: 不支持的算法时抛出
+        """
+        algo_lower = algorithm.lower()
+        if algo_lower not in SignUtil._ALGORITHM_MAP:
+            raise ValueError(f"不支持的签名算法: {algorithm}，支持: {', '.join(SignUtil._ALGORITHM_MAP.keys())}")
+
+        # 1. 按 key 排序，过滤掉值为 None 的参数
+        sorted_keys = sorted(params.keys())
+
+        # 2. 拼接
+        parts = []
+        for key in sorted_keys:
+            value = params[key]
+            if value is not None:
+                parts.append(f"{key}={value}")
+        parts.append(f"secret={secret}")
+        sign_str = "&".join(parts)
+
+        # 3. 计算摘要
+        func, is_hmac = SignUtil._ALGORITHM_MAP[algo_lower]
+        if is_hmac:
+            return func(sign_str, secret)
+        return func(sign_str)
+
+    @staticmethod
+    def sort_sign(params: Dict[str, str], secret: str, algorithm: str = "md5") -> str:
+        """排序签名（功能同 sign_params）
+
+        这是 sign_params 的别名，方便不同调用场景使用。
+
+        :param params: 待签名的参数字典
+        :param secret: 密钥
+        :param algorithm: 签名算法
+        :return: 签名后的十六进制字符串
+        """
+        return SignUtil.sign_params(params, secret, algorithm)

hutool/dfa/__init__.py

@@ -0,0 +1,3 @@
+from .sensitive_util import SensitiveUtil
+
+__all__ = ["SensitiveUtil"]

hutool/dfa/sensitive_util.py

@@ -0,0 +1,114 @@
+"""敏感词过滤工具，基于DFA（确定性有限自动机）算法"""
+
+from typing import List
+
+
+class SensitiveUtil:
+    """敏感词过滤工具，基于DFA（确定性有限自动机）算法"""
+
+    _root: dict = {}
+    _initialized: bool = False
+
+    @classmethod
+    def init(cls, words: List[str]) -> None:
+        """初始化敏感词库
+
+        :param words: 敏感词列表
+        """
+        cls._root = {}
+        for word in words:
+            node = cls._root
+            for char in word:
+                if char not in node:
+                    node[char] = {}
+                node = node[char]
+            # 标记词结束
+            node["__end__"] = True
+        cls._initialized = True
+
+    @classmethod
+    def contains(cls, text: str) -> bool:
+        """是否包含敏感词
+
+        :param text: 待检测文本
+        :return: 是否包含敏感词
+        """
+        if not cls._initialized:
+            return False
+        for i in range(len(text)):
+            node = cls._root
+            j = i
+            while j < len(text) and text[j] in node:
+                node = node[text[j]]
+                if node.get("__end__"):
+                    return True
+                j += 1
+        return False
+
+    @classmethod
+    def find_first(cls, text: str) -> str:
+        """查找第一个敏感词
+
+        :param text: 待检测文本
+        :return: 第一个匹配的敏感词，未找到返回空字符串
+        """
+        if not cls._initialized:
+            return ""
+        for i in range(len(text)):
+            node = cls._root
+            j = i
+            while j < len(text) and text[j] in node:
+                node = node[text[j]]
+                if node.get("__end__"):
+                    return text[i : j + 1]
+                j += 1
+        return ""
+
+    @classmethod
+    def find_all(cls, text: str) -> List[str]:
+        """查找所有敏感词
+
+        :param text: 待检测文本
+        :return: 所有匹配的敏感词列表
+        """
+        if not cls._initialized:
+            return []
+        result: List[str] = []
+        for i in range(len(text)):
+            node = cls._root
+            j = i
+            while j < len(text) and text[j] in node:
+                node = node[text[j]]
+                if node.get("__end__"):
+                    result.append(text[i : j + 1])
+                j += 1
+        return result
+
+    @classmethod
+    def replace(cls, text: str, replace_char: str = "*") -> str:
+        """替换敏感词
+
+        :param text: 待处理文本
+        :param replace_char: 替换字符，默认为 '*'
+        :return: 替换后的文本
+        """
+        if not cls._initialized:
+            return text
+        chars = list(text)
+        i = 0
+        while i < len(chars):
+            node = cls._root
+            j = i
+            match_end = -1
+            while j < len(chars) and chars[j] in node:
+                node = node[chars[j]]
+                if node.get("__end__"):
+                    match_end = j
+                j += 1
+            if match_end >= 0:
+                for k in range(i, match_end + 1):
+                    chars[k] = replace_char
+                i = match_end + 1
+            else:
+                i += 1
+        return "".join(chars)

hutool/extra/__init__.py

@@ -0,0 +1,6 @@
+from .emoji_util import EmojiUtil
+from .pinyin_util import PinyinUtil
+from .qr_code_util import QrCodeUtil
+from .template_util import TemplateUtil
+
+__all__ = ["EmojiUtil", "PinyinUtil", "QrCodeUtil", "TemplateUtil"]

hutool/extra/emoji_util.py

@@ -0,0 +1,90 @@
+"""Emoji工具类"""
+
+import re
+
+# 匹配emoji的正则表达式
+_EMOJI_PATTERN = re.compile(
+    "["
+    "\U0001f600-\U0001f64f"  # 表情符号
+    "\U0001f300-\U0001f5ff"  # 符号和象形文字
+    "\U0001f680-\U0001f6ff"  # 交通和地图符号
+    "\U0001f1e0-\U0001f1ff"  # 旗帜
+    "\U00002702-\U000027b0"  # 杂项符号
+    "\U000024c2-\U0001f251"  # 封闭字符
+    "\U0001f926-\U0001f937"  # 补充表情
+    "\U00010000-\U0010ffff"  # 补充平面
+    "♀-♂"  # 性别符号
+    "☀-⭕"  # 杂项符号
+    "‍"  # 零宽连接符
+    "⏏"
+    "⏩-⏳"
+    "⏸-⏺"
+    "️"  # 变体选择符
+    "⤴-⤵"
+    "▪-◾"
+    "⬅-⬇"
+    "⬛-⬜"
+    "⭐"
+    "〰"
+    "〽"
+    "㊗"
+    "㊙"
+    "]+",
+    flags=re.UNICODE,
+)
+
+
+class EmojiUtil:
+    """Emoji工具类"""
+
+    @staticmethod
+    def contains_emoji(str_val: str) -> bool:
+        """判断是否包含emoji
+
+        :param str_val: 待检测字符串
+        :return: 是否包含emoji
+        """
+        return bool(_EMOJI_PATTERN.search(str_val))
+
+    @staticmethod
+    def emoji_to_unicode(emoji_str: str) -> str:
+        """将emoji转换为Unicode编码
+
+        :param emoji_str: 包含emoji的字符串
+        :return: Unicode编码字符串（格式：\\U0001F600）
+        """
+        result = []
+        for char in emoji_str:
+            code_point = ord(char)
+            if code_point > 0xFFFF:
+                result.append(f"\\U{code_point:08X}")
+            elif code_point > 0xFF:
+                result.append(f"\\u{code_point:04X}")
+            else:
+                result.append(char)
+        return "".join(result)
+
+    @staticmethod
+    def unicode_to_emoji(unicode_str: str) -> str:
+        """将Unicode编码转换为emoji
+
+        :param unicode_str: Unicode编码字符串（格式：\\U0001F600 或 \\u2764）
+        :return: 包含emoji的字符串
+        """
+
+        def _replace(match: re.Match) -> str:
+            code_point = int(match.group(1), 16)
+            return chr(code_point)
+
+        # 匹配 \\U 开头的8位和 \\u 开头的4位十六进制
+        result = re.sub(r"\\[Uu]([0-9a-fA-F]{4,8})", _replace, unicode_str)
+        return result
+
+    @staticmethod
+    def remove_emojis(str_val: str) -> str:
+        """移除字符串中的所有emoji
+
+        :param str_val: 待处理字符串
+        :return: 移除emoji后的字符串
+        """
+        return _EMOJI_PATTERN.sub("", str_val)

hutool/extra/pinyin_util.py

@@ -0,0 +1,44 @@
+"""拼音工具类，基于pypinyin"""
+
+
+
+class PinyinUtil:
+    """拼音工具类，基于pypinyin"""
+
+    @staticmethod
+    def get_pinyin(str_val: str, separator: str = "") -> str:
+        """获取拼音
+
+        :param str_val: 中文字符串
+        :param separator: 分隔符，默认为空字符串
+        :return: 拼音字符串
+        """
+        from pypinyin import Style, pinyin
+
+        result = pinyin(str_val, style=Style.TONE, errors="ignore")
+        return separator.join([item[0] for item in result if item])
+
+    @staticmethod
+    def get_pinyin_first_letter(str_val: str) -> str:
+        """获取拼音首字母
+
+        :param str_val: 中文字符串
+        :return: 拼音首字母字符串
+        """
+        from pypinyin import Style, lazy_pinyin
+
+        result = lazy_pinyin(str_val, style=Style.FIRST_LETTER, errors="ignore")
+        return "".join(result)
+
+    @staticmethod
+    def get_full_pinyin(str_val: str, separator: str = " ") -> str:
+        """获取全拼
+
+        :param str_val: 中文字符串
+        :param separator: 分隔符，默认为空格
+        :return: 全拼字符串
+        """
+        from pypinyin import Style, lazy_pinyin
+
+        result = lazy_pinyin(str_val, style=Style.TONE, errors="ignore")
+        return separator.join(result)