funcguard 0.1.6__tar.gz → 0.1.8__tar.gz

{funcguard-0.1.6 → funcguard-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: funcguard
-Version: 0.1.6
+Version: 0.1.8
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -23,6 +23,7 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 - HTTP请求封装（支持自动重试）
 - 格式化打印工具（分隔线和块打印）
 - 时间日志记录和耗时统计
+- 函数执行时间监控和警告
 
 ## 安装/升级
 
@@ -110,10 +111,14 @@ print(response)
 
 ### 格式化打印
 
-使用`print_line`和`print_block`函数进行格式化打印，便于查看和调试：
+使用`print_line`、`print_block`和`print_title`函数进行格式化打印，便于查看和调试：
 
 ```python
-from funcguard import print_line, print_block
+from funcguard import print_line, print_block, print_title
+
+# 打印带等号的标题
+print_title("初始化分类器")  # 输出：=== 初始化分类器 ===
+print_title("训练完成", separator_char="*", padding_length=2)  # 输出：** 训练完成 **
 
 # 打印分隔线
 print_line()  # 默认使用40个'-'字符
@@ -174,12 +179,49 @@ for i in range(1, 101):
 
 ```
 
+### 执行时间监控
+
+使用`monitor_execution_time`函数监控函数执行时间：
+
+```python
+from funcguard import monitor_execution_time
+
+def some_function():
+    # 模拟一个耗时操作
+    import time
+    time.sleep(2)
+    return "操作完成"
+
+# 模式1：总是打印执行时间
+result = monitor_execution_time(
+    func=some_function,
+    print_mode=1
+)
+print(f"结果: {result}")
+
+# 模式2：仅在超过阈值时打印警告
+result = monitor_execution_time(
+    func=some_function,
+    warning_threshold=1.5,  # 设置1.5秒的警告阈值
+    print_mode=2
+)
+print(f"结果: {result}")
+
+# 模式0：不打印任何信息，仅返回结果和执行时间
+result, duration = monitor_execution_time(
+    func=some_function,
+    print_mode=0
+)
+print(f"结果: {result}, 耗时: {duration}秒")
+```
+
 时间日志功能特点：
 - 自动显示北京时间（UTC+8）
 - 支持进度显示和预计完成时间计算
 - 提供中英文双语统计信息
 - 可显示总耗时、平均耗时等详细统计
 - 支持i从0或从1开始的计数方式
+- 支持函数执行时间监控和警告
 
 ## API文档
 
@@ -222,6 +264,8 @@ for i in range(1, 101):
 - **返回值**: 根据return_type参数返回不同格式的响应数据
 - **异常**: 当请求失败且重试次数用尽后，抛出相应的异常
 
+### funcguard.time_utils
+
 #### time_log(message, i=0, max_num=0, s_time=None, start_from=0)
 
 - **参数**:
@@ -233,15 +277,42 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印带时间戳的日志信息，支持进度显示和预计完成时间计算
 
-#### time_diff(s_time=None, max_num=0, language="cn")
+#### time_diff(s_time=None, max_num=0, language="cn", return_duration=1)
 
 - **参数**:
   - `s_time`: 开始时间，默认为None
   - `max_num`: 任务数量，默认为0
   - `language`: 语言选择（"cn"中文，其他为英文），默认为"cn"
-- **返回值**: 如果s_time为None则返回当前时间，否则返回None
+  - `return_duration`: 返回模式，默认为1:
+    - 0 - 仅返回 total_seconds，不打印信息
+    - 1 - 仅打印信息,不返回 total_seconds
+    - 2 - 打印信息，并返回 total_seconds
+- **返回值**: 
+  - 如果s_time为None则返回当前时间
+  - 如果return_duration为0或2则返回持续时间（秒）
+  - 否则返回None
 - **功能**: 计算并打印任务执行时间统计信息，支持中英文双语输出
 
+#### monitor_execution_time(warning_threshold=None, print_mode=2, func=None, *args, **kwargs)
+
+- **参数**:
+  - `warning_threshold`: 警告阈值（秒），如果执行耗时超过此值则打印警告，默认为None
+  - `print_mode`: 打印模式，支持三种模式:
+    - 0 - 仅返回total_seconds，不打印任何信息
+    - 1 - 总是打印执行时间
+    - 2 - 仅在超时打印警告信息（默认）
+  - `func`: 要监控的函数
+  - `args`: 函数的位置参数
+  - `kwargs`: 函数的关键字参数
+- **返回值**: 
+  - print_mode == 0: 元组 (result, total_seconds) - 函数的执行结果和执行时间（秒）
+  - print_mode == 1: 函数的执行结果
+  - print_mode == 2: 函数的执行结果
+- **功能**: 监控函数执行时间，并返回函数的执行结果和执行时间
+- **注意**: 该方法内部使用 time_diff 函数，根据 print_mode 自动设置 return_duration 参数
+  - print_mode 为 0 或 2 时，设置 return_duration=0（ time_diff 仅返回total_seconds，不打印信息）
+  - print_mode 为 1 时，设置 return_duration=2（ time_diff 打印信息，并返回total_seconds）
+
 ### funcguard.printer
 
 #### print_line(separator_char: str = "-", separator_length: int = 40) -> None
@@ -252,6 +323,15 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印分隔线，用于分隔不同的打印块
 
+#### print_title(title: str, separator_char: str = "=", padding_length: int = 3) -> None
+
+- **参数**:
+  - `title`: 标题内容
+  - `separator_char`: 分隔符字符，默认为'='
+  - `padding_length`: 标题两侧的分隔符数量，默认为3
+- **返回值**: 无
+- **功能**: 打印带分隔符的标题，格式如：=== 初始化分类器 ===
+
 #### print_block(title: str, content: Any, separator_char: str = "-", separator_length: int = 40) -> None
 
 - **参数**:

{funcguard-0.1.6 → funcguard-0.1.8}/README.md

@@ -9,6 +9,7 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 - HTTP请求封装（支持自动重试）
 - 格式化打印工具（分隔线和块打印）
 - 时间日志记录和耗时统计
+- 函数执行时间监控和警告
 
 ## 安装/升级
 
@@ -96,10 +97,14 @@ print(response)
 
 ### 格式化打印
 
-使用`print_line`和`print_block`函数进行格式化打印，便于查看和调试：
+使用`print_line`、`print_block`和`print_title`函数进行格式化打印，便于查看和调试：
 
 ```python
-from funcguard import print_line, print_block
+from funcguard import print_line, print_block, print_title
+
+# 打印带等号的标题
+print_title("初始化分类器")  # 输出：=== 初始化分类器 ===
+print_title("训练完成", separator_char="*", padding_length=2)  # 输出：** 训练完成 **
 
 # 打印分隔线
 print_line()  # 默认使用40个'-'字符
@@ -160,12 +165,49 @@ for i in range(1, 101):
 
 ```
 
+### 执行时间监控
+
+使用`monitor_execution_time`函数监控函数执行时间：
+
+```python
+from funcguard import monitor_execution_time
+
+def some_function():
+    # 模拟一个耗时操作
+    import time
+    time.sleep(2)
+    return "操作完成"
+
+# 模式1：总是打印执行时间
+result = monitor_execution_time(
+    func=some_function,
+    print_mode=1
+)
+print(f"结果: {result}")
+
+# 模式2：仅在超过阈值时打印警告
+result = monitor_execution_time(
+    func=some_function,
+    warning_threshold=1.5,  # 设置1.5秒的警告阈值
+    print_mode=2
+)
+print(f"结果: {result}")
+
+# 模式0：不打印任何信息，仅返回结果和执行时间
+result, duration = monitor_execution_time(
+    func=some_function,
+    print_mode=0
+)
+print(f"结果: {result}, 耗时: {duration}秒")
+```
+
 时间日志功能特点：
 - 自动显示北京时间（UTC+8）
 - 支持进度显示和预计完成时间计算
 - 提供中英文双语统计信息
 - 可显示总耗时、平均耗时等详细统计
 - 支持i从0或从1开始的计数方式
+- 支持函数执行时间监控和警告
 
 ## API文档
 
@@ -208,6 +250,8 @@ for i in range(1, 101):
 - **返回值**: 根据return_type参数返回不同格式的响应数据
 - **异常**: 当请求失败且重试次数用尽后，抛出相应的异常
 
+### funcguard.time_utils
+
 #### time_log(message, i=0, max_num=0, s_time=None, start_from=0)
 
 - **参数**:
@@ -219,15 +263,42 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印带时间戳的日志信息，支持进度显示和预计完成时间计算
 
-#### time_diff(s_time=None, max_num=0, language="cn")
+#### time_diff(s_time=None, max_num=0, language="cn", return_duration=1)
 
 - **参数**:
   - `s_time`: 开始时间，默认为None
   - `max_num`: 任务数量，默认为0
   - `language`: 语言选择（"cn"中文，其他为英文），默认为"cn"
-- **返回值**: 如果s_time为None则返回当前时间，否则返回None
+  - `return_duration`: 返回模式，默认为1:
+    - 0 - 仅返回 total_seconds，不打印信息
+    - 1 - 仅打印信息,不返回 total_seconds
+    - 2 - 打印信息，并返回 total_seconds
+- **返回值**: 
+  - 如果s_time为None则返回当前时间
+  - 如果return_duration为0或2则返回持续时间（秒）
+  - 否则返回None
 - **功能**: 计算并打印任务执行时间统计信息，支持中英文双语输出
 
+#### monitor_execution_time(warning_threshold=None, print_mode=2, func=None, *args, **kwargs)
+
+- **参数**:
+  - `warning_threshold`: 警告阈值（秒），如果执行耗时超过此值则打印警告，默认为None
+  - `print_mode`: 打印模式，支持三种模式:
+    - 0 - 仅返回total_seconds，不打印任何信息
+    - 1 - 总是打印执行时间
+    - 2 - 仅在超时打印警告信息（默认）
+  - `func`: 要监控的函数
+  - `args`: 函数的位置参数
+  - `kwargs`: 函数的关键字参数
+- **返回值**: 
+  - print_mode == 0: 元组 (result, total_seconds) - 函数的执行结果和执行时间（秒）
+  - print_mode == 1: 函数的执行结果
+  - print_mode == 2: 函数的执行结果
+- **功能**: 监控函数执行时间，并返回函数的执行结果和执行时间
+- **注意**: 该方法内部使用 time_diff 函数，根据 print_mode 自动设置 return_duration 参数
+  - print_mode 为 0 或 2 时，设置 return_duration=0（ time_diff 仅返回total_seconds，不打印信息）
+  - print_mode 为 1 时，设置 return_duration=2（ time_diff 打印信息，并返回total_seconds）
+
 ### funcguard.printer
 
 #### print_line(separator_char: str = "-", separator_length: int = 40) -> None
@@ -238,6 +309,15 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印分隔线，用于分隔不同的打印块
 
+#### print_title(title: str, separator_char: str = "=", padding_length: int = 3) -> None
+
+- **参数**:
+  - `title`: 标题内容
+  - `separator_char`: 分隔符字符，默认为'='
+  - `padding_length`: 标题两侧的分隔符数量，默认为3
+- **返回值**: 无
+- **功能**: 打印带分隔符的标题，格式如：=== 初始化分类器 ===
+
 #### print_block(title: str, content: Any, separator_char: str = "-", separator_length: int = 40) -> None
 
 - **参数**:

{funcguard-0.1.6 → funcguard-0.1.8}/funcguard/__init__.py

@@ -1,6 +1,7 @@
 from .core import timeout_handler, retry_function
-from .tools import send_request, time_log, time_diff
-from .printer import print_block, print_line
+from .tools import send_request
+from .time_utils import time_log, time_diff, monitor_execution_time
+from .printer import print_block, print_line, print_title
 
 __author__ = "ruocen"
 
@@ -11,6 +12,8 @@ __all__ = [
     "send_request",
     "time_log",
     "time_diff",
+    "monitor_execution_time",
     "print_block",
     "print_line",
+    "print_title",
 ]

{funcguard-0.1.6 → funcguard-0.1.8}/funcguard/printer.py

@@ -1,5 +1,18 @@
 from typing import Any
 
+# 打印带等号的标题（如：=== 初始化分类器 ===）
+def print_title(title: str, separator_char: str = "=", padding_length: int = 3) -> None:
+    """
+    打印带分隔符的标题，格式如：=== 初始化分类器 ===
+    
+    :param title: 标题内容
+    :param separator_char: 分隔符字符，默认为'='
+    :param padding_length: 标题两侧的分隔符数量，默认为3
+    """
+    separator = separator_char * padding_length
+    print(f"{separator} {title} {separator}")
+
+
 # 打印分隔线
 def print_line(separator_char: str = "-", separator_length: int = 40) -> None:
     """

funcguard-0.1.6/funcguard/tools.py → funcguard-0.1.8/funcguard/time_utils.py

@@ -1,70 +1,8 @@
-import json
-import requests
+"""
+时间工具模块，提供时间计算、日志记录和执行时间监控功能
+"""
 from datetime import datetime, timezone, timedelta
-from typing import Optional, Dict, Any, Union
-from .core import retry_function
-
-
-# 发起请求
-def send_request(
-    method: str,
-    url: str,
-    headers: Dict[str, str],
-    data: Optional[Any] = None,
-    return_type: str = "json",
-    timeout: int = 60,
-    auto_retry: Optional[Dict[str, Any]] = None,
-) -> Union[Dict, str, requests.Response]:
-    """
-    发送HTTP请求的通用函数
-
-    :param method: HTTP方法（GET, POST等）
-    :param url: 请求URL
-    :param headers: 请求头
-    :param data: 请求数据
-    :param return_type: 返回类型（json, text, response）
-    :param timeout: 请求超时时间
-    :param auto_retry: 自动重试配置，格式为：
-                     {"task_name": "任务名称", "max_retries": 最大重试次数, "execute_timeout": 执行超时时间}
-    :return: 请求结果
-    """
-    if data is None:
-        payload = {}
-    else:
-        if (isinstance(data, dict) or isinstance(data, list)) and data != {}:
-            payload = json.dumps(data, ensure_ascii=False)
-        else:
-            payload = data
-    if auto_retry is None:
-        response = requests.request(
-            method, url, headers=headers, data=payload, timeout=timeout
-        )
-    else:
-        max_retries = auto_retry.get("max_retries", 5)
-        execute_timeout = auto_retry.get("execute_timeout", 90)
-        task_name = auto_retry.get("task_name", "")
-        response = retry_function(
-            requests.request,
-            max_retries,
-            execute_timeout,
-            task_name,
-            method,
-            url,
-            headers=headers,
-            data=payload,
-            timeout=timeout,
-        )
-
-    if response is None:
-        raise ValueError("请求返回的响应为None")
-
-    if return_type == "json":
-        result = response.json()
-    elif return_type == "response":
-        return response
-    else:
-        result = response.text
-    return result
+from typing import Optional, Union
 
 
 # 打印时间
@@ -103,14 +41,19 @@ def time_log(message, i = 0, max_num = 0, s_time = None, start_from = 0 ) :
 
 
 # 计算持续时间
-def time_diff(s_time = None, max_num = 0, language = "cn") :
+def time_diff(s_time = None, max_num = 0, language = "cn", return_duration = 1) :
     """
     计算并打印任务执行时间统计信息
     
     :param s_time: 开始时间
     :param max_num: 任务数量
     :param language: 语言选择（"cn"中文，其他为英文）
-    :return: 如果s_time为None则返回当前时间，否则返回None
+    :param return_duration: 
+        返回模式，默认为1,
+        0，仅返回 total_seconds，不打印信息
+        1，仅打印信息,不返回 total_seconds
+        2，print 信息，并返回 total_seconds
+    :return: 如果s_time为None则返回当前时间
     """
     # 获取当前时间并转换为北京时间
     now = datetime.now( timezone( timedelta( hours = 8 ) ) )
@@ -120,18 +63,22 @@ def time_diff(s_time = None, max_num = 0, language = "cn") :
 
     e_time = now
     duration = e_time - s_time
-    hours = duration.seconds // 3600
-    duration_minutes = (duration.seconds % 3600) // 60
-    seconds = duration.seconds % 60
+    total_seconds = int(duration.total_seconds())
+    if return_duration == 0:
+        return total_seconds
+
+    hours = total_seconds // 3600
+    duration_minutes = (total_seconds % 3600) // 60
+    seconds = total_seconds % 60
     result = f"{hours:02d}:{duration_minutes:02d}:{seconds:02d}"
 
     # 将时间差转化为分钟
     minutes = round( duration.total_seconds() / 60 )
     if max_num == 0 :
         if language == "cn" :
-            print( "总耗时：{}".format( result ) )
+            print( "总耗时：{:02d} : {:02d} : {:02d}".format( hours, duration_minutes, seconds ) )
         else :
-            print( "Total time: {}".format( result ) )
+            print( "Total time: {:02d} : {:02d} : {:02d}".format( hours, duration_minutes, seconds ) )
     else :
         eve_minutes = round( minutes / max_num, 3 )
         if language == "cn" :
@@ -143,6 +90,55 @@ def time_diff(s_time = None, max_num = 0, language = "cn") :
                                                         e_time.strftime( "%Y-%m-%d %H:%M" ) ) )
             print( "Total time: {}，Total minutes: {}，Number: {}，Average time: {} minutes".format( result, minutes, 
                                                                                                    max_num, 
-                                                                                                   eve_minutes ) )
+                                                                                                       eve_minutes ) )
+    if return_duration == 2:
+        return total_seconds
+    return 
+
 
-    return
+# 监控程序的执行时间
+def monitor_execution_time(warning_threshold=None, print_mode=2, func=None, *args, **kwargs):
+    """
+    监控函数执行时间，并返回函数的执行结果和执行时间
+    
+    :param warning_threshold: 警告阈值（秒），如果执行耗时超过此值则打印警告
+    :param print_mode: 打印模式，支持三种模式:
+                      0 - 仅返回total_seconds，不打印任何信息
+                      1 - 总是打印执行时间
+                      2 - 仅在超时打印警告信息（默认）
+    :param func: 要监控的函数
+    :param args: 函数的位置参数
+    :param kwargs: 函数的关键字参数
+    :return: 
+        print_mode == 0: 函数的执行结果, total_seconds
+        print_mode == 1: 函数的执行结果
+        print_mode == 2: 函数的执行结果
+    """
+    s_time = datetime.now( timezone( timedelta( hours = 8 ) ) )
+    
+    if func is None:
+        raise ValueError("func is None, func must be a function")
+    
+    # 执行函数并获取结果
+    result = func(*args, **kwargs)
+    
+    # 计算执行时间
+    if print_mode in [ 0, 2 ]  :  # print_mode：0 和 2 需要 time_diff 内部不执行 print 但返回 total_seconds 信息
+        return_duration = 0
+
+    elif print_mode == 1 :
+        return_duration = 2
+
+    else:
+        raise ValueError("print_mode must be 0, 1 or 2")
+
+    total_seconds = time_diff(s_time, return_duration=return_duration) # pyright: ignore[reportGeneralTypeIssues]
+    
+    # 根据打印模式决定是否打印耗时信息
+    if print_mode == 2 and warning_threshold is not None and total_seconds > warning_threshold:
+        print(f"警告: 函数 {func.__name__} 执行耗时 {total_seconds:.2f}秒，超过阈值 {warning_threshold}秒")
+
+    if print_mode == 0:
+        return result, total_seconds
+    
+    return result

funcguard-0.1.8/funcguard/tools.py

@@ -0,0 +1,68 @@
+import json
+import requests
+from datetime import datetime, timezone, timedelta
+from typing import Optional, Dict, Any, Union
+from .core import retry_function
+from .time_utils import time_log, time_diff, monitor_execution_time
+
+
+# 发起请求
+def send_request(
+    method: str,
+    url: str,
+    headers: Dict[str, str],
+    data: Optional[Any] = None,
+    return_type: str = "json",
+    timeout: int = 60,
+    auto_retry: Optional[Dict[str, Any]] = None,
+) -> Union[Dict, str, requests.Response]:
+    """
+    发送HTTP请求的通用函数
+
+    :param method: HTTP方法（GET, POST等）
+    :param url: 请求URL
+    :param headers: 请求头
+    :param data: 请求数据
+    :param return_type: 返回类型（json, text, response）
+    :param timeout: 请求超时时间
+    :param auto_retry: 自动重试配置，格式为：
+                     {"task_name": "任务名称", "max_retries": 最大重试次数, "execute_timeout": 执行超时时间}
+    :return: 请求结果
+    """
+    if data is None:
+        payload = {}
+    else:
+        if (isinstance(data, dict) or isinstance(data, list)) and data != {}:
+            payload = json.dumps(data, ensure_ascii=False)
+        else:
+            payload = data
+    if auto_retry is None:
+        response = requests.request(
+            method, url, headers=headers, data=payload, timeout=timeout
+        )
+    else:
+        max_retries = auto_retry.get("max_retries", 5)
+        execute_timeout = auto_retry.get("execute_timeout", 90)
+        task_name = auto_retry.get("task_name", "")
+        response = retry_function(
+            requests.request,
+            max_retries,
+            execute_timeout,
+            task_name,
+            method,
+            url,
+            headers=headers,
+            data=payload,
+            timeout=timeout,
+        )
+
+    if response is None:
+        raise ValueError("请求返回的响应为None")
+
+    if return_type == "json":
+        result = response.json()
+    elif return_type == "response":
+        return response
+    else:
+        result = response.text
+    return result

{funcguard-0.1.6 → funcguard-0.1.8}/funcguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: funcguard
-Version: 0.1.6
+Version: 0.1.8
 Summary: FuncGuard是一个Python库，提供函数执行超时控制、重试机制、HTTP请求封装和格式化打印工具。
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -23,6 +23,7 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 - HTTP请求封装（支持自动重试）
 - 格式化打印工具（分隔线和块打印）
 - 时间日志记录和耗时统计
+- 函数执行时间监控和警告
 
 ## 安装/升级
 
@@ -110,10 +111,14 @@ print(response)
 
 ### 格式化打印
 
-使用`print_line`和`print_block`函数进行格式化打印，便于查看和调试：
+使用`print_line`、`print_block`和`print_title`函数进行格式化打印，便于查看和调试：
 
 ```python
-from funcguard import print_line, print_block
+from funcguard import print_line, print_block, print_title
+
+# 打印带等号的标题
+print_title("初始化分类器")  # 输出：=== 初始化分类器 ===
+print_title("训练完成", separator_char="*", padding_length=2)  # 输出：** 训练完成 **
 
 # 打印分隔线
 print_line()  # 默认使用40个'-'字符
@@ -174,12 +179,49 @@ for i in range(1, 101):
 
 ```
 
+### 执行时间监控
+
+使用`monitor_execution_time`函数监控函数执行时间：
+
+```python
+from funcguard import monitor_execution_time
+
+def some_function():
+    # 模拟一个耗时操作
+    import time
+    time.sleep(2)
+    return "操作完成"
+
+# 模式1：总是打印执行时间
+result = monitor_execution_time(
+    func=some_function,
+    print_mode=1
+)
+print(f"结果: {result}")
+
+# 模式2：仅在超过阈值时打印警告
+result = monitor_execution_time(
+    func=some_function,
+    warning_threshold=1.5,  # 设置1.5秒的警告阈值
+    print_mode=2
+)
+print(f"结果: {result}")
+
+# 模式0：不打印任何信息，仅返回结果和执行时间
+result, duration = monitor_execution_time(
+    func=some_function,
+    print_mode=0
+)
+print(f"结果: {result}, 耗时: {duration}秒")
+```
+
 时间日志功能特点：
 - 自动显示北京时间（UTC+8）
 - 支持进度显示和预计完成时间计算
 - 提供中英文双语统计信息
 - 可显示总耗时、平均耗时等详细统计
 - 支持i从0或从1开始的计数方式
+- 支持函数执行时间监控和警告
 
 ## API文档
 
@@ -222,6 +264,8 @@ for i in range(1, 101):
 - **返回值**: 根据return_type参数返回不同格式的响应数据
 - **异常**: 当请求失败且重试次数用尽后，抛出相应的异常
 
+### funcguard.time_utils
+
 #### time_log(message, i=0, max_num=0, s_time=None, start_from=0)
 
 - **参数**:
@@ -233,15 +277,42 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印带时间戳的日志信息，支持进度显示和预计完成时间计算
 
-#### time_diff(s_time=None, max_num=0, language="cn")
+#### time_diff(s_time=None, max_num=0, language="cn", return_duration=1)
 
 - **参数**:
   - `s_time`: 开始时间，默认为None
   - `max_num`: 任务数量，默认为0
   - `language`: 语言选择（"cn"中文，其他为英文），默认为"cn"
-- **返回值**: 如果s_time为None则返回当前时间，否则返回None
+  - `return_duration`: 返回模式，默认为1:
+    - 0 - 仅返回 total_seconds，不打印信息
+    - 1 - 仅打印信息,不返回 total_seconds
+    - 2 - 打印信息，并返回 total_seconds
+- **返回值**: 
+  - 如果s_time为None则返回当前时间
+  - 如果return_duration为0或2则返回持续时间（秒）
+  - 否则返回None
 - **功能**: 计算并打印任务执行时间统计信息，支持中英文双语输出
 
+#### monitor_execution_time(warning_threshold=None, print_mode=2, func=None, *args, **kwargs)
+
+- **参数**:
+  - `warning_threshold`: 警告阈值（秒），如果执行耗时超过此值则打印警告，默认为None
+  - `print_mode`: 打印模式，支持三种模式:
+    - 0 - 仅返回total_seconds，不打印任何信息
+    - 1 - 总是打印执行时间
+    - 2 - 仅在超时打印警告信息（默认）
+  - `func`: 要监控的函数
+  - `args`: 函数的位置参数
+  - `kwargs`: 函数的关键字参数
+- **返回值**: 
+  - print_mode == 0: 元组 (result, total_seconds) - 函数的执行结果和执行时间（秒）
+  - print_mode == 1: 函数的执行结果
+  - print_mode == 2: 函数的执行结果
+- **功能**: 监控函数执行时间，并返回函数的执行结果和执行时间
+- **注意**: 该方法内部使用 time_diff 函数，根据 print_mode 自动设置 return_duration 参数
+  - print_mode 为 0 或 2 时，设置 return_duration=0（ time_diff 仅返回total_seconds，不打印信息）
+  - print_mode 为 1 时，设置 return_duration=2（ time_diff 打印信息，并返回total_seconds）
+
 ### funcguard.printer
 
 #### print_line(separator_char: str = "-", separator_length: int = 40) -> None
@@ -252,6 +323,15 @@ for i in range(1, 101):
 - **返回值**: 无
 - **功能**: 打印分隔线，用于分隔不同的打印块
 
+#### print_title(title: str, separator_char: str = "=", padding_length: int = 3) -> None
+
+- **参数**:
+  - `title`: 标题内容
+  - `separator_char`: 分隔符字符，默认为'='
+  - `padding_length`: 标题两侧的分隔符数量，默认为3
+- **返回值**: 无
+- **功能**: 打印带分隔符的标题，格式如：=== 初始化分类器 ===
+
 #### print_block(title: str, content: Any, separator_char: str = "-", separator_length: int = 40) -> None
 
 - **参数**:

{funcguard-0.1.6 → funcguard-0.1.8}/funcguard.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ setup.py
 funcguard/__init__.py
 funcguard/core.py
 funcguard/printer.py
+funcguard/time_utils.py
 funcguard/tools.py
 funcguard.egg-info/PKG-INFO
 funcguard.egg-info/SOURCES.txt
@@ -11,7 +12,4 @@ funcguard.egg-info/dependency_links.txt
 funcguard.egg-info/not-zip-safe
 funcguard.egg-info/requires.txt
 funcguard.egg-info/top_level.txt
-tests/__init__.py
-tests/run_test.py
-tests/test_core.py
-tests/test_tools.py
+tests/__init__.py

{funcguard-0.1.6 → funcguard-0.1.8}/setup.py

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

funcguard-0.1.6/tests/run_test.py

@@ -1,40 +0,0 @@
-#!/usr/bin/env python3
-"""
-测试运行脚本
-运行所有测试用例
-"""
-
-import unittest
-import sys
-import os
-
-# 添加项目根目录到Python路径
-project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-sys.path.insert(0, project_root)
-
-# 导入测试模块
-from tests.test_core import TestTimeoutHandler, TestRetryFunction
-from tests.test_tools import TestSendRequest
-
-
-def run_all_tests():
-    """运行所有测试"""
-    # 创建测试套件
-    loader = unittest.TestLoader()
-    suite = unittest.TestSuite()
-    
-    # 添加测试类
-    suite.addTests(loader.loadTestsFromTestCase(TestTimeoutHandler))
-    suite.addTests(loader.loadTestsFromTestCase(TestRetryFunction))
-    suite.addTests(loader.loadTestsFromTestCase(TestSendRequest))
-    
-    # 运行测试
-    runner = unittest.TextTestRunner(verbosity=2)
-    result = runner.run(suite)
-    
-    return result.wasSuccessful()
-
-
-if __name__ == '__main__':
-    success = run_all_tests()
-    sys.exit(0 if success else 1)

funcguard-0.1.6/tests/test_core.py

@@ -1,109 +0,0 @@
-import time
-import unittest
-from unittest.mock import patch
-
-from funcguard.core import timeout_handler, retry_function
-
-
-class TestTimeoutHandler(unittest.TestCase):
-    """测试timeout_handler函数"""
-    
-    def test_normal_execution(self):
-        """测试正常执行的函数"""
-        def quick_function():
-            time.sleep(0.1)
-            return "success"
-        
-        result = timeout_handler(quick_function, execution_timeout=2)
-        self.assertEqual(result, "success")
-    
-    def test_timeout_execution(self):
-        """测试超时的函数"""
-        def slow_function():
-            time.sleep(2)
-            return "should not reach here"
-        
-        from funcguard.core import FuncguardTimeoutError
-        with self.assertRaises(FuncguardTimeoutError) as context:
-            timeout_handler(slow_function, execution_timeout=1)
-        
-        self.assertIn("执行时间超过 1 秒", str(context.exception))
-    
-    def test_function_with_args(self):
-        """测试带参数的函数"""
-        def add_numbers(a, b):
-            return a + b
-        
-        result = timeout_handler(add_numbers, args=(3, 4), execution_timeout=2)
-        self.assertEqual(result, 7)
-    
-    def test_function_with_kwargs(self):
-        """测试带关键字参数的函数"""
-        def greet(name, greeting="Hello"):
-            return f"{greeting}, {name}!"
-        
-        result = timeout_handler(greet, kwargs={"name": "World", "greeting": "Hi"}, execution_timeout=2)
-        self.assertEqual(result, "Hi, World!")
-
-
-class TestRetryFunction(unittest.TestCase):
-    """测试retry_function函数"""
-    
-    def test_successful_first_try(self):
-        """测试第一次就成功的函数"""
-        def always_success():
-            return "success"
-        
-        result = retry_function(always_success, max_retries=2, task_name="test")
-        self.assertEqual(result, "success")
-    
-    def test_retry_until_success(self):
-        """测试重试后成功的函数"""
-        attempts = []
-        
-        def sometimes_fail():
-            attempts.append(len(attempts))
-            if len(attempts) < 2:
-                raise ValueError("Not yet")
-            return "finally success"
-        
-        result = retry_function(sometimes_fail, max_retries=2, task_name="test")
-        self.assertEqual(result, "finally success")
-        self.assertEqual(len(attempts), 2)
-    
-    def test_exhaust_all_retries(self):
-        """测试耗尽所有重试次数"""
-        def always_fail():
-            raise RuntimeError("Always fails")
-        
-        with self.assertRaises(RuntimeError) as context:
-            retry_function(always_fail, max_retries=2, task_name="test")
-        
-        self.assertEqual(str(context.exception), "Always fails")
-    
-    def test_timeout_in_retry(self):
-        """测试重试中的超时处理"""
-        def timeout_function():
-            time.sleep(2)
-            return "should timeout"
-        
-        # retry_function会在重试耗尽后抛出最后的异常
-        from funcguard.core import FuncguardTimeoutError
-        with self.assertRaises(FuncguardTimeoutError):
-            retry_function(timeout_function, max_retries=1, execute_timeout=1, task_name="test")
-    
-    @patch('time.sleep')
-    def test_retry_with_custom_delay(self, mock_sleep):
-        """测试重试延迟"""
-        def always_fail():
-            raise ValueError("test")
-        
-        with self.assertRaises(ValueError):
-            retry_function(always_fail, max_retries=2, task_name="test")
-        
-        # 验证sleep被调用了正确的次数
-        self.assertEqual(mock_sleep.call_count, 1)
-
-
-if __name__ == '__main__':
-    unittest.main()

funcguard-0.1.6/tests/test_tools.py

@@ -1,165 +0,0 @@
-import json
-import unittest
-from unittest.mock import patch, MagicMock
-from typing import Any, Optional, Dict
-import requests
-
-from funcguard.tools import send_request
-
-
-class MockResponse:
-    """模拟requests响应"""
-    
-    json_data: Dict[str, Any]
-    text: str
-    status_code: int
-    
-    def __init__(self, json_data: Optional[Dict[str, Any]] = None, text: str = "", status_code: int = 200):
-        self.json_data = json_data or {}
-        self.text = text
-        self.status_code = status_code
-    
-    def json(self) -> Dict[str, Any]:
-        return self.json_data
-
-
-class TestSendRequest(unittest.TestCase):
-    """测试send_request函数"""
-    
-    @patch('requests.request')
-    def test_get_request_json_response(self, mock_request):
-        """测试GET请求返回JSON"""
-        mock_response = MockResponse(json_data={"key": "value"})
-        mock_request.return_value = mock_response
-        
-        result = send_request(
-            method="GET",
-            url="https://api.example.com/data",
-            headers={"Content-Type": "application/json"}
-        )
-        
-        self.assertEqual(result, {"key": "value"})
-        mock_request.assert_called_once()
-    
-    @patch('requests.request')
-    def test_post_request_with_data(self, mock_request):
-        """测试POST请求带数据"""
-        mock_response = MockResponse(json_data={"status": "created"})
-        mock_request.return_value = mock_response
-        
-        result = send_request(
-            method="POST",
-            url="https://api.example.com/users",
-            headers={"Content-Type": "application/json"},
-            data={"name": "test", "email": "test@example.com"}
-        )
-        
-        self.assertEqual(result, {"status": "created"})
-        mock_request.assert_called_once()
-    
-    @patch('requests.request')
-    def test_return_response_object(self, mock_request):
-        """测试返回response对象"""
-        mock_response = MockResponse(text="raw response")
-        mock_request.return_value = mock_response
-        
-        result = send_request(
-            method="GET",
-            url="https://api.example.com/raw",
-            headers={},
-            return_type="response"
-        )
-        
-        self.assertEqual(result, mock_response)
-    
-    @patch('requests.request')
-    def test_return_text_response(self, mock_request):
-        """测试返回文本响应"""
-        mock_response = MockResponse(text="plain text response")
-        mock_request.return_value = mock_response
-        
-        result = send_request(
-            method="GET",
-            url="https://api.example.com/text",
-            headers={},
-            return_type="text"
-        )
-        
-        self.assertEqual(result, "plain text response")
-    
-    @patch('requests.request')
-    def test_custom_timeout(self, mock_request):
-        """测试自定义超时时间"""
-        mock_response = MockResponse()
-        mock_request.return_value = mock_response
-        
-        send_request(
-            method="GET",
-            url="https://api.example.com/data",
-            headers={},
-            timeout=30
-        )
-        
-        mock_request.assert_called_once()
-    
-    @patch('funcguard.tools.retry_function')
-    @patch('requests.request')
-    def test_auto_retry_enabled(self, mock_request, mock_retry):
-        """测试启用自动重试"""
-        # 设置retry_function返回一个包含正确json数据的MockResponse对象
-        mock_response = MockResponse(json_data={"success": True})
-        mock_retry.return_value = mock_response
-        
-        result = send_request(
-            method="POST",
-            url="https://api.example.com/data",
-            headers={"Content-Type": "application/json"},
-            data={"key": "value"},
-            auto_retry={
-                "task_name": "API测试",
-                "max_retries": 3,
-                "execute_timeout": 60
-            }
-        )
-        
-        # 验证结果 - 使用更安全的方式处理可能的类型差异
-        if isinstance(result, dict):
-            # 如果result是字典（JSON解析结果）
-            self.assertEqual(result, {"success": True})
-        elif hasattr(result, 'json_data'):
-            # 如果result是MockResponse对象，使用getattr避免类型检查错误
-            json_data = getattr(result, 'json_data')
-            self.assertEqual(json_data, {"success": True})
-        else:
-            # 其他情况，直接比较
-            self.assertEqual(result, {"success": True})
-        mock_retry.assert_called_once()
-    
-    @patch('requests.request')
-    def test_none_response_raises_error(self, mock_request):
-        """测试None响应抛出错误"""
-        mock_request.return_value = None
-        
-        with self.assertRaises(ValueError) as context:
-            send_request("GET", "https://api.example.com/data", {})
-        
-        self.assertEqual(str(context.exception), "请求返回的响应为None")
-    
-    def test_invalid_return_type(self):
-        """测试无效的返回类型"""
-        with patch('requests.request') as mock_request:
-            mock_response = MockResponse()
-            mock_request.return_value = mock_response
-            
-            # 对于无效的return_type，函数会尝试访问response.text
-            result = send_request(
-                method="GET",
-                url="https://api.example.com/data",
-                headers={},
-                return_type="invalid"
-            )
-            self.assertEqual(result, "")
-
-
-if __name__ == '__main__':
-    unittest.main()