funcguard 0.2.54__tar.gz → 0.2.56__tar.gz

{funcguard-0.2.54 → funcguard-0.2.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.54
+Version: 0.2.56
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -188,6 +188,15 @@ response = send_request(
 )
 print(response)
 
+# 带 URL 查询参数的 GET 请求
+response = send_request(
+    method="GET",
+    url="https://api.example.com/users",
+    params={"page": 1, "size": 20, "search": "张三"}
+    # 等价于: https://api.example.com/users?page=1&size=20&search=%E5%BC%A0%E4%B8%89
+)
+print(response)
+
 # POST 请求（自动将 dict/list 转为 JSON）
 response = send_request(
     method="POST",
@@ -515,7 +524,7 @@ FuncGuard提供了丰富的pandas数据处理功能，包括数据填充、类
 
 ```python
 import pandas as pd
-from funcguard.pd_utils import fill_na, convert_columns, round_columns, load_json
+from funcguard.pd_utils import fill_na, convert_columns, load_json
 
 # 快速示例
 df = pd.DataFrame({
@@ -622,7 +631,8 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_group_agg` | 分组聚合统计 | [查看](docs/pandas/agg.md) |
 | `pd_build_mask` / `pd_build_masks` / `pd_combine_masks` | 掩码构建 | [查看](docs/pandas/mask.md) |
 | `DataFrameStatistics` | 统计分析 | [查看](docs/pandas/statistics.md) |
-| `pd_cal_date_diff` / `pd_round_columns` | 日期计算和数值舍入 | [查看](docs/pandas/date.md) |
+| `pd_cal_date_diff` | 日期计算 | [查看](docs/pandas/date.md) |
+| `pd_round_columns` | 数值舍入 | [查看](docs/pandas/convert.md) |
 
 ### 计算工具
 

{funcguard-0.2.54 → funcguard-0.2.56}/README.md

@@ -156,6 +156,15 @@ response = send_request(
 )
 print(response)
 
+# 带 URL 查询参数的 GET 请求
+response = send_request(
+    method="GET",
+    url="https://api.example.com/users",
+    params={"page": 1, "size": 20, "search": "张三"}
+    # 等价于: https://api.example.com/users?page=1&size=20&search=%E5%BC%A0%E4%B8%89
+)
+print(response)
+
 # POST 请求（自动将 dict/list 转为 JSON）
 response = send_request(
     method="POST",
@@ -483,7 +492,7 @@ FuncGuard提供了丰富的pandas数据处理功能，包括数据填充、类
 
 ```python
 import pandas as pd
-from funcguard.pd_utils import fill_na, convert_columns, round_columns, load_json
+from funcguard.pd_utils import fill_na, convert_columns, load_json
 
 # 快速示例
 df = pd.DataFrame({
@@ -590,7 +599,8 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_group_agg` | 分组聚合统计 | [查看](docs/pandas/agg.md) |
 | `pd_build_mask` / `pd_build_masks` / `pd_combine_masks` | 掩码构建 | [查看](docs/pandas/mask.md) |
 | `DataFrameStatistics` | 统计分析 | [查看](docs/pandas/statistics.md) |
-| `pd_cal_date_diff` / `pd_round_columns` | 日期计算和数值舍入 | [查看](docs/pandas/date.md) |
+| `pd_cal_date_diff` | 日期计算 | [查看](docs/pandas/date.md) |
+| `pd_round_columns` | 数值舍入 | [查看](docs/pandas/convert.md) |
 
 ### 计算工具
 

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/__init__.py

@@ -1,3 +1,9 @@
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("funcguard")
+except Exception:
+    __version__ = "unknown"
+
 from .core import timeout_handler, retry_function, ask_select
 from .tools import send_request, curl_cffi_request, check_url_valid, encode_basic_auth, md5_hash
 from .time_utils import (

funcguard-0.2.56/funcguard/data_models/request_models.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class RequestLog:
+    save_method: bool | None = True
+    save_url: bool | None = True
+    save_headers: bool | None = True
+    save_body: bool | None = True
+    save_response: bool | None = True
+    save_path: str | None = ""

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/ip_utils.py

@@ -53,7 +53,8 @@ def get_public_ip():
                         return ip
             except Exception:
                 continue
-                
+        
+        print("警告: 所有公网IP查询服务均失败，请检查网络连接")
         return None
     except Exception as e:
         print(f"获取公网IP地址失败: {e}")

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/log_utils.py

@@ -2,7 +2,7 @@
 
 import logging
 import sys
-from typing import Optional, TextIO, Union, cast
+from typing import TextIO, cast
 
 
 class ColoredFormatter(logging.Formatter):
@@ -92,7 +92,7 @@ if not hasattr(logging.Logger, "progress"):
     setattr(logging.Logger, "progress", _logger_progress)
 
 
-def _normalize_level(level: Union[int, str]) -> int:
+def _normalize_level(level: int | str) -> int:
     """
     规范化日志等级。
 
@@ -113,32 +113,32 @@ def _normalize_level(level: Union[int, str]) -> int:
 
 
 def setup_logger(
-    name: Optional[str] = None,
-    level: Union[int, str] = logging.DEBUG,
-    stream: Optional[TextIO] = None,
+    name: str | None = None,
+    level: int | str = logging.DEBUG,
+    stream: TextIO | None = None,
     message_only: bool = False,
 ) -> SuccessLogger:
     """
     创建并配置彩色日志输出。
 
     Args:
-        name: logger 的名称，默认 全局共享1个 logger 实例。
+        name: logger 的名称，默认全局共享1个 logger 实例。
             示例：
-            # 在 network.py
-            logger_a = setup_logger("network")
-            logger_a.debug("网络调试信息")
-
-            # 在 db.py
-            logger_b = setup_logger("db")
-            logger_b.debug("数据库调试信息")
-        作用:
-            通过不同名称创建的 logger 互不干扰，适合在大型项目中使用。
-                            每个 logger 设置不同的日志级别、格式、输出流等。
-                level: 日志等级。支持 int 或字符串，默认 "DEBUG"。根据等级过滤后交给 handler 输出。
-                    常用等级：DEBUG(10), INFO(20), SUCCESS(25), WARNING(30), PROGRESS(35), ERROR(40), CRITICAL(50)。
-                    字符串支持："DEBUG"、"INFO"、"PROGRESS"、"SUCCESS"、"WARNING"/"WARN"、"ERROR"、"CRITICAL"/"FATAL"（大小写不敏感）。
-            stream: 输出流，默认 sys.stdout。
-            message_only: 是否仅输出日志消息（不包含时间与等级），默认 False。
+                # 在 network.py
+                logger_a = setup_logger("network")
+                logger_a.debug("网络调试信息")
+
+                # 在 db.py
+                logger_b = setup_logger("db")
+                logger_b.debug("数据库调试信息")
+
+            作用：通过不同名称创建的 logger 互不干扰，适合在大型项目中使用。
+            每个 logger 设置不同的日志级别、格式、输出流等。
+        level: 日志等级。支持 int 或字符串，默认 "DEBUG"。根据等级过滤后交给 handler 输出。
+            常用等级：DEBUG(10), INFO(20), SUCCESS(25), WARNING(30), PROGRESS(35), ERROR(40), CRITICAL(50)。
+            字符串支持："DEBUG"、"INFO"、"PROGRESS"、"SUCCESS"、"WARNING"/"WARN"、"ERROR"、"CRITICAL"/"FATAL"（大小写不敏感）。
+        stream: 输出流，默认 sys.stdout。
+        message_only: 是否仅输出日志消息（不包含时间与等级），默认 False。
 
     Returns:
         配置完成的 logger。示例:

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/__init__.py

@@ -1,5 +1,5 @@
 import pandas as pd
-from .fill_round import fill_na, round_columns
+from .fill_utils import fill_na
 from .date_utils import fill_nat, cal_date_diff
 from .convert_utils import (
     convert_series,
@@ -8,7 +8,8 @@ from .convert_utils import (
     convert_numeric_series, 
     load_json, 
     convert_str_datetime, 
-    convert_datetime_str
+    convert_datetime_str,
+    round_columns
 )
 from .statistics import (
     pd_build_mask, 
@@ -29,7 +30,6 @@ __all__ = [
 	# 数据填充类
 	'fill_na',
     'fill_nat',
-	'round_columns',
     'cal_date_diff',
 
 	# 数据转换类
@@ -40,6 +40,7 @@ __all__ = [
     'convert_str_datetime',
 	'convert_datetime_str',
 	'load_json',
+    'round_columns',
 
     # 数据筛选类
     "pd_filter",

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/convert_utils.py

@@ -1,6 +1,6 @@
 import pandas as pd
 from decimal import Decimal
-from typing import Union, List, Dict, Any, Optional, Literal
+from typing import Any, Literal
 from pandas import (
     Int64Dtype,
     Float64Dtype,
@@ -10,10 +10,55 @@ from pandas import (
 from .json_utils import json_loads
 
 
+# 数据类型映射常量
+TYPE_MAPPING = {
+    "int": Int64Dtype(),
+    "float": Float64Dtype(),
+    "str": StringDtype(),
+    "bool": BooleanDtype(),
+    "datetime": "datetime64[ns]",  # datetime使用字符串形式
+}
+
+
+def convert_columns(df: pd.DataFrame, columns: dict[str, str], decimal_places: int | None = None) -> pd.DataFrame:
+    """
+    转换DataFrame中指定列的数据类型。
+
+    参数：
+    - df (pd.DataFrame)：输入的DataFrame。
+    - columns (Dict[str, str])：
+        要转换类型的字典，键为列名，值为目标数据类型。
+        支持的数据类型：'int', 'float', 'str', 'bool', 'datetime'。
+    - decimal_places (int, optional)：当转换为'float'类型时保留的小数位数，默认为None表示不限制
+
+    返回：
+    - pd.DataFrame：列类型转换后的DataFrame。
+    """
+    for column, target_type in columns.items():
+        if column in df.columns and target_type in TYPE_MAPPING:
+            try:
+                if target_type == "datetime":
+                    df[column] = pd.to_datetime(df[column], errors="coerce")
+                elif target_type == "float":
+                    df[column] = df[column].astype(
+                        TYPE_MAPPING[target_type]
+                    )  # pyright: ignore[reportArgumentType]
+                    if decimal_places is not None:
+                        df[column] = df[column].round(decimal_places)
+                else:
+                    df[column] = df[column].astype(
+                        TYPE_MAPPING[target_type]
+                    )  # pyright: ignore[reportArgumentType]
+            except (ValueError, TypeError):
+                # 如果转换失败，保持原类型
+                pass
+    return df
+
+
 def convert_series(
     data: pd.Series,
     return_type: Literal["dict", "df", "series"] = "dict"
-) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+) -> dict[Any, int | float] | pd.DataFrame | pd.Series:
     """
     将 pandas Series 格式化为指定的返回类型。
 
@@ -52,29 +97,20 @@ def convert_series(
         return data
 
 
-# 数据类型映射常量
-TYPE_MAPPING = {
-    "int": Int64Dtype(),
-    "float": Float64Dtype(),
-    "str": StringDtype(),
-    "bool": BooleanDtype(),
-    "datetime": "datetime64[ns]",  # datetime使用字符串形式
-}
-
-
-def convert_numeric_series(series: pd.Series, decimal_places: Optional[int] = None) -> pd.Series:
+def convert_numeric_series(series: pd.Series, decimal_places: int | None = None) -> pd.Series:
     """
     将Series转换为数值类型，并自动检测应该使用 int 还是 float。
+    当 decimal_places == 0 时，round后自动转为Int64类型。
 
     流程：
     1. 先统一转换为 float64（确保所有值都是数值类型）
-    2. 检测非空值中是否存在小数
-    3. 如果没有小数则转换为 int64，否则保持 float64
-    4. 如果指定了decimal_places且为float类型，则执行round操作
+    2. 如果指定了decimal_places，先执行round操作
+    3. 当decimal_places为0时，round后自动转为Int64类型
+    4. 否则检测非空值中是否存在小数，没有小数则转换为Int64，否则保持float64
 
     参数：
     - series (pd.Series)：输入的Series
-    - decimal_places (int, optional)：当结果为float类型时保留的小数位数，默认为None表示不限制
+    - decimal_places (int, optional)：保留的小数位数，默认为None表示不限制
 
     返回：
     - pd.Series：转换后的Series
@@ -82,55 +118,87 @@ def convert_numeric_series(series: pd.Series, decimal_places: Optional[int] = No
     # 先统一转换为 float
     series = series.astype(float)
 
+    # 如果指定了decimal_places，先执行round操作
+    if decimal_places is not None:
+        series = series.round(decimal_places)
+        if decimal_places == 0:
+            # decimal_places为0时，round后自动转为Int64类型（支持NaN）
+            return series.astype("Int64")
+
     # 检测是否存在小数
     non_null_values = series.dropna()
     if len(non_null_values) > 0:
         # 检查是否有任何值有小数部分
         has_decimal = any(non_null_values != non_null_values.round())
         if not has_decimal:
-            # 没有小数，转换为 int64，并返回int64类型的Series
-            return series.astype("int64")
+            # 没有小数，转换为 Int64（支持NaN），并返回Int64类型的Series
+            return series.astype("Int64")
 
     # 有小数或全是空值，保持 float64
-    # 如果指定了decimal_places，对float类型执行round操作
-    if decimal_places is not None:
-        series = series.round(decimal_places)
-    
     return series
 
 
-def convert_columns(df: pd.DataFrame, columns: Dict[str, str], decimal_places: Optional[int] = None) -> pd.DataFrame:
+def _resolve_columns_decimal_places(
+    columns: list[str] | dict[str, int | None],
+    decimal_places: int | None,
+) -> tuple[list[str], dict[str, int | None]]:
     """
-    转换DataFrame中指定列的数据类型。
+    解析 columns 参数，返回目标列列表和每列对应的 decimal_places 字典。
+
+    参数：
+    - columns: 列名列表或字典
+    - decimal_places: 默认的 decimal_places 值
+
+    返回：
+    - target_columns: 目标列列表
+    - column_decimal_places: 每列对应的 decimal_places 字典
+    """
+    if isinstance(columns, list):
+        target_columns = columns
+        column_decimal_places = {col: decimal_places for col in target_columns}
+    elif isinstance(columns, dict):
+        for col, val in columns.items():
+            if val is not None and not isinstance(val, int):
+                raise TypeError(
+                    f"列 '{col}' 的 decimal_places 必须是整数或 None，得到 {type(val).__name__}"
+                )
+        target_columns = list(columns.keys())
+        column_decimal_places = {col: val for col, val in columns.items()}
+    else:
+        raise TypeError(
+            f"columns 参数类型不支持，期望 List[str] 或 Dict[str, Optional[int]]，"
+            f"得到 {type(columns).__name__}"
+        )
+
+    return target_columns, column_decimal_places
+
+
+def round_columns(
+    df: pd.DataFrame,
+    columns: list[str] | dict[str, int | None],
+    decimal_places: int = 0,
+) -> pd.DataFrame:
+    """
+    对DataFrame中指定列进行四舍五入操作。
+    自动支持 Decimal 类型列和 NaN 值。
 
     参数：
     - df (pd.DataFrame)：输入的DataFrame。
-    - columns (Dict[str, str])：
-        要转换类型的字典，键为列名，值为目标数据类型。
-        支持的数据类型：'int', 'float', 'str', 'bool', 'datetime'。
-    - decimal_places (int, optional)：当转换为'float'类型时保留的小数位数，默认为None表示不限制
+    - columns (List[str], Dict[str, Optional[int]])：
+        * 如果为List[str]，则对指定列进行四舍五入
+        * 如果为Dict[str, Optional[int]]，则键为列名，值为该列的decimal_places（可选）
+    - decimal_places (int, optional)：保留的小数位数，默认为0。
 
     返回：
-    - pd.DataFrame：列类型转换后的DataFrame。
+    - pd.DataFrame：四舍五入后的DataFrame。
     """
-    for column, target_type in columns.items():
-        if column in df.columns and target_type in TYPE_MAPPING:
-            try:
-                if target_type == "datetime":
-                    df[column] = pd.to_datetime(df[column], errors="coerce")
-                elif target_type == "float":
-                    df[column] = df[column].astype(
-                        TYPE_MAPPING[target_type]
-                    )  # pyright: ignore[reportArgumentType]
-                    if decimal_places is not None:
-                        df[column] = df[column].round(decimal_places)
-                else:
-                    df[column] = df[column].astype(
-                        TYPE_MAPPING[target_type]
-                    )  # pyright: ignore[reportArgumentType]
-            except (ValueError, TypeError):
-                # 如果转换失败，保持原类型
-                pass
+    target_columns, column_decimal_places = _resolve_columns_decimal_places(
+        columns, decimal_places
+    )
+    for column in target_columns:
+        if column in df.columns:
+            col_dp = column_decimal_places.get(column, decimal_places)
+            df[column] = convert_numeric_series(df[column], col_dp)
     return df
 
 
@@ -144,23 +212,22 @@ def _has_decimal(df: pd.DataFrame, column: str) -> bool:
 
 def convert_decimal(
     df: pd.DataFrame,
-    columns: Union[List[str], Dict[str, str], None] = None,
-    target_type: str = "int",
-    decimal_places: Optional[int] = None,
+    columns: list[str] | dict[str, int | None] | None = None,
+    decimal_places: int | None = None,
 ) -> pd.DataFrame:
     """
-    检测DataFrame中是否包含Decimal类型的字段，如果包含则转换为指定的数据类型。
+    检测DataFrame中是否包含Decimal类型的字段，如果包含则转换为数值类型。
+    自动检测：先转为float，如果没有小数则转为int，否则保持float。
+    当 decimal_places == 0 时，round后自动转为Int64类型。
 
     参数：
     - df (pd.DataFrame)：输入的DataFrame。
-    - columns (List[str], Dict[str, str], or None)：
+    - columns (List[str], Dict[str, Optional[int]], or None)：
         * 如果为None，则检测所有列
-        * 如果为List[str]，则检测指定列，发现Decimal时转换为target_type指定的类型
-        * 如果为Dict[str, str]，则键为列名，值为当发现Decimal时要转换的目标类型（支持'int'、'float'或'auto'）
-    - target_type (str, optional)：当columns为列表时的默认转换类型，默认为'int'。
-                                支持'int'、'float'或'auto'。
-                                'auto'表示自动检测：先转为float，如果没有小数则转为int。
-    - decimal_places (int, optional)：当target_type为'auto'或'float'时，保留的小数位数，默认为None表示不限制
+        * 如果为List[str]，则检测指定列
+        * 如果为Dict[str, Optional[int]]，则键为列名，值为该列的decimal_places（可选）
+    - decimal_places (int, optional)：保留的小数位数，默认为None表示不限制。
+                                     当decimal_places为0时，round后自动转为Int64类型。
 
     返回：
     - pd.DataFrame：转换后的DataFrame。
@@ -168,23 +235,11 @@ def convert_decimal(
     if columns is None:
         # 检测所有列
         target_columns = df.columns.tolist()
-        column_types = {col: target_type for col in target_columns}
-    elif isinstance(columns, list):
-        # 检测指定列，使用默认类型
-        target_columns = columns
-        column_types = {col: target_type for col in target_columns}
-    elif isinstance(columns, dict):
-        # 使用字典指定的类型
-        target_columns = list(columns.keys())
-        column_types = columns
-
-    # 验证target_type和字典中的类型是否有效
-    valid_types = {"int", "float", "auto"}
-    for col, target_type in column_types.items():
-        if target_type not in valid_types:
-            raise ValueError(
-                f"无效的类型指定：{target_type}。支持的类型为：{valid_types}"
-            )
+        column_decimal_places = {col: decimal_places for col in target_columns}
+    else:
+        target_columns, column_decimal_places = _resolve_columns_decimal_places(
+            columns, decimal_places
+        )
 
     for column in target_columns:
         # 检查列是否存在且为object类型 (只有object类型列才可能包含Decimal)
@@ -192,23 +247,15 @@ def convert_decimal(
             continue
         # 检查列中是否存在 Decimal 类型值
         if _has_decimal(df, column):
-            # 根据指定的类型进行转换
-            col_target_type = column_types[column]
-            if col_target_type == "int":
-                df[column] = df[column].astype(int)
-            elif col_target_type == "float":
-                df[column] = df[column].astype(float)
-                if decimal_places is not None:
-                    df[column] = df[column].round(decimal_places)
-            elif col_target_type == "auto":
-                df[column] = convert_numeric_series(df[column], decimal_places)
+            col_dp = column_decimal_places.get(column, decimal_places)
+            df[column] = convert_numeric_series(df[column], col_dp)
 
     return df
 
 
 def load_json(
     df: pd.DataFrame,
-    columns: List[str],
+    columns: list[str],
     empty_to_dict: bool = True,
 ) -> pd.DataFrame:
     """
@@ -233,7 +280,7 @@ def load_json(
 
 def convert_datetime_str(
     df: pd.DataFrame,
-    columns: List[str],
+    columns: list[str],
     include_time: bool = True,
     include_seconds: bool = True,
     fail_fill: Any = "",
@@ -272,28 +319,23 @@ def convert_datetime_str(
 
 
 def convert_str_datetime(
-    df: pd.DataFrame, columns: List[str]
+    df: pd.DataFrame, columns: list[str]
 ) -> pd.DataFrame:
     """
     将DataFrame中指定字符串列转换为datetime类型。
 
     参数：
     - df (pd.DataFrame)：输入的DataFrame。
-    - columns (List[str])：要转换为datetime类型的列名列表。
+    - columns (list[str])：要转换为datetime类型的列名列表。
 
     返回：
     - pd.DataFrame：转换后的DataFrame。
     """
-    def parse_datetime(value: str) -> Union[pd.Timestamp, str]:
-        try:
-            return pd.to_datetime(value)
-        except (ValueError, TypeError):
-            return value
-
     for column in columns:
         if column not in df.columns:
             continue
 
-        df[column] = df[column].apply(parse_datetime)
+        df[column] = pd.to_datetime(df[column], errors="coerce")
+
+    return df
 
-    return df

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/date_utils.py

@@ -1,14 +1,14 @@
 import pandas as pd
 from datetime import datetime
 from pandas.api.types import is_datetime64_any_dtype, is_timedelta64_dtype
-from typing import Union, List, Any, Optional
+from typing import Any
 
 
 # 单位 -> 对应秒数
 _UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
 
 
-def _resolve_date(df: pd.DataFrame, date: Union[str, datetime]) -> pd.Series:
+def _resolve_date(df: pd.DataFrame, date: str | datetime) -> pd.Series:
     """将列名或 datetime 统一转换为 pd.Series"""
     if isinstance(date, datetime):
         return pd.Series([date] * len(df), index=df.index)
@@ -21,7 +21,7 @@ def _resolve_date(df: pd.DataFrame, date: Union[str, datetime]) -> pd.Series:
 
 
 def fill_nat(
-    df: pd.DataFrame, columns: Union[List[str], str], fill_value: Any = ""
+    df: pd.DataFrame, columns: list[str] | str, fill_value: Any = ""
 ) -> pd.DataFrame:
     """将指定列的 NaT（Datetime/Timedelta）替换为空字符串"""
 
@@ -45,11 +45,11 @@ def fill_nat(
 def cal_date_diff(
     df: pd.DataFrame,
     target_column: str,
-    old_date: Union[str, datetime],
-    new_date: Union[str, datetime],
+    old_date: str | datetime,
+    new_date: str | datetime,
     unit: str = "h",
     decimal_places: int = 1,
-    nat: Optional[int] = None
+    nat: int | None = None
 ) -> pd.DataFrame:
     """
     计算DataFrame中两列日期的时间差，并将结果填充到指定列。

funcguard-0.2.54/funcguard/pd_utils/fill_round.py → funcguard-0.2.56/funcguard/pd_utils/fill_utils.py

@@ -1,14 +1,15 @@
 import pandas as pd
-from pandas.api.types import is_datetime64_any_dtype, is_timedelta64_dtype, is_numeric_dtype
-from typing import Union, List, Any, Dict, Optional
+from pandas.api.types import is_datetime64_any_dtype, is_timedelta64_dtype
+from typing import Any
 from .convert_utils import convert_numeric_series
 
 
 def fill_na(
     df: pd.DataFrame,
-    columns: Union[List[str], Dict[str, Any]],
+    columns: list[str] | dict[str, Any],
     fill_value: Any = "",
-    decimal_places: Optional[int] = None,
+    decimal_places: int | None = None,
+    copy: bool = False,
 ) -> pd.DataFrame:
     """
     替换DataFrame中指定列的空值为指定值。
@@ -21,13 +22,16 @@ def fill_na(
         * 如果为List[str]且为空列表，则对所有列应用fill_value填充
     - fill_value (Any, optional)：当columns为列表时的默认填充值，默认为空字符串。
     - decimal_places (int, optional)：当进行数值转换时保留的小数位数，默认为None表示不限制
+    - copy (bool, optional)：是否在副本上操作而非修改原 DataFrame，默认 False。
 
     返回：
     - pd.DataFrame：替换空值后的DataFrame。
 
-    注意：本函数直接修改传入的 DataFrame，不返回副本。如需保留原数据，
-    请在调用前使用 df.copy()。
+    注意：当 copy=False 时，本函数直接修改传入的 DataFrame。
+    如需保留原数据，请设置 copy=True 或在调用前使用 df.copy()。
     """
+    if copy:
+        df = df.copy()
     _is_numeric_fill = isinstance(fill_value, (int, float))
 
     if isinstance(columns, list):
@@ -64,32 +68,3 @@ def fill_na(
                 column_dtype = df[column].dtype
                 raise TypeError(f"处理列 '{column}' (类型: {column_dtype}) 时出错: {e}") from e
     return df
-
-
-def round_columns(
-    df: pd.DataFrame, columns: List[str], decimal_places: int = 0
-) -> pd.DataFrame:
-    """
-    对DataFrame中指定列进行四舍五入操作。
-
-    参数：
-    - df (pd.DataFrame)：输入的DataFrame。
-    - columns (List[str])：要进行四舍五入的列名列表。
-    - decimal_places (int, optional)：保留的小数位数，默认为0。
-
-    返回：
-    - pd.DataFrame：四舍五入后的DataFrame。
-
-    注意：
-    - 当 decimal_places 为 0 时，结果列会自动转换为 Int64（可空整数）类型。
-    - decimal.Decimal 类型在 pandas 中以 object dtype 存储，不被视为数值类型，
-      调用本函数会抛出 TypeError。需先手动将其转换为 float 类型再调用本函数。
-    """
-    for column in columns:
-        if column in df.columns:
-            if not is_numeric_dtype(df[column]):
-                raise TypeError(f"列 '{column}' 不是数值类型，无法执行四舍五入操作")
-            df[column] = df[column].round(decimal_places)
-            if decimal_places == 0:
-                df[column] = df[column].astype('Int64')
-    return df

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/filter.py

@@ -1,12 +1,11 @@
 import pandas as pd
-from typing import Union, List, Tuple
 
 from .statistics.mask_utils import build_single_mask, build_base_mask, combine_masks
 
 
 def pd_filter(
     df: pd.DataFrame,
-    conditions: Union[Tuple, List[Tuple], List[pd.Series]],
+    conditions: tuple | list[tuple] | list[pd.Series],
     logic: str = "and"
 ) -> pd.DataFrame:
     """

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/statistics/agg_utils.py

@@ -6,7 +6,7 @@ sum、mean、max、min、count、median、std、var等聚合计算。
 """
 
 import pandas as pd
-from typing import Any, Dict, Optional, Union, List, Tuple, Literal
+from typing import Any, Literal
 from .mask_utils import build_single_mask, build_base_mask
 from ..convert_utils import convert_series
 
@@ -16,13 +16,13 @@ def group_agg(
     group_col: str,
     agg_col: str,
     agg_func: str = "sum",
-    sort: Optional[str] = None,
-    conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+    sort: str | None = None,
+    conditions: tuple | list[tuple] | None = None,
     logic: str = "and",
-    true_mask: Optional[pd.Series] = None,
-    false_mask: Optional[pd.Series] = None,
+    true_mask: pd.Series | None = None,
+    false_mask: pd.Series | None = None,
     return_type: Literal["dict", "df", "series"] = "dict"
-) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+) -> dict[Any, int | float] | pd.DataFrame | pd.Series:
     """
     按指定列分组，对另一列进行聚合统计。
 

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/statistics/count_utils.py

@@ -1,5 +1,6 @@
 import pandas as pd
-from typing import List, Tuple, Union, Optional, Dict, Any, Mapping, Literal
+from collections.abc import Mapping
+from typing import Any, Literal
 from .mask_utils import build_single_mask, build_base_mask
 from ..convert_utils import convert_series
 
@@ -8,14 +9,14 @@ def value_counts(
     df: pd.DataFrame,
     column: str,
     mode: str = "count",
-    sort: Optional[str] = None,
+    sort: str | None = None,
     dropna: bool = True,
-    conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+    conditions: tuple | list[tuple] | None = None,
     logic: str = "and",
-    true_mask: Optional[pd.Series] = None,
-    false_mask: Optional[pd.Series] = None,
+    true_mask: pd.Series | None = None,
+    false_mask: pd.Series | None = None,
     return_type: Literal["dict", "df", "series"] = "dict"
-) -> Union[Mapping[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+) -> Mapping[Any, int | float] | pd.DataFrame | pd.Series:
     """
     统计DataFrame指定列中不同值的计数数据。
 
@@ -84,10 +85,10 @@ def value_counts(
 
 def count(
     df: pd.DataFrame,
-    conditions: Union[Tuple, List[Tuple]],
+    conditions: tuple | list[tuple],
     logic: str = "and",
-    true_mask: Optional[pd.Series] = None,
-    false_mask: Optional[pd.Series] = None
+    true_mask: pd.Series | None = None,
+    false_mask: pd.Series | None = None
 ) -> int:
     """
     使用int sum 方法，统计DataFrame中符合条件的非空值数量。

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/statistics/df_statistics.py

@@ -1,5 +1,6 @@
 import pandas as pd
-from typing import  Any, Dict, List, Tuple, Union, Optional, Mapping, Literal
+from collections.abc import Mapping
+from typing import Any, Literal
 from .mask_utils import build_single_mask as _original_build_single_mask, build_base_mask as _original_build_base_mask, combine_masks
 from .count_utils import count as _original_count, value_counts as _original_value_counts
 from .agg_utils import group_agg as _original_group_agg
@@ -32,9 +33,6 @@ class DataFrameStatistics:
         self._false_mask = None
         self._reset_base_masks()
 
-        # 方法继承
-        self.combine_masks = combine_masks
-
 
     # 重置 true_mask 和 false_mask
     def _reset_base_masks(self):
@@ -47,9 +45,16 @@ class DataFrameStatistics:
         if self._true_mask is not None and len(self._true_mask) != len(self._df):
             self._reset_base_masks()
 
-    def build_base_mask(self, conditions: List[Tuple], logic: str = "and",
-                       true_mask: Optional[pd.Series] = None,
-                       false_mask: Optional[pd.Series] = None) -> pd.Series:
+    def combine_masks(self, masks: list[pd.Series], logic: str = "and") -> pd.Series:
+        """
+        合并多个布尔掩码，支持复杂的嵌套逻辑组合（委托给模块级 combine_masks 函数）
+        """
+        return combine_masks(masks, logic)
+
+
+    def build_base_mask(self, conditions: list[tuple], logic: str = "and",
+                       true_mask: pd.Series | None = None,
+                       false_mask: pd.Series | None = None) -> pd.Series:
         """
         构建基础查询条件掩码，自动使用内部掩码参数
         
@@ -71,7 +76,7 @@ class DataFrameStatistics:
         return _original_build_base_mask(self._df, conditions, logic, true_mask, false_mask)
 
 
-    def build_single_mask(self, condition: Tuple) -> pd.Series:
+    def build_single_mask(self, condition: tuple) -> pd.Series:
         """
         构建单个掩码，用于简单条件判断，自动使用内部DataFrame
 
@@ -86,9 +91,9 @@ class DataFrameStatistics:
         return _original_build_single_mask(self._df, condition)
 
 
-    def count(self, conditions: Union[Tuple, List[Tuple]], logic: str = "and",
-             true_mask: Optional[pd.Series] = None,
-             false_mask: Optional[pd.Series] = None) -> int:
+    def count(self, conditions: tuple | list[tuple], logic: str = "and",
+             true_mask: pd.Series | None = None,
+             false_mask: pd.Series | None = None) -> int:
         """
         统计DataFrame中符合条件的非空值数量，自动使用内部掩码参数
 
@@ -114,14 +119,14 @@ class DataFrameStatistics:
         self,
         column: str,
         mode: str = "count",
-        sort: Optional[str] = None,
+        sort: str | None = None,
         dropna: bool = True,
-        conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+        conditions: tuple | list[tuple] | None = None,
         logic: str = "and",
-        true_mask: Optional[pd.Series] = None,
-        false_mask: Optional[pd.Series] = None,
+        true_mask: pd.Series | None = None,
+        false_mask: pd.Series | None = None,
         return_type: Literal["dict", "df", "series"] = "dict"
-    ) -> Union[Mapping[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+    ) -> Mapping[Any, int | float] | pd.DataFrame | pd.Series:
         """
         统计指定列中不同值的计数数据，自动使用内部掩码参数
 
@@ -170,13 +175,13 @@ class DataFrameStatistics:
         group_col: str,
         agg_col: str,
         agg_func: str = "sum",
-        sort: Optional[str] = None,
-        conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+        sort: str | None = None,
+        conditions: tuple | list[tuple] | None = None,
         logic: str = "and",
-        true_mask: Optional[pd.Series] = None,
-        false_mask: Optional[pd.Series] = None,
+        true_mask: pd.Series | None = None,
+        false_mask: pd.Series | None = None,
         return_type: Literal["dict", "df", "series"] = "dict"
-    ) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+    ) -> dict[Any, int | float] | pd.DataFrame | pd.Series:
         """
         按指定列分组，对另一列进行聚合统计，自动使用内部掩码参数
 
@@ -217,7 +222,7 @@ class DataFrameStatistics:
         )
 
 
-    def dataframe_info(self) -> Dict[str, Any]:
+    def dataframe_info(self) -> dict[str, Any]:
         """获取DataFrame的基本信息"""
         return {
             "shape": self._df.shape,

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/pd_utils/statistics/mask_utils.py

@@ -1,7 +1,5 @@
 import numpy as np
 import pandas as pd
-from typing import List, Tuple, Optional
-
 
 
 def _is_empty(x):
@@ -40,7 +38,7 @@ def _is_not_empty(x):
     return True
 
 
-def build_single_mask(df: pd.DataFrame, condition: Tuple) -> pd.Series:
+def build_single_mask(df: pd.DataFrame, condition: tuple) -> pd.Series:
     """
     构建单个掩码，用于简单条件判断
 
@@ -121,10 +119,10 @@ def build_single_mask(df: pd.DataFrame, condition: Tuple) -> pd.Series:
 
 def build_base_mask(
     df: pd.DataFrame,
-    conditions: List[Tuple],
+    conditions: list[tuple],
     logic: str = "and",
-    true_mask: Optional[pd.Series] = None,
-    false_mask: Optional[pd.Series] = None,
+    true_mask: pd.Series | None = None,
+    false_mask: pd.Series | None = None,
 ) -> pd.Series:
     """
     构建基础查询条件掩码
@@ -145,20 +143,26 @@ def build_base_mask(
     说明：
     - 如需复杂的嵌套逻辑组合，请使用 combine_masks 方法。
     """
+    def _and_mask(m, c):
+        return m & c
+
+    def _or_mask(m, c):
+        return m | c
+
     if logic == "and":
         mask = (
             true_mask
             if true_mask is not None
             else pd.Series([True] * len(df), index=df.index)
         )
-        operator_func = lambda m, c: m & c
+        operator_func = _and_mask
     elif logic == "or":
         mask = (
             false_mask
             if false_mask is not None
             else pd.Series([False] * len(df), index=df.index)
         )
-        operator_func = lambda m, c: m | c
+        operator_func = _or_mask
     else:
         raise ValueError(f"不支持的逻辑操作类型: {logic}，支持 'and' 或 'or'")
 
@@ -169,7 +173,7 @@ def build_base_mask(
     return mask
 
 
-def combine_masks(masks: List[pd.Series], logic: str = "and") -> pd.Series:
+def combine_masks(masks: list[pd.Series], logic: str = "and") -> pd.Series:
     """
     合并多个布尔掩码，支持复杂的嵌套逻辑组合
 

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard/tools.py

@@ -2,9 +2,10 @@ import json
 import base64
 import hashlib
 import requests
+import urllib.parse
 from curl_cffi import requests as cffi_requests
 
-from typing import Optional, Dict, Any, Union, Literal
+from typing import Any, Literal
 from .core import retry_function
 from .data_models import RequestLog
 
@@ -14,7 +15,7 @@ HttpMethod = Literal["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "TRACE",
 
 # impersonate 名称 → 对应真实浏览器 User-Agent 映射
 # 只维护 curl_cffi 支持的主流标识
-_IMPERSONATE_UA_MAP: Dict[str, str] = {
+_IMPERSONATE_UA_MAP: dict[str, str] = {
     "chrome123": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
     "chrome124": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
     "safari15_5": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Safari/605.1.15",
@@ -54,9 +55,9 @@ def encode_basic_auth(username: str, password: str) -> str:
 def curl_cffi_request(
     method: HttpMethod,
     url: str,
-    req_kwargs: Dict[str, Any],
+    req_kwargs: dict[str, Any],
     impersonate: str,
-    auto_retry: Optional[Dict[str, Any]] = None,
+    auto_retry: dict[str, Any] | None = None,
 ) -> Any:
     """
     使用 curl_cffi 发起请求的内部封装。
@@ -105,16 +106,17 @@ def curl_cffi_request(
 def send_request(
     method: HttpMethod,
     url: str,
-    headers: Optional[Dict[str, str]] = None,
-    data: Optional[Any] = None,
+    headers: dict[str, str] | None = None,
+    data: Any | None = None,
+    params: dict[str, Any] | None = None,
     return_type: str = "json",
     timeout: int = 60,
-    auto_retry: Optional[Dict[str, Any]] = None,
+    auto_retry: dict[str, Any] | None = None,
     request_log: RequestLog = RequestLog(),
     curl_fallback: bool = False,
     curl_fallback_impersonate: str = _DEFAULT_IMPERSONATE,
     stream: bool = False,
-) -> Union[Dict, str, requests.Response]:
+) -> dict | str | requests.Response:
     """
     发送HTTP请求的通用函数
 
@@ -122,6 +124,7 @@ def send_request(
     :param url: 请求URL
     :param headers: 请求头
     :param data: 请求数据
+    :param params: URL查询参数，dict 类型，会自动进行 URL 编码并拼接在 URL 后
     :param return_type: 返回类型（json, text, response）
     :param timeout: 请求超时时间
     :param auto_retry: 自动重试配置，格式为：
@@ -139,6 +142,10 @@ def send_request(
     """
     payload = None
 
+    # 处理 URL 查询参数
+    parameters = urllib.parse.urlencode(params) if params else ""
+    url = url + (f"?{parameters}" if parameters else "")
+
     if data is not None:
         if isinstance(data, dict) or isinstance(data, list):
             payload = json.dumps(data, ensure_ascii=False)
@@ -221,7 +228,7 @@ def send_request(
 # 检查URL是否有效
 def check_url_valid(
     url: str,
-    headers: Optional[Dict[str, str]] = None,
+    headers: dict[str, str] | None = None,
     max_retries: int = 3,
     curl_fallback: bool = False,
     curl_fallback_impersonate: str = _DEFAULT_IMPERSONATE,

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.54
+Version: 0.2.56
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -188,6 +188,15 @@ response = send_request(
 )
 print(response)
 
+# 带 URL 查询参数的 GET 请求
+response = send_request(
+    method="GET",
+    url="https://api.example.com/users",
+    params={"page": 1, "size": 20, "search": "张三"}
+    # 等价于: https://api.example.com/users?page=1&size=20&search=%E5%BC%A0%E4%B8%89
+)
+print(response)
+
 # POST 请求（自动将 dict/list 转为 JSON）
 response = send_request(
     method="POST",
@@ -515,7 +524,7 @@ FuncGuard提供了丰富的pandas数据处理功能，包括数据填充、类
 
 ```python
 import pandas as pd
-from funcguard.pd_utils import fill_na, convert_columns, round_columns, load_json
+from funcguard.pd_utils import fill_na, convert_columns, load_json
 
 # 快速示例
 df = pd.DataFrame({
@@ -622,7 +631,8 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_group_agg` | 分组聚合统计 | [查看](docs/pandas/agg.md) |
 | `pd_build_mask` / `pd_build_masks` / `pd_combine_masks` | 掩码构建 | [查看](docs/pandas/mask.md) |
 | `DataFrameStatistics` | 统计分析 | [查看](docs/pandas/statistics.md) |
-| `pd_cal_date_diff` / `pd_round_columns` | 日期计算和数值舍入 | [查看](docs/pandas/date.md) |
+| `pd_cal_date_diff` | 日期计算 | [查看](docs/pandas/date.md) |
+| `pd_round_columns` | 数值舍入 | [查看](docs/pandas/convert.md) |
 
 ### 计算工具
 

{funcguard-0.2.54 → funcguard-0.2.56}/funcguard.egg-info/SOURCES.txt

@@ -20,7 +20,7 @@ funcguard/data_models/request_models.py
 funcguard/pd_utils/__init__.py
 funcguard/pd_utils/convert_utils.py
 funcguard/pd_utils/date_utils.py
-funcguard/pd_utils/fill_round.py
+funcguard/pd_utils/fill_utils.py
 funcguard/pd_utils/filter.py
 funcguard/pd_utils/json_utils/__init__.py
 funcguard/pd_utils/json_utils/json_parser.py

{funcguard-0.2.54 → funcguard-0.2.56}/setup.py

@@ -9,7 +9,7 @@ except FileNotFoundError:
 
 setup(
     name='funcguard',
-    version='0.2.54',
+    version='0.2.56',
     packages=find_packages(),
     install_requires=[
         'requests',

funcguard-0.2.54/funcguard/data_models/request_models.py

@@ -1,12 +0,0 @@
-from dataclasses import dataclass
-
-from typing import Optional
-
-@dataclass
-class RequestLog:
-    save_method: Optional[bool] = True
-    save_url: Optional[bool] = True
-    save_headers: Optional[bool] = True
-    save_body: Optional[bool] = True
-    save_response: Optional[bool] = True
-    save_path: Optional[str] = ""