kevin-toolbox-dev 1.4.11__tar.gz → 1.4.13__tar.gz

kevin-toolbox-dev-1.4.13/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.1
+Name: kevin-toolbox-dev
+Version: 1.4.13
+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.13 （2025-07-21）【bug fix】【new feature】
+  - data_flow.file.markdown
+    - modify find_tables()，完善读取表格函数，支持更多的表格格式，包括以梅花线作为标题栏分割线，表格最左侧和最右侧分割线省略等情况。
+  - nested_dict_list.serializer
+    - modify read()，支持在读取时通过参数 b_keep_identical_relations 对 record.json 中的同名参数进行覆盖。
+  - computer_science.algorithm
+    - redirector
+      - 【bug fix】fix bug in _randomly_idx_redirector() for Redirectable_Sequence_Fetcher，改正了 rng.randint(low, high) 中参数 high 的设置。
+    - pareto_front
+      - modify get_pareto_points_idx()，支持参数 directions 只输入单个值来表示所有方向都使用该值。
+    - sampler
+      - 【new feature】add Recent_Sampler，最近采样器：始终保留最近加入的 capacity 个样本。
+  - patches.for_matplotlib
+    - common_charts.utils
+      - modify .save_plot()，将原来在 output_path 为 None 时使用 plt.show() 展示图像的行为改为返回 np.array 形式的图像，并支持通过参数 b_show_plot 来单独控制是否展示图像。
+      - 【new feature】add log_scaling()，用于处理坐标系变换。
+    - common_charts
+      - 【new feature】add plot_3d()，绘制3D图，支持：散点图、三角剖分曲面及其平滑版本。
+      - 【new feature】add plot_contour()，绘制等高线图。
+      - 【new feature】add plot_mean_std_lines()，绘制均值和标准差折线图及其区域填充。
+      - 【new feature】add plot_2d_matrix()，计算并绘制混淆矩阵。
+
+
+

kevin-toolbox-dev-1.4.13/README.md

@@ -0,0 +1,51 @@
+# 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.13 （2025-07-21）【bug fix】【new feature】
+  - data_flow.file.markdown
+    - modify find_tables()，完善读取表格函数，支持更多的表格格式，包括以梅花线作为标题栏分割线，表格最左侧和最右侧分割线省略等情况。
+  - nested_dict_list.serializer
+    - modify read()，支持在读取时通过参数 b_keep_identical_relations 对 record.json 中的同名参数进行覆盖。
+  - computer_science.algorithm
+    - redirector
+      - 【bug fix】fix bug in _randomly_idx_redirector() for Redirectable_Sequence_Fetcher，改正了 rng.randint(low, high) 中参数 high 的设置。
+    - pareto_front
+      - modify get_pareto_points_idx()，支持参数 directions 只输入单个值来表示所有方向都使用该值。
+    - sampler
+      - 【new feature】add Recent_Sampler，最近采样器：始终保留最近加入的 capacity 个样本。
+  - patches.for_matplotlib
+    - common_charts.utils
+      - modify .save_plot()，将原来在 output_path 为 None 时使用 plt.show() 展示图像的行为改为返回 np.array 形式的图像，并支持通过参数 b_show_plot 来单独控制是否展示图像。
+      - 【new feature】add log_scaling()，用于处理坐标系变换。
+    - common_charts
+      - 【new feature】add plot_3d()，绘制3D图，支持：散点图、三角剖分曲面及其平滑版本。
+      - 【new feature】add plot_contour()，绘制等高线图。
+      - 【new feature】add plot_mean_std_lines()，绘制均值和标准差折线图及其区域填充。
+      - 【new feature】add plot_2d_matrix()，计算并绘制混淆矩阵。
+

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.4.11"
+__version__ = "1.4.13"
 
 
 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 1760340881 --verbose 0'
+    f'--expiration_timestamp 1768647143 --verbose 0'
 )

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/pareto_front/get_pareto_points_idx.py

@@ -31,6 +31,8 @@ def get_pareto_points_idx(points, directions=None):
     """
     points = np.asarray(points)
     assert points.ndim == 2 and len(points) > 0
+    if directions is not None and not isinstance(directions, (list, tuple,)):
+        directions = [directions] * points.shape[-1]
     assert directions is None or isinstance(directions, (list, tuple,)) and len(directions) == points.shape[-1]
 
     # 计算排序的权重

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/redirector/redirectable_sequence_fetcher.py

@@ -6,11 +6,11 @@ from kevin_toolbox.computer_science.algorithm.cache_manager import Cache_Manager
 
 def _randomly_idx_redirector(idx, seq_len, attempts, rng, *args):
     if idx == 0:
-        return rng.randint(1, seq_len - 1)
+        return rng.randint(1, seq_len)
     elif idx == seq_len - 1:
-        return rng.randint(0, seq_len - 2)
+        return rng.randint(0, seq_len - 1)
     else:
-        return rng.choice([rng.randint(0, idx - 1), rng.randint(idx + 1, seq_len - 1)], size=1,
+        return rng.choice([rng.randint(0, idx), rng.randint(idx + 1, seq_len)], size=1,
                           p=[idx / (seq_len - 1), (seq_len - idx - 1) / (seq_len - 1)])[0]
 
 

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/sampler/__init__.py

@@ -1 +1,2 @@
 from .reservoir_sampler import Reservoir_Sampler
+from .recent_sampler import Recent_Sampler

kevin-toolbox-dev-1.4.13/kevin_toolbox/computer_science/algorithm/sampler/recent_sampler.py

@@ -0,0 +1,128 @@
+class Recent_Sampler:
+    """
+        最近采样器：始终保留最近加入的 capacity 个样本
+    """
+
+    def __init__(self, **kwargs):
+        """
+            参数：
+                capacity:                       <int> 缓冲区或窗口的容量
+        """
+        # 默认参数
+        paras = {
+            "capacity": 1,
+        }
+
+        # 获取并更新参数
+        paras.update(kwargs)
+
+        # 校验 capacity
+        assert paras["capacity"] >= 1
+
+        self.paras = paras
+        self.cache = []  # 用列表来保存最近的样本
+        self.state = self._init_state()  # state 只记录 total_nums
+
+    @staticmethod
+    def _init_state():
+        """
+            初始化状态，仅记录已添加的总样本数
+        """
+        return dict(
+            total_nums=0,
+        )
+
+    def add(self, item, **kwargs):
+        """
+            添加单个数据 item 到采样器中。
+            - 更新 total_nums 计数
+            - 将 item 追加到 cache 末尾
+            - 如果超出 capacity，则删除最旧的一个（即列表开头的元素）
+        """
+        self.state["total_nums"] += 1
+        self.cache.append(item)
+        if len(self.cache) > self.paras["capacity"]:
+            self.cache.pop(0)
+
+    def add_sequence(self, item_ls, **kwargs):
+        """
+            批量添加：对列表中每个元素多次调用 add
+        """
+        for item in item_ls:
+            self.add(item, **kwargs)
+
+    def get(self, **kwargs):
+        """
+            返回当前缓冲区中的数据列表（浅拷贝）。
+        """
+        return self.cache.copy()
+
+    def clear(self):
+        """
+            清空已有数据和状态，重置采样器。
+        """
+        self.cache.clear()
+        self.state = self._init_state()
+
+    def __len__(self):
+        """
+            返回已添加的总样本数（state["total_nums"]），
+            而不是当前缓冲区长度
+        """
+        return self.state["total_nums"]
+
+    # ---------------------- 用于保存和加载状态 ---------------------- #
+
+    def load_state_dict(self, state_dict):
+        """
+            加载状态
+            - 清空当前缓冲区和 state
+            - 恢复 state["total_nums"]
+            - 恢复 cache 列表内容
+            - 恢复 rng 状态
+        """
+        self.clear()
+        self.state.update(state_dict["state"])
+        self.cache.extend(state_dict["cache"])
+
+    def state_dict(self, b_deepcopy=True):
+        """
+            获取当前状态，包含：
+            - state: {"total_nums": ...}
+            - cache: 当前缓冲区列表
+        """
+        temp = {
+            "state": self.state,
+            "cache": self.cache
+        }
+        if b_deepcopy:
+            import kevin_toolbox.nested_dict_list as ndl
+            temp = ndl.copy_(var=temp, b_deepcopy=True, b_keep_internal_references=True)
+        return temp
+
+
+# 测试示例
+if __name__ == "__main__":
+    # 创建一个容量为 5 的 Recent_Sampler
+    sampler = Recent_Sampler(capacity=5)
+
+    # 逐个添加 1 到 10 的数字
+    for i in range(1, 11):
+        sampler.add(i)
+        print(f"添加 {i} 后缓冲区: {sampler.get()}")
+
+    # 到这里，缓冲区中应该只保留最近加入的 5 个样本：6,7,8,9,10
+    print("最终缓冲区:", sampler.get())  # 预期输出: [6,7,8,9,10]
+    print("总共添加个数:", len(sampler))  # 预期输出: 10
+
+    # 保存当前状态
+    state = sampler.state_dict()
+    print("状态字典:", state)
+
+    # 清空后再恢复状态
+    sampler.clear()
+    print("清空后缓冲区:", sampler.get())  # 预期输出: []
+
+    sampler.load_state_dict(state)
+    print("恢复后缓冲区:", sampler.get())  # 预期输出: [6,7,8,9,10]
+    print("恢复后总共添加个数:", len(sampler))  # 预期输出: 10

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/sampler/reservoir_sampler.py

@@ -61,13 +61,13 @@ class Reservoir_Sampler:
 
     def get(self, **kwargs):
         """
-        返回当前水库中的数据列表（拷贝）。
+            返回当前水库中的数据列表（浅拷贝）。
         """
         return self.reservoir.copy()
 
     def clear(self):
         """
-        清空已有数据和状态，重置采样器。
+            清空已有数据和状态，重置采样器。
         """
         self.reservoir.clear()
         self.state = self._init_state()

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/statistician/__init__.py

@@ -2,3 +2,5 @@ from .accumulator_base import Accumulator_Base
 from .exponential_moving_average import Exponential_Moving_Average
 from .average_accumulator import Average_Accumulator
 from .accumulator_for_ndl import Accumulator_for_Ndl
+from .maximum_accumulator import Maximum_Accumulator
+from .minimum_accumulator import Minimum_Accumulator

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/statistician/average_accumulator.py

@@ -27,7 +27,7 @@ class Average_Accumulator(Accumulator_Base):
                         以上三种方式，默认选用最后一种。
                         如果三种方式同时被指定，则优先级与对应方式在上面的排名相同。
         """
-        super(Average_Accumulator, self).__init__(**kwargs)
+        super().__init__(**kwargs)
 
     def add_sequence(self, var_ls, **kwargs):
         for var in var_ls:

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/computer_science/algorithm/statistician/exponential_moving_average.py

@@ -56,7 +56,7 @@ class Exponential_Moving_Average(Accumulator_Base):
         # 校验参数
         assert isinstance(paras["keep_ratio"], (int, float,)) and 0 <= paras["keep_ratio"] <= 1
         #
-        super(Exponential_Moving_Average, self).__init__(**paras)
+        super().__init__(**paras)
 
     def add_sequence(self, var_ls, **kwargs):
         for var in var_ls:

kevin-toolbox-dev-1.4.13/kevin_toolbox/computer_science/algorithm/statistician/maximum_accumulator.py

@@ -0,0 +1,80 @@
+import numpy as np
+import torch
+from kevin_toolbox.computer_science.algorithm.statistician import Accumulator_Base
+
+
+class Maximum_Accumulator(Accumulator_Base):
+    """
+        用于计算最大值的累积器
+    """
+
+    def __init__(self, **kwargs):
+        """
+            参数：
+                data_format:            指定数据格式
+                like:                   指定数据格式
+                    指定输入数据的格式，有三种方式：
+                        1. 显式指定数据的形状和所在设备等。
+                            data_format:        <dict of paras>
+                                    其中需要包含以下参数：
+                                        type_:              <str>
+                                                                "numpy":        np.ndarray
+                                                                "torch":        torch.tensor
+                                        shape:              <list of integers>
+                                        device:             <torch.device>
+                                        dtype:              <torch.dtype>
+                        2. 根据输入的数据，来推断出形状、设备等。
+                            like:               <torch.tensor / np.ndarray / int / float>
+                        3. 均不指定 data_format 和 like，此时将等到第一次调用 add()/add_sequence() 时再根据输入来自动推断。
+                        以上三种方式，默认选用最后一种。
+                        如果三种方式同时被指定，则优先级与对应方式在上面的排名相同。
+        """
+        super().__init__(**kwargs)
+
+    def add_sequence(self, var_ls, **kwargs):
+        for var in var_ls:
+            self.add(var, **kwargs)
+
+    def add(self, var, **kwargs):
+        """
+            添加单个数据
+
+            参数:
+                var:                数据
+        """
+        if self.var is None:
+            self.var = var
+        else:
+            # 统计
+            if torch.is_tensor(var):
+                self.var = torch.maximum(self.var, var)
+            else:
+                self.var = np.maximum(self.var, var)
+        self.state["total_nums"] += 1
+
+    def get(self, **kwargs):
+        """
+            获取当前累加的平均值
+                当未有累积时，返回 None
+        """
+        if len(self) == 0:
+            return None
+        return self.var
+
+    @staticmethod
+    def _init_state():
+        """
+            初始化状态
+        """
+        return dict(
+            total_nums=0
+        )
+
+
+if __name__ == '__main__':
+
+    seq = list(torch.tensor(range(1, 10))-5)
+    avg = Maximum_Accumulator()
+    for i, v in enumerate(seq):
+        avg.add(var=v)
+        print(i, v, avg.get())

kevin-toolbox-dev-1.4.13/kevin_toolbox/computer_science/algorithm/statistician/minimum_accumulator.py

@@ -0,0 +1,34 @@
+import numpy as np
+import torch
+from kevin_toolbox.computer_science.algorithm.statistician import Maximum_Accumulator
+
+
+class Minimum_Accumulator(Maximum_Accumulator):
+    """
+        用于计算最小值的累积器
+    """
+
+    def add(self, var, **kwargs):
+        """
+            添加单个数据
+
+            参数:
+                var:                数据
+        """
+        if self.var is None:
+            self.var = var
+        else:
+            # 统计
+            if torch.is_tensor(var):
+                self.var = torch.minimum(self.var, var)
+            else:
+                self.var = np.minimum(self.var, var)
+        self.state["total_nums"] += 1
+
+
+if __name__ == '__main__':
+    seq = list(torch.tensor(range(1, 10)) + 5)
+    avg = Minimum_Accumulator()
+    for i, v in enumerate(seq):
+        avg.add(var=v)
+        print(i, v, avg.get())

{kevin-toolbox-dev-1.4.11 → kevin-toolbox-dev-1.4.13}/kevin_toolbox/data_flow/file/markdown/table/find_tables.py

@@ -52,23 +52,49 @@ def find_tables(text, b_compact_format=True):
         return table_ls, part_slices_ls, table_idx_ls
 
 
+# def _find_table(text):
+#     # 正则表达式匹配Markdown表格
+#     table_pattern = re.compile(r'\|([^\n]+)\|', re.DOTALL)
+#     table_matches = table_pattern.findall(text)
+#     if len(table_matches) < 2:
+#         # 因为一个合法的 markdown 表格需要含有表头的分隔线，所以行数至少应该为 2
+#         return None
+#
+#     # 去除表头的分隔线
+#     table_matches.pop(1)
+#     #
+#     tables = []  # 每个元素为一行
+#     for match in table_matches:
+#         # 分割每一行
+#         tables.append([i.strip() for i in match.split('|', -1)])
+#
+#     return {"matrix": tables, "orientation": None}
+
 def _find_table(text):
-    # 正则表达式匹配Markdown表格
-    table_pattern = re.compile(r'\|([^\n]+)\|', re.DOTALL)
-    table_matches = table_pattern.findall(text)
-    if len(table_matches) < 2:
+    # 按行分割文本
+    lines = text.splitlines()
+    table_rows = []
+    for line in lines:
+        # 移除行首尾空白
+        stripped_line = line.strip()
+        if not stripped_line:
+            continue  # 跳过空行
+        # 移除行首尾的可选竖线（如果存在）
+        if stripped_line.startswith('|'):
+            stripped_line = stripped_line[1:]
+        if stripped_line.endswith('|'):
+            stripped_line = stripped_line[:-1]
+        # 分割单元格并去除每个单元格的空白
+        row_cells = [cell.strip() for cell in stripped_line.split('|')]
+        table_rows.append(row_cells)
+
+    if len(table_rows) < 2:
         # 因为一个合法的 markdown 表格需要含有表头的分隔线，所以行数至少应该为 2
         return None
-
     # 去除表头的分隔线
-    table_matches.pop(1)
-    #
-    tables = []  # 每个元素为一行
-    for match in table_matches:
-        # 分割每一行
-        tables.append([i.strip() for i in match.split('|', -1)])
+    table_rows.pop(1)
 
-    return {"matrix": tables, "orientation": None}
+    return {"matrix": table_rows, "orientation": None}
 
 
 if __name__ == '__main__':

kevin-toolbox-dev-1.4.13/kevin_toolbox/developing/file_management/__init__.py

@@ -0,0 +1 @@
+from .file_feature_extractor import File_Feature_Extractor