hutool-python 1.0.0__py3-none-any.whl

hutool/core/util/system_util.py

@@ -0,0 +1,62 @@
+"""系统属性工具类"""
+
+from __future__ import annotations
+
+import os
+import platform
+import tempfile
+from typing import Optional
+
+
+class SystemUtil:
+    """系统属性工具类，对应 Java SystemPropsUtil"""
+
+    @staticmethod
+    def get(name: str, default: Optional[str] = None) -> Optional[str]:
+        """获取系统环境变量"""
+        return os.environ.get(name, default)
+
+    @staticmethod
+    def get_all() -> dict:
+        """获取所有环境变量"""
+        return dict(os.environ)
+
+    @staticmethod
+    def get_os_name() -> str:
+        """获取操作系统名称"""
+        return platform.system()
+
+    @staticmethod
+    def get_os_arch() -> str:
+        """获取操作系统架构"""
+        return platform.machine()
+
+    @staticmethod
+    def get_user_dir() -> str:
+        """获取用户当前工作目录"""
+        return os.getcwd()
+
+    @staticmethod
+    def get_user_home() -> str:
+        """获取用户主目录"""
+        return os.path.expanduser("~")
+
+    @staticmethod
+    def get_tmp_dir() -> str:
+        """获取临时目录"""
+        return tempfile.gettempdir()
+
+    @staticmethod
+    def get_file_separator() -> str:
+        """获取文件分隔符"""
+        return os.sep
+
+    @staticmethod
+    def get_line_separator() -> str:
+        """获取行分隔符"""
+        return os.linesep
+
+    @staticmethod
+    def is_windows() -> bool:
+        """是否Windows系统"""
+        return platform.system().lower() == "windows"

hutool/core/util/url_util.py

@@ -0,0 +1,232 @@
+import re
+from typing import Dict, List
+from urllib.parse import parse_qs, parse_qsl, quote, unquote, urlencode, urlparse
+
+
+class URLUtil:
+    """URL工具类，对应 Java cn.hutool.core.util.URLUtil"""
+
+    @staticmethod
+    def normalize(url_str: str) -> str:
+        """标准化URL，补齐协议头
+
+        如果URL缺少协议头（http:// 或 https://），自动补充 http://。
+
+        :param url_str: 原始URL字符串
+        :return: 标准化后的URL字符串
+        """
+        if not url_str:
+            return url_str
+        url_str = url_str.strip()
+        if not re.match(r"^[a-zA-Z]+://", url_str):
+            url_str = "http://" + url_str
+        return url_str
+
+    @staticmethod
+    def encode(url_str: str, charset: str = "utf-8") -> str:
+        """URL编码
+
+        对整个URL字符串进行编码。
+
+        :param url_str: 待编码的URL字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 编码后的URL字符串
+        """
+        if not url_str:
+            return url_str
+        return quote(url_str, encoding=charset, safe=":/?#[]@!$&'()*+,;=-._~%")
+
+    @staticmethod
+    def decode(url_str: str, charset: str = "utf-8") -> str:
+        """URL解码
+
+        对URL编码的字符串进行解码。
+
+        :param url_str: 待解码的URL字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 解码后的URL字符串
+        """
+        if not url_str:
+            return url_str
+        return unquote(url_str, encoding=charset)
+
+    @staticmethod
+    def encode_params(params_str: str, charset: str = "utf-8") -> str:
+        """编码URL参数部分
+
+        对URL查询参数字符串中的值部分进行编码。
+
+        :param params_str: 参数字符串，如 "key1=value1&key2=value2"
+        :param charset: 字符编码，默认utf-8
+        :return: 编码后的参数字符串
+        """
+        if not params_str:
+            return params_str
+        pairs = parse_qsl(params_str, keep_blank_values=True)
+        encoded_pairs = []
+        for key, value in pairs:
+            encoded_key = quote(key, encoding=charset, safe="")
+            encoded_value = quote(value, encoding=charset, safe="")
+            encoded_pairs.append(f"{encoded_key}={encoded_value}")
+        return "&".join(encoded_pairs)
+
+    @staticmethod
+    def get_path(url_str: str) -> str:
+        """获取URL的路径部分
+
+        :param url_str: URL字符串
+        :return: URL的路径部分，解析失败返回空字符串
+        """
+        if not url_str:
+            return ""
+        try:
+            parsed = urlparse(url_str)
+            return parsed.path
+        except Exception:
+            return ""
+
+    @staticmethod
+    def get_host(url_str: str) -> str:
+        """获取URL的主机部分
+
+        :param url_str: URL字符串
+        :return: URL的主机名，解析失败返回空字符串
+        """
+        if not url_str:
+            return ""
+        try:
+            parsed = urlparse(url_str)
+            return parsed.hostname or ""
+        except Exception:
+            return ""
+
+    @staticmethod
+    def get_port(url_str: str) -> int:
+        """获取URL的端口号，无端口返回-1
+
+        :param url_str: URL字符串
+        :return: 端口号，无端口或解析失败返回-1
+        """
+        if not url_str:
+            return -1
+        try:
+            parsed = urlparse(url_str)
+            return parsed.port if parsed.port is not None else -1
+        except Exception:
+            return -1
+
+    @staticmethod
+    def get_query(url_str: str) -> str:
+        """获取URL的查询参数部分
+
+        :param url_str: URL字符串
+        :return: URL的查询参数字符串（不含?），解析失败返回空字符串
+        """
+        if not url_str:
+            return ""
+        try:
+            parsed = urlparse(url_str)
+            return parsed.query
+        except Exception:
+            return ""
+
+    @staticmethod
+    def build_url(base: str, params: Dict[str, str]) -> str:
+        """构建带参数的URL
+
+        在基础URL上附加参数，如果原URL已有参数则追加。
+
+        :param base: 基础URL
+        :param params: 参数字典
+        :return: 带参数的完整URL
+        """
+        if not base:
+            return ""
+        if not params:
+            return base
+
+        param_str = urlencode(params, encoding="utf-8")
+        separator = "&" if "?" in base else "?"
+        return f"{base}{separator}{param_str}"
+
+    @staticmethod
+    def url_with_form(url: str, form: Dict[str, str]) -> str:
+        """在URL后附加表单参数
+
+        与build_url类似，将表单参数附加到URL后。
+
+        :param url: 原始URL
+        :param form: 表单参数字典
+        :return: 附加参数后的URL
+        """
+        return URLUtil.build_url(url, form)
+
+    @staticmethod
+    def to_params(param_map: Dict[str, str], 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 ""
+        return urlencode(param_map, encoding=charset)
+
+    @staticmethod
+    def decode_param_map(params_str: str, charset: str = "utf-8") -> Dict[str, str]:
+        """URL参数字符串转Map（每个key只保留最后一个值）
+
+        :param params_str: 参数字符串，如 "key1=value1&key2=value2"
+        :param charset: 字符编码，默认utf-8
+        :return: 参数字典，重复key时保留最后一个值
+        """
+        if not params_str:
+            return {}
+        pairs = parse_qsl(params_str, keep_blank_values=True, encoding=charset)
+        result: Dict[str, str] = {}
+        for key, value in pairs:
+            result[key] = value
+        return result
+
+    @staticmethod
+    def decode_params(params_str: str, charset: str = "utf-8") -> Dict[str, List[str]]:
+        """URL参数字符串转Map（每个key对应值列表）
+
+        :param params_str: 参数字符串，如 "key=value1&key=value2"
+        :param charset: 字符编码，默认utf-8
+        :return: 参数字典，每个key对应一个值列表
+        """
+        if not params_str:
+            return {}
+        return parse_qs(params_str, keep_blank_values=True, encoding=charset)
+
+    @staticmethod
+    def is_https(url_str: str) -> bool:
+        """是否为HTTPS
+
+        :param url_str: URL字符串
+        :return: 是HTTPS返回True，否则返回False
+        """
+        if not url_str:
+            return False
+        try:
+            parsed = urlparse(url_str)
+            return parsed.scheme.lower() == "https"
+        except Exception:
+            return False
+
+    @staticmethod
+    def is_http(url_str: str) -> bool:
+        """是否为HTTP
+
+        :param url_str: URL字符串
+        :return: 是HTTP返回True，否则返回False
+        """
+        if not url_str:
+            return False
+        try:
+            parsed = urlparse(url_str)
+            return parsed.scheme.lower() == "http"
+        except Exception:
+            return False

hutool/core/util/version_util.py

@@ -0,0 +1,41 @@
+"""版本比较工具类"""
+
+from __future__ import annotations
+
+
+class VersionUtil:
+    """版本比较工具类"""
+
+    @staticmethod
+    def compare(version1: str, version2: str) -> int:
+        """比较两个版本号，1: v1>v2, 0: 相等, -1: v1<v2
+        支持 "1.2.3" 格式
+        """
+        v1_parts = version1.split(".")
+        v2_parts = version2.split(".")
+        max_len = max(len(v1_parts), len(v2_parts))
+
+        for i in range(max_len):
+            v1 = int(v1_parts[i]) if i < len(v1_parts) else 0
+            v2 = int(v2_parts[i]) if i < len(v2_parts) else 0
+            if v1 > v2:
+                return 1
+            if v1 < v2:
+                return -1
+
+        return 0
+
+    @staticmethod
+    def is_greater(version1: str, version2: str) -> bool:
+        """version1是否大于version2"""
+        return VersionUtil.compare(version1, version2) == 1
+
+    @staticmethod
+    def is_lower(version1: str, version2: str) -> bool:
+        """version1是否小于version2"""
+        return VersionUtil.compare(version1, version2) == -1
+
+    @staticmethod
+    def get_main_version(version: str) -> str:
+        """获取主版本号，如 "1.2.3" -> "1" """
+        return version.split(".")[0]

hutool/core/util/xml_util.py

@@ -0,0 +1,158 @@
+import re
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, Optional
+from xml.dom import minidom
+
+
+class XmlUtil:
+    """XML工具类"""
+
+    @staticmethod
+    def read_xml(xml_str_or_path: str) -> ET.Element:
+        """读取XML（字符串或文件路径）
+
+        支持传入XML字符串或文件路径，自动判断并解析。
+
+        :param xml_str_or_path: XML字符串或文件路径
+        :return: 解析后的XML根元素
+        """
+        xml_str_or_path = xml_str_or_path.strip()
+        if xml_str_or_path.startswith("<"):
+            return ET.fromstring(xml_str_or_path)
+        else:
+            tree = ET.parse(xml_str_or_path)
+            return tree.getroot()
+
+    @staticmethod
+    def parse_to_map(xml_str: str) -> dict:
+        """XML转字典
+
+        将XML字符串递归转换为嵌套字典结构。如果同名子元素出现多次，值为列表。
+
+        :param xml_str: XML字符串
+        :return: 转换后的字典
+        """
+        root = ET.fromstring(xml_str) if xml_str.strip().startswith("<") else ET.parse(xml_str).getroot()
+
+        def _element_to_dict(element: ET.Element) -> Any:
+            children = list(element)
+            if not children:
+                text = element.text
+                if text is not None:
+                    text = text.strip()
+                return text if text else ""
+
+            result: Dict[str, Any] = {}
+            for child in children:
+                child_data = _element_to_dict(child)
+                if child.tag in result:
+                    existing = result[child.tag]
+                    if isinstance(existing, list):
+                        existing.append(child_data)
+                    else:
+                        result[child.tag] = [existing, child_data]
+                else:
+                    result[child.tag] = child_data
+
+            # 添加属性
+            if element.attrib:
+                for key, value in element.attrib.items():
+                    result[f"@{key}"] = value
+
+            return result
+
+        tag = root.tag
+        return {tag: _element_to_dict(root)}
+
+    @staticmethod
+    def to_xml_str(root_name: str, data: dict) -> str:
+        """字典转XML字符串
+
+        :param root_name: 根元素名称
+        :param data: 待转换的字典数据
+        :return: XML字符串
+        """
+        return XmlUtil.map_to_xml(data, root_name)
+
+    @staticmethod
+    def map_to_xml(data: dict, root_name: str = "root") -> str:
+        """字典转XML
+
+        将字典递归转换为XML字符串。
+
+        :param data: 待转换的字典数据
+        :param root_name: 根元素名称，默认为"root"
+        :return: XML字符串
+        """
+        root = ET.Element(root_name)
+        XmlUtil._build_xml(root, data)
+        return ET.tostring(root, encoding="unicode")
+
+    @staticmethod
+    def _build_xml(parent: ET.Element, data: Any) -> None:
+        """递归构建XML元素
+
+        :param parent: 父元素
+        :param data: 当前数据（字典或值）
+        """
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if key.startswith("@"):
+                    # XML属性
+                    parent.set(key[1:], str(value))
+                elif isinstance(value, list):
+                    for item in value:
+                        child = ET.SubElement(parent, key)
+                        XmlUtil._build_xml(child, item)
+                else:
+                    child = ET.SubElement(parent, key)
+                    XmlUtil._build_xml(child, value)
+        else:
+            parent.text = str(data) if data is not None else ""
+
+    @staticmethod
+    def format_xml(xml_str: str) -> str:
+        """格式化XML
+
+        将XML字符串格式化为带缩进的可读格式。
+
+        :param xml_str: 待格式化的XML字符串
+        :return: 格式化后的XML字符串
+        """
+        dom = minidom.parseString(xml_str)
+        pretty_xml = dom.toprettyxml(indent="  ", encoding=None)
+        # 去除minidom添加的多余空行
+        lines = [line for line in pretty_xml.split("\n") if line.strip()]
+        return "\n".join(lines)
+
+    @staticmethod
+    def get_element_text(element: ET.Element, xpath: str) -> Optional[str]:
+        """获取元素文本
+
+        通过xpath查找子元素并返回其文本内容。
+
+        :param element: XML元素
+        :param xpath: 子元素的标签路径，如 "child/subchild"
+        :return: 元素文本内容，未找到则返回None
+        """
+        target = element.find(xpath)
+        if target is not None:
+            return target.text
+        return None
+
+    @staticmethod
+    def clean_invalid(xml_str: str) -> str:
+        """清理XML中的非法字符
+
+        移除XML规范中不允许的控制字符（除了制表符、换行符、回车符）。
+
+        :param xml_str: 原始XML字符串
+        :return: 清理后的XML字符串
+        """
+        # 移除非法字符：XML合法字符为 #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
+        valid_xml_chars = re.compile(
+            r"[^\x09\x0A\x0D\x20-\x7E\x80-\xFF"
+            r"Ā-퟿-�"
+            r"\U00010000-\U0010FFFF]"
+        )
+        return valid_xml_chars.sub("", xml_str)

hutool/core/util/zip_util.py

@@ -0,0 +1,126 @@
+import gzip
+import os
+import zipfile
+import zlib
+from typing import Optional
+
+
+class ZipUtil:
+    """压缩工具类"""
+
+    @staticmethod
+    def zip(src_path: str, dest_path: Optional[str] = None, charset: str = "utf-8") -> str:
+        """压缩文件或目录为zip
+
+        :param src_path: 源文件或目录路径
+        :param dest_path: 目标zip文件路径，默认为源路径加.zip后缀
+        :param charset: 文件名编码字符集，默认utf-8
+        :return: 生成的zip文件路径
+        """
+        if not os.path.exists(src_path):
+            raise FileNotFoundError(f"源路径不存在: {src_path}")
+
+        if dest_path is None:
+            dest_path = src_path + ".zip"
+
+        dest_path = os.path.abspath(dest_path)
+        src_path = os.path.abspath(src_path)
+
+        with zipfile.ZipFile(dest_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            if os.path.isfile(src_path):
+                zf.write(src_path, os.path.basename(src_path))
+            elif os.path.isdir(src_path):
+                base_dir = os.path.basename(src_path)
+                for root, dirs, files in os.walk(src_path):
+                    for file in files:
+                        file_path = os.path.join(root, file)
+                        arcname = os.path.join(base_dir, os.path.relpath(file_path, src_path))
+                        zf.write(file_path, arcname)
+            else:
+                raise ValueError(f"不支持的路径类型: {src_path}")
+
+        return dest_path
+
+    @staticmethod
+    def unzip(zip_file: str, dest_path: str, charset: str = "utf-8") -> str:
+        """解压zip文件
+
+        :param zip_file: zip文件路径
+        :param dest_path: 解压目标目录
+        :param charset: 文件名编码字符集，默认utf-8
+        :return: 解压目标目录路径
+        """
+        if not os.path.exists(zip_file):
+            raise FileNotFoundError(f"zip文件不存在: {zip_file}")
+
+        dest_path = os.path.abspath(dest_path)
+        os.makedirs(dest_path, exist_ok=True)
+
+        with zipfile.ZipFile(zip_file, "r") as zf:
+            for info in zf.infolist():
+                # 尝试用指定编码解码文件名
+                try:
+                    filename = info.filename.encode("cp437").decode(charset)
+                except (UnicodeDecodeError, UnicodeEncodeError):
+                    filename = info.filename
+                info.filename = filename
+                zf.extract(info, dest_path)
+
+        return dest_path
+
+    @staticmethod
+    def gzip(data: bytes) -> bytes:
+        """Gzip压缩
+
+        :param data: 待压缩的字节数据
+        :return: 压缩后的字节数据
+        """
+        return gzip.compress(data)
+
+    @staticmethod
+    def gzip_str(data: str, charset: str = "utf-8") -> bytes:
+        """字符串Gzip压缩
+
+        :param data: 待压缩的字符串
+        :param charset: 字符编码，默认utf-8
+        :return: 压缩后的字节数据
+        """
+        return gzip.compress(data.encode(charset))
+
+    @staticmethod
+    def ungzip(data: bytes) -> bytes:
+        """Gzip解压
+
+        :param data: 待解压的字节数据
+        :return: 解压后的字节数据
+        """
+        return gzip.decompress(data)
+
+    @staticmethod
+    def ungzip_str(data: bytes, charset: str = "utf-8") -> str:
+        """Gzip解压为字符串
+
+        :param data: 待解压的字节数据
+        :param charset: 字符编码，默认utf-8
+        :return: 解压后的字符串
+        """
+        return gzip.decompress(data).decode(charset)
+
+    @staticmethod
+    def zlib_compress(data: bytes, level: int = -1) -> bytes:
+        """Zlib压缩
+
+        :param data: 待压缩的字节数据
+        :param level: 压缩级别，-1为默认，0为不压缩，1-9为压缩级别（1最快，9最小）
+        :return: 压缩后的字节数据
+        """
+        return zlib.compress(data, level)
+
+    @staticmethod
+    def zlib_uncompress(data: bytes) -> bytes:
+        """Zlib解压
+
+        :param data: 待解压的字节数据
+        :return: 解压后的字节数据
+        """
+        return zlib.decompress(data)

hutool/cron/__init__.py

@@ -0,0 +1,4 @@
+from .cron_pattern import CronPattern
+from .cron_util import CronUtil
+
+__all__ = ["CronPattern", "CronUtil"]