hutool-python 1.0.0__py3-none-any.whl

hutool/http/http_util.py

@@ -0,0 +1,237 @@
+import re
+from typing import Dict, List, Optional
+from urllib.parse import parse_qs, quote, unquote
+
+from .http_request import HttpRequest
+
+
+class HttpUtil:
+    """HTTP工具类，提供常用的HTTP操作方法"""
+
+    @staticmethod
+    def is_https(url: str) -> bool:
+        """判断URL是否为HTTPS协议
+
+        :param url: 待判断的URL字符串
+        :return: 如果URL以 https:// 开头返回 True，否则返回 False
+        """
+        return url is not None and url.lower().startswith("https://")
+
+    @staticmethod
+    def is_http(url: str) -> bool:
+        """判断URL是否为HTTP协议
+
+        :param url: 待判断的URL字符串
+        :return: 如果URL以 http:// 开头返回 True，否则返回 False
+        """
+        return url is not None and url.lower().startswith("http://")
+
+    @staticmethod
+    def get(
+        url: str,
+        params: Optional[dict] = None,
+        timeout: int = 30000,
+        headers: Optional[dict] = None,
+    ) -> str:
+        """发送GET请求并返回响应体字符串
+
+        :param url: 请求URL
+        :param params: 查询参数
+        :param timeout: 超时时间（毫秒）
+        :param headers: 请求头
+        :return: 响应体字符串
+        """
+        request = HttpRequest.get(url).timeout(timeout)
+        if headers:
+            request.headers(headers)
+        if params:
+            request._params = params
+        response = request.execute()
+        return response.to_str()
+
+    @staticmethod
+    def post(
+        url: str,
+        data=None,
+        json_data=None,
+        timeout: int = 30000,
+        headers: Optional[dict] = None,
+    ) -> str:
+        """发送POST请求并返回响应体字符串
+
+        :param url: 请求URL
+        :param data: 表单数据
+        :param json_data: JSON数据
+        :param timeout: 超时时间（毫秒）
+        :param headers: 请求头
+        :return: 响应体字符串
+        """
+        request = HttpRequest.post(url).timeout(timeout)
+        if headers:
+            request.headers(headers)
+        if data is not None:
+            if isinstance(data, dict):
+                for k, v in data.items():
+                    request.form(k, str(v))
+            else:
+                request.body(str(data))
+        if json_data is not None:
+            request.json(json_data)
+        response = request.execute()
+        return response.to_str()
+
+    @staticmethod
+    def create_get(url: str) -> HttpRequest:
+        """创建GET请求对象
+
+        :param url: 请求URL
+        :return: HttpRequest对象
+        """
+        return HttpRequest.get(url)
+
+    @staticmethod
+    def create_post(url: str) -> HttpRequest:
+        """创建POST请求对象
+
+        :param url: 请求URL
+        :return: HttpRequest对象
+        """
+        return HttpRequest.post(url)
+
+    @staticmethod
+    def download_string(url: str, charset: str = "utf-8") -> str:
+        """下载URL内容为字符串
+
+        :param url: 下载URL
+        :param charset: 字符集，默认utf-8
+        :return: 下载的字符串内容
+        """
+        response = HttpRequest.get(url).charset(charset).execute()
+        return response.to_str()
+
+    @staticmethod
+    def download_file(url: str, dest: str) -> int:
+        """下载URL内容到文件
+
+        :param url: 下载URL
+        :param dest: 目标文件路径
+        :return: 下载的字节数
+        """
+        import httpx
+
+        with httpx.stream("GET", url, follow_redirects=True, timeout=60) as response:
+            response.raise_for_status()
+            total = 0
+            with open(dest, "wb") as f:
+                for chunk in response.iter_bytes():
+                    f.write(chunk)
+                    total += len(chunk)
+            return total
+
+    @staticmethod
+    def download_bytes(url: str) -> bytes:
+        """下载URL内容为字节数组
+
+        :param url: 下载URL
+        :return: 下载的字节数组
+        """
+        response = HttpRequest.get(url).execute()
+        return response.to_bytes()
+
+    @staticmethod
+    def to_params(param_map: dict, charset: str = "utf-8") -> str:
+        """将参数Map转换为URL查询字符串
+
+        :param param_map: 参数字典
+        :param charset: 字符集，默认utf-8
+        :return: URL编码后的查询字符串，如 "key1=value1&key2=value2"
+        """
+        if not param_map:
+            return ""
+        encoded_pairs = []
+        for key, value in param_map.items():
+            encoded_key = quote(str(key), encoding=charset)
+            encoded_value = quote(str(value), encoding=charset) if value is not None else ""
+            encoded_pairs.append(f"{encoded_key}={encoded_value}")
+        return "&".join(encoded_pairs)
+
+    @staticmethod
+    def decode_param_map(params_str: str) -> Dict[str, str]:
+        """将URL查询字符串解码为单值参数字典
+
+        如果某个键对应多个值，只取第一个值。
+
+        :param params_str: URL查询字符串，如 "key1=value1&key2=value2"
+        :return: 参数字典，值为单个字符串
+        """
+        if not params_str:
+            return {}
+        result: Dict[str, str] = {}
+        parsed = parse_qs(params_str, keep_blank_values=True)
+        for key, values in parsed.items():
+            result[key] = values[0] if values else ""
+        return result
+
+    @staticmethod
+    def decode_params(params_str: str) -> Dict[str, List[str]]:
+        """将URL查询字符串解码为多值参数字典
+
+        :param params_str: URL查询字符串，如 "key=value1&key=value2"
+        :return: 参数字典，值为字符串列表
+        """
+        if not params_str:
+            return {}
+        return parse_qs(params_str, keep_blank_values=True)
+
+    @staticmethod
+    def url_with_form(url: str, form: dict) -> str:
+        """将表单参数附加到URL上
+
+        :param url: 基础URL
+        :param form: 表单参数字典
+        :return: 附加参数后的完整URL
+        """
+        if not form:
+            return url
+        params_str = HttpUtil.to_params(form)
+        if "?" in url:
+            if url.endswith("&") or url.endswith("?"):
+                return url + params_str
+            return url + "&" + params_str
+        return url + "?" + params_str
+
+    @staticmethod
+    def get_charset(content_type: str) -> str:
+        """从Content-Type中提取字符集
+
+        :param content_type: Content-Type头值，如 "text/html; charset=utf-8"
+        :return: 字符集名称，如 "utf-8"；如果未指定则返回 "utf-8"
+        """
+        if not content_type:
+            return "utf-8"
+        match = re.search(r"charset\s*=\s*([^\s;]+)", content_type, re.IGNORECASE)
+        if match:
+            return match.group(1).strip().strip('"').strip("'")
+        return "utf-8"
+
+    @staticmethod
+    def encode_url(url_str: str) -> str:
+        """URL编码
+
+        :param url_str: 待编码的URL字符串
+        :return: 编码后的URL字符串
+        """
+        if not url_str:
+            return ""
+        return quote(url_str, safe=":/?#[]@!$&'()*+,;=-._~%")
+
+    @staticmethod
+    def decode_url(url_str: str) -> str:
+        """URL解码
+
+        :param url_str: 待解码的URL字符串
+        :return: 解码后的URL字符串
+        """
+        if not url_str:
+            return ""
+        return unquote(url_str)

hutool/json_util.py

@@ -0,0 +1,251 @@
+import json
+import re
+from typing import Any, List, Optional, Type, Union
+
+
+class JSONUtil:
+    """JSON工具类"""
+
+    @staticmethod
+    def create_obj() -> dict:
+        """创建空JSON对象"""
+        return {}
+
+    @staticmethod
+    def create_array() -> list:
+        """创建空JSON数组"""
+        return []
+
+    # ------------------------------------------------------------------ #
+    #  解析
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def parse_obj(json_str: str) -> dict:
+        """解析JSON字符串为字典"""
+        result = json.loads(json_str)
+        if not isinstance(result, dict):
+            raise ValueError("JSON字符串不是对象类型")
+        return result
+
+    @staticmethod
+    def parse_array(json_str: str) -> list:
+        """解析JSON字符串为列表"""
+        result = json.loads(json_str)
+        if not isinstance(result, list):
+            raise ValueError("JSON字符串不是数组类型")
+        return result
+
+    @staticmethod
+    def parse(json_str: str):
+        """解析JSON字符串，自动返回对应Python类型"""
+        return json.loads(json_str)
+
+    # ------------------------------------------------------------------ #
+    #  序列化
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def to_json_str(obj: Any, indent: Optional[int] = None) -> str:
+        """对象转JSON字符串
+
+        :param obj: 待序列化的对象
+        :param indent: 缩进空格数，None表示不缩进
+        """
+        return json.dumps(obj, ensure_ascii=False, indent=indent)
+
+    @staticmethod
+    def to_json_pretty_str(obj: Any) -> str:
+        """对象转格式化JSON字符串（缩进2空格）"""
+        return json.dumps(obj, ensure_ascii=False, indent=2)
+
+    # ------------------------------------------------------------------ #
+    #  Bean 转换（简易实现，基于类构造器）
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def to_bean(json_str: str, bean_class: Type):
+        """JSON字符串转对象
+
+        将JSON解析为字典后，通过 bean_class(\\*\\*dict) 构造实例。
+        如果 bean_class 提供了 from_dict 类方法，则优先调用。
+        """
+        data = json.loads(json_str)
+        if hasattr(bean_class, "from_dict") and callable(bean_class.from_dict):
+            return bean_class.from_dict(data)
+        if isinstance(data, dict):
+            return bean_class(**data)
+        return bean_class(data)
+
+    @staticmethod
+    def to_bean_list(json_str: str, element_class: Type) -> list:
+        """JSON字符串转对象列表"""
+        data = json.loads(json_str)
+        if not isinstance(data, list):
+            raise ValueError("JSON字符串不是数组类型")
+        if hasattr(element_class, "from_dict") and callable(element_class.from_dict):
+            return [element_class.from_dict(item) for item in data]
+        return [element_class(**item) if isinstance(item, dict) else element_class(item) for item in data]
+
+    @staticmethod
+    def from_bean(obj: Any) -> str:
+        """对象转JSON字符串
+
+        如果对象具有 to_dict 方法则先调用，否则直接序列化。
+        """
+        if hasattr(obj, "to_dict") and callable(obj.to_dict):
+            return json.dumps(obj.to_dict(), ensure_ascii=False)
+        return json.dumps(obj, ensure_ascii=False, default=str)
+
+    # ------------------------------------------------------------------ #
+    #  文件读写
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def read_json(path: str, charset: str = "utf-8"):
+        """读取JSON文件并解析"""
+        with open(path, encoding=charset) as f:
+            return json.load(f)
+
+    @staticmethod
+    def read_json_object(path: str, charset: str = "utf-8") -> dict:
+        """读取JSON文件为字典"""
+        result = JSONUtil.read_json(path, charset)
+        if not isinstance(result, dict):
+            raise ValueError("JSON文件内容不是对象类型")
+        return result
+
+    @staticmethod
+    def read_json_array(path: str, charset: str = "utf-8") -> list:
+        """读取JSON文件为列表"""
+        result = JSONUtil.read_json(path, charset)
+        if not isinstance(result, list):
+            raise ValueError("JSON文件内容不是数组类型")
+        return result
+
+    @staticmethod
+    def write_json(path: str, obj: Any, charset: str = "utf-8", indent: Optional[int] = None) -> None:
+        """写入JSON文件
+
+        :param path: 文件路径
+        :param obj: 待写入对象
+        :param charset: 文件编码
+        :param indent: 缩进空格数，None表示不缩进
+        """
+        with open(path, "w", encoding=charset) as f:
+            json.dump(obj, f, ensure_ascii=False, indent=indent)
+
+    # ------------------------------------------------------------------ #
+    #  校验
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def is_json(str_val: str) -> bool:
+        """是否为有效JSON"""
+        try:
+            json.loads(str_val)
+            return True
+        except (json.JSONDecodeError, TypeError):
+            return False
+
+    @staticmethod
+    def is_json_obj(str_val: str) -> bool:
+        """是否为JSON对象"""
+        try:
+            return isinstance(json.loads(str_val), dict)
+        except (json.JSONDecodeError, TypeError):
+            return False
+
+    @staticmethod
+    def is_json_array(str_val: str) -> bool:
+        """是否为JSON数组"""
+        try:
+            return isinstance(json.loads(str_val), list)
+        except (json.JSONDecodeError, TypeError):
+            return False
+
+    # ------------------------------------------------------------------ #
+    #  格式化 / 压缩
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def format_json(json_str: str, indent: int = 2) -> str:
+        """格式化JSON字符串"""
+        obj = json.loads(json_str)
+        return json.dumps(obj, ensure_ascii=False, indent=indent)
+
+    @staticmethod
+    def compress(json_str: str) -> str:
+        """压缩JSON（去除所有空白）"""
+        obj = json.loads(json_str)
+        return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+
+    # ------------------------------------------------------------------ #
+    #  路径操作（支持 'a.b.c' 和 'a[0].b'）
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _parse_path_keys(path: str) -> List[Union[str, int]]:
+        """将路径字符串解析为键列表
+
+        例如 'a.b[0].c' -> ['a', 'b', 0, 'c']
+        """
+        keys: List[Union[str, int]] = []
+        for part in re.split(r"\.(?![^\[]*\])", path):
+            # 处理 key[index] 形式
+            match = re.match(r"^(\w+)((?:\[\d+\])*)$", part)
+            if match:
+                keys.append(match.group(1))
+                for idx in re.findall(r"\[(\d+)\]", match.group(2)):
+                    keys.append(int(idx))
+            elif part:
+                keys.append(part)
+        return keys
+
+    @staticmethod
+    def get_by_path(json_data: Any, path: str) -> Any:
+        """按路径获取值
+
+        :param json_data: JSON数据（字典或列表）
+        :param path: 路径，如 'a.b.c' 或 'a[0].b'
+        :return: 对应路径的值，路径不存在时返回 None
+        """
+        keys = JSONUtil._parse_path_keys(path)
+        current = json_data
+        for key in keys:
+            if current is None:
+                return None
+            try:
+                current = current[key]
+            except (KeyError, IndexError, TypeError):
+                return None
+        return current
+
+    @staticmethod
+    def put_by_path(json_data: Any, path: str, value: Any) -> None:
+        """按路径设置值
+
+        :param json_data: JSON数据（字典或列表）
+        :param path: 路径，如 'a.b.c' 或 'a[0].b'
+        :param value: 要设置的值
+        """
+        keys = JSONUtil._parse_path_keys(path)
+        if not keys:
+            raise ValueError("路径不能为空")
+        current = json_data
+        for key in keys[:-1]:
+            next_key = keys[keys.index(key) + 1] if keys.index(key) + 1 < len(keys) else None
+            if isinstance(current, dict):
+                if key not in current:
+                    current[key] = {} if isinstance(next_key, str) else []
+                current = current[key]
+            elif isinstance(current, list):
+                while len(current) <= key:
+                    current.append(None)
+                if current[key] is None:
+                    current[key] = {} if isinstance(next_key, str) else []
+                current = current[key]
+            else:
+                raise TypeError(f"无法在路径 '{path}' 上设置值：中间节点类型不支持")
+        last_key = keys[-1]
+        current[last_key] = value

hutool/jwt_util.py

@@ -0,0 +1,57 @@
+"""JWT工具类"""
+
+
+import jwt
+
+
+class JWTUtil:
+    """JWT工具类"""
+
+    @staticmethod
+    def create_token(payload: dict, secret: str, algorithm: str = "HS256") -> str:
+        """创建JWT token
+
+        :param payload: 载荷数据
+        :param secret: 密钥
+        :param algorithm: 加密算法，默认为 'HS256'
+        :return: JWT token字符串
+        """
+        return jwt.encode(payload, secret, algorithm=algorithm)
+
+    @staticmethod
+    def parse_token(token: str, secret: str, algorithm: str = "HS256") -> dict:
+        """解析并验证JWT token
+
+        :param token: JWT token字符串
+        :param secret: 密钥
+        :param algorithm: 加密算法，默认为 'HS256'
+        :return: 解析后的载荷数据
+        :raises jwt.ExpiredSignatureError: token已过期
+        :raises jwt.InvalidTokenError: token无效
+        """
+        return jwt.decode(token, secret, algorithms=[algorithm])
+
+    @staticmethod
+    def verify(token: str, secret: str, algorithm: str = "HS256") -> bool:
+        """验证token是否有效
+
+        :param token: JWT token字符串
+        :param secret: 密钥
+        :param algorithm: 加密算法，默认为 'HS256'
+        :return: token是否有效
+        """
+        try:
+            jwt.decode(token, secret, algorithms=[algorithm])
+            return True
+        except jwt.PyJWTError:
+            return False
+
+    @staticmethod
+    def get_payload(token: str) -> dict:
+        """获取token的payload（不验证签名）
+
+        :param token: JWT token字符串
+        :return: 解析后的载荷数据
+        :raises jwt.DecodeError: token格式无效
+        """
+        return jwt.decode(token, options={"verify_signature": False}, algorithms=["HS256", "HS384", "HS512"])

hutool/setting/__init__.py

@@ -0,0 +1,5 @@
+from .props_util import PropsUtil
+from .setting_util import SettingUtil
+from .yaml_util import YamlUtil
+
+__all__ = ["PropsUtil", "SettingUtil", "YamlUtil"]

hutool/setting/props_util.py

@@ -0,0 +1,79 @@
+"""Properties文件工具类"""
+
+import os
+import re
+from typing import Any
+
+
+class PropsUtil:
+    """Properties文件工具类
+
+    加载和解析标准 .properties 格式的配置文件。
+    """
+
+    @staticmethod
+    def load(path: str, charset: str = "utf-8") -> dict:
+        """加载.properties文件
+
+        支持的格式:
+            - key=value
+            - key: value
+            - key value
+            - # 注释行
+            - ! 注释行
+            - 续行符（行尾 \\）
+
+        :param path: .properties文件路径
+        :param charset: 文件编码，默认为 'utf-8'
+        :return: 解析后的属性字典
+        """
+        path = os.path.abspath(path)
+        props: dict = {}
+        with open(path, encoding=charset) as f:
+            lines = f.readlines()
+
+        continued_line = ""
+        for line in lines:
+            line = line.strip()
+            # 跳过空行和注释
+            if not line or line.startswith("#") or line.startswith("!"):
+                continue
+
+            # 处理续行
+            if continued_line:
+                line = continued_line + line
+                continued_line = ""
+
+            if line.endswith("\\"):
+                continued_line = line[:-1]
+                continue
+
+            # 解析 key=value 或 key: value 或 key value
+            match = re.match(r"^([^=: \t]+)[ \t]*[=: \t](.*)$", line)
+            if match:
+                key = match.group(1).strip()
+                value = match.group(2).strip()
+                props[key] = PropsUtil._unescape(value)
+
+        return props
+
+    @staticmethod
+    def get(props: dict, key: str, default: Any = None) -> Any:
+        """获取属性值
+
+        :param props: 属性字典
+        :param key: 属性键
+        :param default: 默认值
+        :return: 属性值，不存在时返回默认值
+        """
+        return props.get(key, default)
+
+    @staticmethod
+    def _unescape(value: str) -> str:
+        """反转义properties值中的特殊字符
+
+        :param value: 原始值
+        :return: 反转义后的值
+        """
+        result = value.replace("\\n", "\n").replace("\\t", "\t").replace("\\\\", "\\")
+        return result