funcguard 0.2.39__tar.gz → 0.2.41__tar.gz

{funcguard-0.2.39 → funcguard-0.2.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.39
+Version: 0.2.41
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -32,16 +32,16 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 
 ## 功能特点
 
-| 分类 | 功能描述 |
-|------|----------|
-| **核心功能** | 函数执行超时控制、函数执行失败自动重试 |
-| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 |
-| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） |
-| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 |
-| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 |
-| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 |
-| **计算工具** | 数值差异格式化（如+5、-3等） |
-| **日志工具** | 彩色日志输出、logger配置 |
+| 分类 | 功能描述 | 文档 |
+|------|----------|------|
+| **核心功能** | 函数执行超时控制、函数执行失败自动重试 | - |
+| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 | [查看](./docs/network.md) |
+| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） | [查看](./docs/time_utils.md) |
+| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 | - |
+| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 | - |
+| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 | [查看](./docs/pd_utils.md) |
+| **计算工具** | 数值差异格式化（如+5、-3等） | - |
+| **日志工具** | 彩色日志输出、logger配置 | - |
 
 ## 安装/升级
 
@@ -124,6 +124,16 @@ response = send_request(
     timeout=30
 )
 print(response)
+
+# 流式传输请求（用于大文件下载）
+response = send_request(
+    method="GET",
+    url="https://api.example.com/largefile",
+    stream=True  # 启用流式传输，通过 iter_content() 分块读取
+)
+for chunk in response.iter_content(chunk_size=8192):
+    # 处理数据块
+    pass
 ```
 
 #### 自动重试
@@ -534,7 +544,9 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_fill_na` / `pd_fill_nat` | 数据填充 | [查看](docs/pandas/fill.md) |
 | `pd_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
-| `pd_filter` / `pd_count` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |
+| `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) |

{funcguard-0.2.39 → funcguard-0.2.41}/README.md

@@ -5,16 +5,16 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 
 ## 功能特点
 
-| 分类 | 功能描述 |
-|------|----------|
-| **核心功能** | 函数执行超时控制、函数执行失败自动重试 |
-| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 |
-| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） |
-| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 |
-| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 |
-| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 |
-| **计算工具** | 数值差异格式化（如+5、-3等） |
-| **日志工具** | 彩色日志输出、logger配置 |
+| 分类 | 功能描述 | 文档 |
+|------|----------|------|
+| **核心功能** | 函数执行超时控制、函数执行失败自动重试 | - |
+| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 | [查看](./docs/network.md) |
+| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） | [查看](./docs/time_utils.md) |
+| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 | - |
+| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 | - |
+| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 | [查看](./docs/pd_utils.md) |
+| **计算工具** | 数值差异格式化（如+5、-3等） | - |
+| **日志工具** | 彩色日志输出、logger配置 | - |
 
 ## 安装/升级
 
@@ -97,6 +97,16 @@ response = send_request(
     timeout=30
 )
 print(response)
+
+# 流式传输请求（用于大文件下载）
+response = send_request(
+    method="GET",
+    url="https://api.example.com/largefile",
+    stream=True  # 启用流式传输，通过 iter_content() 分块读取
+)
+for chunk in response.iter_content(chunk_size=8192):
+    # 处理数据块
+    pass
 ```
 
 #### 自动重试
@@ -507,7 +517,9 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_fill_na` / `pd_fill_nat` | 数据填充 | [查看](docs/pandas/fill.md) |
 | `pd_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
-| `pd_filter` / `pd_count` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |
+| `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) |

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard/__init__.py

@@ -30,6 +30,8 @@ from .pd_utils import (
     pd_build_masks,
     pd_combine_masks,
     pd_count,
+    pd_value_counts,
+    pd_group_agg,
     DataFrameStatistics,
 
 )
@@ -101,6 +103,8 @@ __all__ = [
     "pd_build_masks",
     "pd_combine_masks",
     "pd_count",
+    "pd_value_counts",
+    "pd_group_agg",
     "DataFrameStatistics",
     
     # 计算工具

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard/pd_utils/__init__.py

@@ -1,8 +1,23 @@
 import pandas as pd
 from .fill_round import fill_na, round_columns
 from .date_utils import fill_nat, cal_date_diff
-from .convert_utils import convert_columns, convert_decimal, convert_numeric_series, load_json, convert_str_datetime, convert_datetime_str
-from .statistics import pd_build_mask, pd_build_masks, pd_combine_masks, pd_count, DataFrameStatistics
+from .convert_utils import (
+    convert_columns, 
+    convert_decimal, 
+    convert_numeric_series, 
+    load_json, 
+    convert_str_datetime, 
+    convert_datetime_str
+)
+from .statistics import (
+    pd_build_mask, 
+    pd_build_masks, 
+    pd_combine_masks, 
+    pd_count, 
+    pd_value_counts, 
+    pd_group_agg, 
+    DataFrameStatistics
+)
 from .filter import pd_filter
 
 # 启用未来行为：禁止静默降级
@@ -32,5 +47,7 @@ __all__ = [
     "pd_build_masks",
     "pd_combine_masks",
     "pd_count",
+    "pd_value_counts",
+    "pd_group_agg",
     "DataFrameStatistics",
 ]

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard/pd_utils/statistics/__init__.py

@@ -5,6 +5,7 @@ from .mask_utils import (
     build_base_mask as pd_build_masks,
     combine_masks as pd_combine_masks,
 )
+from .agg_utils import group_agg as pd_group_agg
 
 __all__ = [
     # 掩码构建函数
@@ -14,6 +15,8 @@ __all__ = [
     # 统计函数
     "pd_count",
     "pd_value_counts",
+    # 聚合函数
+    "pd_group_agg",
     # 统计分析类
     "DataFrameStatistics",
 ]

funcguard-0.2.41/funcguard/pd_utils/statistics/agg_utils.py

@@ -0,0 +1,83 @@
+
+"""
+聚合(aggregation)操作工具模块。
+
+提供DataFrame分组聚合统计功能，支持按指定列分组后对另一列进行
+sum、mean、max、min、count、median、std、var等聚合计算。
+"""
+
+import pandas as pd
+from typing import Any, Dict, Optional, Union, List, Tuple
+from .mask_utils import build_single_mask, build_base_mask
+
+
+def group_agg(
+    df: pd.DataFrame,
+    group_col: str,
+    agg_col: str,
+    agg_func: str = "sum",
+    sort: Optional[str] = None,
+    conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+    logic: str = "and",
+    true_mask: Optional[pd.Series] = None,
+    false_mask: Optional[pd.Series] = None
+) -> Dict[Any, Union[int, float]]:
+    """
+    按指定列分组，对另一列进行聚合统计。
+
+    参数：
+    - df (pd.DataFrame)：输入的DataFrame。
+    - group_col (str)：分组列名（如A列）。
+    - agg_col (str)：聚合列名（如B列）。
+    - agg_func (str)：聚合函数，支持 "sum"、"mean"、"max"、"min"、"count"、"median"、"std"、"var"，
+        默认为 "sum"。
+    - sort (Optional[str])：排序方式，"asc" 表示升序，"desc" 表示降序，
+        默认为None表示按分组列的原始顺序。
+    - conditions (Optional[Union[Tuple, List[Tuple]]])：可选的过滤条件，
+        格式与count函数相同。如果提供，则只统计符合条件的行。
+    - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"。
+    - true_mask (pd.Series)：初始True掩码，默认为None。
+    - false_mask (pd.Series)：初始False掩码，默认为None。
+
+    返回：
+    - Dict[Any, Union[int, float]]：以分组值为键，聚合结果为值的字典。
+
+    示例：
+        >>> group_agg(df, "category", "amount", "sum")
+        {'A': 1000, 'B': 2000, 'C': 1500}
+        >>> group_agg(df, "category", "amount", "mean")
+        {'A': 100.0, 'B': 200.0, 'C': 150.0}
+        >>> group_agg(df, "category", "amount", "sum", sort="desc")
+        {'B': 2000, 'C': 1500, 'A': 1000}
+        >>> group_agg(df, "category", "amount", "sum", conditions=[("status", "==", "active")])
+        {'A': 800, 'B': 1500}
+    """
+    # 参数校验
+    valid_agg_funcs = ("sum", "mean", "max", "min", "count", "median", "std", "var")
+    if agg_func not in valid_agg_funcs:
+        raise ValueError(f"agg_func 参数必须是 {valid_agg_funcs} 之一，当前值: {agg_func}")
+    if sort is not None and sort not in ("asc", "desc"):
+        raise ValueError(f"sort 参数必须是 'asc'、'desc' 或 None，当前值: {sort}")
+
+    # 如果有过滤条件，先应用条件筛选
+    if conditions is not None:
+        if isinstance(conditions, tuple):
+            mask = build_single_mask(df, conditions)
+        else:
+            mask = build_base_mask(df, conditions, logic, true_mask, false_mask)
+        filtered_df = df[mask]
+    else:
+        filtered_df = df
+
+    # 使用pandas的groupby进行聚合
+    grouped = filtered_df.groupby(group_col)[agg_col]
+    result_series = grouped.agg(agg_func)
+
+    # 排序处理
+    if sort == "asc":
+        result_series = result_series.sort_values(ascending=True)
+    elif sort == "desc":
+        result_series = result_series.sort_values(ascending=False)
+
+    # 转换为字典返回
+    return result_series.to_dict()

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard/pd_utils/statistics/df_statistics.py

@@ -2,6 +2,7 @@ import pandas as pd
 from typing import  Any, Dict, List, Tuple, Union, Optional, Mapping
 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
 
 
 
@@ -154,6 +155,54 @@ class DataFrameStatistics:
         )
 
 
+    def group_agg(
+        self,
+        group_col: str,
+        agg_col: str,
+        agg_func: str = "sum",
+        sort: Optional[str] = None,
+        conditions: Optional[Union[Tuple, List[Tuple]]] = None,
+        logic: str = "and",
+        true_mask: Optional[pd.Series] = None,
+        false_mask: Optional[pd.Series] = None
+    ) -> Dict[Any, Union[int, float]]:
+        """
+        按指定列分组，对另一列进行聚合统计，自动使用内部掩码参数
+
+        参数：
+        - group_col (str)：分组列名（如A列）
+        - agg_col (str)：聚合列名（如B列）
+        - agg_func (str)：聚合函数，支持 "sum"、"mean"、"max"、"min"、"count"、"median"、"std"、"var"，
+            默认为 "sum"
+        - sort (Optional[str])：排序方式，"asc" 表示升序，"desc" 表示降序，
+            默认为None表示按分组列的原始顺序
+        - conditions (Optional[Union[Tuple, List[Tuple]]])：可选的过滤条件
+        - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"
+        - true_mask (pd.Series)：初始True掩码，默认为None（使用内部缓存）
+        - false_mask (pd.Series)：初始False掩码，默认为None（使用内部缓存）
+
+        返回：
+        - Dict[Any, Union[int, float]]：以分组值为键，聚合结果为值的字典
+
+        示例：
+            >>> stats.group_agg("category", "amount", "sum")
+            {'A': 1000, 'B': 2000, 'C': 1500}
+            >>> stats.group_agg("category", "amount", "mean")
+            {'A': 100.0, 'B': 200.0, 'C': 150.0}
+            >>> stats.group_agg("category", "amount", "sum", sort="desc")
+            {'B': 2000, 'C': 1500, 'A': 1000}
+        """
+        # 如果没有提供外部掩码，使用内部缓存的掩码
+        if true_mask is None:
+            true_mask = self._true_mask
+        if false_mask is None:
+            false_mask = self._false_mask
+        return _original_group_agg(
+            self._df, group_col, agg_col, agg_func, sort,
+            conditions, logic, true_mask, false_mask
+        )
+
+
     def dataframe_info(self) -> Dict[str, Any]:
         """获取DataFrame的基本信息"""
         return {

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard/tools.py

@@ -113,6 +113,7 @@ def send_request(
     request_log: RequestLog = RequestLog(),
     curl_fallback: bool = False,
     curl_fallback_impersonate: str = _DEFAULT_IMPERSONATE,
+    stream: bool = False,
 ) -> Union[Dict, str, requests.Response]:
     """
     发送HTTP请求的通用函数
@@ -132,6 +133,8 @@ def send_request(
                           需与对应浏览器 User-Agent 匹配（未自定义 UA 时由内部自动注入）。
                           支持的值见 _IMPERSONATE_UA_MAP。
                           若 send_request 配置了 auto_retry，curl_cffi 兜底会继承同样的重试参数。
+    :param stream: 是否使用流式传输，默认 False。启用后响应内容不会立即下载，
+                   可通过 iter_content() 分块读取，适合大文件下载场景。
     :return: 请求结果
     """
     payload = None
@@ -149,7 +152,7 @@ def send_request(
     if headers is None:
         headers = {}
 
-    req_kwargs = {"headers": headers, "timeout": timeout}
+    req_kwargs = {"headers": headers, "timeout": timeout, "stream": stream}
 
     # POST/PUT/PATCH 等需要 body 的方法，始终传递 data（即使为空）
     # GET/DELETE/HEAD 等无 body 方法，仅在有实际内容时传递

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.39
+Version: 0.2.41
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -32,16 +32,16 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 
 ## 功能特点
 
-| 分类 | 功能描述 |
-|------|----------|
-| **核心功能** | 函数执行超时控制、函数执行失败自动重试 |
-| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 |
-| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） |
-| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 |
-| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 |
-| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 |
-| **计算工具** | 数值差异格式化（如+5、-3等） |
-| **日志工具** | 彩色日志输出、logger配置 |
+| 分类 | 功能描述 | 文档 |
+|------|----------|------|
+| **核心功能** | 函数执行超时控制、函数执行失败自动重试 | - |
+| **网络请求** | HTTP请求封装（支持自动重试）、MD5哈希、Basic Auth编码 | [查看](./docs/network.md) |
+| **时间工具** | 时间日志记录、耗时统计、执行时间监控和警告、时间等待（带倒计时） | [查看](./docs/time_utils.md) |
+| **打印工具** | 格式化分隔线、块打印、标题打印、进度条显示 | - |
+| **IP工具** | 局域网IP检测、公网IP检测、IP格式验证 | - |
+| **pandas工具** | 数据填充、类型转换、JSON解析、数据筛选、统计分析 | [查看](./docs/pd_utils.md) |
+| **计算工具** | 数值差异格式化（如+5、-3等） | - |
+| **日志工具** | 彩色日志输出、logger配置 | - |
 
 ## 安装/升级
 
@@ -124,6 +124,16 @@ response = send_request(
     timeout=30
 )
 print(response)
+
+# 流式传输请求（用于大文件下载）
+response = send_request(
+    method="GET",
+    url="https://api.example.com/largefile",
+    stream=True  # 启用流式传输，通过 iter_content() 分块读取
+)
+for chunk in response.iter_content(chunk_size=8192):
+    # 处理数据块
+    pass
 ```
 
 #### 自动重试
@@ -534,7 +544,9 @@ print(f"当前价格: {current_price}, 变化: {price_change}")  # 输出: 当
 | `pd_fill_na` / `pd_fill_nat` | 数据填充 | [查看](docs/pandas/fill.md) |
 | `pd_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
-| `pd_filter` / `pd_count` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
+| `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |
+| `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) |

{funcguard-0.2.39 → funcguard-0.2.41}/funcguard.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ funcguard/pd_utils/filter.py
 funcguard/pd_utils/json_utils/__init__.py
 funcguard/pd_utils/json_utils/json_parser.py
 funcguard/pd_utils/statistics/__init__.py
+funcguard/pd_utils/statistics/agg_utils.py
 funcguard/pd_utils/statistics/count_utils.py
 funcguard/pd_utils/statistics/df_statistics.py
 funcguard/pd_utils/statistics/mask_utils.py

{funcguard-0.2.39 → funcguard-0.2.41}/setup.py

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