funcguard 0.2.49__tar.gz → 0.2.51__tar.gz

{funcguard-0.2.49 → funcguard-0.2.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.49
+Version: 0.2.51
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -97,17 +97,20 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
 
-# 基础用法 - 选择属性填写模式
+# 基础用法 - 选择属性填写模式（默认超时10秒）
 result = ask_select(
     options={True: "需要填写属性", False: "不需要填写属性", "all": "不限制"},
     default_key="all",
     prompt="请选择属性填写模式",
-    timeout=5
+    timeout=10
 )
 print(f"用户选择: {result}")  # 返回 True, False 或 "all"
 
@@ -116,7 +119,7 @@ env = ask_select(
     options={"dev": "开发环境", "test": "测试环境", "prod": "生产环境"},
     default_key="dev",
     prompt="请选择部署环境",
-    timeout=3
+    timeout=10
 )
 print(f"当前环境: {env}")
 
@@ -125,11 +128,41 @@ count = ask_select(
     options={10: "10条", 50: "50条", 100: "100条"},
     default_key=50,
     prompt="查询数量",
-    timeout=5
+    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
+# 无超时模式 - 一直等待用户输入
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
+    timeout=None
+)
+print(f"用户选择: {result}")
+```
+
 ### HTTP请求
 
 FuncGuard 提供了强大的 HTTP 请求功能，支持自动重试、请求日志记录、以及 curl_cffi 兜底（用于绕过反爬虫检测）。详细文档请参考 [network.md](docs/network.md)。

{funcguard-0.2.49 → funcguard-0.2.51}/README.md

@@ -70,17 +70,20 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
 
-# 基础用法 - 选择属性填写模式
+# 基础用法 - 选择属性填写模式（默认超时10秒）
 result = ask_select(
     options={True: "需要填写属性", False: "不需要填写属性", "all": "不限制"},
     default_key="all",
     prompt="请选择属性填写模式",
-    timeout=5
+    timeout=10
 )
 print(f"用户选择: {result}")  # 返回 True, False 或 "all"
 
@@ -89,7 +92,7 @@ env = ask_select(
     options={"dev": "开发环境", "test": "测试环境", "prod": "生产环境"},
     default_key="dev",
     prompt="请选择部署环境",
-    timeout=3
+    timeout=10
 )
 print(f"当前环境: {env}")
 
@@ -98,11 +101,41 @@ count = ask_select(
     options={10: "10条", 50: "50条", 100: "100条"},
     default_key=50,
     prompt="查询数量",
-    timeout=5
+    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
+# 无超时模式 - 一直等待用户输入
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
+    timeout=None
+)
+print(f"用户选择: {result}")
+```
+
 ### HTTP请求
 
 FuncGuard 提供了强大的 HTTP 请求功能，支持自动重试、请求日志记录、以及 curl_cffi 兜底（用于绕过反爬虫检测）。详细文档请参考 [network.md](docs/network.md)。

{funcguard-0.2.49 → funcguard-0.2.51}/funcguard/core.py

@@ -92,46 +92,70 @@ 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 = 5,
+    timeout: int | None = 10,
 ):
     """
     显示一个数字选择菜单，接受用户输入，超时自动返回默认值。
 
     参数:
-        options: 字典，键为选项标识（任意类型），值为显示文本
-                 例如: {True: "需要填写属性", False: "不需要填写属性", "all": "不限制"}
-        default_key: 超时或输入无效时的默认返回值，若为None则使用最后一个选项的键
+        options: 字典或列表。
+                 字典模式: 键为选项标识，值为显示文本，返回选中的键
+                 列表模式: 元素为显示文本，返回选中的元素值
+                 例如: {True: "需要填写属性", False: "不需要填写属性"} 或 ["选项A", "选项B", "选项C"]
+        default_key: 超时或输入无效时的默认返回值
+                     字典模式下为某个键，若为None则使用最后一个选项的键
+                     列表模式下为某个元素值，若为None则使用最后一个元素
         prompt: 提示语前缀
-        timeout: 超时时间（秒），默认5秒
+        timeout: 超时时间（秒），默认10秒；若为None则不设置超时，一直等待用户输入
 
     返回:
-        用户选择的选项键（options中的某个键），或default_key
+        字典模式: 返回选项键（options中的某个键），或default_key
+        列表模式: 返回选中的列表元素值，或default_key
 
     示例:
+        >>> # 字典模式
         >>> result = ask_select(
         ...     {True: "需要填写属性", False: "不需要填写属性", "all": "不限制"},
         ...     default_key="all",
         ...     prompt="请选择属性填写模式",
-        ...     timeout=5,
+        ...     timeout=10,
+        ... )
+        >>> # 列表模式
+        >>> value = ask_select(
+        ...     ["选项A", "选项B", "选项C"],
+        ...     default_key="选项A",
+        ...     prompt="请选择一个选项",
+        ...     timeout=10,
         ... )
     """
     # 确保选项非空
     if not options:
-        raise ValueError("options字典不能为空")
-
-    # 设置默认值
-    if default_key is None:
-        default_key = list(options.keys())[-1]
-
-    # 构建选项列表（保持字典顺序）
-    items = list(options.items())
+        raise ValueError("options不能为空")
+
+    # 判断是字典，还是列表
+    is_list_mode = isinstance(options, list)
+
+    # 设置默认值并构建选项列表
+    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
@@ -149,12 +173,17 @@ def ask_select(
     thread = Thread(target=input_thread, daemon=True)
     thread.start()
 
-    # 倒计时显示
-    remaining = timeout
-    while remaining > 0 and thread.is_alive():
-        print(f"\r{prompt} ({option_lines})，{remaining} 秒后自动选择[{default_label}]: ", end="", flush=True)
-        time.sleep(1)
-        remaining -= 1
+    # 倒计时显示（仅当设置了timeout时）
+    if timeout is not None:
+        remaining = timeout
+        while remaining > 0 and thread.is_alive():
+            print(f"\r{prompt} ({option_lines})，{remaining} 秒后自动选择[{default_label}]: ", end="", flush=True)
+            time.sleep(1)
+            remaining -= 1
+    else:
+        # 无超时，直接显示提示并等待用户输入
+        print(f"{prompt} ({option_lines}): ", end="", flush=True)
+        thread.join()
 
     # 等待线程结束（如果用户已输入）或超时
     thread.join(0)
@@ -164,18 +193,18 @@ def ask_select(
     except Empty:
         user_input = None
 
-    if user_input is None:
+    if user_input is None and timeout is not None:
         print(f"\n超时，自动选择[{default_label}]")
         return default_key
 
     # 验证输入
     try:
-        choice = int(user_input)
+        choice = int(user_input)  # pyright: ignore[reportArgumentType]
         if 0 <= choice < len(items):
             selected_key, selected_label = items[choice]
             print(f"\n已选择 {choice}：{selected_label}")
             return selected_key
-    except ValueError:
+    except (ValueError, TypeError):
         pass
 
     # 输入无效，返回默认值

{funcguard-0.2.49 → funcguard-0.2.51}/funcguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcguard
-Version: 0.2.49
+Version: 0.2.51
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -97,17 +97,20 @@ except Exception as e:
 
 ### 交互式选择菜单
 
-使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示：
+使用 `ask_select` 函数创建一个带数字编号的交互式选择菜单（编号从0开始），支持超时自动选择和倒计时动态显示。`options` 参数支持**字典**或**列表**两种模式：
+
+#### 字典模式
+字典模式下，键为选项标识（任意类型），值为显示文本，返回用户选择的键：
 
 ```python
 from funcguard import ask_select
 
-# 基础用法 - 选择属性填写模式
+# 基础用法 - 选择属性填写模式（默认超时10秒）
 result = ask_select(
     options={True: "需要填写属性", False: "不需要填写属性", "all": "不限制"},
     default_key="all",
     prompt="请选择属性填写模式",
-    timeout=5
+    timeout=10
 )
 print(f"用户选择: {result}")  # 返回 True, False 或 "all"
 
@@ -116,7 +119,7 @@ env = ask_select(
     options={"dev": "开发环境", "test": "测试环境", "prod": "生产环境"},
     default_key="dev",
     prompt="请选择部署环境",
-    timeout=3
+    timeout=10
 )
 print(f"当前环境: {env}")
 
@@ -125,11 +128,41 @@ count = ask_select(
     options={10: "10条", 50: "50条", 100: "100条"},
     default_key=50,
     prompt="查询数量",
-    timeout=5
+    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
+# 无超时模式 - 一直等待用户输入
+result = ask_select(
+    options={"save": "保存", "discard": "放弃", "cancel": "取消"},
+    default_key="cancel",
+    prompt="文件已修改，请选择操作",
+    timeout=None
+)
+print(f"用户选择: {result}")
+```
+
 ### HTTP请求
 
 FuncGuard 提供了强大的 HTTP 请求功能，支持自动重试、请求日志记录、以及 curl_cffi 兜底（用于绕过反爬虫检测）。详细文档请参考 [network.md](docs/network.md)。

{funcguard-0.2.49 → funcguard-0.2.51}/setup.py

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