funcguard 0.2.50__tar.gz → 0.2.53__tar.gz

{funcguard-0.2.50 → funcguard-0.2.53}/PKG-INFO

@@ -1,11 +1,16 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.50
+Version: 0.2.53
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
 Author-email: sky_ruocen@qq.com
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -97,7 +102,10 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
@@ -128,15 +136,36 @@ count = ask_select(
     timeout=10
 )
 print(f"查询 {count} 条数据")
+```
+
+#### 列表模式
+列表模式下，元素即为选项值，返回用户选中的元素：
+
+```python
+from funcguard import ask_select
+
+# 使用列表 - 返回选中的元素值
+env = ask_select(
+    options=["开发环境", "测试环境", "生产环境"],
+    default_key="开发环境",
+    prompt="请选择部署环境",
+    timeout=10
+)
+print(f"当前环境: {env}")  # 直接返回 "开发环境"、"测试环境" 或 "生产环境"
+```
+
+#### 无超时模式
+设置 `timeout=None` 可以禁用超时，一直等待用户输入：
 
+```python
 # 无超时模式 - 一直等待用户输入
-count = ask_select(
-    options={10: "10条", 50: "50条", 100: "100条"},
-    default_key=50,
-    prompt="查询数量",
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
     timeout=None
 )
-print(f"查询 {count} 条数据")
+print(f"用户选择: {result}")
 ```
 
 ### HTTP请求

{funcguard-0.2.50 → funcguard-0.2.53}/README.md

@@ -70,7 +70,10 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
@@ -101,15 +104,36 @@ count = ask_select(
     timeout=10
 )
 print(f"查询 {count} 条数据")
+```
+
+#### 列表模式
+列表模式下，元素即为选项值，返回用户选中的元素：
+
+```python
+from funcguard import ask_select
+
+# 使用列表 - 返回选中的元素值
+env = ask_select(
+    options=["开发环境", "测试环境", "生产环境"],
+    default_key="开发环境",
+    prompt="请选择部署环境",
+    timeout=10
+)
+print(f"当前环境: {env}")  # 直接返回 "开发环境"、"测试环境" 或 "生产环境"
+```
+
+#### 无超时模式
+设置 `timeout=None` 可以禁用超时，一直等待用户输入：
 
+```python
 # 无超时模式 - 一直等待用户输入
-count = ask_select(
-    options={10: "10条", 50: "50条", 100: "100条"},
-    default_key=50,
-    prompt="查询数量",
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
     timeout=None
 )
-print(f"查询 {count} 条数据")
+print(f"用户选择: {result}")
 ```
 
 ### HTTP请求

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/core.py

@@ -92,7 +92,7 @@ def retry_function( func , max_retries = 5 , execute_timeout = 90 , task_name =
 
 # 交互式选择菜单
 def ask_select(
-    options: dict,
+    options: dict | list,
     default_key = None,
     prompt: str = "请选择",
     timeout: int | None = 10,
@@ -101,37 +101,61 @@ def ask_select(
     显示一个数字选择菜单，接受用户输入，超时自动返回默认值。
 
     参数:
-        options: 字典，键为选项标识（任意类型），值为显示文本
-                 例如: {True: "需要填写属性", False: "不需要填写属性", "all": "不限制"}
-        default_key: 超时或输入无效时的默认返回值，若为None则使用最后一个选项的键
+        options: 字典或列表。
+                 字典模式: 键为选项标识，值为显示文本，返回选中的键
+                 列表模式: 元素为显示文本，返回选中的元素值
+                 例如: {True: "需要填写属性", False: "不需要填写属性"} 或 ["选项A", "选项B", "选项C"]
+        default_key: 超时或输入无效时的默认返回值
+                     字典模式下为某个键，若为None则使用最后一个选项的键
+                     列表模式下为某个元素值，若为None则使用最后一个元素
         prompt: 提示语前缀
         timeout: 超时时间（秒），默认10秒；若为None则不设置超时，一直等待用户输入
 
     返回:
-        用户选择的选项键（options中的某个键），或default_key
+        字典模式: 返回选项键（options中的某个键），或default_key
+        列表模式: 返回选中的列表元素值，或default_key
 
     示例:
+        >>> # 字典模式
         >>> result = ask_select(
         ...     {True: "需要填写属性", False: "不需要填写属性", "all": "不限制"},
         ...     default_key="all",
         ...     prompt="请选择属性填写模式",
         ...     timeout=10,
         ... )
+        >>> # 列表模式
+        >>> value = ask_select(
+        ...     ["选项A", "选项B", "选项C"],
+        ...     default_key="选项A",
+        ...     prompt="请选择一个选项",
+        ...     timeout=10,
+        ... )
     """
     # 确保选项非空
     if not options:
-        raise ValueError("options字典不能为空")
+        raise ValueError("options不能为空")
 
-    # 设置默认值
-    if default_key is None:
-        default_key = list(options.keys())[-1]
+    # 判断是字典，还是列表
+    is_list_mode = isinstance(options, list)
 
-    # 构建选项列表（保持字典顺序）
-    items = list(options.items())
+    # 设置默认值并构建选项列表
+    if is_list_mode:
+        # 列表模式: 将列表转为 {值: 显示文本} 的字典格式
+        if default_key is None:
+            default_key = options[-1]
+        items = [(value, value) for value in options]
+    else:
+        # 字典模式: 保持原有逻辑
+        if default_key is None:
+            default_key = list(options.keys())[-1]
+        items = list(options.items())
 
     # 显示选项
     option_lines = ", ".join([f"{i}-{label}" for i, (_, label) in enumerate(items)])
-    default_label = options.get(default_key, default_key)
+    if is_list_mode:
+        default_label = default_key
+    else:
+        default_label = options.get(default_key, default_key)
 
     # 使用线程实现跨平台超时输入
     from threading import Thread

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/ip_utils.py

@@ -51,7 +51,7 @@ def get_public_ip():
                     # 验证是否为有效的IP地址格式
                     if is_valid_ip(ip):
                         return ip
-            except:
+            except Exception:
                 continue
                 
         return None
@@ -80,7 +80,7 @@ def is_valid_ip(ip_string):
                 return False
                 
         return True
-    except:
+    except Exception:
         return False
 
 

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/pd_utils/convert_utils.py

@@ -134,6 +134,14 @@ def convert_columns(df: pd.DataFrame, columns: Dict[str, str], decimal_places: O
     return df
 
 
+def _has_decimal(df: pd.DataFrame, column: str) -> bool:
+    """检查列中是否存在 Decimal 类型值"""
+    for val in df[column]:
+        if pd.notna(val) and isinstance(val, Decimal):
+            return True
+    return False
+
+
 def convert_decimal(
     df: pd.DataFrame,
     columns: Union[List[str], Dict[str, str], None] = None,
@@ -182,20 +190,17 @@ def convert_decimal(
         # 检查列是否存在且为object类型 (只有object类型列才可能包含Decimal)
         if column not in df.columns or df[column].dtype != object:
             continue
-        # 检查列中的第一个非空值是否是Decimal类型
-        first_non_null = df[column].first_valid_index()
-        if first_non_null is None:
-            continue
-        if isinstance( df.at[first_non_null, column], Decimal ):  # pyright: ignore[reportArgumentType]
+        # 检查列中是否存在 Decimal 类型值
+        if _has_decimal(df, column):
             # 根据指定的类型进行转换
-            target_type = column_types[column]
-            if target_type == "int":
+            col_target_type = column_types[column]
+            if col_target_type == "int":
                 df[column] = df[column].astype(int)
-            elif target_type == "float":
+            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 target_type == "auto":
+            elif col_target_type == "auto":
                 df[column] = convert_numeric_series(df[column], decimal_places)
 
     return df

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/pd_utils/fill_round.py

@@ -24,6 +24,9 @@ def fill_na(
 
     返回：
     - pd.DataFrame：替换空值后的DataFrame。
+
+    注意：本函数直接修改传入的 DataFrame，不返回副本。如需保留原数据，
+    请在调用前使用 df.copy()。
     """
     _is_numeric_fill = isinstance(fill_value, (int, float))
 
@@ -76,10 +79,17 @@ def round_columns(
 
     返回：
     - 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.50 → funcguard-0.2.53}/funcguard/pd_utils/statistics/df_statistics.py

@@ -39,9 +39,13 @@ class DataFrameStatistics:
     # 重置 true_mask 和 false_mask
     def _reset_base_masks(self):
         """重置基础掩码为全True和全False"""
-        self._true_mask = pd.Series([True] * self._length, index=self._index)
-        self._false_mask = pd.Series([False] * self._length, index=self._index)
+        self._true_mask = pd.Series([True] * len(self._df), index=self._df.index)
+        self._false_mask = pd.Series([False] * len(self._df), index=self._df.index)
 
+    def _ensure_masks_valid(self):
+        """如果 DataFrame 发生变化，重新生成基础掩码"""
+        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,
@@ -58,6 +62,7 @@ class DataFrameStatistics:
         返回：
         - pd.Series：布尔掩码，True表示符合条件的行
         """
+        self._ensure_masks_valid()
         # 如果没有提供外部掩码，使用内部缓存的掩码
         if true_mask is None:
             true_mask = self._true_mask
@@ -96,6 +101,7 @@ class DataFrameStatistics:
         返回：
         - int：符合条件的数量
         """
+        self._ensure_masks_valid()
         # 如果没有提供外部掩码，使用内部缓存的掩码
         if true_mask is None:
             true_mask = self._true_mask
@@ -147,6 +153,7 @@ class DataFrameStatistics:
             >>> stats.value_counts("status", conditions=[("age", ">", 18)])
             {'active': 120, 'inactive': 30}
         """
+        self._ensure_masks_valid()
         # 如果没有提供外部掩码，使用内部缓存的掩码
         if true_mask is None:
             true_mask = self._true_mask
@@ -198,6 +205,7 @@ class DataFrameStatistics:
             >>> stats.group_agg("category", "amount", "sum", sort="desc")
             {'B': 2000, 'C': 1500, 'A': 1000}
         """
+        self._ensure_masks_valid()
         # 如果没有提供外部掩码，使用内部缓存的掩码
         if true_mask is None:
             true_mask = self._true_mask

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/pd_utils/statistics/mask_utils.py

@@ -35,8 +35,8 @@ def _is_not_empty(x):
         if pd.isna(x):
             return False
     except ValueError:
-        # pd.isna() 返回数组或产生歧义时，说明有值
-        return True
+        # pd.isna() 失败说明 x 不是可空的标量值，应视为有值
+        pass
     return True
 
 

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/printer.py

@@ -15,6 +15,9 @@ def print_progress(idx: int, total: int, message: str = "") -> None:
     :param message: 额外消息，默认为空字符串
     """
     # 计算当前进度百分比（0-100）
+    if total <= 0:
+        print(f"警告: total 必须大于 0（当前值: {total}）")
+        return
     percent = int(idx / total * 100)
     
     # 构建进度条：

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard/tools.py

@@ -42,7 +42,7 @@ def md5_hash(*texts: str, encoding: str = "utf-8") -> str:
 
 
 # 生成 base64 格式的 Basic Auth 字符串
-def encode_basic_auth(username, password):
+def encode_basic_auth(username: str, password: str) -> str:
     # 将 Username 和 Password 拼接成字符串
     auth_str = f"{username}:{password}"
 
@@ -189,7 +189,12 @@ def send_request(
 
     # ---------- 结果处理 ----------
     if return_type == "json":
-        result = response.json()
+        try:
+            result = response.json()
+        except (json.JSONDecodeError, ValueError) as e:
+            raise ValueError(
+                f"响应内容不是有效的 JSON 格式 (status={response.status_code}): {e}"
+            ) from e
         if request_log.save_path:
             res_log = {}
             save_fields = [
@@ -247,7 +252,7 @@ def check_url_valid(
             response = curl_cffi_request(
                 "HEAD", url, req_kwargs, curl_fallback_impersonate, auto_retry
             )
-            if response.status_code == 200: # type: ignore
+            if response is not None and response.status_code == 200: # type: ignore
                 return True
         except Exception:
             pass

{funcguard-0.2.50 → funcguard-0.2.53}/funcguard.egg-info/PKG-INFO

@@ -1,11 +1,16 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.50
+Version: 0.2.53
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
 Author-email: sky_ruocen@qq.com
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -97,7 +102,10 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
@@ -128,15 +136,36 @@ count = ask_select(
     timeout=10
 )
 print(f"查询 {count} 条数据")
+```
+
+#### 列表模式
+列表模式下，元素即为选项值，返回用户选中的元素：
+
+```python
+from funcguard import ask_select
+
+# 使用列表 - 返回选中的元素值
+env = ask_select(
+    options=["开发环境", "测试环境", "生产环境"],
+    default_key="开发环境",
+    prompt="请选择部署环境",
+    timeout=10
+)
+print(f"当前环境: {env}")  # 直接返回 "开发环境"、"测试环境" 或 "生产环境"
+```
+
+#### 无超时模式
+设置 `timeout=None` 可以禁用超时，一直等待用户输入：
 
+```python
 # 无超时模式 - 一直等待用户输入
-count = ask_select(
-    options={10: "10条", 50: "50条", 100: "100条"},
-    default_key=50,
-    prompt="查询数量",
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
     timeout=None
 )
-print(f"查询 {count} 条数据")
+print(f"用户选择: {result}")
 ```
 
 ### HTTP请求

{funcguard-0.2.50 → funcguard-0.2.53}/setup.py

@@ -9,7 +9,7 @@ except FileNotFoundError:
 
 setup(
     name='funcguard',
-    version='0.2.50',
+    version='0.2.53',
     packages=find_packages(),
     install_requires=[
         'requests',
@@ -24,6 +24,11 @@ setup(
     url='https://github.com/tinycen/funcguard',
     classifiers=[
         'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Programming Language :: Python :: 3.13',
+        'Programming Language :: Python :: 3.14',
         'License :: OSI Approved :: MIT License',
         'Operating System :: OS Independent',
     ],