hutool-python 1.0.0__py3-none-any.whl

hutool/__init__.py

@@ -0,0 +1,174 @@
+"""Hutool-Python - Java Hutool 的 Python 移植版工具库。
+
+全量移植 Java Hutool 的 Python 版工具库，涵盖：
+- core: 核心工具类（字符串、数字、集合、日期、IO、Bean、编解码等）
+- http: HTTP 客户端工具
+- json_util: JSON 工具
+- crypto: 加密工具（摘要、对称/非对称加密、签名）
+- cache: 缓存工具（FIFO、LFU、LRU、定时）
+- captcha: 验证码
+- dfa: 敏感词过滤
+- extra: 扩展工具（拼音、Emoji、模板、二维码）
+- cron: 定时任务
+- jwt_util: JWT 工具
+- setting: 配置工具（YAML、Properties）
+"""
+
+__version__ = "1.0.0"
+
+# 核心工具类 - 顶层快捷导入
+from .core.bean import BeanUtil
+from .core.codec import Base32, Base64
+from .core.coll import CollUtil, ListUtil
+from .core.date import DateTime, DateUtil
+from .core.io.data_size_util import DataSizeUtil
+from .core.io.file_name_util import FileNameUtil
+from .core.io.file_util import FileUtil
+from .core.io.io_util import IoUtil
+from .core.io.path_util import PathUtil
+from .core.io.resource_util import ResourceUtil
+from .core.map import BiMap, DictUtil, MapUtil
+from .core.math_util import BitStatusUtil, MathUtil
+from .core.net import Ipv4Util, MaskBit, NetUtil
+from .core.text.csv_util import CsvUtil
+from .core.text.str_builder import StrBuilder
+from .core.text.unicode_util import UnicodeUtil
+from .core.tree import TreeNode, TreeUtil
+from .core.util.array_util import ArrayUtil
+from .core.util.boolean_util import BooleanUtil
+from .core.util.charset_util import CharsetUtil
+from .core.util.class_util import ClassUtil
+from .core.util.coordinate_util import Coordinate, CoordinateUtil
+from .core.util.credit_code_util import CreditCodeUtil
+from .core.util.desensitized_util import DesensitizedUtil
+from .core.util.enum_util import EnumUtil
+from .core.util.escape_util import EscapeUtil
+from .core.util.hash_util import HashUtil
+from .core.util.hex_util import HexUtil
+from .core.util.id_util import IdUtil
+from .core.util.idcard_util import IdcardUtil
+from .core.util.number_util import NumberUtil
+from .core.util.object_util import ObjectUtil
+from .core.util.page_util import PageUtil
+from .core.util.phone_util import PhoneUtil
+from .core.util.random_util import RandomUtil
+from .core.util.re_util import ReUtil
+from .core.util.reflect_util import ReflectUtil
+from .core.util.runtime_util import RuntimeUtil
+from .core.util.str_util import CharPool, CharUtil, StrUtil
+from .core.util.system_util import SystemUtil
+from .core.util.url_util import URLUtil
+from .core.util.version_util import VersionUtil
+from .core.util.xml_util import XmlUtil
+from .core.util.zip_util import ZipUtil
+
+# 其他模块
+from .cache import CacheUtil, FIFOCache, LFUCache, LRUCache, TimedCache
+from .captcha import ArithmeticCaptcha, CaptchaUtil, LineCaptcha
+from .crypto import DigestUtil, SecureUtil, SignUtil
+from .cron import CronPattern, CronUtil
+from .dfa import SensitiveUtil
+from .extra import EmojiUtil, PinyinUtil, QrCodeUtil, TemplateUtil
+from .http import HtmlUtil, HttpRequest, HttpResponse, HttpUtil
+from .json_util import JSONUtil
+from .jwt_util import JWTUtil
+from .setting import PropsUtil, SettingUtil, YamlUtil
+
+__all__ = [
+    # core/util
+    "ArrayUtil",
+    "BooleanUtil",
+    "CharsetUtil",
+    "CharPool",
+    "CharUtil",
+    "ClassUtil",
+    "Coordinate",
+    "CoordinateUtil",
+    "CreditCodeUtil",
+    "DesensitizedUtil",
+    "EnumUtil",
+    "EscapeUtil",
+    "HashUtil",
+    "HexUtil",
+    "IdUtil",
+    "IdcardUtil",
+    "NumberUtil",
+    "ObjectUtil",
+    "PageUtil",
+    "PhoneUtil",
+    "RandomUtil",
+    "ReUtil",
+    "ReflectUtil",
+    "RuntimeUtil",
+    "StrUtil",
+    "SystemUtil",
+    "URLUtil",
+    "VersionUtil",
+    "XmlUtil",
+    "ZipUtil",
+    # core/io
+    "DataSizeUtil",
+    "FileNameUtil",
+    "FileUtil",
+    "IoUtil",
+    "PathUtil",
+    "ResourceUtil",
+    # core/text
+    "CsvUtil",
+    "StrBuilder",
+    "UnicodeUtil",
+    # core 其他
+    "Base32",
+    "Base64",
+    "BeanUtil",
+    "BiMap",
+    "BitStatusUtil",
+    "CollUtil",
+    "DateTime",
+    "DateUtil",
+    "DictUtil",
+    "Ipv4Util",
+    "ListUtil",
+    "MapUtil",
+    "MaskBit",
+    "MathUtil",
+    "NetUtil",
+    "TreeNode",
+    "TreeUtil",
+    # http
+    "HtmlUtil",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpUtil",
+    # json / jwt
+    "JSONUtil",
+    "JWTUtil",
+    # cache
+    "CacheUtil",
+    "FIFOCache",
+    "LFUCache",
+    "LRUCache",
+    "TimedCache",
+    # captcha
+    "ArithmeticCaptcha",
+    "CaptchaUtil",
+    "LineCaptcha",
+    # crypto
+    "DigestUtil",
+    "SecureUtil",
+    "SignUtil",
+    # cron
+    "CronPattern",
+    "CronUtil",
+    # dfa
+    "SensitiveUtil",
+    # extra
+    "EmojiUtil",
+    "PinyinUtil",
+    "QrCodeUtil",
+    "TemplateUtil",
+    # setting
+    "PropsUtil",
+    "SettingUtil",
+    "YamlUtil",
+]

hutool/cache/__init__.py

@@ -0,0 +1,7 @@
+from .cache_util import CacheUtil
+from .fifo_cache import FIFOCache
+from .lfu_cache import LFUCache
+from .lru_cache import LRUCache
+from .timed_cache import TimedCache
+
+__all__ = ["CacheUtil", "FIFOCache", "LFUCache", "LRUCache", "TimedCache"]

hutool/cache/cache_util.py

@@ -0,0 +1,47 @@
+from .fifo_cache import FIFOCache
+from .lfu_cache import LFUCache
+from .lru_cache import LRUCache
+from .timed_cache import TimedCache
+
+
+class CacheUtil:
+    """缓存工厂类。
+
+    提供各种缓存实现的便捷创建方法。
+    """
+
+    @staticmethod
+    def new_fifo_cache(capacity: int = 16) -> FIFOCache:
+        """创建FIFO（先进先出）缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        :return: FIFOCache实例
+        """
+        return FIFOCache(capacity)
+
+    @staticmethod
+    def new_lfu_cache(capacity: int = 16) -> LFUCache:
+        """创建LFU（最不经常使用）缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        :return: LFUCache实例
+        """
+        return LFUCache(capacity)
+
+    @staticmethod
+    def new_lru_cache(capacity: int = 16) -> LRUCache:
+        """创建LRU（最近最少使用）缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        :return: LRUCache实例
+        """
+        return LRUCache(capacity)
+
+    @staticmethod
+    def new_timed_cache(timeout: int = 60) -> TimedCache:
+        """创建定时缓存。
+
+        :param timeout: 默认过期时间（秒），默认60秒
+        :return: TimedCache实例
+        """
+        return TimedCache(timeout)

hutool/cache/fifo_cache.py

@@ -0,0 +1,87 @@
+from collections import OrderedDict
+from typing import Any, KeysView
+
+
+class FIFOCache:
+    """FIFO（先进先出）缓存实现。
+
+    当缓存满时，最早插入的元素会被淘汰。
+    """
+
+    def __init__(self, capacity: int = 16) -> None:
+        """初始化FIFO缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        """
+        self._capacity: int = capacity
+        self._cache: OrderedDict = OrderedDict()
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        """获取缓存值。
+
+        :param key: 缓存键
+        :param default: 键不存在时返回的默认值
+        :return: 缓存值，不存在时返回默认值
+        """
+        return self._cache.get(key, default)
+
+    def put(self, key: Any, value: Any) -> None:
+        """放入缓存。如果缓存已满，淘汰最早插入的元素。
+
+        :param key: 缓存键
+        :param value: 缓存值
+        """
+        if key in self._cache:
+            self._cache[key] = value
+            return
+        if len(self._cache) >= self._capacity:
+            self._cache.popitem(last=False)
+        self._cache[key] = value
+
+    def remove(self, key: Any) -> Any:
+        """移除指定键的缓存。
+
+        :param key: 缓存键
+        :return: 被移除的值，键不存在时返回None
+        """
+        return self._cache.pop(key, None)
+
+    def size(self) -> int:
+        """获取当前缓存大小。
+
+        :return: 当前缓存条目数
+        """
+        return len(self._cache)
+
+    def capacity(self) -> int:
+        """获取缓存最大容量。
+
+        :return: 缓存最大容量
+        """
+        return self._capacity
+
+    def clear(self) -> None:
+        """清空所有缓存。"""
+        self._cache.clear()
+
+    def is_full(self) -> bool:
+        """判断缓存是否已满。
+
+        :return: 缓存已满返回True，否则返回False
+        """
+        return len(self._cache) >= self._capacity
+
+    def keys(self) -> KeysView:
+        """获取所有缓存键。
+
+        :return: 缓存键的视图
+        """
+        return self._cache.keys()
+
+    def __contains__(self, key: Any) -> bool:
+        """判断键是否存在于缓存中。"""
+        return key in self._cache
+
+    def __len__(self) -> int:
+        """返回缓存大小。"""
+        return len(self._cache)

hutool/cache/lfu_cache.py

@@ -0,0 +1,129 @@
+from collections import defaultdict
+from typing import Any
+
+
+class LFUCache:
+    """LFU（最不经常使用）缓存实现。
+
+    当缓存满时，访问频率最低的元素会被淘汰。
+    若有多个元素频率相同，淘汰最早插入的。
+    """
+
+    def __init__(self, capacity: int = 16) -> None:
+        """初始化LFU缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        """
+        self._capacity: int = capacity
+        self._cache: dict = {}  # key -> value
+        self._freq: dict = {}  # key -> frequency
+        self._freq_to_keys: dict = defaultdict(list)  # frequency -> [keys]
+        self._min_freq: int = 0
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        """获取缓存值，并更新访问频率。
+
+        :param key: 缓存键
+        :param default: 键不存在时返回的默认值
+        :return: 缓存值，不存在时返回默认值
+        """
+        if key not in self._cache:
+            return default
+        self._update_freq(key)
+        return self._cache[key]
+
+    def put(self, key: Any, value: Any) -> None:
+        """放入缓存。如果缓存已满，淘汰访问频率最低的元素。
+
+        :param key: 缓存键
+        :param value: 缓存值
+        """
+        if self._capacity <= 0:
+            return
+
+        if key in self._cache:
+            self._cache[key] = value
+            self._update_freq(key)
+            return
+
+        if len(self._cache) >= self._capacity:
+            self._evict()
+
+        self._cache[key] = value
+        self._freq[key] = 1
+        self._freq_to_keys[1].append(key)
+        self._min_freq = 1
+
+    def remove(self, key: Any) -> Any:
+        """移除指定键的缓存。
+
+        :param key: 缓存键
+        :return: 被移除的值，键不存在时返回None
+        """
+        if key not in self._cache:
+            return None
+
+        freq = self._freq[key]
+        self._freq_to_keys[freq].remove(key)
+        if not self._freq_to_keys[freq]:
+            del self._freq_to_keys[freq]
+            if self._min_freq == freq:
+                self._min_freq = min(self._freq_to_keys.keys()) if self._freq_to_keys else 0
+
+        value = self._cache[key]
+        del self._cache[key]
+        del self._freq[key]
+        return value
+
+    def size(self) -> int:
+        """获取当前缓存大小。
+
+        :return: 当前缓存条目数
+        """
+        return len(self._cache)
+
+    def capacity(self) -> int:
+        """获取缓存最大容量。
+
+        :return: 缓存最大容量
+        """
+        return self._capacity
+
+    def clear(self) -> None:
+        """清空所有缓存。"""
+        self._cache.clear()
+        self._freq.clear()
+        self._freq_to_keys.clear()
+        self._min_freq = 0
+
+    def is_full(self) -> bool:
+        """判断缓存是否已满。
+
+        :return: 缓存已满返回True，否则返回False
+        """
+        return len(self._cache) >= self._capacity
+
+    def _update_freq(self, key: Any) -> None:
+        """更新键的访问频率。
+
+        :param key: 缓存键
+        """
+        freq = self._freq[key]
+        self._freq_to_keys[freq].remove(key)
+        if not self._freq_to_keys[freq]:
+            del self._freq_to_keys[freq]
+            if self._min_freq == freq:
+                self._min_freq = freq + 1
+
+        new_freq = freq + 1
+        self._freq[key] = new_freq
+        self._freq_to_keys[new_freq].append(key)
+
+    def _evict(self) -> None:
+        """淘汰访问频率最低且最早插入的元素。"""
+        keys = self._freq_to_keys[self._min_freq]
+        evict_key = keys.pop(0)
+        if not keys:
+            del self._freq_to_keys[self._min_freq]
+        del self._cache[evict_key]
+        del self._freq[evict_key]

hutool/cache/lru_cache.py

@@ -0,0 +1,93 @@
+from collections import OrderedDict
+from typing import Any, KeysView
+
+
+class LRUCache:
+    """LRU（最近最少使用）缓存实现。
+
+    当缓存满时，最近最少使用的元素会被淘汰。
+    每次get操作会将元素移至最新位置。
+    """
+
+    def __init__(self, capacity: int = 16) -> None:
+        """初始化LRU缓存。
+
+        :param capacity: 缓存最大容量，默认16
+        """
+        self._capacity: int = capacity
+        self._cache: OrderedDict = OrderedDict()
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        """获取缓存值，并将该元素移至最新位置。
+
+        :param key: 缓存键
+        :param default: 键不存在时返回的默认值
+        :return: 缓存值，不存在时返回默认值
+        """
+        if key not in self._cache:
+            return default
+        self._cache.move_to_end(key)
+        return self._cache[key]
+
+    def put(self, key: Any, value: Any) -> None:
+        """放入缓存。如果键已存在则更新并移至最新位置；
+        如果缓存已满，淘汰最近最少使用的元素。
+
+        :param key: 缓存键
+        :param value: 缓存值
+        """
+        if key in self._cache:
+            self._cache.move_to_end(key)
+            self._cache[key] = value
+            return
+        if len(self._cache) >= self._capacity:
+            self._cache.popitem(last=False)
+        self._cache[key] = value
+
+    def remove(self, key: Any) -> Any:
+        """移除指定键的缓存。
+
+        :param key: 缓存键
+        :return: 被移除的值，键不存在时返回None
+        """
+        return self._cache.pop(key, None)
+
+    def size(self) -> int:
+        """获取当前缓存大小。
+
+        :return: 当前缓存条目数
+        """
+        return len(self._cache)
+
+    def capacity(self) -> int:
+        """获取缓存最大容量。
+
+        :return: 缓存最大容量
+        """
+        return self._capacity
+
+    def clear(self) -> None:
+        """清空所有缓存。"""
+        self._cache.clear()
+
+    def is_full(self) -> bool:
+        """判断缓存是否已满。
+
+        :return: 缓存已满返回True，否则返回False
+        """
+        return len(self._cache) >= self._capacity
+
+    def keys(self) -> KeysView:
+        """获取所有缓存键，按使用顺序排列。
+
+        :return: 缓存键的视图（从最久未使用到最近使用）
+        """
+        return self._cache.keys()
+
+    def __contains__(self, key: Any) -> bool:
+        """判断键是否存在于缓存中。"""
+        return key in self._cache
+
+    def __len__(self) -> int:
+        """返回缓存大小。"""
+        return len(self._cache)

hutool/cache/timed_cache.py

@@ -0,0 +1,115 @@
+import threading
+import time
+from typing import Any, Optional
+
+
+class TimedCache:
+    """定时缓存实现。
+
+    每个缓存条目可以设置独立的过期时间，过期后自动失效。
+    支持定时清理过期条目以释放内存。
+    """
+
+    def __init__(self, timeout: int = 60) -> None:
+        """初始化定时缓存。
+
+        :param timeout: 默认过期时间（秒），默认60秒
+        """
+        self._timeout: int = timeout
+        self._cache: dict = {}  # key -> (value, expire_time)
+        self._lock: threading.Lock = threading.Lock()
+        self._prune_timer: Optional[threading.Timer] = None
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        """获取缓存值。若已过期则返回默认值。
+
+        :param key: 缓存键
+        :param default: 键不存在或已过期时返回的默认值
+        :return: 缓存值，不存在或已过期时返回默认值
+        """
+        with self._lock:
+            if key not in self._cache:
+                return default
+            value, expire_time = self._cache[key]
+            if time.time() > expire_time:
+                del self._cache[key]
+                return default
+            return value
+
+    def put(self, key: Any, value: Any, timeout: Optional[int] = None) -> None:
+        """放入缓存。
+
+        :param key: 缓存键
+        :param value: 缓存值
+        :param timeout: 过期时间（秒），为None时使用默认过期时间
+        """
+        expire_time = time.time() + (timeout if timeout is not None else self._timeout)
+        with self._lock:
+            self._cache[key] = (value, expire_time)
+
+    def remove(self, key: Any) -> Any:
+        """移除指定键的缓存。
+
+        :param key: 缓存键
+        :return: 被移除的值，键不存在时返回None
+        """
+        with self._lock:
+            entry = self._cache.pop(key, None)
+            if entry is None:
+                return None
+            value, _ = entry
+            return value
+
+    def size(self) -> int:
+        """获取当前缓存大小（包含已过期但未清理的条目）。
+
+        :return: 当前缓存条目数
+        """
+        with self._lock:
+            return len(self._cache)
+
+    def clear(self) -> None:
+        """清空所有缓存。"""
+        with self._lock:
+            self._cache.clear()
+
+    def prune(self) -> int:
+        """清理过期缓存条目。
+
+        :return: 被清理的条目数
+        """
+        now = time.time()
+        expired_keys: list = []
+        with self._lock:
+            for key, (_, expire_time) in self._cache.items():
+                if now > expire_time:
+                    expired_keys.append(key)
+            for key in expired_keys:
+                del self._cache[key]
+        return len(expired_keys)
+
+    def schedule_prune(self, delay_seconds: int = 60) -> None:
+        """启动定时清理线程，定期清理过期缓存。
+
+        :param delay_seconds: 清理间隔（秒），默认60秒
+        """
+        self._cancel_prune_timer()
+        self._prune_timer = threading.Timer(delay_seconds, self._prune_callback, args=(delay_seconds,))
+        self._prune_timer.daemon = True
+        self._prune_timer.start()
+
+    def _prune_callback(self, delay_seconds: int) -> None:
+        """清理回调，执行清理后重新调度。
+
+        :param delay_seconds: 下次清理间隔（秒）
+        """
+        self.prune()
+        self._prune_timer = threading.Timer(delay_seconds, self._prune_callback, args=(delay_seconds,))
+        self._prune_timer.daemon = True
+        self._prune_timer.start()
+
+    def _cancel_prune_timer(self) -> None:
+        """取消定时清理线程。"""
+        if self._prune_timer is not None:
+            self._prune_timer.cancel()
+            self._prune_timer = None

hutool/captcha/__init__.py

@@ -0,0 +1,3 @@
+from .captcha_util import ArithmeticCaptcha, CaptchaUtil, LineCaptcha
+
+__all__ = ["ArithmeticCaptcha", "CaptchaUtil", "LineCaptcha"]