funcguard 0.2.40__tar.gz → 0.2.42__tar.gz

{funcguard-0.2.40 → funcguard-0.2.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.40
+Version: 0.2.42
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -544,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.40 → funcguard-0.2.42}/README.md

@@ -517,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.40 → funcguard-0.2.42}/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.40 → funcguard-0.2.42}/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.40 → funcguard-0.2.42}/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.42/funcguard/pd_utils/statistics/agg_utils.py

@@ -0,0 +1,88 @@
+
+"""
+聚合(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,
+    to_dict: bool = True
+) -> 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。
+    - to_dict (bool)：是否将结果转换为字典，默认为True。
+
+    返回：
+    - 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)
+    
+    # 转换为字典返回
+    if to_dict:
+        return result_series.to_dict()
+    else:
+        return result_series

{funcguard-0.2.40 → funcguard-0.2.42}/funcguard/pd_utils/statistics/count_utils.py

@@ -12,7 +12,8 @@ def value_counts(
     conditions: Optional[Union[Tuple, List[Tuple]]] = None,
     logic: str = "and",
     true_mask: Optional[pd.Series] = None,
-    false_mask: Optional[pd.Series] = None
+    false_mask: Optional[pd.Series] = None,
+    to_dict: bool = True
 ) -> Mapping[Any, Union[int, float]]:
     """
     统计DataFrame指定列中不同值的计数数据。
@@ -29,6 +30,7 @@ def value_counts(
     - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"。
     - true_mask (pd.Series)：初始True掩码，默认为None。
     - false_mask (pd.Series)：初始False掩码，默认为None。
+    - to_dict (bool)：是否将结果转换为字典，默认为True。
 
     返回：
     - Mapping[Any, Union[int, float]]：以值为键，计数/百分比为值的字典。
@@ -75,7 +77,10 @@ def value_counts(
     )
 
     # 转换为字典返回
-    return result_series.to_dict()
+    if to_dict:
+        return result_series.to_dict()
+    else:
+        return result_series
 
 
 def count(

{funcguard-0.2.40 → funcguard-0.2.42}/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
 
 
 
@@ -112,7 +113,8 @@ class DataFrameStatistics:
         conditions: Optional[Union[Tuple, List[Tuple]]] = None,
         logic: str = "and",
         true_mask: Optional[pd.Series] = None,
-        false_mask: Optional[pd.Series] = None
+        false_mask: Optional[pd.Series] = None,
+        to_dict: bool = True
     ) -> Mapping[Any, Union[int, float]]:
         """
         统计指定列中不同值的计数数据，自动使用内部掩码参数
@@ -127,7 +129,9 @@ class DataFrameStatistics:
         - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"
         - true_mask (pd.Series)：初始True掩码，默认为None（使用内部缓存）
         - false_mask (pd.Series)：初始False掩码，默认为None（使用内部缓存）
+        - to_dict (bool)：是否将结果转换为字典，默认为True。
 
+        
         返回：
         - Mapping[Any, Union[int, float]]：以值为键，计数/百分比为值的字典
 
@@ -150,7 +154,58 @@ class DataFrameStatistics:
             false_mask = self._false_mask
         return _original_value_counts(
             self._df, column, mode, sort, dropna,
-            conditions, logic, true_mask, false_mask
+            conditions, logic, true_mask, false_mask, to_dict
+        )
+
+
+    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,
+        to_dict: bool = True
+    ) -> 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（使用内部缓存）
+        - to_dict (bool)：是否将结果转换为字典，默认为True。
+
+        
+        返回：
+        - 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, to_dict
         )
 
 

{funcguard-0.2.40 → funcguard-0.2.42}/funcguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.40
+Version: 0.2.42
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -544,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.40 → funcguard-0.2.42}/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.40 → funcguard-0.2.42}/setup.py

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