funcguard 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

funcguard/__init__.py

@@ -1,7 +1,16 @@
 from .core import timeout_handler, retry_function
-from .tools import send_request
+from .tools import send_request, time_log, time_diff
+from .printer import print_block, print_line
 
 __author__ = "ruocen"
 
 # 暴露主要接口
-__all__ = ["timeout_handler", "retry_function","send_request"]
+__all__ = [
+    "timeout_handler",
+    "retry_function",
+    "send_request",
+    "time_log",
+    "time_diff",
+    "print_block",
+    "print_line",
+]

funcguard/core.py

@@ -1,4 +1,11 @@
 class FuncguardTimeoutError(Exception):
+    """
+    funcguard库专用的超时异常类。
+    
+    为了避免与concurrent.futures.TimeoutError和Python内置TimeoutError的命名冲突，
+    特定义此异常类来明确表示这是funcguard库抛出的函数执行超时异常。
+    这样用户可以清晰地区分异常来源，并进行针对性的异常处理。
+    """
     pass
 
 import time
@@ -55,7 +62,7 @@ def retry_function( func , max_retries = 5 , execute_timeout = 90 , task_name =
             result = timeout_handler( func , args = args , kwargs = kwargs , execution_timeout = current_timeout )
             return result  # 如果调用成功，则返回结果
 
-        except BaseException as e :
+        except Exception as e :
             last_exception = e
             retry_count += 1
             print( e )

funcguard/printer.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+# 打印分隔线
+def print_line(separator_char: str = "-", separator_length: int = 40) -> None:
+    """
+    打印分隔线，用于分隔不同的打印块
+
+    :param separator_char: 分隔符字符，默认为'-'
+    :param separator_length: 分隔符长度，默认为40
+    """
+    separator = separator_char * separator_length
+    print(separator)
+
+
+# 块打印
+def print_block(title: str, content: Any, separator_char: str = "-", separator_length: int = 40) -> None:
+    """
+    使用分隔符打印标题和内容，便于查看
+
+    :param title: 标题
+    :param content: 打印的内容
+    :param separator_char: 分隔符字符，默认为'-'
+    :param separator_length: 分隔符长度，默认为40
+    """
+    print_line(separator_char, separator_length)
+
+    if title:
+        print(f"{title} :")
+    print(content)
+
+    print_line(separator_char, separator_length)
+    # print()  # 添加一个空行便于阅读

funcguard/tools.py

@@ -1,13 +1,23 @@
 import json
 import requests
-from . import core
-# 使用 from .core import retry_function 会导致测试失败
+from datetime import datetime, timezone, timedelta
+from typing import Optional, Dict, Any, Union
+from .core import retry_function
+
 
 # 发起请求
-def send_request( method , url , headers , data = None , return_type = "json" , timeout = 60 , auto_retry = None ) :
-    '''
+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: 请求头
@@ -17,30 +27,121 @@ def send_request( method , url , headers , data = None , return_type = "json" ,
     :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 :
+    """
+    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 = core.retry_function( requests.request , max_retries , execute_timeout , task_name , method , url ,
-                                        headers = headers , data = payload , timeout = timeout )
+    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" :
+
+    if return_type == "json":
         result = response.json()
-    elif return_type == "response" :
+    elif return_type == "response":
         return response
-    else :
+    else:
         result = response.text
-    return result
+    return result
+
+
+# 打印时间
+def time_log(message, i = 0, max_num = 0, s_time = None) :
+    """
+    打印带时间戳的日志信息，支持进度显示和预计完成时间
+    
+    :param message: 日志消息
+    :param i: 当前进度（从0开始）
+    :param max_num: 总进度数量
+    :param s_time: 开始时间，用于计算预计完成时间
+    :return: None
+    """
+    now = datetime.now( timezone( timedelta( hours = 8 ) ) )
+    time_log = "{:02d}:{:02d}:{:02d}".format( now.hour, now.minute, now.second )
+    if i < 2 :
+        print( time_log + " " + message )
+    else :
+        if max_num == 0 :
+            text = "{}".format( i )
+        else :
+            text = "{}/{}".format( i, max_num )
+        # 检查是否应该显示预计完成时间和剩余时间
+        if i % 10 == 0 and s_time is not None and i < max_num :
+            duration = now - s_time
+            ev_duration = duration / i  # 每项平均耗时
+            remaining_items = max_num - i
+            time_left = ev_duration * remaining_items
+            end_time = now + time_left
+            end_time_str = end_time.strftime( "%Y-%m-%d %H:%M" )
+            remaining_time_str = str( timedelta( seconds = int( time_left.total_seconds() ) ) )
+            text = text + "（{}）etr {}".format( end_time_str, remaining_time_str )
+        print( time_log + " " + message + " " + text )
+    return
+
+
+# 计算持续时间
+def time_diff(s_time = None, max_num = 0, language = "cn") :
+    """
+    计算并打印任务执行时间统计信息
+    
+    :param s_time: 开始时间
+    :param max_num: 任务数量
+    :param language: 语言选择（"cn"中文，其他为英文）
+    :return: 如果s_time为None则返回当前时间，否则返回None
+    """
+    # 获取当前时间并转换为北京时间
+    now = datetime.now( timezone( timedelta( hours = 8 ) ) )
+
+    if s_time is None :
+        return now
+
+    e_time = now
+    duration = e_time - s_time
+    hours = duration.seconds // 3600
+    duration_minutes = (duration.seconds % 3600) // 60
+    seconds = duration.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 ) )
+        else :
+            print( "Total time: {}".format( result ) )
+    else :
+        eve_minutes = round( minutes / max_num, 3 )
+        if language == "cn" :
+            print( "开始时间：{}，结束时间：{}".format( s_time.strftime( "%Y-%m-%d %H:%M" ), 
+                                                     e_time.strftime( "%Y-%m-%d %H:%M" ) ) )
+            print( "总耗时：{}，累计：{}分钟，数量；{}，平均耗时：{}分钟".format( result, minutes, max_num, eve_minutes ) )
+        else :
+            print( "Start time：{}，End time：{}".format( s_time.strftime( "%Y-%m-%d %H:%M" ), 
+                                                        e_time.strftime( "%Y-%m-%d %H:%M" ) ) )
+            print( "Total time: {}，Total minutes: {}，Number: {}，Average time: {} minutes".format( result, minutes, 
+                                                                                                   max_num, 
+                                                                                                   eve_minutes ) )
+
+    return

{funcguard-0.1.1.dist-info → funcguard-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: funcguard
-Version: 0.1.1
+Version: 0.1.4
 Summary: A funcguard for Python.
 Home-page: https://github.com/tinycen/funcguard
 Author: tinycen
@@ -22,13 +22,11 @@ FuncGuard是一个Python库，提供了函数执行超时控制和重试机制
 - 函数执行超时控制
 - 函数执行失败自动重试
 - HTTP请求封装（支持自动重试）
+- 格式化打印工具（分隔线和块打印）
+- 时间日志记录和耗时统计
 
 ## 安装/升级
 
-```bash
-pip install funcguard
-```
-
 ```bash
 pip install --upgrade funcguard
 ```
@@ -41,7 +39,7 @@ pip install --upgrade funcguard
 使用`timeout_handler`函数可以控制函数的执行时间，防止函数运行时间过长：
 
 ```python
-from funcguard.core import timeout_handler
+from funcguard import timeout_handler
 
 def long_running_function():
     # 模拟一个耗时操作
@@ -62,7 +60,7 @@ except TimeoutError as e:
 使用`retry_function`函数可以在函数执行失败时自动重试：
 
 ```python
-from funcguard.core import retry_function
+from funcguard import retry_function
 
 def unstable_function():
     # 模拟一个可能失败的操作
@@ -84,7 +82,7 @@ except Exception as e:
 使用`send_request`函数发送HTTP请求，支持自动重试：
 
 ```python
-from funcguard.tools import send_request
+from funcguard import send_request
 
 # 不使用重试
 response = send_request(
@@ -111,6 +109,63 @@ response = send_request(
 print(response)
 ```
 
+### 格式化打印
+
+使用`print_line`和`print_block`函数进行格式化打印，便于查看和调试：
+
+```python
+from funcguard import print_line, print_block
+
+# 打印分隔线
+print_line()  # 默认使用40个'-'字符
+print_line("*", 30)  # 使用30个'*'字符
+
+# 打印块内容
+print_block("用户信息", {"name": "张三", "age": 25})
+
+# 自定义分隔符
+print_block("配置信息", {"debug": True, "port": 8080}, "=", 50)
+
+# 打印复杂内容
+result = {
+    "status": "success",
+    "data": [1, 2, 3, 4, 5],
+    "message": "操作完成"
+}
+print_block("API响应", result)
+```
+
+### 时间日志记录
+
+使用`time_log`和`time_diff`函数记录任务执行时间和统计信息：
+
+```python
+from funcguard import time_log, time_diff
+
+# 获取开始时间
+start_time = time_diff()
+
+# 记录任务开始
+time_log("开始处理数据", 0, 100, start_time)
+
+# 模拟处理过程
+import time
+for i in range(1, 101):
+    time.sleep(0.1)  # 模拟处理时间
+    if i % 20 == 0:
+        time_log(f"处理进度", i, 100, start_time)  # 显示进度和预计完成时间
+
+# 记录任务完成并打印统计信息
+time_log("数据处理完成", 100, 100, start_time)
+time_diff(start_time, 100, "cn")  # 中文显示统计信息
+```
+
+时间日志功能特点：
+- 自动显示北京时间（UTC+8）
+- 支持进度显示和预计完成时间计算
+- 提供中英文双语统计信息
+- 可显示总耗时、平均耗时等详细统计
+
 ## API文档
 
 ### funcguard.core
@@ -152,6 +207,45 @@ print(response)
 - **返回值**: 根据return_type参数返回不同格式的响应数据
 - **异常**: 当请求失败且重试次数用尽后，抛出相应的异常
 
+#### time_log(message, i=0, max_num=0, s_time=None)
+
+- **参数**:
+  - `message`: 日志消息
+  - `i`: 当前进度（从0开始），默认为0
+  - `max_num`: 总进度数量，默认为0
+  - `s_time`: 开始时间，用于计算预计完成时间，默认为None
+- **返回值**: 无
+- **功能**: 打印带时间戳的日志信息，支持进度显示和预计完成时间计算
+
+#### time_diff(s_time=None, max_num=0, language="cn")
+
+- **参数**:
+  - `s_time`: 开始时间，默认为None
+  - `max_num`: 任务数量，默认为0
+  - `language`: 语言选择（"cn"中文，其他为英文），默认为"cn"
+- **返回值**: 如果s_time为None则返回当前时间，否则返回None
+- **功能**: 计算并打印任务执行时间统计信息，支持中英文双语输出
+
+### funcguard.printer
+
+#### print_line(separator_char: str = "-", separator_length: int = 40) -> None
+
+- **参数**:
+  - `separator_char`: 分隔符字符，默认为'-'
+  - `separator_length`: 分隔符长度，默认为40
+- **返回值**: 无
+- **功能**: 打印分隔线，用于分隔不同的打印块
+
+#### print_block(title: str, content: Any, separator_char: str = "-", separator_length: int = 40) -> None
+
+- **参数**:
+  - `title`: 标题
+  - `content`: 打印的内容
+  - `separator_char`: 分隔符字符，默认为'-'
+  - `separator_length`: 分隔符长度，默认为40
+- **返回值**: 无
+- **功能**: 使用分隔符打印标题和内容，便于查看
+
 ## 许可证
 
 MIT License

funcguard-0.1.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+funcguard/__init__.py,sha256=iyM7STP-KSxUn7PUaBWEQcZus2XskiGTTweI4qjoETE,342
+funcguard/core.py,sha256=-rFRkE-udxM0wxlcv9Qi_yIQBRdVrGgwza-LYQsVRLg,3632
+funcguard/printer.py,sha256=c93x6Z-6a7nnead_Rk_f0Xe23kdVdSj4qaxsuBMKfd0,958
+funcguard/tools.py,sha256=S7t46KurOedvVKCVoFLW_CoDvLSC__lfVLUYBse5ABM,5433
+tests/__init__.py,sha256=VW6FdWdSC_PL3zEtpkRQfUMf6yVD2OfwtSds82jawTs,26
+tests/run_test.py,sha256=-SLdUV7gDifLxuCCAlU8qLxYMx6KpK4cxfG4UYfUIgA,1005
+tests/test_core.py,sha256=aZNbQK4eTnnkCI4c2txYZNTcYIUhSJvII5Dvn0vNJKo,3732
+tests/test_tools.py,sha256=g9dK-WW1s5SIobscRuelufBfPrSgNLZU8d1AJteBpd0,5609
+funcguard-0.1.4.dist-info/LICENSE,sha256=jgOquECfjiXp5xXQ2zuzItDr4XDBLan-bIzIXl1lS4Y,1064
+funcguard-0.1.4.dist-info/METADATA,sha256=ayz3u_YGwUqH3ziy-awhbPMjWgFdPWYCxSQmTZJF-HI,7175
+funcguard-0.1.4.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+funcguard-0.1.4.dist-info/top_level.txt,sha256=7wL9mWT062DttKNO7Wi1wYWTZilR2AOPRO0rE3gvtB4,16
+funcguard-0.1.4.dist-info/RECORD,,

tests/test_tools.py

@@ -1,6 +1,7 @@
 import json
 import unittest
 from unittest.mock import patch, MagicMock
+from typing import Any, Optional, Dict
 import requests
 
 from funcguard.tools import send_request
@@ -9,12 +10,16 @@ from funcguard.tools import send_request
 class MockResponse:
     """模拟requests响应"""
     
-    def __init__(self, json_data=None, text="", status_code=200):
+    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):
+    def json(self) -> Dict[str, Any]:
         return self.json_data
 
 
@@ -97,7 +102,7 @@ class TestSendRequest(unittest.TestCase):
         
         mock_request.assert_called_once()
     
-    @patch('funcguard.core.retry_function')
+    @patch('funcguard.tools.retry_function')
     @patch('requests.request')
     def test_auto_retry_enabled(self, mock_request, mock_retry):
         """测试启用自动重试"""
@@ -117,12 +122,16 @@ class TestSendRequest(unittest.TestCase):
             }
         )
         
-        # 验证结果
-        if hasattr(result, 'json_data'):
-            # 如果result是MockResponse对象，直接比较其json_data
-            self.assertEqual(result.json_data, {"success": True})
+        # 验证结果 - 使用更安全的方式处理可能的类型差异
+        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:
-            # 否则直接比较result
+            # 其他情况，直接比较
             self.assertEqual(result, {"success": True})
         mock_retry.assert_called_once()
     

funcguard-0.1.1.dist-info/RECORD

@@ -1,12 +0,0 @@
-funcguard/__init__.py,sha256=He897o7aWOzpu2RnoRsjYQb5bhEMwC6XhFy0pot7-pA,189
-funcguard/core.py,sha256=41C2bpVTaabK3QHN0vJmnhrKwnT_Ml8mxNitfN5gNdc,3291
-funcguard/tools.py,sha256=UWvMUGj-ga_QbCZp1dJANeZbkyp76ozqbD4CpZkAymo,1807
-tests/__init__.py,sha256=VW6FdWdSC_PL3zEtpkRQfUMf6yVD2OfwtSds82jawTs,26
-tests/run_test.py,sha256=-SLdUV7gDifLxuCCAlU8qLxYMx6KpK4cxfG4UYfUIgA,1005
-tests/test_core.py,sha256=aZNbQK4eTnnkCI4c2txYZNTcYIUhSJvII5Dvn0vNJKo,3732
-tests/test_tools.py,sha256=jBKoam-X3irTynaNg23V_3HgzAHBRvE6S9OyoalLfvI,5170
-funcguard-0.1.1.dist-info/LICENSE,sha256=jgOquECfjiXp5xXQ2zuzItDr4XDBLan-bIzIXl1lS4Y,1064
-funcguard-0.1.1.dist-info/METADATA,sha256=ns_c9tJ_fjnsQjAA3OiKT26cSpDfpqebE8y12608Lu8,4230
-funcguard-0.1.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-funcguard-0.1.1.dist-info/top_level.txt,sha256=7wL9mWT062DttKNO7Wi1wYWTZilR2AOPRO0rE3gvtB4,16
-funcguard-0.1.1.dist-info/RECORD,,