hutool-python 1.0.0__py3-none-any.whl

hutool/cron/cron_pattern.py

@@ -0,0 +1,123 @@
+"""Cron表达式解析与匹配"""
+
+from datetime import datetime, timedelta
+from typing import List, Optional, Set
+
+
+class CronPattern:
+    """Cron表达式解析与匹配
+
+    支持标准5位cron: 分 时 日 月 周
+
+    特殊字符说明:
+
+    - ``*`` : 匹配任意值
+    - ``,`` : 列举多个值 (如 1,3,5)
+    - ``-`` : 范围 (如 1-5)
+    - ``/`` : 步长 (如 */5 表示每5个单位)
+    """
+
+    def __init__(self, pattern: str) -> None:
+        """初始化CronPattern
+
+        :param pattern: cron表达式字符串，格式为 "分 时 日 月 周"
+        :raises ValueError: 表达式格式不正确
+        """
+        self._pattern: str = pattern
+        self._fields: List[str] = pattern.strip().split()
+        if len(self._fields) != 5:
+            raise ValueError(f"无效的cron表达式 '{pattern}'，必须包含5个字段: 分 时 日 月 周")
+
+    def match(self, dt: datetime) -> bool:
+        """判断给定时间是否匹配
+
+        :param dt: 待匹配的时间
+        :return: 是否匹配cron表达式
+        """
+        minute_set = self._parse_field(self._fields[0], 0, 59)
+        hour_set = self._parse_field(self._fields[1], 0, 23)
+        day_set = self._parse_field(self._fields[2], 1, 31)
+        month_set = self._parse_field(self._fields[3], 1, 12)
+        weekday_set = self._parse_field(self._fields[4], 0, 6)
+
+        return (
+            dt.minute in minute_set
+            and dt.hour in hour_set
+            and dt.day in day_set
+            and dt.month in month_set
+            and dt.weekday() % 7 in weekday_set
+        )
+
+    def next_match_time(self, after: Optional[datetime] = None) -> datetime:
+        """获取下一次匹配时间
+
+        :param after: 基准时间，默认为当前时间
+        :return: 下一次匹配的时间
+        :raises RuntimeError: 超过搜索上限仍未找到匹配时间
+        """
+        if after is None:
+            after = datetime.now()
+        # 从下一分钟开始搜索
+        current = after.replace(second=0, microsecond=0) + timedelta(minutes=1)
+        # 最多搜索2年内的匹配
+        max_search = 366 * 24 * 60
+        for _ in range(max_search):
+            if self.match(current):
+                return current
+            current += timedelta(minutes=1)
+        raise RuntimeError(f"在2年内未找到匹配 '{self._pattern}' 的时间")
+
+    @staticmethod
+    def _parse_field(field: str, min_val: int, max_val: int) -> Set[int]:
+        """解析单个cron字段
+
+        :param field: 字段字符串
+        :param min_val: 最小值
+        :param max_val: 最大值
+        :return: 匹配的值集合
+        :raises ValueError: 字段格式不正确
+        """
+        values: Set[int] = set()
+
+        parts = field.split(",")
+        for part in parts:
+            step: Optional[int] = None
+            if "/" in part:
+                range_part, step_str = part.split("/", 1)
+                step = int(step_str)
+                if step <= 0:
+                    raise ValueError(f"步长必须大于0: {part}")
+            else:
+                range_part = part
+
+            if range_part == "*":
+                start = min_val
+                end = max_val
+            elif "-" in range_part:
+                start_str, end_str = range_part.split("-", 1)
+                start = int(start_str)
+                end = int(end_str)
+            else:
+                val = int(range_part)
+                if step is not None:
+                    start = val
+                    end = max_val
+                else:
+                    if val < min_val or val > max_val:
+                        raise ValueError(f"值 {val} 超出范围 [{min_val}, {max_val}]")
+                    values.add(val)
+                    continue
+
+            if step is None:
+                step = 1
+
+            for v in range(start, end + 1, step):
+                if v < min_val or v > max_val:
+                    raise ValueError(f"值 {v} 超出范围 [{min_val}, {max_val}]")
+                values.add(v)
+
+        return values
+
+    def __str__(self) -> str:
+        """返回cron表达式字符串"""
+        return self._pattern

hutool/cron/cron_util.py

@@ -0,0 +1,115 @@
+"""定时任务工具类"""
+
+import threading
+import time
+from datetime import datetime
+from typing import Callable, List, Optional
+
+from .cron_pattern import CronPattern
+
+
+class _CronTask:
+    """内部Cron任务"""
+
+    def __init__(self, pattern: CronPattern, func: Callable) -> None:
+        self.pattern = pattern
+        self.func = func
+
+
+class _FixedRateTask:
+    """内部固定频率任务"""
+
+    def __init__(self, func: Callable, period_seconds: int) -> None:
+        self.func = func
+        self.period_seconds = period_seconds
+        self.last_run: Optional[float] = None
+
+
+class CronUtil:
+    """定时任务工具类"""
+
+    _tasks: List[_CronTask] = []
+    _fixed_tasks: List[_FixedRateTask] = []
+    _running: bool = False
+    _thread: Optional[threading.Thread] = None
+    _lock = threading.Lock()
+
+    @classmethod
+    def schedule(cls, cron_pattern: str, func: Callable) -> None:
+        """添加定时任务
+
+        :param cron_pattern: cron表达式字符串，格式为 "分 时 日 月 周"
+        :param func: 定时执行的函数
+        """
+        pattern = CronPattern(cron_pattern)
+        with cls._lock:
+            cls._tasks.append(_CronTask(pattern, func))
+
+    @classmethod
+    def schedule_at_fixed_rate(cls, func: Callable, period_seconds: int) -> None:
+        """添加固定频率任务
+
+        :param func: 定时执行的函数
+        :param period_seconds: 执行间隔（秒）
+        """
+        with cls._lock:
+            task = _FixedRateTask(func, period_seconds)
+            cls._fixed_tasks.append(task)
+
+    @classmethod
+    def start(cls) -> None:
+        """启动调度器
+
+        调度器在后台线程中运行，每秒检查一次是否有需要执行的任务。
+        """
+        if cls._running:
+            return
+        cls._running = True
+        cls._thread = threading.Thread(target=cls._run_loop, daemon=True)
+        cls._thread.start()
+
+    @classmethod
+    def stop(cls) -> None:
+        """停止调度器"""
+        cls._running = False
+        if cls._thread is not None:
+            cls._thread.join(timeout=5)
+            cls._thread = None
+
+    @classmethod
+    def restart(cls) -> None:
+        """重启调度器"""
+        cls.stop()
+        cls.start()
+
+    @classmethod
+    def _run_loop(cls) -> None:
+        """调度器主循环"""
+        while cls._running:
+            now = datetime.now()
+            # 检查cron任务
+            with cls._lock:
+                tasks_snapshot = list(cls._tasks)
+                fixed_tasks_snapshot = list(cls._fixed_tasks)
+
+            for task in tasks_snapshot:
+                try:
+                    if task.pattern.match(now):
+                        task.func()
+                except Exception as e:
+                    print(f"[CronUtil] 执行cron任务时发生异常: {e}")
+
+            # 检查固定频率任务
+            for task in fixed_tasks_snapshot:
+                try:
+                    current_time = time.time()
+                    if task.last_run is None or (current_time - task.last_run >= task.period_seconds):
+                        task.func()
+                        task.last_run = current_time
+                except Exception as e:
+                    print(f"[CronUtil] 执行固定频率任务时发生异常: {e}")
+
+            # 休眠到下一个分钟的开始
+            now = datetime.now()
+            seconds_until_next_minute = 60 - now.second
+            time.sleep(max(1, seconds_until_next_minute))

hutool/crypto/__init__.py

@@ -0,0 +1,5 @@
+from .digest_util import DigestUtil
+from .secure_util import SecureUtil
+from .sign_util import SignUtil
+
+__all__ = ["DigestUtil", "SecureUtil", "SignUtil"]

hutool/crypto/digest_util.py

@@ -0,0 +1,167 @@
+import hashlib
+import hmac
+from typing import Union
+
+
+class DigestUtil:
+    """摘要工具类
+
+    提供常用的摘要（哈希）算法封装，包括：
+    - MD5 / SHA-1 / SHA-256 / SHA-384 / SHA-512
+    - HMAC-MD5 / HMAC-SHA1 / HMAC-SHA256
+    所有方法同时支持 str 和 bytes 输入。
+    """
+
+    # ------------------------------------------------------------------ #
+    #  内部辅助
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _to_bytes(data: Union[str, bytes]) -> bytes:
+        """将输入统一转为 bytes"""
+        if isinstance(data, str):
+            return data.encode("utf-8")
+        return data
+
+    @staticmethod
+    def _digest(data: Union[str, bytes], algorithm: str) -> bytes:
+        """通用摘要计算，返回原始 bytes"""
+        return hashlib.new(algorithm, DigestUtil._to_bytes(data)).digest()
+
+    @staticmethod
+    def _hex_digest(data: Union[str, bytes], algorithm: str) -> str:
+        """通用摘要计算，返回十六进制字符串"""
+        return hashlib.new(algorithm, DigestUtil._to_bytes(data)).hexdigest()
+
+    # ------------------------------------------------------------------ #
+    #  MD5
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def md5(data: Union[str, bytes]) -> bytes:
+        """计算MD5摘要，返回原始bytes"""
+        return DigestUtil._digest(data, "md5")
+
+    @staticmethod
+    def md5_hex(data: Union[str, bytes]) -> str:
+        """计算MD5摘要，返回32位十六进制字符串"""
+        return DigestUtil._hex_digest(data, "md5")
+
+    @staticmethod
+    def md5_hex16(data: Union[str, bytes]) -> str:
+        """计算MD5摘要，返回16位十六进制字符串（取32位结果的中间16位）"""
+        return DigestUtil.md5_hex(data)[8:24]
+
+    # ------------------------------------------------------------------ #
+    #  SHA-1
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def sha1(data: Union[str, bytes]) -> bytes:
+        """计算SHA-1摘要，返回原始bytes"""
+        return DigestUtil._digest(data, "sha1")
+
+    @staticmethod
+    def sha1_hex(data: Union[str, bytes]) -> str:
+        """计算SHA-1摘要，返回十六进制字符串"""
+        return DigestUtil._hex_digest(data, "sha1")
+
+    # ------------------------------------------------------------------ #
+    #  SHA-256
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def sha256(data: Union[str, bytes]) -> bytes:
+        """计算SHA-256摘要，返回原始bytes"""
+        return DigestUtil._digest(data, "sha256")
+
+    @staticmethod
+    def sha256_hex(data: Union[str, bytes]) -> str:
+        """计算SHA-256摘要，返回十六进制字符串"""
+        return DigestUtil._hex_digest(data, "sha256")
+
+    # ------------------------------------------------------------------ #
+    #  SHA-384
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def sha384(data: Union[str, bytes]) -> bytes:
+        """计算SHA-384摘要，返回原始bytes"""
+        return DigestUtil._digest(data, "sha384")
+
+    @staticmethod
+    def sha384_hex(data: Union[str, bytes]) -> str:
+        """计算SHA-384摘要，返回十六进制字符串"""
+        return DigestUtil._hex_digest(data, "sha384")
+
+    # ------------------------------------------------------------------ #
+    #  SHA-512
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def sha512(data: Union[str, bytes]) -> bytes:
+        """计算SHA-512摘要，返回原始bytes"""
+        return DigestUtil._digest(data, "sha512")
+
+    @staticmethod
+    def sha512_hex(data: Union[str, bytes]) -> str:
+        """计算SHA-512摘要，返回十六进制字符串"""
+        return DigestUtil._hex_digest(data, "sha512")
+
+    # ------------------------------------------------------------------ #
+    #  HMAC
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _hmac_digest(data: Union[str, bytes], key: Union[str, bytes], algorithm: str) -> bytes:
+        """通用HMAC计算，返回原始bytes"""
+        return hmac.new(
+            DigestUtil._to_bytes(key),
+            DigestUtil._to_bytes(data),
+            algorithm,
+        ).digest()
+
+    @staticmethod
+    def _hmac_hex_digest(data: Union[str, bytes], key: Union[str, bytes], algorithm: str) -> str:
+        """通用HMAC计算，返回十六进制字符串"""
+        return hmac.new(
+            DigestUtil._to_bytes(key),
+            DigestUtil._to_bytes(data),
+            algorithm,
+        ).hexdigest()
+
+    # HMAC-MD5
+
+    @staticmethod
+    def hmac_md5(data: Union[str, bytes], key: Union[str, bytes]) -> bytes:
+        """HMAC-MD5计算，返回原始bytes"""
+        return DigestUtil._hmac_digest(data, key, "md5")
+
+    @staticmethod
+    def hmac_md5_hex(data: Union[str, bytes], key: Union[str, bytes]) -> str:
+        """HMAC-MD5计算，返回十六进制字符串"""
+        return DigestUtil._hmac_hex_digest(data, key, "md5")
+
+    # HMAC-SHA1
+
+    @staticmethod
+    def hmac_sha1(data: Union[str, bytes], key: Union[str, bytes]) -> bytes:
+        """HMAC-SHA1计算，返回原始bytes"""
+        return DigestUtil._hmac_digest(data, key, "sha1")
+
+    @staticmethod
+    def hmac_sha1_hex(data: Union[str, bytes], key: Union[str, bytes]) -> str:
+        """HMAC-SHA1计算，返回十六进制字符串"""
+        return DigestUtil._hmac_hex_digest(data, key, "sha1")
+
+    # HMAC-SHA256
+
+    @staticmethod
+    def hmac_sha256(data: Union[str, bytes], key: Union[str, bytes]) -> bytes:
+        """HMAC-SHA256计算，返回原始bytes"""
+        return DigestUtil._hmac_digest(data, key, "sha256")
+
+    @staticmethod
+    def hmac_sha256_hex(data: Union[str, bytes], key: Union[str, bytes]) -> str:
+        """HMAC-SHA256计算，返回十六进制字符串"""
+        return DigestUtil._hmac_hex_digest(data, key, "sha256")