funcguard 0.2.54__tar.gz → 0.2.55__tar.gz

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

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

@@ -483,7 +483,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 +590,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.55}/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.55}/funcguard/pd_utils/convert_utils.py

@@ -10,6 +10,51 @@ 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: Optional[int] = 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"
@@ -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:
     """
     将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: Union[List[str], Dict[str, Optional[int]]],
+    decimal_places: Optional[int],
+) -> tuple[List[str], Dict[str, Optional[int]]]:
     """
-    转换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: Union[List[str], Dict[str, Optional[int]]],
+    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",
+    columns: Union[List[str], Dict[str, Optional[int]], None] = None,
     decimal_places: Optional[int] = 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,16 +247,8 @@ 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
 
@@ -296,4 +343,5 @@ def convert_str_datetime(
 
         df[column] = df[column].apply(parse_datetime)
 
-    return df
+    return df
+

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

@@ -1,5 +1,5 @@
 import pandas as pd
-from pandas.api.types import is_datetime64_any_dtype, is_timedelta64_dtype, is_numeric_dtype
+from pandas.api.types import is_datetime64_any_dtype, is_timedelta64_dtype
 from typing import Union, List, Any, Dict, Optional
 from .convert_utils import convert_numeric_series
 
@@ -64,32 +64,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.55}/funcguard.egg-info/PKG-INFO

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

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