hutool-python 1.0.0__py3-none-any.whl

hutool/core/math_util.py

@@ -0,0 +1,105 @@
+"""数学工具类，提供精确运算、坐标转换、位运算状态管理等功能"""
+
+import math
+from decimal import Decimal
+from typing import Union
+
+__all__ = ("BitStatusUtil", "MathUtil")
+
+
+class MathUtil:
+    """数学工具类，提供精确数学运算和坐标转换功能"""
+
+    @staticmethod
+    def add(value1: Union[int, float, str, Decimal], value2: Union[int, float, str, Decimal]) -> Decimal:
+        """
+        精确加法，使用Decimal避免浮点精度问题
+
+        :param value1: 加数1
+        :param value2: 加数2
+        :return: 精确的加法结果
+        """
+        d1 = Decimal(str(value1))
+        d2 = Decimal(str(value2))
+        return d1 + d2
+
+    @staticmethod
+    def point_to_radians(point: tuple) -> float:
+        """
+        坐标点转弧度，根据(x, y)坐标计算对应的弧度值
+
+        :param point: 坐标点(x, y)
+        :return: 弧度值
+        """
+        if point is None or len(point) < 2:
+            raise ValueError("坐标点必须包含x和y两个分量")
+        x, y = float(point[0]), float(point[1])
+        return math.atan2(y, x)
+
+    @staticmethod
+    def radians_to_point(radians: float) -> tuple:
+        """
+        弧度转坐标点，根据弧度计算单位圆上的(x, y)坐标
+
+        :param radians: 弧度值
+        :return: 坐标点(x, y)
+        """
+        x = math.cos(radians)
+        y = math.sin(radians)
+        return (x, y)
+
+
+class BitStatusUtil:
+    """位运算状态工具类，使用位运算管理多状态组合"""
+
+    @staticmethod
+    def add(status: int, *values: int) -> int:
+        """
+        添加状态位，将一个或多个状态值添加到当前状态中
+
+        :param status: 当前状态值
+        :param values: 要添加的一个或多个状态值
+        :return: 添加后的状态值
+        """
+        for value in values:
+            status |= value
+        return status
+
+    @staticmethod
+    def has(status: int, value: int) -> bool:
+        """
+        是否包含指定状态
+
+        :param status: 当前状态值
+        :param value: 要检测的状态值
+        :return: 是否包含该状态
+        """
+        return (status & value) == value
+
+    @staticmethod
+    def remove(status: int, *values: int) -> int:
+        """
+        移除状态位，从当前状态中移除一个或多个状态值
+
+        :param status: 当前状态值
+        :param values: 要移除的一个或多个状态值
+        :return: 移除后的状态值
+        """
+        for value in values:
+            status &= ~value
+        return status
+
+    @staticmethod
+    def to_binary_string(status: int) -> str:
+        """
+        转二进制字符串
+
+        :param status: 状态值
+        :return: 二进制字符串表示
+        """
+        if status == 0:
+            return "0"
+        if status > 0:
+            return bin(status)[2:]
+        # 负数使用补码表示
+        return bin(status & 0xFFFFFFFF)[2:]

hutool/core/net.py

@@ -0,0 +1,288 @@
+"""网络工具类，提供端口检测、IP地址处理、子网掩码转换等功能"""
+
+import ipaddress
+import random
+import socket
+import uuid
+from socket import AF_INET, SO_REUSEADDR, SOCK_DGRAM, SOCK_STREAM, SOL_SOCKET
+from typing import Final, Optional
+
+__all__ = ("Ipv4Util", "MaskBit", "NetUtil")
+
+
+class MaskBit:
+    """掩码位和掩码之间的对应关系"""
+
+    MASK_BIT_MAP: Final[dict] = {
+        1: "128.0.0.0",
+        2: "192.0.0.0",
+        3: "224.0.0.0",
+        4: "240.0.0.0",
+        5: "248.0.0.0",
+        6: "252.0.0.0",
+        7: "254.0.0.0",
+        8: "255.0.0.0",
+        9: "255.128.0.0",
+        10: "255.192.0.0",
+        11: "255.224.0.0",
+        12: "255.240.0.0",
+        13: "255.248.0.0",
+        14: "255.252.0.0",
+        15: "255.254.0.0",
+        16: "255.255.0.0",
+        17: "255.255.128.0",
+        18: "255.255.192.0",
+        19: "255.255.224.0",
+        20: "255.255.240.0",
+        21: "255.255.248.0",
+        22: "255.255.252.0",
+        23: "255.255.254.0",
+        24: "255.255.255.0",
+        25: "255.255.255.128",
+        26: "255.255.255.192",
+        27: "255.255.255.224",
+        28: "255.255.255.240",
+        29: "255.255.255.248",
+        30: "255.255.255.252",
+        31: "255.255.255.254",
+        32: "255.255.255.255",
+    }
+
+    # 反向映射：掩码字符串 -> 掩码位
+    _MASK_TO_BIT: Final[dict] = {v: k for k, v in MASK_BIT_MAP.items()}
+
+    @staticmethod
+    def get(mask_bit: int) -> str:
+        """
+        根据掩码位获取掩码
+
+        :param mask_bit: 掩码位，范围1-32
+        :return: 掩码字符串，如"255.255.255.0"
+        :raises KeyError: 掩码位不在合法范围内
+        """
+        return MaskBit.MASK_BIT_MAP[mask_bit]
+
+    @staticmethod
+    def get_mask_bit(mask: str) -> Optional[int]:
+        """
+        根据掩码获取掩码位
+
+        :param mask: 掩码的点分十进制表示，如"255.255.255.0"
+        :return: 掩码位，如24；如果掩码不合法则返回None
+        """
+        return MaskBit._MASK_TO_BIT.get(mask)
+
+
+class Ipv4Util:
+    """IPV4地址工具类"""
+
+    LOCAL_IP: Final[str] = "127.0.0.1"
+    # IP段的分割符
+    IP_SPLIT_MARK: Final[str] = "-"
+    # IP与掩码的分割符
+    IP_MASK_SPLIT_MARK: Final[str] = "/"
+    # 最大掩码位
+    IP_MASK_MAX: Final[int] = 32
+
+    @staticmethod
+    def format_ip_block(ip: str, mask: str) -> str:
+        """
+        格式化IP段
+
+        :param ip: IP地址
+        :param mask: 掩码
+        :return: 返回xxx.xxx.xxx.xxx/mask的格式
+        """
+        return ip + Ipv4Util.IP_MASK_SPLIT_MARK + str(Ipv4Util.get_mask_bit_by_mask(mask))
+
+    @staticmethod
+    def get_mask_bit_by_mask(mask: str) -> int:
+        """
+        根据子网掩码转换为掩码位
+
+        :param mask: 掩码的点分十进制表示，例如"255.255.255.0"
+        :return: 掩码位，例如24
+        :raises ValueError: 子网掩码非法
+        """
+        mask_bit = MaskBit.get_mask_bit(mask)
+        if mask_bit is None:
+            raise ValueError("Invalid netmask: " + mask)
+        return mask_bit
+
+
+class NetUtil:
+    """网络工具类，提供端口检测、IP获取、地址转换等功能"""
+
+    # 本地IPv4地址
+    LOCAL_IP: Final[str] = Ipv4Util.LOCAL_IP
+    # 默认最小端口，1024
+    PORT_RANGE_MIN: Final[int] = 1024
+    # 默认最大端口，65535
+    PORT_RANGE_MAX: Final[int] = 0xFFFF
+
+    @staticmethod
+    def is_usable_local_port(port: int) -> bool:
+        """
+        检测本地端口可用性
+
+        :param port: 被检测的端口
+        :return: 是否可用
+        """
+        if not NetUtil.is_valid_port(port):
+            return False
+
+        # 使用TCP协议检测
+        try:
+            with socket.socket(AF_INET, SOCK_STREAM) as s:
+                s.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
+                s.bind((NetUtil.LOCAL_IP, port))
+        except OSError:
+            return False
+
+        # 使用UDP协议检测
+        try:
+            with socket.socket(AF_INET, SOCK_DGRAM) as s:
+                s.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1)
+                s.bind((NetUtil.LOCAL_IP, port))
+        except OSError:
+            return False
+
+        return True
+
+    @staticmethod
+    def is_valid_port(port: int) -> bool:
+        """
+        是否为有效的端口，此方法并不检查端口是否被占用
+
+        :param port: 端口号
+        :return: 是否有效
+        """
+        return 0 <= port <= NetUtil.PORT_RANGE_MAX
+
+    @staticmethod
+    def get_usable_local_port(min_port: int = PORT_RANGE_MIN, max_port: int = PORT_RANGE_MAX) -> int:
+        """
+        查找指定范围内的可用端口
+
+        此方法只检测给定范围内的随机一个端口，最多检测max_port-min_port次。
+
+        :param min_port: 端口最小值（包含）
+        :param max_port: 端口最大值（包含）
+        :return: 可用的端口
+        :raises RuntimeError: 在指定范围内未找到可用端口
+        """
+        max_port_exclude = max_port + 1
+        for _ in range(min_port, max_port_exclude):
+            random_port = random.randint(min_port, max_port)
+            if NetUtil.is_usable_local_port(random_port):
+                return random_port
+        raise RuntimeError(
+            f"Could not find an available port in the range [{min_port}, {max_port}] "
+            f"after {max_port - min_port} attempts"
+        )
+
+    @staticmethod
+    def get_local_ip() -> str:
+        """
+        获取本机IP地址，通过UDP连接外部地址获取本机对外IP
+
+        :return: 本机IP地址，获取失败时返回127.0.0.1
+        """
+        try:
+            with socket.socket(AF_INET, SOCK_DGRAM) as s:
+                # 不实际发送数据，仅用于获取本机出口IP
+                s.connect(("8.8.8.8", 80))
+                return s.getsockname()[0]
+        except Exception:
+            return NetUtil.LOCAL_IP
+
+    @staticmethod
+    def get_localhost() -> str:
+        """
+        获取本机主机名
+
+        :return: 主机名
+        """
+        return socket.gethostname()
+
+    @staticmethod
+    def get_mac_address() -> str:
+        """
+        获取本机MAC地址
+
+        :return: MAC地址字符串，格式为xx:xx:xx:xx:xx:xx
+        """
+        mac = uuid.getnode()
+        return ":".join(f"{(mac >> (8 * i)) & 0xFF:02x}" for i in reversed(range(6)))
+
+    @staticmethod
+    def is_inner(ip: str) -> bool:
+        """
+        判断是否为内网IP地址
+
+        内网IP范围：
+        - 10.0.0.0 ~ 10.255.255.255（A类私有地址）
+        - 172.16.0.0 ~ 172.31.255.255（B类私有地址）
+        - 192.168.0.0 ~ 192.168.255.255（C类私有地址）
+        - 127.0.0.0 ~ 127.255.255.255（本地回环地址）
+
+        :param ip: IP地址字符串
+        :return: 是否为内网IP
+        """
+        if ip is None:
+            return False
+        try:
+            addr = ipaddress.ip_address(ip)
+            return addr.is_private
+        except ValueError:
+            return False
+
+    @staticmethod
+    def ipv4_to_long(ip: str) -> int:
+        """
+        将IPv4地址转换为long整型数值
+
+        :param ip: IPv4地址字符串，如"192.168.1.1"
+        :return: 对应的long整型值
+        :raises ValueError: IP地址格式非法
+        """
+        try:
+            return int(ipaddress.IPv4Address(ip))
+        except ipaddress.AddressValueError as e:
+            raise ValueError(f"非法的IPv4地址: {ip}") from e
+
+    @staticmethod
+    def long_to_ipv4(long_ip: int) -> str:
+        """
+        将long整型数值转换为IPv4地址
+
+        :param long_ip: long整型值
+        :return: IPv4地址字符串
+        :raises ValueError: 数值不在合法范围内
+        """
+        if long_ip < 0 or long_ip > 0xFFFFFFFF:
+            raise ValueError(f"非法的long型IP值: {long_ip}")
+        return str(ipaddress.IPv4Address(long_ip))
+
+    @staticmethod
+    def is_open(host: str, port: int, timeout: int = 2000) -> bool:
+        """
+        检测远程主机端口是否可连接
+
+        :param host: 主机地址
+        :param port: 端口号
+        :param timeout: 超时时间，单位毫秒，默认2000ms
+        :return: 端口是否可连接
+        """
+        if host is None:
+            return False
+        if not NetUtil.is_valid_port(port):
+            return False
+
+        try:
+            with socket.socket(AF_INET, SOCK_STREAM) as s:
+                s.settimeout(timeout / 1000.0)
+                s.connect((host, port))
+            return True
+        except (socket.timeout, OSError):
+            return False

hutool/core/text/csv_util.py

@@ -0,0 +1,54 @@
+import csv
+import io
+from typing import List
+
+
+class CsvUtil:
+    """CSV工具类"""
+
+    @staticmethod
+    def read(path: str, charset: str = "utf-8") -> List[List[str]]:
+        """读取CSV文件为二维列表
+
+        :param path: CSV文件路径
+        :param charset: 文件编码，默认utf-8
+        :return: 二维列表，每个元素为一行的数据
+        """
+        with open(path, encoding=charset, newline="") as f:
+            reader = csv.reader(f)
+            return [row for row in reader]
+
+    @staticmethod
+    def read_string(csv_str: str) -> List[List[str]]:
+        """读取CSV字符串为二维列表
+
+        :param csv_str: CSV格式的字符串
+        :return: 二维列表，每个元素为一行的数据
+        """
+        f = io.StringIO(csv_str)
+        reader = csv.reader(f)
+        return [row for row in reader]
+
+    @staticmethod
+    def write(path: str, data: List[List[str]], charset: str = "utf-8") -> None:
+        """写入CSV文件
+
+        :param path: CSV文件路径
+        :param data: 二维列表数据
+        :param charset: 文件编码，默认utf-8
+        """
+        with open(path, "w", encoding=charset, newline="") as f:
+            writer = csv.writer(f)
+            writer.writerows(data)
+
+    @staticmethod
+    def write_string(data: List[List[str]]) -> str:
+        """将二维列表转为CSV字符串
+
+        :param data: 二维列表数据
+        :return: CSV格式的字符串
+        """
+        f = io.StringIO()
+        writer = csv.writer(f)
+        writer.writerows(data)
+        return f.getvalue()

hutool/core/text/str_builder.py

@@ -0,0 +1,224 @@
+from typing import List, Optional
+
+
+class StrBuilder:
+    """字符串构建器，类似Java StringBuilder
+
+    提供高效的字符串拼接操作，内部使用列表缓存各段字符串，
+    最终在 to_string 时一次性拼接，避免频繁字符串拼接带来的性能问题。
+    """
+
+    def __init__(self, capacity: int = 16):
+        """初始化字符串构建器
+
+        :param capacity: 初始容量（提示性，不强制约束）
+        """
+        self._parts: List[str] = []
+        self._length: int = 0
+
+    def _to_str(self) -> str:
+        """内部方法：将当前所有片段拼接为完整字符串"""
+        return "".join(self._parts)
+
+    def append(self, *args: object) -> "StrBuilder":
+        """追加内容
+
+        支持追加任意类型，会自动调用 str() 转换。
+        可一次追加多个对象，也可追加列表/元组（展开其元素）。
+
+        :param args: 要追加的一个或多个对象
+        :return: self，支持链式调用
+        """
+        for arg in args:
+            if isinstance(arg, (list, tuple)):
+                for item in arg:
+                    s = str(item)
+                    self._parts.append(s)
+                    self._length += len(s)
+            else:
+                s = str(arg)
+                self._parts.append(s)
+                self._length += len(s)
+        return self
+
+    def insert(self, index: int, obj: object) -> "StrBuilder":
+        """在指定位置插入内容
+
+        :param index: 插入位置索引
+        :param obj: 要插入的对象，会被转换为字符串
+        :return: self，支持链式调用
+        :raises IndexError: 索引越界
+        """
+        current = self._to_str()
+        if index < 0 or index > len(current):
+            raise IndexError(f"索引越界: {index}, 当前长度: {len(current)}")
+        s = str(obj)
+        self._parts = [current[:index], s, current[index:]]
+        self._length += len(s)
+        return self
+
+    def delete(self, start: int, end: int) -> "StrBuilder":
+        """删除指定范围的内容 [start, end)
+
+        :param start: 起始索引（包含）
+        :param end: 结束索引（不包含）
+        :return: self，支持链式调用
+        :raises IndexError: 索引越界
+        """
+        current = self._to_str()
+        if start < 0 or start > len(current):
+            raise IndexError(f"起始索引越界: {start}")
+        if end < 0 or end > len(current):
+            raise IndexError(f"结束索引越界: {end}")
+        if start > end:
+            raise ValueError(f"起始索引 {start} 大于结束索引 {end}")
+        deleted = current[start:end]
+        self._parts = [current[:start], current[end:]]
+        self._length -= len(deleted)
+        return self
+
+    def replace(self, start: int, end: int, string: str) -> "StrBuilder":
+        """替换指定范围的内容 [start, end)
+
+        :param start: 起始索引（包含）
+        :param end: 结束索引（不包含）
+        :param string: 替换内容
+        :return: self，支持链式调用
+        :raises IndexError: 索引越界
+        """
+        current = self._to_str()
+        if start < 0 or start > len(current):
+            raise IndexError(f"起始索引越界: {start}")
+        if end < 0 or end > len(current):
+            raise IndexError(f"结束索引越界: {end}")
+        if start > end:
+            raise ValueError(f"起始索引 {start} 大于结束索引 {end}")
+        removed_len = end - start
+        self._parts = [current[:start], string, current[end:]]
+        self._length = self._length - removed_len + len(string)
+        return self
+
+    def reverse(self) -> "StrBuilder":
+        """反转字符串内容
+
+        :return: self，支持链式调用
+        """
+        current = self._to_str()
+        self._parts = [current[::-1]]
+        return self
+
+    def to_string(self) -> str:
+        """转为字符串
+
+        :return: 当前构建器中的完整字符串
+        """
+        return self._to_str()
+
+    def length(self) -> int:
+        """获取当前字符串长度
+
+        :return: 字符串长度
+        """
+        return self._length
+
+    def is_empty(self) -> bool:
+        """判断构建器是否为空
+
+        :return: 为空返回 True，否则返回 False
+        """
+        return self._length == 0
+
+    def char_at(self, index: int) -> str:
+        """获取指定位置的字符
+
+        :param index: 字符索引
+        :return: 指定位置的字符
+        :raises IndexError: 索引越界
+        """
+        if index < 0 or index >= self._length:
+            raise IndexError(f"索引越界: {index}, 当前长度: {self._length}")
+        current = self._to_str()
+        return current[index]
+
+    def index_of(self, string: str, start: int = 0) -> int:
+        """查找子串首次出现的位置
+
+        :param string: 要查找的子串
+        :param start: 起始搜索位置，默认为0
+        :return: 子串首次出现的索引，未找到返回 -1
+        """
+        current = self._to_str()
+        return current.find(string, start)
+
+    def last_index_of(self, string: str) -> int:
+        """从后查找子串最后一次出现的位置
+
+        :param string: 要查找的子串
+        :return: 子串最后一次出现的索引，未找到返回 -1
+        """
+        current = self._to_str()
+        return current.rfind(string)
+
+    def substring(self, start: int, end: Optional[int] = None) -> str:
+        """获取子串
+
+        :param start: 起始索引（包含）
+        :param end: 结束索引（不包含），默认到末尾
+        :return: 截取的子串
+        """
+        current = self._to_str()
+        if end is None:
+            return current[start:]
+        return current[start:end]
+
+    def starts_with(self, prefix: str) -> bool:
+        """判断是否以指定字符串开头
+
+        :param prefix: 前缀字符串
+        :return: 是返回 True，否则返回 False
+        """
+        return self._to_str().startswith(prefix)
+
+    def ends_with(self, suffix: str) -> bool:
+        """判断是否以指定字符串结尾
+
+        :param suffix: 后缀字符串
+        :return: 是返回 True，否则返回 False
+        """
+        return self._to_str().endswith(suffix)
+
+    def contains(self, string: str) -> bool:
+        """判断是否包含指定字符串
+
+        :param string: 要查找的子串
+        :return: 包含返回 True，否则返回 False
+        """
+        return string in self._to_str()
+
+    def trim(self) -> "StrBuilder":
+        """去除首尾空白字符
+
+        :return: self，支持链式调用
+        """
+        current = self._to_str().strip()
+        self._parts = [current]
+        self._length = len(current)
+        return self
+
+    def clear(self) -> "StrBuilder":
+        """清空构建器
+
+        :return: self，支持链式调用
+        """
+        self._parts.clear()
+        self._length = 0
+        return self
+
+    def __str__(self) -> str:
+        return self._to_str()
+
+    def __len__(self) -> int:
+        return self._length
+
+    def __repr__(self) -> str:
+        return f"StrBuilder({self._to_str()!r})"