funcguard 0.2.41__tar.gz → 0.2.43__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.41
+Version: 0.2.43
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -542,7 +542,7 @@ 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_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` / `pd_convert_series` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
 | `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
 | `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |

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

@@ -515,7 +515,7 @@ 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_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` / `pd_convert_series` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
 | `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
 | `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |

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

@@ -14,7 +14,8 @@ from .pd_utils import (
     round_columns as pd_round_columns,
     cal_date_diff as pd_cal_date_diff,
 
-    # 数据类型转换类
+    # 数据转换类
+    convert_series as pd_convert_series,
     convert_columns as pd_convert_columns,
     convert_decimal as pd_convert_decimal,
     convert_numeric_series as pd_convert_numeric_series,
@@ -86,7 +87,8 @@ __all__ = [
     "pd_fill_nat",
     "pd_round_columns",
 
-    # 数据类型转换类
+    # 数据转换类
+    "pd_convert_series",
     "pd_cal_date_diff",
     "pd_convert_columns",
     "pd_convert_decimal",

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

@@ -2,6 +2,7 @@ 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_series,
     convert_columns, 
     convert_decimal, 
     convert_numeric_series, 
@@ -31,7 +32,8 @@ __all__ = [
 	'round_columns',
     'cal_date_diff',
 
-	# 数据类型转换类
+	# 数据转换类
+    'convert_series',
 	'convert_columns',
 	'convert_decimal',
     'convert_numeric_series',

{funcguard-0.2.41 → funcguard-0.2.43}/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
+from typing import Union, List, Dict, Any, Optional, Literal
 from pandas import (
     Int64Dtype,
     Float64Dtype,
@@ -10,6 +10,47 @@ from pandas import (
 from .json_utils import json_loads
 
 
+def convert_series(
+    data: pd.Series,
+    return_type: Literal["dict", "df", "series"] = "dict"
+) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
+    """
+    将 pandas Series 格式化为指定的返回类型。
+
+    参数：
+    - data (pd.Series)：输入的 pandas Series 数据。
+    - return_type (str)：返回类型，支持：
+        - "dict"：返回字典（默认）。
+        - "df"：返回 DataFrame。
+        - "series"：返回 pandas Series。
+
+    返回：
+    - Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]：
+        根据 return_type 返回格式化后的结果。
+
+    示例：
+        >>> series = pd.Series([1, 2, 3], index=['a', 'b', 'c'])
+        >>> convert_series(series, "dict")
+        {'a': 1, 'b': 2, 'c': 3}
+        >>> convert_series(series, "df")
+           0
+        a  1
+        b  2
+        c  3
+        >>> convert_series(series, "series")
+        a    1
+        b    2
+        c    3
+        dtype: int64
+    """
+
+    if return_type == "dict":
+        return data.to_dict()
+    elif return_type == "df":
+        return data.to_frame()
+    else:  # "series"
+        return data
+
 
 # 数据类型映射常量
 TYPE_MAPPING = {

{funcguard-0.2.41 → funcguard-0.2.43}/funcguard/pd_utils/statistics/agg_utils.py

@@ -1,4 +1,3 @@
-
 """
 聚合(aggregation)操作工具模块。
 
@@ -7,8 +6,9 @@ sum、mean、max、min、count、median、std、var等聚合计算。
 """
 
 import pandas as pd
-from typing import Any, Dict, Optional, Union, List, Tuple
+from typing import Any, Dict, Optional, Union, List, Tuple, Literal
 from .mask_utils import build_single_mask, build_base_mask
+from ..convert_utils import convert_series
 
 
 def group_agg(
@@ -20,8 +20,9 @@ def group_agg(
     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]]:
+    false_mask: Optional[pd.Series] = None,
+    return_type: Literal["dict", "df", "series"] = "dict"
+) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
     """
     按指定列分组，对另一列进行聚合统计。
 
@@ -38,9 +39,11 @@ def group_agg(
     - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"。
     - true_mask (pd.Series)：初始True掩码，默认为None。
     - false_mask (pd.Series)：初始False掩码，默认为None。
+    - return_type (str)：返回类型，支持 "dict"（字典）、"df"（DataFrame）和 "series"（Series），
+        默认为 "dict"。
 
     返回：
-    - Dict[Any, Union[int, float]]：以分组值为键，聚合结果为值的字典。
+    - Union[Dict[Any, Union[int, float]], pd.Series]：以分组值为键，聚合结果为值的字典或Series。
 
     示例：
         >>> group_agg(df, "category", "amount", "sum")
@@ -79,5 +82,5 @@ def group_agg(
     elif sort == "desc":
         result_series = result_series.sort_values(ascending=False)
 
-    # 转换为字典返回
-    return result_series.to_dict()
+    # 格式化并返回结果
+    return convert_series(result_series, return_type)

{funcguard-0.2.41 → funcguard-0.2.43}/funcguard/pd_utils/statistics/count_utils.py

@@ -1,6 +1,7 @@
 import pandas as pd
-from typing import List, Tuple, Union, Optional, Dict, Any, Mapping
+from typing import List, Tuple, Union, Optional, Dict, Any, Mapping, Literal
 from .mask_utils import build_single_mask, build_base_mask
+from ..convert_utils import convert_series
 
 
 def value_counts(
@@ -12,8 +13,9 @@ 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
-) -> Mapping[Any, Union[int, float]]:
+    false_mask: Optional[pd.Series] = None,
+    return_type: Literal["dict", "df", "series"] = "dict"
+) -> Union[Mapping[Any, Union[int, float]], pd.DataFrame, pd.Series]:
     """
     统计DataFrame指定列中不同值的计数数据。
 
@@ -29,9 +31,11 @@ def value_counts(
     - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"。
     - true_mask (pd.Series)：初始True掩码，默认为None。
     - false_mask (pd.Series)：初始False掩码，默认为None。
+    - return_type (str)：返回类型，支持 "dict"（字典）、"df"（DataFrame）和 "series"（Series），
+        默认为 "dict"。
 
     返回：
-    - Mapping[Any, Union[int, float]]：以值为键，计数/百分比为值的字典。
+    - Union[Mapping[Any, Union[int, float]], pd.Series]：以值为键，计数/百分比为值的字典或Series。
 
     示例：
         >>> value_counts(df, "status")
@@ -74,8 +78,8 @@ def value_counts(
         dropna=dropna
     )
 
-    # 转换为字典返回
-    return result_series.to_dict()
+    # 格式化并返回结果
+    return convert_series(result_series, return_type)
 
 
 def count(

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

@@ -1,5 +1,5 @@
 import pandas as pd
-from typing import  Any, Dict, List, Tuple, Union, Optional, Mapping
+from typing import  Any, Dict, List, Tuple, Union, Optional, Mapping, 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
@@ -43,8 +43,8 @@ class DataFrameStatistics:
         self._false_mask = pd.Series([False] * self._length, index=self._index)
 
 
-    def build_base_mask(self, conditions: List[Tuple], logic: str = "and", 
-                       true_mask: Optional[pd.Series] = None, 
+    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:
         """
         构建基础查询条件掩码，自动使用内部掩码参数
@@ -54,7 +54,7 @@ class DataFrameStatistics:
         - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"
         - true_mask (pd.Series)：初始True掩码，默认为None（使用内部缓存）
         - false_mask (pd.Series)：初始False掩码，默认为None（使用内部缓存）
-        
+
         返回：
         - pd.Series：布尔掩码，True表示符合条件的行
         """
@@ -69,10 +69,10 @@ class DataFrameStatistics:
     def build_single_mask(self, condition: Tuple) -> pd.Series:
         """
         构建单个掩码，用于简单条件判断，自动使用内部DataFrame
-        
+
         参数：
         - condition (Tuple)：条件元组，包含(列名, 运算符, 值)
-        
+
         返回：
         - pd.Series：布尔掩码，True表示符合条件的行
             **注意**：此Series是通过原生pandas表达式(df[col] > value)直接返回，
@@ -113,8 +113,9 @@ class DataFrameStatistics:
         conditions: Optional[Union[Tuple, List[Tuple]]] = None,
         logic: str = "and",
         true_mask: Optional[pd.Series] = None,
-        false_mask: Optional[pd.Series] = None
-    ) -> Mapping[Any, Union[int, float]]:
+        false_mask: Optional[pd.Series] = None,
+        return_type: Literal["dict", "df", "series"] = "dict"
+    ) -> Union[Mapping[Any, Union[int, float]], pd.DataFrame, pd.Series]:
         """
         统计指定列中不同值的计数数据，自动使用内部掩码参数
 
@@ -128,9 +129,11 @@ class DataFrameStatistics:
         - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"
         - true_mask (pd.Series)：初始True掩码，默认为None（使用内部缓存）
         - false_mask (pd.Series)：初始False掩码，默认为None（使用内部缓存）
+        - return_type (str)：返回类型，支持 "dict"（字典）、"df"（DataFrame）和 "series"（Series），
+            默认为 "dict"。
 
         返回：
-        - Mapping[Any, Union[int, float]]：以值为键，计数/百分比为值的字典
+        - Union[Mapping[Any, Union[int, float]], pd.DataFrame, pd.Series]：以值为键，计数/百分比为值的字典、DataFrame或Series
 
         示例：
             >>> stats.value_counts("status")
@@ -151,7 +154,7 @@ 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, return_type
         )
 
 
@@ -164,8 +167,9 @@ class DataFrameStatistics:
         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]]:
+        false_mask: Optional[pd.Series] = None,
+        return_type: Literal["dict", "df", "series"] = "dict"
+    ) -> Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]:
         """
         按指定列分组，对另一列进行聚合统计，自动使用内部掩码参数
 
@@ -180,9 +184,11 @@ class DataFrameStatistics:
         - logic (str)：逻辑操作类型，"and" 或 "or"，默认为 "and"
         - true_mask (pd.Series)：初始True掩码，默认为None（使用内部缓存）
         - false_mask (pd.Series)：初始False掩码，默认为None（使用内部缓存）
+        - return_type (str)：返回类型，支持 "dict"（字典）、"df"（DataFrame）和 "series"（Series），
+            默认为 "dict"。
 
         返回：
-        - Dict[Any, Union[int, float]]：以分组值为键，聚合结果为值的字典
+        - Union[Dict[Any, Union[int, float]], pd.DataFrame, pd.Series]：以分组值为键，聚合结果为值的字典、DataFrame或Series
 
         示例：
             >>> stats.group_agg("category", "amount", "sum")
@@ -199,7 +205,7 @@ class DataFrameStatistics:
             false_mask = self._false_mask
         return _original_group_agg(
             self._df, group_col, agg_col, agg_func, sort,
-            conditions, logic, true_mask, false_mask
+            conditions, logic, true_mask, false_mask, return_type
         )
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.41
+Version: 0.2.43
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -542,7 +542,7 @@ 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_convert_columns` / `pd_convert_decimal` / `pd_convert_numeric_series` / `pd_convert_str_datetime` / `pd_convert_datetime_str` / `pd_convert_series` | 类型转换 | [查看](docs/pandas/convert.md) |
 | `pd_load_json` | JSON解析 | [查看](docs/pandas/json.md) |
 | `pd_filter` | 数据筛选 | [查看](docs/pandas/filter.md) |
 | `pd_count` / `pd_value_counts` | 条件计数统计 | [查看](docs/pandas/count.md) |

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

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