hutool-python 1.0.0__py3-none-any.whl

hutool/core/text/unicode_util.py

@@ -0,0 +1,58 @@
+import re
+from typing import List
+
+
+class UnicodeUtil:
+    """Unicode工具类"""
+
+    @staticmethod
+    def to_unicode(string: str) -> str:
+        """字符串转Unicode，如 "中文" -> "\\u4e2d\\u6587"
+
+        :param string: 原始字符串
+        :return: Unicode转义后的字符串
+        """
+        return string.encode("unicode_escape").decode("ascii")
+
+    @staticmethod
+    def from_unicode(unicode_str: str) -> str:
+        """Unicode转字符串，如 "\\u4e2d\\u6587" -> "中文"
+
+        :param unicode_str: Unicode转义字符串
+        :return: 解码后的原始字符串
+        """
+        return unicode_str.encode("ascii").decode("unicode_escape")
+
+    @staticmethod
+    def escape(content: str) -> str:
+        """转义非ASCII字符为Unicode
+
+        将字符串中所有非ASCII字符转换为 \\uXXXX 格式的Unicode转义序列，
+        ASCII字符保持不变。
+
+        :param content: 原始字符串
+        :return: 转义后的字符串
+        """
+        result: List[str] = []
+        for ch in content:
+            if ord(ch) > 127:
+                result.append(f"\\u{ord(ch):04x}")
+            else:
+                result.append(ch)
+        return "".join(result)
+
+    @staticmethod
+    def unescape(content: str) -> str:
+        """反转义Unicode字符
+
+        将字符串中的 \\uXXXX 格式的Unicode转义序列还原为实际字符，
+        同时支持 \\uXXXXX 等五位及以上的Unicode码点。
+
+        :param content: 包含Unicode转义序列的字符串
+        :return: 还原后的原始字符串
+        """
+
+        def _replace(match: re.Match) -> str:
+            return chr(int(match.group(1), 16))
+
+        return re.sub(r"\\u([0-9a-fA-F]{4,})", _replace, content)

hutool/core/tree.py

@@ -0,0 +1,242 @@
+from collections import deque
+from typing import Any, Callable, Dict, List, Optional
+
+
+class TreeNode:
+    """树节点
+
+    用于表示树结构中的单个节点，包含节点标识、父节点标识、
+    名称、权重、子节点列表以及扩展属性。
+    """
+
+    def __init__(
+        self,
+        id: Any = None,
+        parent_id: Any = None,
+        name: str = "",
+        weight: int = 0,
+    ):
+        """初始化树节点
+
+        :param id: 节点唯一标识
+        :param parent_id: 父节点标识，根节点通常为 None 或特定根标识
+        :param name: 节点名称
+        :param weight: 节点权重，用于排序
+        """
+        self.id = id
+        self.parent_id = parent_id
+        self.name = name
+        self.weight = weight
+        self.children: List[TreeNode] = []
+        self.extra: Dict[str, Any] = {}
+
+    def __repr__(self) -> str:
+        return (
+            f"TreeNode(id={self.id!r}, parent_id={self.parent_id!r}, "
+            f"name={self.name!r}, weight={self.weight}, "
+            f"children_count={len(self.children)})"
+        )
+
+    def to_dict(self) -> dict:
+        """将节点及其子树转为字典
+
+        :return: 包含节点信息和子节点列表的字典
+        """
+        result = {
+            "id": self.id,
+            "parentId": self.parent_id,
+            "name": self.name,
+            "weight": self.weight,
+            "children": [child.to_dict() for child in self.children],
+        }
+        if self.extra:
+            result.update(self.extra)
+        return result
+
+
+class TreeUtil:
+    """树工具类
+
+    提供从平铺列表构建树、遍历、查找、统计等常用操作。
+    """
+
+    @staticmethod
+    def build(
+        list_data: List[dict],
+        root_id: Any = None,
+        id_field: str = "id",
+        parent_field: str = "parentId",
+        children_field: str = "children",
+        name_field: str = "name",
+        weight_field: str = "weight",
+    ) -> List[TreeNode]:
+        """从平铺列表构建树
+
+        将包含 id 和 parentId 的平铺字典列表转换为树形结构。
+
+        :param list_data: 平铺的字典列表
+        :param root_id: 根节点的 parent_id 值，默认为 None
+        :param id_field: 节点ID字段名，默认 "id"
+        :param parent_field: 父节点ID字段名，默认 "parentId"
+        :param children_field: 子节点列表字段名，默认 "children"
+        :param name_field: 节点名称字段名，默认 "name"
+        :param weight_field: 权重字段名，默认 "weight"
+        :return: 根节点列表（可能有多个顶级节点）
+        """
+        # 构建 id -> TreeNode 的映射
+        node_map: Dict[Any, TreeNode] = {}
+        for item in list_data:
+            node_id = item.get(id_field)
+            node = TreeNode(
+                id=node_id,
+                parent_id=item.get(parent_field),
+                name=str(item.get(name_field, "")),
+                weight=int(item.get(weight_field, 0)),
+            )
+            # 将未识别的字段存入 extra
+            known_fields = {id_field, parent_field, children_field, name_field, weight_field}
+            for key, value in item.items():
+                if key not in known_fields:
+                    node.extra[key] = value
+            node_map[node_id] = node
+
+        # 组装父子关系
+        roots: List[TreeNode] = []
+        for item in list_data:
+            node_id = item.get(id_field)
+            parent_id = item.get(parent_field)
+            node = node_map[node_id]
+            if parent_id == root_id or parent_id not in node_map:
+                roots.append(node)
+            else:
+                parent = node_map.get(parent_id)
+                if parent is not None:
+                    parent.children.append(node)
+
+        # 按权重排序子节点
+        def _sort_children(nodes: List[TreeNode]) -> None:
+            nodes.sort(key=lambda n: n.weight)
+            for child in nodes:
+                _sort_children(child.children)
+
+        _sort_children(roots)
+        return roots
+
+    @staticmethod
+    def get_node_id(tree_nodes: List[TreeNode], node_id: Any) -> Optional[TreeNode]:
+        """根据ID查找节点
+
+        :param tree_nodes: 树节点列表
+        :param node_id: 要查找的节点ID
+        :return: 匹配的节点，未找到返回 None
+        """
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            if node.id == node_id:
+                return node
+            queue.extend(node.children)
+        return None
+
+    @staticmethod
+    def to_list(tree_nodes: List[TreeNode]) -> List[dict]:
+        """树转平铺列表
+
+        将树形结构展平为字典列表，广度优先遍历。
+
+        :param tree_nodes: 根节点列表
+        :return: 平铺的字典列表
+        """
+        result: List[dict] = []
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            result.append(node.to_dict())
+            queue.extend(node.children)
+        return result
+
+    @staticmethod
+    def foreach(
+        tree_nodes: List[TreeNode],
+        consumer: Callable[[TreeNode], None],
+    ) -> None:
+        """广度优先遍历（BFS）
+
+        对树中每个节点执行 consumer 回调。
+
+        :param tree_nodes: 根节点列表
+        :param consumer: 遍历回调函数
+        """
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            consumer(node)
+            queue.extend(node.children)
+
+    @staticmethod
+    def foreach_df(
+        tree_nodes: List[TreeNode],
+        consumer: Callable[[TreeNode], None],
+    ) -> None:
+        """深度优先遍历（DFS）
+
+        对树中每个节点执行 consumer 回调，使用栈实现非递归遍历。
+
+        :param tree_nodes: 根节点列表
+        :param consumer: 遍历回调函数
+        """
+        stack = list(reversed(tree_nodes))
+        while stack:
+            node = stack.pop()
+            consumer(node)
+            # 反向压栈以保证从左到右的遍历顺序
+            stack.extend(reversed(node.children))
+
+    @staticmethod
+    def to_map(tree_nodes: List[TreeNode]) -> Dict[Any, TreeNode]:
+        """树转ID到节点的映射
+
+        :param tree_nodes: 根节点列表
+        :return: 以节点ID为键、节点对象为值的字典
+        """
+        result: Dict[Any, TreeNode] = {}
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            result[node.id] = node
+            queue.extend(node.children)
+        return result
+
+    @staticmethod
+    def count(tree_nodes: List[TreeNode]) -> int:
+        """统计节点总数
+
+        :param tree_nodes: 根节点列表
+        :return: 树中所有节点的数量
+        """
+        total = 0
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            total += 1
+            queue.extend(node.children)
+        return total
+
+    @staticmethod
+    def get_leaf_nodes(tree_nodes: List[TreeNode]) -> List[TreeNode]:
+        """获取所有叶子节点
+
+        叶子节点是指没有子节点的节点。
+
+        :param tree_nodes: 根节点列表
+        :return: 叶子节点列表
+        """
+        leaves: List[TreeNode] = []
+        queue = deque(tree_nodes)
+        while queue:
+            node = queue.popleft()
+            if not node.children:
+                leaves.append(node)
+            else:
+                queue.extend(node.children)
+        return leaves

hutool/core/util/__init__.py

@@ -0,0 +1,63 @@
+"""Core util 工具类导出。"""
+
+from .array_util import ArrayUtil
+from .boolean_util import BooleanUtil
+from .charset_util import CharsetUtil
+from .class_util import ClassUtil
+from .coordinate_util import CoordinateUtil
+from .credit_code_util import CreditCodeUtil
+from .desensitized_util import DesensitizedUtil
+from .enum_util import EnumUtil
+from .escape_util import EscapeUtil
+from .hash_util import HashUtil
+from .hex_util import HexUtil
+from .id_util import IdUtil
+from .idcard_util import IdcardUtil
+from .number_util import NumberUtil
+from .object_util import ObjectUtil
+from .page_util import PageUtil
+from .phone_util import PhoneUtil
+from .random_util import RandomUtil
+from .re_util import ReUtil
+from .reflect_util import ReflectUtil
+from .runtime_util import RuntimeUtil
+from .str_util import CharPool, CharSequenceUtil, CharUtil, StrPool, StrUtil
+from .system_util import SystemUtil
+from .url_util import URLUtil
+from .version_util import VersionUtil
+from .xml_util import XmlUtil
+from .zip_util import ZipUtil
+
+__all__ = [
+    "ArrayUtil",
+    "BooleanUtil",
+    "CharPool",
+    "CharSequenceUtil",
+    "CharUtil",
+    "CharsetUtil",
+    "ClassUtil",
+    "CoordinateUtil",
+    "CreditCodeUtil",
+    "DesensitizedUtil",
+    "EnumUtil",
+    "EscapeUtil",
+    "HashUtil",
+    "HexUtil",
+    "IdUtil",
+    "IdcardUtil",
+    "NumberUtil",
+    "ObjectUtil",
+    "PageUtil",
+    "PhoneUtil",
+    "RandomUtil",
+    "ReUtil",
+    "ReflectUtil",
+    "RuntimeUtil",
+    "StrPool",
+    "StrUtil",
+    "SystemUtil",
+    "URLUtil",
+    "VersionUtil",
+    "XmlUtil",
+    "ZipUtil",
+]