hutool-python 1.0.0__py3-none-any.whl

hutool/core/util/object_util.py

@@ -0,0 +1,294 @@
+"""
+Python port of Java Hutool's ObjectUtil.
+
+对象工具类，提供对象比较、空值判断、默认值处理、类型判断等常用对象工具方法。
+"""
+
+import copy
+from typing import Any, Optional, Sized
+
+__all__ = [
+    "ObjectUtil",
+]
+
+
+class ObjectUtil:
+    """对象工具类，对应 Java cn.hutool.core.util.ObjectUtil"""
+
+    @staticmethod
+    def equals(obj1: Any, obj2: Any) -> bool:
+        """
+        比较两个对象是否相等，null安全。
+        当两对象均为None时返回True，当其中之一为None时返回False。
+
+        :param obj1: 对象1
+        :param obj2: 对象2
+        :return: 是否相等
+        """
+        if obj1 is obj2:
+            return True
+        if obj1 is None or obj2 is None:
+            return False
+        return obj1 == obj2
+
+    @staticmethod
+    def not_equal(obj1: Any, obj2: Any) -> bool:
+        """
+        比较两个对象是否不等，null安全。
+
+        :param obj1: 对象1
+        :param obj2: 对象2
+        :return: 是否不等
+        """
+        return not ObjectUtil.equals(obj1, obj2)
+
+    @staticmethod
+    def length(obj: Any) -> int:
+        """
+        获取对象长度，支持 str、list、tuple、dict、bytes 等可计算长度的对象。
+        当对象为None时返回0。
+
+        :param obj: 对象
+        :return: 长度
+        """
+        if obj is None:
+            return 0
+        if isinstance(obj, Sized):
+            return len(obj)
+        # 对于不支持len的对象，尝试迭代计数
+        raise TypeError(f"Object of type '{type(obj).__name__}' has no len()")
+
+    @staticmethod
+    def contains(obj: Any, element: Any) -> bool:
+        """
+        对象中是否包含元素。
+        支持的类型：
+        - str: 检查是否包含子串
+        - dict: 检查是否包含key
+        - set: 检查是否包含元素
+        - list/tuple/其他可迭代对象: 检查是否包含元素
+
+        当对象为None时返回False。
+
+        :param obj: 对象
+        :param element: 元素
+        :return: 是否包含
+        """
+        if obj is None:
+            return False
+        if isinstance(obj, str):
+            if element is None:
+                return False
+            return str(element) in obj
+        if isinstance(obj, dict):
+            return element in obj
+        if isinstance(obj, (set, frozenset)):
+            return element in obj
+        if isinstance(obj, (list, tuple)):
+            return element in obj
+        # 兜底：尝试使用 in 运算符
+        try:
+            return element in obj
+        except TypeError:
+            return False
+
+    @staticmethod
+    def is_null(obj: Any) -> bool:
+        """
+        检查对象是否为None。
+
+        :param obj: 对象
+        :return: 是否为None
+        """
+        return obj is None
+
+    @staticmethod
+    def is_not_null(obj: Any) -> bool:
+        """
+        检查对象是否不为None。
+
+        :param obj: 对象
+        :return: 是否不为None
+        """
+        return obj is not None
+
+    @staticmethod
+    def is_empty(obj: Any) -> bool:
+        """
+        检查对象是否为空（None或空容器）。
+        支持 str、list、tuple、dict、set、frozenset、bytes、bytearray。
+        对于非上述类型，如果为None则返回True，否则返回False。
+
+        :param obj: 对象
+        :return: 是否为空
+        """
+        if obj is None:
+            return True
+        if isinstance(obj, (str, bytes, bytearray, list, tuple, dict, set, frozenset)):
+            return len(obj) == 0
+        return False
+
+    @staticmethod
+    def is_not_empty(obj: Any) -> bool:
+        """
+        检查对象是否为非空。
+
+        :param obj: 对象
+        :return: 是否为非空
+        """
+        return not ObjectUtil.is_empty(obj)
+
+    @staticmethod
+    def default_if_null(obj: Any, default_value: Any) -> Any:
+        """
+        如果obj为None，返回默认值，否则返回obj本身。
+
+        :param obj: 对象
+        :param default_value: 默认值
+        :return: 对象或默认值
+        """
+        return default_value if obj is None else obj
+
+    @staticmethod
+    def default_if_empty(obj: Any, default_value: Any) -> Any:
+        """
+        如果obj为空（None或空容器），返回默认值，否则返回obj本身。
+
+        :param obj: 对象
+        :param default_value: 默认值
+        :return: 对象或默认值
+        """
+        return default_value if ObjectUtil.is_empty(obj) else obj
+
+    @staticmethod
+    def default_if_blank(obj: Optional[str], default_value: str) -> str:
+        """
+        如果字符串为空白（None、空串或纯空白），返回默认值。
+
+        :param obj: 字符串对象
+        :param default_value: 默认值
+        :return: 字符串或默认值
+        """
+        if obj is None:
+            return default_value
+        if isinstance(obj, str) and obj.strip() == "":
+            return default_value
+        return obj
+
+    @staticmethod
+    def clone(obj: Any) -> Any:
+        """
+        深拷贝对象。当对象为None时返回None。
+
+        :param obj: 对象
+        :return: 深拷贝后的对象
+        """
+        if obj is None:
+            return None
+        return copy.deepcopy(obj)
+
+    @staticmethod
+    def is_basic_type(obj: Any) -> bool:
+        """
+        是否为基本类型，包括 int、float、complex、bool、str、bytes、None。
+
+        :param obj: 对象
+        :return: 是否为基本类型
+        """
+        if obj is None:
+            return True
+        return isinstance(obj, (int, float, complex, bool, str, bytes))
+
+    @staticmethod
+    def compare(c1: Any, c2: Any) -> int:
+        """
+        比较两个对象的大小。
+        当c1为None时，c2为None返回0，否则返回-1。
+        当c2为None时，返回1。
+        两者均非None时使用比较运算符。
+
+        与Java Comparable接口行为一致：
+        - c1 == c2 -> 0
+        - c1 < c2  -> -1
+        - c1 > c2  -> 1
+
+        :param c1: 对象1
+        :param c2: 对象2
+        :return: 比较结果，0表示相等，-1表示c1小于c2，1表示c1大于c2
+        """
+        if c1 is None:
+            return 0 if c2 is None else -1
+        if c2 is None:
+            return 1
+        if c1 == c2:
+            return 0
+        return -1 if c1 < c2 else 1
+
+    @staticmethod
+    def to_string(obj: Any, default: str = "") -> str:
+        """
+        将对象转为字符串，当对象为None时返回默认值。
+
+        :param obj: 对象
+        :param default: 默认值
+        :return: 字符串
+        """
+        if obj is None:
+            return default
+        return str(obj)
+
+    @staticmethod
+    def has_null(*args: Any) -> bool:
+        """
+        检查参数中是否有None。
+        当没有参数传入时返回False。
+
+        :param args: 参数列表
+        :return: 是否包含None
+        """
+        for arg in args:
+            if arg is None:
+                return True
+        return False
+
+    @staticmethod
+    def has_empty(*args: Any) -> bool:
+        """
+        检查参数中是否有空值（None或空容器）。
+        当没有参数传入时返回False。
+
+        :param args: 参数列表
+        :return: 是否包含空值
+        """
+        for arg in args:
+            if ObjectUtil.is_empty(arg):
+                return True
+        return False
+
+    @staticmethod
+    def is_all_empty(*args: Any) -> bool:
+        """
+        检查是否全部为空。
+        当没有参数传入时返回True。
+
+        :param args: 参数列表
+        :return: 是否全部为空
+        """
+        for arg in args:
+            if ObjectUtil.is_not_empty(arg):
+                return False
+        return True
+
+    @staticmethod
+    def is_all_not_empty(*args: Any) -> bool:
+        """
+        检查是否全部为非空。
+        当没有参数传入时返回True。
+
+        :param args: 参数列表
+        :return: 是否全部为非空
+        """
+        for arg in args:
+            if ObjectUtil.is_empty(arg):
+                return False
+        return True

hutool/core/util/page_util.py

@@ -0,0 +1,61 @@
+"""分页工具类"""
+
+from __future__ import annotations
+
+import math
+from typing import List
+
+
+class PageUtil:
+    """分页工具类"""
+
+    @staticmethod
+    def total_page(total_count: int, page_size: int) -> int:
+        """计算总页数"""
+        if total_count <= 0 or page_size <= 0:
+            return 0
+        return math.ceil(total_count / page_size)
+
+    @staticmethod
+    def rainbow(page_num: int, total_page: int, display_count: int) -> List[int]:
+        """彩虹分页，获取页码列表
+        例如: rainbow(5, 10, 3) -> [3,4,5,6,7]
+        """
+        if page_num < 1 or total_page < 1 or display_count < 1:
+            return []
+
+        half = display_count // 2
+        start = max(1, page_num - half)
+        end = min(total_page, start + display_count - 1)
+
+        # 修正起始位置
+        if end - start + 1 < display_count:
+            start = max(1, end - display_count + 1)
+
+        return list(range(start, end + 1))
+
+    @staticmethod
+    def to_page(start_index: int, page_size: int) -> int:
+        """起始索引转页码（从1开始）"""
+        if page_size <= 0:
+            return 1
+        return start_index // page_size + 1
+
+    @staticmethod
+    def first_page() -> int:
+        """第一页页码，始终返回1"""
+        return 1
+
+    @staticmethod
+    def get_start(page: int, limit: int) -> int:
+        """根据页码和每页条数计算起始行号（从0开始）"""
+        if page < 1 or limit < 1:
+            return 0
+        return (page - 1) * limit
+
+    @staticmethod
+    def to_start_index(page_num: int, page_size: int) -> int:
+        """页码转起始索引"""
+        if page_num < 1 or page_size < 1:
+            return 0
+        return (page_num - 1) * page_size

hutool/core/util/phone_util.py

@@ -0,0 +1,140 @@
+import re
+
+
+class PhoneUtil:
+    """手机号工具类"""
+
+    # 中国大陆手机号正则
+    _MOBILE_PATTERN = re.compile(r"^1[3-9]\d{9}$")
+
+    # 香港手机号正则（8位，5/6/9开头）
+    _MOBILE_HK_PATTERN = re.compile(r"^[569]\d{7}$")
+
+    # 台湾手机号正则（09开头10位）
+    _MOBILE_TW_PATTERN = re.compile(r"^09\d{8}$")
+
+    # 澳门手机号正则（6开头8位）
+    _MOBILE_MO_PATTERN = re.compile(r"^6\d{7}$")
+
+    # 座机正则（区号-号码，区号3-4位，号码7-8位）
+    _FIXED_PHONE_PATTERN = re.compile(r"^0\d{2,3}-?\d{7,8}$")
+
+    @staticmethod
+    def is_mobile(phone: str) -> bool:
+        """是否为中国大陆手机号
+
+        :param phone: 手机号字符串
+        :return: 是否合法
+        """
+        if not phone:
+            return False
+        return bool(PhoneUtil._MOBILE_PATTERN.match(phone.strip()))
+
+    @staticmethod
+    def is_mobile_hk(phone: str) -> bool:
+        """是否为香港手机号（8位，5/6/9开头）
+
+        :param phone: 手机号字符串
+        :return: 是否合法
+        """
+        if not phone:
+            return False
+        return bool(PhoneUtil._MOBILE_HK_PATTERN.match(phone.strip()))
+
+    @staticmethod
+    def is_mobile_tw(phone: str) -> bool:
+        """是否为台湾手机号（09开头10位）
+
+        :param phone: 手机号字符串
+        :return: 是否合法
+        """
+        if not phone:
+            return False
+        return bool(PhoneUtil._MOBILE_TW_PATTERN.match(phone.strip()))
+
+    @staticmethod
+    def is_mobile_mo(phone: str) -> bool:
+        """是否为澳门手机号（6开头8位）
+
+        :param phone: 手机号字符串
+        :return: 是否合法
+        """
+        if not phone:
+            return False
+        return bool(PhoneUtil._MOBILE_MO_PATTERN.match(phone.strip()))
+
+    @staticmethod
+    def is_phone(phone: str) -> bool:
+        """是否为电话号码（手机或座机）
+
+        :param phone: 电话号码字符串
+        :return: 是否合法
+        """
+        if not phone:
+            return False
+        phone = phone.strip()
+        return PhoneUtil.is_mobile(phone) or bool(PhoneUtil._FIXED_PHONE_PATTERN.match(phone))
+
+    @staticmethod
+    def hide_before(phone: str) -> str:
+        """隐藏前3位，如 138****1234
+
+        :param phone: 手机号字符串
+        :return: 脱敏后的手机号
+        """
+        if not phone:
+            return ""
+        phone = phone.strip()
+        if len(phone) < 7:
+            return phone
+        return phone[:3] + "****" + phone[7:]
+
+    @staticmethod
+    def hide_between(phone: str) -> str:
+        """隐藏中间4位，如 138****1234
+
+        :param phone: 手机号字符串
+        :return: 脱敏后的手机号
+        """
+        if not phone:
+            return ""
+        phone = phone.strip()
+        if len(phone) < 11:
+            return phone
+        return phone[:3] + "****" + phone[7:]
+
+    @staticmethod
+    def hide_after(phone: str) -> str:
+        """隐藏后4位
+
+        :param phone: 手机号字符串
+        :return: 脱敏后的手机号
+        """
+        if not phone:
+            return ""
+        phone = phone.strip()
+        if len(phone) < 4:
+            return phone
+        return phone[:-4] + "****"
+
+    @staticmethod
+    def sub_before(phone: str) -> str:
+        """获取手机号前3位
+
+        :param phone: 手机号字符串
+        :return: 前3位
+        """
+        if not phone:
+            return ""
+        return phone.strip()[:3]
+
+    @staticmethod
+    def sub_after(phone: str) -> str:
+        """获取手机号后4位
+
+        :param phone: 手机号字符串
+        :return: 后4位
+        """
+        if not phone:
+            return ""
+        return phone.strip()[-4:]

hutool/core/util/random_util.py

@@ -0,0 +1,112 @@
+import random
+import secrets
+import string
+import sys
+from datetime import datetime, timedelta
+from typing import List, Optional, Sequence, TypeVar
+
+T = TypeVar("T")
+
+
+class RandomUtil:
+    """随机工具类，对应 Java cn.hutool.core.util.RandomUtil
+
+    默认使用线程安全的 secrets 模块生成密码学安全随机数，
+    部分方法（如 random_color、random_date）使用 random 模块。
+    """
+
+    @staticmethod
+    def random_int(min_include: int = 0, max_exclude: int = sys.maxsize) -> int:
+        """生成随机int，范围[min, max)"""
+        if min_include >= max_exclude:
+            raise ValueError(f"min_include({min_include}) 必须小于 max_exclude({max_exclude})")
+        return secrets.randbelow(max_exclude - min_include) + min_include
+
+    @staticmethod
+    def random_long(min_include: int = 0, max_exclude: int = 2**63) -> int:
+        """生成随机long"""
+        if min_include >= max_exclude:
+            raise ValueError(f"min_include({min_include}) 必须小于 max_exclude({max_exclude})")
+        return secrets.randbelow(max_exclude - min_include) + min_include
+
+    @staticmethod
+    def random_float(min_include: float = 0.0, max_exclude: float = 1.0) -> float:
+        """生成随机float"""
+        if min_include >= max_exclude:
+            raise ValueError(f"min_include({min_include}) 必须小于 max_exclude({max_exclude})")
+        # 使用 secrets 生成 [0, 1) 的安全随机数，再映射到目标范围
+        ratio = secrets.randbelow(1 << 32) / (1 << 32)
+        return min_include + ratio * (max_exclude - min_include)
+
+    @staticmethod
+    def random_double(min_include: float = 0.0, max_exclude: float = 1.0) -> float:
+        """生成随机double（别名）"""
+        return RandomUtil.random_float(min_include, max_exclude)
+
+    @staticmethod
+    def random_boolean() -> bool:
+        """生成随机布尔值"""
+        return bool(secrets.randbelow(2))
+
+    @staticmethod
+    def random_bytes(length: int) -> bytes:
+        """生成随机字节数组"""
+        if length < 0:
+            raise ValueError(f"length({length}) 不能为负数")
+        return secrets.token_bytes(length)
+
+    @staticmethod
+    def random_ele(sequence: Sequence[T]) -> T:
+        """从序列中随机选取一个元素"""
+        if not sequence:
+            raise ValueError("序列不能为空")
+        return random.choice(sequence)
+
+    @staticmethod
+    def random_eles(sequence: Sequence[T], count: int) -> List[T]:
+        """从序列中随机选取count个元素（不重复）"""
+        if not sequence:
+            raise ValueError("序列不能为空")
+        if count < 0:
+            raise ValueError(f"count({count}) 不能为负数")
+        if count > len(sequence):
+            raise ValueError(f"count({count}) 不能大于序列长度({len(sequence)})")
+        return random.sample(list(sequence), count)
+
+    @staticmethod
+    def random_string(length: int, base: Optional[str] = None) -> str:
+        """生成随机字符串，默认包含字母和数字"""
+        if length < 0:
+            raise ValueError(f"length({length}) 不能为负数")
+        if base is None:
+            base = string.ascii_letters + string.digits
+        return "".join(secrets.choice(base) for _ in range(length))
+
+    @staticmethod
+    def random_string_upper(length: int) -> str:
+        """生成随机大写字母字符串"""
+        return RandomUtil.random_string(length, string.ascii_uppercase)
+
+    @staticmethod
+    def random_string_lower(length: int) -> str:
+        """生成随机小写字母字符串"""
+        return RandomUtil.random_string(length, string.ascii_lowercase)
+
+    @staticmethod
+    def random_numbers(length: int) -> str:
+        """生成随机数字字符串"""
+        return RandomUtil.random_string(length, string.digits)
+
+    @staticmethod
+    def random_color() -> str:
+        """生成随机十六进制颜色，如 #A1B2C3"""
+        return f"#{random.randint(0, 0xFFFFFF):06X}"
+
+    @staticmethod
+    def random_date(start: datetime, end: datetime) -> datetime:
+        """在日期范围内生成随机日期"""
+        if start >= end:
+            raise ValueError("开始日期必须早于结束日期")
+        delta = end - start
+        random_seconds = random.uniform(0, delta.total_seconds())
+        return start + timedelta(seconds=random_seconds)