kevin-toolbox-dev 1.4.6__tar.gz → 1.4.8__tar.gz

kevin-toolbox-dev-1.4.8/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.1
+Name: kevin-toolbox-dev
+Version: 1.4.8
+Summary: 一个常用的工具代码包集合
+Home-page: https://github.com/cantbeblank96/kevin_toolbox
+Download-URL: https://github.com/username/your-package/archive/refs/tags/v1.0.0.tar.gz
+Author: kevin hsu
+Author-email: xukaiming1996@163.com
+License: MIT
+Keywords: mathematics,pytorch,numpy,machine-learning,algorithm
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Provides-Extra: plot
+Provides-Extra: rest
+
+# kevin_toolbox
+
+一个通用的工具代码包集合
+
+
+
+环境要求
+
+```shell
+numpy>=1.19
+pytorch>=1.2
+```
+
+安装方法：
+
+```shell
+pip install kevin-toolbox  --no-dependencies
+```
+
+
+
+[项目地址 Repo](https://github.com/cantbeblank96/kevin_toolbox)
+
+[使用指南 User_Guide](./notes/User_Guide.md)
+
+[免责声明 Disclaimer](./notes/Disclaimer.md)
+
+[版本更新记录](./notes/Release_Record.md)：
+
+- v 1.4.8 （2025-03-06）【new feature】【refactor】
+
+  - 【new feature】network，新增网络模块。
+    - 该模块包含网络访问相关的函数：
+      - get_response()，获取 url 的响应。
+      - fetch_metadata()，从 URL/response 中获取文件名、后缀（扩展名）、大小等元信息。
+      - fetch_content()，从 URL/response 中获取内容。
+      - download_file()，下载文件。
+  - env_info
+    - modify Env_Vars_Parser.parse()，新增 default 参数用于支持解释失败时候返回默认值。
+  - computer_science.algorithm
+    - 【refactor】【new feature】decorator，从 developing 中将装饰器相关模块整合到 cs.algorithm 中。
+      - 该目录目前包含以下函数：
+        - retry()，在函数执行失败时，等待一定时间后重试多次。
+        - restore_original_work_path()，在运行函数 func 前备份当前工作目录，并在函数运行结束后还原到原始工作目录。
+    - registration
+      - 【new feature】add Serializer_for_Registry_Execution，用于对基于 Registry 中成员构建的执行过程进行序列化和反序列化操作。
+  - nested_dict_list.serializer
+    - modify write()，增加返回值，返回保存到的路径。
+  - patches.for_matplotlib
+    - 【new feature】add COMMON_CHARTS，增加该注册器用于管理 common_charts 模块中的方法。
+    - common_charts
+      - 为所有plot_xx函数增加了注释和测试用例。
+      - 为所有plot_xx函数增加以下参数：
+        - b_generate_record：是否保存函数参数为档案。
+          - 默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+          - 后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+          - 该参数仅在 output_dir 和 output_path 非 None 时起效。
+        - output_path：图片输出路径。
+          - 支持直接指定图片要保存的路径，在原有的通过 output_dir 和 title 自动生成路径的方式之外，提供了另一个指定的方式。
+      - 【new feature】add plot_from_record，从保存的档案 .record.tar 文件中恢复并绘制图像。
+
+

kevin-toolbox-dev-1.4.8/README.md

@@ -0,0 +1,60 @@
+# kevin_toolbox
+
+一个通用的工具代码包集合
+
+
+
+环境要求
+
+```shell
+numpy>=1.19
+pytorch>=1.2
+```
+
+安装方法：
+
+```shell
+pip install kevin-toolbox  --no-dependencies
+```
+
+
+
+[项目地址 Repo](https://github.com/cantbeblank96/kevin_toolbox)
+
+[使用指南 User_Guide](./notes/User_Guide.md)
+
+[免责声明 Disclaimer](./notes/Disclaimer.md)
+
+[版本更新记录](./notes/Release_Record.md)：
+
+- v 1.4.8 （2025-03-06）【new feature】【refactor】
+
+  - 【new feature】network，新增网络模块。
+    - 该模块包含网络访问相关的函数：
+      - get_response()，获取 url 的响应。
+      - fetch_metadata()，从 URL/response 中获取文件名、后缀（扩展名）、大小等元信息。
+      - fetch_content()，从 URL/response 中获取内容。
+      - download_file()，下载文件。
+  - env_info
+    - modify Env_Vars_Parser.parse()，新增 default 参数用于支持解释失败时候返回默认值。
+  - computer_science.algorithm
+    - 【refactor】【new feature】decorator，从 developing 中将装饰器相关模块整合到 cs.algorithm 中。
+      - 该目录目前包含以下函数：
+        - retry()，在函数执行失败时，等待一定时间后重试多次。
+        - restore_original_work_path()，在运行函数 func 前备份当前工作目录，并在函数运行结束后还原到原始工作目录。
+    - registration
+      - 【new feature】add Serializer_for_Registry_Execution，用于对基于 Registry 中成员构建的执行过程进行序列化和反序列化操作。
+  - nested_dict_list.serializer
+    - modify write()，增加返回值，返回保存到的路径。
+  - patches.for_matplotlib
+    - 【new feature】add COMMON_CHARTS，增加该注册器用于管理 common_charts 模块中的方法。
+    - common_charts
+      - 为所有plot_xx函数增加了注释和测试用例。
+      - 为所有plot_xx函数增加以下参数：
+        - b_generate_record：是否保存函数参数为档案。
+          - 默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+          - 后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+          - 该参数仅在 output_dir 和 output_path 非 None 时起效。
+        - output_path：图片输出路径。
+          - 支持直接指定图片要保存的路径，在原有的通过 output_dir 和 title 自动生成路径的方式之外，提供了另一个指定的方式。
+      - 【new feature】add plot_from_record，从保存的档案 .record.tar 文件中恢复并绘制图像。

{kevin-toolbox-dev-1.4.6 → kevin-toolbox-dev-1.4.8}/kevin_toolbox/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.4.6"
+__version__ = "1.4.8"
 
 
 import os
@@ -12,5 +12,5 @@ os.system(
 os.system(
     f'python {os.path.split(__file__)[0]}/env_info/check_validity_and_uninstall.py '
     f'--package_name kevin-toolbox-dev '
-    f'--expiration_timestamp 1753280251 --verbose 0'
+    f'--expiration_timestamp 1756803931 --verbose 0'
 )

{kevin-toolbox-dev-1.4.6/kevin_toolbox/developing → kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm}/decorator/__init__.py

@@ -1 +1,2 @@
-from .restore_original_work_path import restore_original_work_path
+from .restore_original_work_path import restore_original_work_path
+from .retry import retry

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/decorator/retry.py

@@ -0,0 +1,62 @@
+import time
+import functools
+from kevin_toolbox.patches.for_logging import build_logger
+
+default_logger = build_logger(
+    name=":retry",
+    handler_ls=[
+        dict(target=None, level="INFO", formatter="%(name)s - %(levelname)s - %(message)s"),
+    ]
+)
+
+
+def retry(retries=3, delay=0.5, exceptions=(Exception,), logger=None):
+    """
+        在函数执行失败时，等待一定时间后重试多次
+
+        参数：
+            retries:            <int> 重试次数
+                                    默认重试3次
+            delay:              <int/float> 每次重试前等待的秒数
+                                    默认0.5秒
+            exceptions:         <list> 捕获的异常类型
+                                    默认捕获所有 Exception
+
+        使用示例：
+            @retry(retries=5, delay=2)
+            def func():
+                ...
+    """
+    logger = default_logger if logger == "default" else logger
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            last_exception = None
+            for attempt in range(1, retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if logger is not None:
+                        logger.info(f"第 {attempt} 次调用 {func.__name__} 失败\n\t异常：{e}\n\t等待 {delay} 秒后重试...")
+                    time.sleep(delay)
+            # 如果所有重试均失败，则抛出最后一次捕获的异常
+            raise last_exception
+
+        return wrapper
+
+    return decorator
+
+
+if __name__ == '__main__':
+    @retry(retries=2, delay=0.3, logger="default")
+    def func_(*args, **kwargs):
+        if args or kwargs:
+            return args, kwargs
+        else:
+            raise ValueError("no paras")
+
+
+    print(func_(123))
+    func_()

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/__init__.py

@@ -0,0 +1,2 @@
+from .multi_thread_execute import multi_thread_execute
+from .multi_process_execute import multi_process_execute

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/multi_process_execute.py

@@ -0,0 +1,109 @@
+import pickle
+import concurrent.futures
+from multiprocessing import Manager
+from kevin_toolbox.computer_science.data_structure import Executor
+from kevin_toolbox.computer_science.algorithm.parallel_and_concurrent.utils import wrapper_for_mp as wrapper
+from kevin_toolbox.computer_science.algorithm.parallel_and_concurrent.utils import DEFAULT_PROCESS_NUMS
+
+
+def multi_process_execute(executors, worker_nums=DEFAULT_PROCESS_NUMS, b_display_progress=True, timeout=None,
+                          _hook_for_debug=None):
+    """
+        多进程执行
+
+        参数：
+            executors:                  <list/generator/iterator of Executor> 执行器序列
+            worker_nums:                <int> 进程数
+            b_display_progress:         <boolean> 是否显示进度条
+            timeout:                    <int/float> 每个进程的最大等待时间，单位是s
+                                            默认为 None，表示允许等待无限长的时间
+            _hook_for_debug:            <dict/None> 当设置为非 None 值时，将保存中间的执行信息。
+                                            包括：
+                                                - "execution_orders":    执行顺序
+                                                - "completion_orders":   完成顺序
+                                            这些信息与最终结果无关，仅面向更底层的调试需求，任何人都不应依赖该特性
+        返回：
+            res_ls, failed_idx_ls
+            执行结果列表，以及执行失败的执行器索引列表
+    """
+    executor_ls = []
+    for i in executors:
+        assert isinstance(i, (Executor,))
+        try:
+            pickle.dumps(i)
+        except:
+            raise AttributeError(
+                f'非法任务。因为进程池中的任务必须要能被pickle化。\n对象 {i} 无法被 pickle，请检查其中是否使用了闭包内定义的函数')
+        executor_ls.append(i)
+    if b_display_progress:
+        from tqdm import tqdm
+        p_bar = tqdm(total=len(executor_ls))
+    else:
+        p_bar = None
+
+    if isinstance(_hook_for_debug, dict):
+        _execution_orders, _completion_orders = Manager().list(), Manager().list()
+    else:
+        _execution_orders, _completion_orders = None, None
+
+    res_ls = [None] * len(executor_ls)
+    failed_idx_ls = []
+    with concurrent.futures.ProcessPoolExecutor(max_workers=worker_nums) as process_pool:
+        # 提交任务并添加进度回调
+        futures = []
+        for i, executor in enumerate(executor_ls):
+            future = process_pool.submit(wrapper, executor, timeout, i, _execution_orders, _completion_orders)
+            if b_display_progress:
+                future.add_done_callback(lambda _: p_bar.update())
+            futures.append(future)
+
+        # 收集结果
+        for i, future in enumerate(futures):
+            try:
+                res, b_success = future.result()
+            except:
+                b_success = False
+            if b_success:
+                res_ls[i] = res
+            else:
+                failed_idx_ls.append(i)
+
+    if b_display_progress:
+        p_bar.close()
+
+    if isinstance(_hook_for_debug, (dict,)):
+        _hook_for_debug.update({
+            "execution_orders": list(_execution_orders),
+            "completion_orders": list(_completion_orders)
+        })
+
+    return res_ls, failed_idx_ls
+
+
+if __name__ == '__main__':
+    import time
+
+
+    def func_(i):
+        # 模拟部分任务长时间运行，部分任务正常结束
+        if i in [2, 3, 7]:
+            time.sleep(100)
+        else:
+            time.sleep(0.01)
+        print(f"任务 {i} 执行完成")
+        return i * 2
+
+
+    hook_for_debug = dict()
+    a = time.time()
+    results, failed = multi_process_execute(
+        executors=[Executor(func=func_, args=(i,)) for i in range(10)],
+        worker_nums=10,
+        timeout=0.2,
+        _hook_for_debug=hook_for_debug
+    )
+    gap = time.time() - a
+    print("执行结果:", results)
+    print("超时失败的任务索引:", failed)
+    print("调试信息:", hook_for_debug)
+    print("总耗时:", gap)

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/multi_thread_execute.py

@@ -0,0 +1,105 @@
+import concurrent.futures
+from multiprocessing import Manager
+from kevin_toolbox.computer_science.data_structure import Executor
+from kevin_toolbox.computer_science.algorithm.parallel_and_concurrent.utils import wrapper_for_mt as wrapper
+from kevin_toolbox.computer_science.algorithm.parallel_and_concurrent.utils import DEFAULT_THREAD_NUMS
+
+
+def multi_thread_execute(executors, worker_nums=DEFAULT_THREAD_NUMS, b_display_progress=True, timeout=None,
+                         _hook_for_debug=None):
+    """
+        多线程执行
+
+        参数：
+            executors:                  <list/generator/iterator of Executor> 执行器序列
+            worker_nums:                <int> 线程数
+            b_display_progress:         <boolean> 是否显示进度条
+            timeout:                    <int> 每个线程的最大等待时间，单位是s
+                                            默认为 None，表示允许等待无限长的时间
+            _hook_for_debug:            <dict/None> 当设置为非 None 值时，将保存中间的执行信息。
+                                            包括：
+                                                - "execution_order":    执行顺序
+                                                - "completion_order":   完成顺序
+                                            这些信息与最终结果无关，仅面向更底层的调试需求，任何人都不应依赖该特性
+        返回：
+            res_ls, failed_idx_ls
+            执行结果列表，执行失败的执行器 idx
+    """
+    executor_ls = []
+    for i in executors:
+        assert isinstance(i, (Executor,))
+        executor_ls.append(i)
+    if b_display_progress:
+        from tqdm import tqdm
+        p_bar = tqdm(total=len(executor_ls))
+    else:
+        p_bar = None
+
+    if isinstance(_hook_for_debug, dict):
+        _execution_orders, _completion_orders = Manager().list(), Manager().list()
+    else:
+        _execution_orders, _completion_orders = None, None
+
+    res_ls = [None] * len(executor_ls)
+    failed_idx_ls = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=worker_nums) as thread_pool:
+        # 提交任务
+        futures = []
+        for i, executor in enumerate(executor_ls):
+            future = thread_pool.submit(wrapper, executor, timeout, i, _execution_orders, _completion_orders)
+            if b_display_progress:
+                future.add_done_callback(lambda _: p_bar.update())
+            futures.append(future)
+
+        # 收集结果
+        for i, future in enumerate(futures):
+            try:
+                res, b_success = future.result()
+            except:
+                b_success = False
+            if b_success:
+                res_ls[i] = res
+            else:
+                failed_idx_ls.append(i)
+
+    if b_display_progress:
+        p_bar.close()
+
+    if isinstance(_hook_for_debug, (dict,)):
+        _hook_for_debug.update({
+            "execution_orders": list(_execution_orders),
+            "completion_orders": list(_completion_orders)
+        })
+
+    return res_ls, failed_idx_ls
+
+
+if __name__ == '__main__':
+    import time
+
+
+    def func_(i):
+        # 模拟部分任务长时间运行，部分任务正常结束
+        if i in [2, 3, 7]:
+            time.sleep(100)
+        elif i in [4, 5, 6]:
+            time.sleep(0.01)
+        else:
+            time.sleep(0.05)
+        print(f"任务 {i} 执行完成")
+        return i * 2
+
+
+    hook_for_debug = dict()
+    a = time.time()
+    results, failed = multi_thread_execute(
+        executors=[Executor(func=func_, args=(i,)) for i in range(10)],
+        worker_nums=5,
+        timeout=0.2,
+        _hook_for_debug=hook_for_debug
+    )
+    gap = time.time() - a
+    print("执行结果:", results)
+    print("超时失败的任务索引:", failed)
+    print("调试信息:", hook_for_debug)
+    print("总耗时:", gap)

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/utils/__init__.py

@@ -0,0 +1,15 @@
+from .wrapper_with_timeout_1 import wrapper_with_timeout_1
+from .wrapper_with_timeout_2 import wrapper_with_timeout_2
+
+import signal
+import multiprocessing
+
+if callable(getattr(signal, "setitimer", None)):
+    wrapper_for_mp = wrapper_with_timeout_1  # 效率更高，优先选择
+else:
+    wrapper_for_mp = wrapper_with_timeout_2
+
+wrapper_for_mt = wrapper_with_timeout_2
+
+DEFAULT_PROCESS_NUMS = multiprocessing.cpu_count() + 2
+DEFAULT_THREAD_NUMS = DEFAULT_PROCESS_NUMS * 2

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/utils/wrapper_with_timeout_1.py

@@ -0,0 +1,69 @@
+import signal
+
+
+# 定义超时异常
+class TimeoutException(Exception):
+    pass
+
+
+# 定时器信号处理函数
+def __alarm_handler(*args, **kwargs):
+    raise TimeoutException("任务超时")
+
+
+def wrapper_with_timeout_1(executor, timeout=None, idx=-1, _execution_orders=None, _completion_orders=None):
+    """
+        限制执行时间，使用 multiprocessing.Process 强制终止超时任务
+            该函数仅适用于多进程以及 unix 操作系统
+
+        参数:
+            executor:               <Executor>执行器，需实现 run() 方法
+            idx:                    <int> 任务索引（用于调试）
+            timeout:                <int/float>最大等待时间（单位：秒，支持 float）
+            _execution_orders, _completion_orders: 用于记录调试信息的 Manager.list
+        返回:
+            (result, b_success)     若超时或异常则 b_success 为 False
+    """
+    if _execution_orders is not None:
+        _execution_orders.append(idx)
+
+    # 定时器
+    if timeout is not None:
+        signal.signal(signal.SIGALRM, __alarm_handler)
+        signal.setitimer(signal.ITIMER_REAL, timeout)
+
+    # 执行
+    res, b_success = None, True
+    try:
+        res = executor.run()
+        if _completion_orders is not None:
+            _completion_orders.append(idx)
+    except TimeoutException:
+        b_success = False
+    finally:
+        signal.alarm(0)  # 取消定时器
+    return res, b_success
+
+
+if __name__ == '__main__':
+    import time
+
+
+    def func_(i):
+        if i in [2, 3, 7]:
+            time.sleep(300)
+        else:
+            time.sleep(0.5)
+        return i * 2
+
+
+    from kevin_toolbox.computer_science.data_structure import Executor
+
+    print(wrapper_with_timeout_1(Executor(func=func_, args=(2,)), timeout=1))
+    print(wrapper_with_timeout_1(Executor(func=func_, args=(1,)), timeout=1))
+
+    execution_orders = []
+    completion_orders = []
+    print(wrapper_with_timeout_1(Executor(func=func_, args=(2,)), timeout=1, _execution_orders=execution_orders,
+                                 _completion_orders=completion_orders))
+    print(execution_orders, completion_orders)

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/parallel_and_concurrent/utils/wrapper_with_timeout_2.py

@@ -0,0 +1,76 @@
+from multiprocessing import Process, Queue
+
+
+def __inner_wrapper(q, executor):
+    try:
+        res = executor.run()
+        q.put((res, True))
+    except:
+        q.put((None, False))
+
+
+def wrapper_with_timeout_2(executor, timeout=None, idx=-1, _execution_orders=None, _completion_orders=None):
+    """
+        限制执行时间，使用 multiprocessing.Process 强制终止超时任务
+            该函数适用于多线程、多进程以及所有操作系统，但是效率相较于 wrapper_with_timeout_1 较差
+
+        参数:
+            executor:               <Executor>执行器，需实现 run() 方法
+            idx:                    <int> 任务索引（用于调试）
+            timeout:                <int/float>最大等待时间（单位：秒，支持 float）
+            _execution_orders, _completion_orders: 用于记录调试信息的 Manager.list
+        返回:
+            (result, b_success)     若超时或异常则 b_success 为 False
+    """
+    if _execution_orders is not None:
+        _execution_orders.append(idx)
+
+    res, b_success = None, False
+    if timeout is not None:
+        q = Queue()
+        p = Process(target=__inner_wrapper, args=(q, executor))
+        p.start()
+        p.join(timeout)  # 最多等待 timeout 秒
+
+        if q.qsize():
+            try:
+                res, b_success = q.get_nowait()
+            except:
+                pass
+        if p.is_alive():
+            p.terminate()
+            p.join()
+    else:
+        try:
+            res, b_success = executor.run(), True
+        except:
+            pass
+
+    if b_success:
+        if _completion_orders is not None:
+            _completion_orders.append(idx)
+    return res, b_success
+
+
+if __name__ == '__main__':
+    import time
+
+
+    def func_(i):
+        if i in [2, 3, 7]:
+            time.sleep(300)
+        else:
+            time.sleep(0.5)
+        return i * 2
+
+
+    from kevin_toolbox.computer_science.data_structure import Executor
+
+    print(wrapper_with_timeout_2(Executor(func=func_, args=(2,)), timeout=1))
+    print(wrapper_with_timeout_2(Executor(func=func_, args=(1,)), timeout=1))
+
+    execution_orders = []
+    completion_orders = []
+    print(wrapper_with_timeout_2(Executor(func=func_, args=(2,)), timeout=1, _execution_orders=execution_orders,
+                                 _completion_orders=completion_orders))
+    print(execution_orders, completion_orders)

kevin-toolbox-dev-1.4.8/kevin_toolbox/computer_science/algorithm/registration/__init__.py

@@ -0,0 +1,2 @@
+from .registry import Registry, UNIFIED_REGISTRY
+from .serializer_for_registry_execution import Serializer_for_Registry_Execution, execution_serializer