hutool-python 1.0.0__py3-none-any.whl

hutool/captcha/captcha_util.py

@@ -0,0 +1,215 @@
+import io
+import random
+import string
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+class LineCaptcha:
+    """线段干扰验证码。
+
+    在图片上绘制随机字符，并添加随机干扰线段以增加识别难度。
+    """
+
+    def __init__(self, width: int = 100, height: int = 35, code_count: int = 4, line_count: int = 5) -> None:
+        """初始化线段干扰验证码。
+
+        :param width: 图片宽度，默认100像素
+        :param height: 图片高度，默认35像素
+        :param code_count: 验证码字符个数，默认4
+        :param line_count: 干扰线条数，默认5
+        """
+        self._width: int = width
+        self._height: int = height
+        self._code_count: int = code_count
+        self._line_count: int = line_count
+        self._code: str = ""
+
+    def create_code(self) -> str:
+        """生成随机验证码字符串并绘制验证码图片。
+
+        :return: 生成的验证码字符串
+        """
+        chars = string.ascii_letters + string.digits
+        self._code = "".join(random.choices(chars, k=self._code_count))
+        return self._code
+
+    def verify(self, code: str) -> bool:
+        """校验输入的验证码是否正确（不区分大小写）。
+
+        :param code: 用户输入的验证码
+        :return: 验证成功返回True，否则返回False
+        """
+        if not self._code or not code:
+            return False
+        return self._code.lower() == code.lower()
+
+    def get_image_bytes(self, fmt: str = "png") -> bytes:
+        """生成验证码图片的字节数据。
+
+        :param fmt: 图片格式，默认"png"
+        :return: 图片的字节数据
+        """
+        if not self._code:
+            self.create_code()
+
+        img = Image.new("RGB", (self._width, self._height), (255, 255, 255))
+        draw = ImageDraw.Draw(img)
+
+        # 尝试加载字体，失败则使用默认字体
+        try:
+            font = ImageFont.truetype("arial.ttf", size=int(self._height * 0.6))
+        except OSError:
+            font = ImageFont.load_default()
+
+        # 绘制验证码字符
+        char_width = self._width // (self._code_count + 1)
+        for i, ch in enumerate(self._code):
+            x = char_width * i + random.randint(2, 8)
+            y = random.randint(0, max(1, self._height // 4))
+            color = (random.randint(0, 150), random.randint(0, 150), random.randint(0, 150))
+            draw.text((x, y), ch, fill=color, font=font)
+
+        # 绘制干扰线
+        for _ in range(self._line_count):
+            x1 = random.randint(0, self._width)
+            y1 = random.randint(0, self._height)
+            x2 = random.randint(0, self._width)
+            y2 = random.randint(0, self._height)
+            color = (random.randint(100, 200), random.randint(100, 200), random.randint(100, 200))
+            draw.line([(x1, y1), (x2, y2)], fill=color, width=1)
+
+        buf = io.BytesIO()
+        img.save(buf, format=fmt)
+        return buf.getvalue()
+
+
+class ArithmeticCaptcha:
+    """算术验证码。
+
+    生成简单的数学表达式（如"3+5=?"），用户需计算结果。
+    """
+
+    def __init__(self, width: int = 100, height: int = 35) -> None:
+        """初始化算术验证码。
+
+        :param width: 图片宽度，默认100像素
+        :param height: 图片高度，默认35像素
+        """
+        self._width: int = width
+        self._height: int = height
+        self._expression: str = ""
+        self._result: str = ""
+
+    def create_code(self) -> str:
+        """生成随机算术表达式，并计算结果。
+
+        :return: 生成的算术表达式（如"3+5=?"）
+        """
+        a = random.randint(1, 20)
+        b = random.randint(1, 20)
+        op = random.choice(["+", "-", "*"])
+
+        if op == "+":
+            result = a + b
+        elif op == "-":
+            # 确保结果非负
+            if a < b:
+                a, b = b, a
+                result = a - b
+            else:
+                result = a - b
+        else:
+            result = a * b
+
+        self._expression = f"{a}{op}{b}=?"
+        self._result = str(result)
+        return self._expression
+
+    def get_result(self) -> str:
+        """获取算术表达式的正确结果。
+
+        :return: 表达式结果字符串
+        """
+        return self._result
+
+    def verify(self, code: str) -> bool:
+        """校验用户输入的答案是否正确。
+
+        :param code: 用户输入的答案
+        :return: 答案正确返回True，否则返回False
+        """
+        if not self._result or not code:
+            return False
+        return self._result == code.strip()
+
+    def get_image_bytes(self, fmt: str = "png") -> bytes:
+        """生成验证码图片的字节数据。
+
+        :param fmt: 图片格式，默认"png"
+        :return: 图片的字节数据
+        """
+        if not self._expression:
+            self.create_code()
+
+        img = Image.new("RGB", (self._width, self._height), (255, 255, 255))
+        draw = ImageDraw.Draw(img)
+
+        try:
+            font = ImageFont.truetype("arial.ttf", size=int(self._height * 0.5))
+        except OSError:
+            font = ImageFont.load_default()
+
+        # 计算文字居中位置
+        bbox = draw.textbbox((0, 0), self._expression, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_height = bbox[3] - bbox[1]
+        x = (self._width - text_width) // 2
+        y = (self._height - text_height) // 2
+
+        color = (random.randint(0, 100), random.randint(0, 100), random.randint(0, 100))
+        draw.text((x, y), self._expression, fill=color, font=font)
+
+        # 绘制干扰线
+        for _ in range(3):
+            x1 = random.randint(0, self._width)
+            y1 = random.randint(0, self._height)
+            x2 = random.randint(0, self._width)
+            y2 = random.randint(0, self._height)
+            line_color = (random.randint(100, 200), random.randint(100, 200), random.randint(100, 200))
+            draw.line([(x1, y1), (x2, y2)], fill=line_color, width=1)
+
+        buf = io.BytesIO()
+        img.save(buf, format=fmt)
+        return buf.getvalue()
+
+
+class CaptchaUtil:
+    """验证码工厂类。
+
+    提供各种验证码的便捷创建方法。
+    """
+
+    @staticmethod
+    def create_line_captcha(
+        width: int = 100, height: int = 35, code_count: int = 4, line_count: int = 5
+    ) -> LineCaptcha:
+        """创建线段干扰验证码。
+
+        :param width: 图片宽度，默认100像素
+        :param height: 图片高度，默认35像素
+        :param code_count: 验证码字符个数，默认4
+        :param line_count: 干扰线条数，默认5
+        :return: LineCaptcha实例
+        """
+        return LineCaptcha(width, height, code_count, line_count)
+
+    @staticmethod
+    def create_arithmetic_captcha(width: int = 100, height: int = 35) -> ArithmeticCaptcha:
+        """创建算术验证码。
+
+        :param width: 图片宽度，默认100像素
+        :param height: 图片高度，默认35像素
+        :return: ArithmeticCaptcha实例
+        """
+        return ArithmeticCaptcha(width, height)

hutool/core/__init__.py

@@ -0,0 +1,23 @@
+"""PyHutool Core 核心模块。"""
+
+from .exceptions import (
+    IllegalArgumentException,
+    IllegalStateException,
+    IORuntimeException,
+    NotInitedException,
+    NullPointerException,
+    StatefulException,
+    UnsupportedOperationException,
+    UtilException,
+)
+
+__all__ = [
+    "IORuntimeException",
+    "IllegalArgumentException",
+    "IllegalStateException",
+    "NotInitedException",
+    "NullPointerException",
+    "StatefulException",
+    "UnsupportedOperationException",
+    "UtilException",
+]

hutool/core/_base.py

@@ -0,0 +1,61 @@
+"""基础类和常量，对应 Java cn.hutool.core.lang."""
+
+from typing import Final
+
+
+class DefaultParam:
+    """默认参数标记类，用于区分用户传入的 None 和未传参。"""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self):
+        return "<DEFAULT>"
+
+
+# 通用常量
+EMPTY: Final[str] = ""
+SPACE: Final[str] = " "
+TAB: Final[str] = "\t"
+DOT: Final[str] = "."
+SLASH: Final[str] = "/"
+BACKSLASH: Final[str] = "\\"
+CR: Final[str] = "\r"
+LF: Final[str] = "\n"
+CRLF: Final[str] = "\r\n"
+COMMA: Final[str] = ","
+COLON: Final[str] = ":"
+SEMICOLON: Final[str] = ";"
+DASH: Final[str] = "-"
+UNDERLINE: Final[str] = "_"
+AT: Final[str] = "@"
+HASH: Final[str] = "#"
+AMP: Final[str] = "&"
+PIPE: Final[str] = "|"
+TILDE: Final[str] = "~"
+PERCENT: Final[str] = "%"
+DOLLAR: Final[str] = "$"
+QUESTION: Final[str] = "?"
+EXCLAMATION: Final[str] = "!"
+STAR: Final[str] = "*"
+PLUS: Final[str] = "+"
+MINUS: Final[str] = "-"
+EQ: Final[str] = "="
+LT: Final[str] = "<"
+GT: Final[str] = ">"
+NOT: Final[str] = "^"
+
+# 常用编码
+UTF_8: Final[str] = "UTF-8"
+GBK: Final[str] = "GBK"
+ISO_8859_1: Final[str] = "ISO-8859-1"
+US_ASCII: Final[str] = "US-ASCII"
+
+# 日期格式
+NORM_DATETIME_PATTERN: Final[str] = "yyyy-MM-dd HH:mm:ss"
+NORM_DATE_PATTERN: Final[str] = "yyyy-MM-dd"
+NORM_TIME_PATTERN: Final[str] = "HH:mm:ss"

hutool/core/bean.py

@@ -0,0 +1,214 @@
+"""Bean工具类，提供对象与字典之间的转换、属性复制等功能"""
+
+from typing import Any, List, Optional, Type, TypeVar
+
+T = TypeVar("T")
+
+__all__ = ("BeanUtil",)
+
+
+class BeanUtil:
+    """Bean工具类，提供对象属性的读写、对象与字典互转、属性复制等功能"""
+
+    @staticmethod
+    def get_field_value(bean: Any, field_name: str) -> Any:
+        """
+        获取对象字段值
+
+        :param bean: 对象实例
+        :param field_name: 字段名
+        :return: 字段值，若字段不存在返回None
+        """
+        if bean is None:
+            return None
+        try:
+            return getattr(bean, field_name, None)
+        except Exception:
+            return None
+
+    @staticmethod
+    def set_field_value(bean: Any, field_name: str, value: Any) -> None:
+        """
+        设置对象字段值
+
+        :param bean: 对象实例
+        :param field_name: 字段名
+        :param value: 要设置的值
+        """
+        if bean is None:
+            raise ValueError("Bean不能为None")
+        setattr(bean, field_name, value)
+
+    @staticmethod
+    def map_to_bean(map_data: dict, bean_class: Type[T], ignore_error: bool = False) -> T:
+        """
+        字典转对象
+
+        :param map_data: 字典数据
+        :param bean_class: 目标Bean类型
+        :param ignore_error: 是否忽略错误，若为True则跳过无法设置的字段
+        :return: Bean对象
+        """
+        if map_data is None:
+            raise ValueError("map_data不能为None")
+        if bean_class is None:
+            raise ValueError("bean_class不能为None")
+
+        try:
+            bean = bean_class()
+        except Exception as e:
+            raise TypeError(f"无法实例化{bean_class.__name__}: {e}") from e
+
+        BeanUtil.fill_bean_with_map(map_data, bean, ignore_error)
+        return bean
+
+    @staticmethod
+    def bean_to_map(bean: Any) -> dict:
+        """
+        对象转字典，将对象中所有非下划线开头的公共属性转为字典
+
+        :param bean: Bean对象
+        :return: 字典
+        """
+        if bean is None:
+            raise ValueError("bean不能为None")
+
+        result = {}
+        # 使用__dict__获取实例属性
+        if hasattr(bean, "__dict__"):
+            for key, value in bean.__dict__.items():
+                if not key.startswith("_"):
+                    result[key] = value
+
+        # 获取类级别的公共属性（非下划线开头、非方法、非内置类型）
+        for key in dir(bean):
+            if key.startswith("_"):
+                continue
+            if key in result:
+                continue
+            try:
+                value = getattr(bean, key)
+                if not callable(value):
+                    result[key] = value
+            except Exception:
+                continue
+
+        return result
+
+    @staticmethod
+    def copy_properties(source: Any, target: Any, *ignore_properties: str) -> None:
+        """
+        复制属性，将源对象的属性值复制到目标对象
+
+        :param source: 源对象
+        :param target: 目标对象
+        :param ignore_properties: 忽略的属性名列表
+        """
+        if source is None:
+            raise ValueError("source不能为None")
+        if target is None:
+            raise ValueError("target不能为None")
+
+        ignore_set = set(ignore_properties)
+
+        if hasattr(source, "__dict__"):
+            for key, value in source.__dict__.items():
+                if key.startswith("_") or key in ignore_set:
+                    continue
+                if hasattr(target, key) or not hasattr(target, "__dict__"):
+                    try:
+                        setattr(target, key, value)
+                    except (AttributeError, TypeError):
+                        pass
+
+    @staticmethod
+    def to_bean(source: Any, clazz: Type[T], copy_options: Optional[dict] = None) -> T:
+        """
+        转为指定类型对象
+
+        :param source: 源对象或字典
+        :param clazz: 目标类型
+        :param copy_options: 复制选项字典，可包含ignore_properties列表
+        :return: 转换后的对象
+        """
+        if source is None:
+            return None
+        if clazz is None:
+            raise ValueError("clazz不能为None")
+
+        if isinstance(source, dict):
+            ignore_error = (copy_options or {}).get("ignore_error", False)
+            return BeanUtil.map_to_bean(source, clazz, ignore_error=ignore_error)
+
+        try:
+            target = clazz()
+        except Exception as e:
+            raise TypeError(f"无法实例化{clazz.__name__}: {e}") from e
+
+        ignore_properties = (copy_options or {}).get("ignore_properties", ())
+        BeanUtil.copy_properties(source, target, *ignore_properties)
+        return target
+
+    @staticmethod
+    def to_bean_list(source_list: list, clazz: Type[T]) -> List[T]:
+        """
+        转为对象列表
+
+        :param source_list: 源列表（字典列表或对象列表）
+        :param clazz: 目标类型
+        :return: 转换后的对象列表
+        """
+        if source_list is None:
+            return []
+        return [BeanUtil.to_bean(item, clazz) for item in source_list]
+
+    @staticmethod
+    def is_readable_bean(obj: Any) -> bool:
+        """
+        是否为可读的Bean，即拥有至少一个非下划线开头的公共属性
+
+        :param obj: 待检测对象
+        :return: 是否为可读Bean
+        """
+        if obj is None:
+            return False
+
+        # 检查__dict__中是否有非下划线开头的属性
+        if hasattr(obj, "__dict__"):
+            for key in obj.__dict__:
+                if not key.startswith("_"):
+                    return True
+
+        # 检查类级别的公共属性
+        for key in dir(obj):
+            if key.startswith("_"):
+                continue
+            try:
+                value = getattr(obj, key)
+                if not callable(value):
+                    return True
+            except Exception:
+                continue
+
+        return False
+
+    @staticmethod
+    def fill_bean_with_map(map_data: dict, bean: Any, ignore_error: bool = False) -> None:
+        """
+        用字典填充Bean，将字典中的键值对设置到Bean的对应属性上
+
+        :param map_data: 字典数据
+        :param bean: Bean对象
+        :param ignore_error: 是否忽略设置错误
+        """
+        if map_data is None:
+            raise ValueError("map_data不能为None")
+        if bean is None:
+            raise ValueError("bean不能为None")
+
+        for key, value in map_data.items():
+            try:
+                setattr(bean, key, value)
+            except Exception as e:
+                if not ignore_error:
+                    raise ValueError(f"设置字段{key}失败: {e}") from e

hutool/core/codec.py

@@ -0,0 +1,111 @@
+"""编解码工具类，提供Base64、Base32等编解码功能"""
+
+import base64
+
+__all__ = ("Base32", "Base64")
+
+
+class Base64:
+    """Base64编解码工具类"""
+
+    @staticmethod
+    def encode(data: bytes) -> str:
+        """
+        编码字节数据为Base64字符串
+
+        :param data: 待编码的字节数据
+        :return: Base64编码字符串
+        """
+        if data is None:
+            raise ValueError("待编码数据不能为None")
+        return base64.b64encode(data).decode("ascii")
+
+    @staticmethod
+    def encode_str(data: str, charset: str = "utf-8") -> str:
+        """
+        编码字符串为Base64字符串
+
+        :param data: 待编码的字符串
+        :param charset: 字符编码，默认utf-8
+        :return: Base64编码字符串
+        """
+        if data is None:
+            raise ValueError("待编码字符串不能为None")
+        return base64.b64encode(data.encode(charset)).decode("ascii")
+
+    @staticmethod
+    def decode(base64_str: str) -> bytes:
+        """
+        解码Base64字符串为字节数据
+
+        :param base64_str: Base64编码字符串
+        :return: 解码后的字节数据
+        """
+        if base64_str is None:
+            raise ValueError("Base64字符串不能为None")
+        return base64.b64decode(base64_str)
+
+    @staticmethod
+    def decode_str(base64_str: str, charset: str = "utf-8") -> str:
+        """
+        解码Base64字符串为字符串
+
+        :param base64_str: Base64编码字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 解码后的字符串
+        """
+        if base64_str is None:
+            raise ValueError("Base64字符串不能为None")
+        return base64.b64decode(base64_str).decode(charset)
+
+    @staticmethod
+    def encode_url_safe(data: bytes) -> str:
+        """
+        编码为URL安全的Base64字符串（使用-和_代替+和/）
+
+        :param data: 待编码的字节数据
+        :return: URL安全的Base64编码字符串
+        """
+        if data is None:
+            raise ValueError("待编码数据不能为None")
+        return base64.urlsafe_b64encode(data).decode("ascii")
+
+    @staticmethod
+    def decode_url_safe(base64_str: str) -> bytes:
+        """
+        解码URL安全的Base64字符串
+
+        :param base64_str: URL安全的Base64编码字符串
+        :return: 解码后的字节数据
+        """
+        if base64_str is None:
+            raise ValueError("Base64字符串不能为None")
+        return base64.urlsafe_b64decode(base64_str)
+
+
+class Base32:
+    """Base32编解码工具类"""
+
+    @staticmethod
+    def encode(data: bytes) -> str:
+        """
+        编码字节数据为Base32字符串
+
+        :param data: 待编码的字节数据
+        :return: Base32编码字符串
+        """
+        if data is None:
+            raise ValueError("待编码数据不能为None")
+        return base64.b32encode(data).decode("ascii")
+
+    @staticmethod
+    def decode(base32_str: str) -> bytes:
+        """
+        解码Base32字符串为字节数据
+
+        :param base32_str: Base32编码字符串
+        :return: 解码后的字节数据
+        """
+        if base32_str is None:
+            raise ValueError("Base32字符串不能为None")
+        return base64.b32decode(base32_str)