kevin-toolbox-dev 1.2.7__tar.gz → 1.3.0__tar.gz

kevin-toolbox-dev-1.3.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.1
+Name: kevin-toolbox-dev
+Version: 1.3.0
+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
+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.3.0 （2023-12-13）【bug fix】【new feature】【incompatible change】
+  - nested_dict_list
+    - serializer
+      - 【bug fix】fix bug in read() and write()，解除这两个函数中出现的 nested_dict_list 和 kevin_toolbox.computer_science.algorithm.registration.Registry 模块之间的交叉引用。
+    - 【bug fix】fix bug in set_value()，对于使用method=@，但是node不为正整数的name进行强制写入的情况，未修复前表现为错误地尝试使用list进行构建并报错，现修复为使用 dict 进行构建。在新的策略下，对于强制写入，只有 method=@ 且 node 为非负正整数的情况下才会使用 list 进行构建，其他一律用 dict。
+      - 添加了对应的测试用例。
+  - patches.for_os
+    - 【new feature】add walk()，该方法在 os.walk() 的基础上增加了 ignore_s 参数，用于设定规则排除特定的目录和文件。相较于先使用 os.walk() 递归遍历这个目录，再对内容进行逐个过滤筛选的这种方式，本方法在遍历过程中就可以使用规则进行过滤并决定是否要继续深入遍历，更加高效。
+      - 补充了对应的测试用例。
+    - 【new feature】add Path_Ignorer，该类用于解释 ignore_s 参数，并进行基于规则的判断。
+    - 【new feature】modify remove()，支持对软连接的删除。
+  - computer_science.algorithm.registration
+    - 【new feature】【incompatible change】modify Registry.collect_from_paths()，将原有的通过目录前缀匹配来排除目录的 path_ls_to_exclude 参数，替换成通过规则匹配待排除目录的 ignore_s 参数，更加自由灵活。ignore_s 参数的设定方式与 for_os.walk() 中的 ignore_s 参数相同。
+      - 添加了对应的测试用例。
+  - patches.for_optuna
+    - 【new feature】【incompatible change】modify sample_from_feasible_domain()，进行了以下改变：
+      - 允许在 <feasible_domain> 中通过 "p_name" 字段来强制指定该参数在 trial 中的注册名称。
+      - 支持通过 f_p_name_builder 和 b_use_name_as_idx 决定如何从 <feasible_domain> 的位置生成参数的注册名称。
+      - 删去了 pre_name 参数，如果要实现原 pre_name 的效果，可以等效使用：
+        - `f_p_name_builder =lambda idx, p_type: f'{pre_name}{idx}'`
+      - 原来返回 var, node_name_ls 改为返回 var, node_vs_paras_s，其中 node_vs_paras_s 是一个`<dict>`，以被采样的节点在 var 中位置的名称作为键，以对应节点在 trial 中注册的参数名为值。

kevin-toolbox-dev-1.3.0/README.md

@@ -0,0 +1,50 @@
+# 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.3.0 （2023-12-13）【bug fix】【new feature】【incompatible change】
+  - nested_dict_list
+    - serializer
+      - 【bug fix】fix bug in read() and write()，解除这两个函数中出现的 nested_dict_list 和 kevin_toolbox.computer_science.algorithm.registration.Registry 模块之间的交叉引用。
+    - 【bug fix】fix bug in set_value()，对于使用method=@，但是node不为正整数的name进行强制写入的情况，未修复前表现为错误地尝试使用list进行构建并报错，现修复为使用 dict 进行构建。在新的策略下，对于强制写入，只有 method=@ 且 node 为非负正整数的情况下才会使用 list 进行构建，其他一律用 dict。
+      - 添加了对应的测试用例。
+  - patches.for_os
+    - 【new feature】add walk()，该方法在 os.walk() 的基础上增加了 ignore_s 参数，用于设定规则排除特定的目录和文件。相较于先使用 os.walk() 递归遍历这个目录，再对内容进行逐个过滤筛选的这种方式，本方法在遍历过程中就可以使用规则进行过滤并决定是否要继续深入遍历，更加高效。
+      - 补充了对应的测试用例。
+    - 【new feature】add Path_Ignorer，该类用于解释 ignore_s 参数，并进行基于规则的判断。
+    - 【new feature】modify remove()，支持对软连接的删除。
+  - computer_science.algorithm.registration
+    - 【new feature】【incompatible change】modify Registry.collect_from_paths()，将原有的通过目录前缀匹配来排除目录的 path_ls_to_exclude 参数，替换成通过规则匹配待排除目录的 ignore_s 参数，更加自由灵活。ignore_s 参数的设定方式与 for_os.walk() 中的 ignore_s 参数相同。
+      - 添加了对应的测试用例。
+  - patches.for_optuna
+    - 【new feature】【incompatible change】modify sample_from_feasible_domain()，进行了以下改变：
+      - 允许在 <feasible_domain> 中通过 "p_name" 字段来强制指定该参数在 trial 中的注册名称。
+      - 支持通过 f_p_name_builder 和 b_use_name_as_idx 决定如何从 <feasible_domain> 的位置生成参数的注册名称。
+      - 删去了 pre_name 参数，如果要实现原 pre_name 的效果，可以等效使用：
+        - `f_p_name_builder =lambda idx, p_type: f'{pre_name}{idx}'`
+      - 原来返回 var, node_name_ls 改为返回 var, node_vs_paras_s，其中 node_vs_paras_s 是一个`<dict>`，以被采样的节点在 var 中位置的名称作为键，以对应节点在 trial 中注册的参数名为值。

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.7"
+__version__ = "1.3.0"
 
 
 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 1710582827 --verbose 0'
+    f'--expiration_timestamp 1718018144 --verbose 0'
 )

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/computer_science/algorithm/registration/registry.py

@@ -4,6 +4,8 @@ import inspect
 import pkgutil
 import weakref
 import kevin_toolbox.nested_dict_list as ndl
+from kevin_toolbox.patches import for_os
+from kevin_toolbox.patches.for_os import Path_Ignorer, Ignore_Scope
 
 
 class Registry:
@@ -218,14 +220,22 @@ class Registry:
 
     # -------------------- 通过路径添加 --------------------- #
 
-    def collect_from_paths(self, path_ls=None, path_ls_to_exclude=None, b_execute_now=False):
+    def collect_from_paths(self, path_ls=None, ignore_s=None, b_execute_now=False):
         """
             遍历 path_ls 下的所有模块，并自动导入其中主要被注册的部分
                 比如被 register() 装饰器包裹或者通过 add() 添加的部分
 
             参数：
                 path_ls:            <list of paths> 需要搜索的目录
-                path_ls_to_exclude: <list of paths> 需要排除的目录
+                ignore_s:           <list/tuple of dict> 在搜索遍历目录时候要执行的排除规则
+                                        具体设置方式参考 patches.for_os.walk() 中的 ignore_s 参数。
+                                        比如使用下面的规则就可以排除待搜索目录下的所有 temp/ 和 test/ 文件夹：
+                                        [
+                                            {
+                                                "func": lambda _, __, path: os.path.basename(path) in ["temp", "test"],
+                                                "scope": ["root", "dirs"]
+                                            },
+                                        ]
                 b_execute_now:      <boolean> 现在就执行导入
                                         默认为 False，将等到第一次执行 get() 函数时才会真正尝试导入
 
@@ -243,10 +253,13 @@ class Registry:
             f'calling Registry.collect_from_paths() in __init__.py is forbidden, file: {caller_frame.filename}.\n' \
             f'you can call it in other files, and then import the result of the call in __init__.py'
 
+        # 根据 ignore_s 构建 Path_Ignorer
+        path_ignorer = ignore_s if isinstance(ignore_s, (Path_Ignorer,)) else Path_Ignorer(ignore_s=ignore_s)
+
         #
         if not b_execute_now:
             self._path_to_collect.append(
-                dict(path_ls=path_ls, path_ls_to_exclude=path_ls_to_exclude, b_execute_now=True))
+                dict(path_ls=path_ls, ignore_s=path_ignorer, b_execute_now=True))
             return
 
         #
@@ -254,27 +267,38 @@ class Registry:
             temp = []
             for path in filter(lambda x: os.path.isdir(x), path_ls):
                 temp.append(path)
-                for root, dirs, _ in os.walk(path, topdown=False):
+                for root, dirs, _ in for_os.walk(path, topdown=False, ignore_s=path_ignorer, followlinks=True):
                     temp.extend([os.path.join(root, i) for i in dirs])
-            if path_ls_to_exclude is not None:
-                for path_ex in path_ls_to_exclude:
-                    if not os.path.exists(path_ex):
-                        continue
-                    for i in reversed(range(len(temp))):
-                        if os.path.samefile(os.path.commonpath([path_ex, temp[i]]), path_ex):
-                            temp.pop(i)
             # 从深到浅导入，可以避免继承引起的 TypeError: super(type, obj) 类型错误
             path_ls = list(set(temp))
             path_ls.sort(reverse=True)
+        path_set = set(path_ls)
 
         temp = None
         for loader, module_name, is_pkg in pkgutil.walk_packages(path_ls):
+            # 判断该模块是否需要导入
+            #   （快速判断）判断该模块所在目录是否在 path_set 中
+            if loader.path not in path_set:
+                continue
+            if is_pkg:
+                #   若不是 package，判断是否满足 Path_Ignorer 中的 dirs 对应的规则
+                path = os.path.dirname(loader.find_module(module_name).path)
+                if path_ignorer(Ignore_Scope.DIRS, True, os.path.islink(path), path):
+                    continue
+            else:
+                #   若该模块是 package，判断该模块的文件路径是否满足 Path_Ignorer 中的 files 对应的规则
+                path = loader.find_module(module_name).path
+                if path_ignorer(Ignore_Scope.FILES, False, os.path.islink(path), path):
+                    continue
+            # 加载模块
             module = loader.find_module(module_name).load_module(module_name)
+            # 选择遍历过程中第一次找到的 Registry 实例
             if temp is None:
                 for name, obj in inspect.getmembers(module):
                     if getattr(obj, "name", None) == Registry.name and getattr(obj, "uid", None) == self.uid:
                         temp = obj
                         break
+
         if temp is not None:
             self.database = temp.database
 

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/computer_science/algorithm/statistician/__init__.py

@@ -1,2 +1,3 @@
+from .accumulator_base import Accumulator_Base
 from .exponential_moving_average import Exponential_Moving_Average
 from .average_accumulator import Average_Accumulator

kevin-toolbox-dev-1.3.0/kevin_toolbox/computer_science/algorithm/statistician/accumulator_base.py

@@ -0,0 +1,146 @@
+from kevin_toolbox.computer_science.algorithm.statistician import init_var
+import kevin_toolbox.nested_dict_list as ndl
+
+
+class Accumulator_Base(object):
+    """
+        累积型统计器的抽象基类
+
+        包含以下变量：
+            self.var            <torch.tensor / np.ndarray / int / float> 用于保存累积值
+                                    使用 statistician._init_var() 函数进行初始化。
+                                    有三种初始化累积值（指定输入数据的格式）方式：
+                                        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()
+                                            时再根据输入来自动推断。
+                                            要实现该方式，需要在 add() 中添加:
+                                                if self.var is None:
+                                                    self.var = self._init_var(like=var)
+                                        以上三种方式，默认选用最后一种。
+                                        如果三种方式同时被指定，则优先级与对应方式在上面的排名相同。
+            self.state          <dict> 用于保存状态的字典
+                                    其中包含以下字段：
+                                        "total_nums":     <int> 用于统计一共调用了多少次 self.add() 方法去进行累积
+            self.paras          <dict> 用于保存构建实例时的各个参数
+
+        包含以下接口：
+            add()               (*)添加单个数据
+            add_sequence()      (*)添加一系列数据
+            get()               (*)获取累积值
+            clear()             情况已有数据（self.var）和状态（self.state）
+            state_dict()        返回当前实例的状态（返回一个包含 self.var 和 self.state 的字典）
+            load_state_dict()   通过接受 state_dict 来更新当前实例的状态
+
+        有可能需要另外实现or覆写的函数：
+            上面带有 (*)的接口
+            _init_state() 方法
+            _init_var() 方法
+    """
+
+    def __init__(self, **kwargs):
+        """
+            至少包含以下参数：
+                data_format:            指定数据格式（对应方式1）
+                like:                   指定数据格式（对应方式2）
+        """
+        # 默认参数
+        paras = {
+            # 指定输入数据的形状、设备
+            "data_format": None,
+            "like": None,
+        }
+
+        # 获取参数
+        paras.update(kwargs)
+
+        # 校验参数
+        #
+        self.paras = paras
+        self.var = self._init_var(like=paras["like"], data_format=paras["data_format"])
+        self.state = self._init_state()
+
+    def add_sequence(self, var_ls, **kwargs):
+        # for var in var_ls:
+        #     self.add(var)
+        raise NotImplementedError
+
+    def add(self, var, **kwargs):
+        """
+            添加单个数据
+
+            参数:
+                var:                数据
+        """
+        # if self.var is None:
+        #     self.var = self._init_var(like=var)
+        # # 累积
+        # self.state["total_nums"] += 1
+        # # 对 self.var 做处理（需要具体实现）
+        raise NotImplementedError
+
+    def get(self, **kwargs):
+        """
+            获取当前累加的平均值
+                当未有累积时，返回 None
+        """
+        # if len(self) == 0:
+        #     return None
+        # # 对 self.var 做处理并返回（需要具体实现）
+        raise NotImplementedError
+
+    @staticmethod
+    def _init_state():
+        """
+            初始化状态
+        """
+        return dict(
+            total_nums=0,
+        )
+
+    @staticmethod
+    def _init_var(like=None, data_format=None):
+        if like is not None:
+            var = init_var.by_like(var=like)
+        elif data_format is not None:
+            var = init_var.by_data_format(**kwargs)
+        else:
+            var = None
+        return var
+
+    def clear(self):
+        self.var = self._init_var(like=self.var)
+        self.state = self._init_state()
+
+    def __len__(self):
+        return self.state["total_nums"]
+
+    # ---------------------- 用于保存和加载状态 ---------------------- #
+
+    def load_state_dict(self, state_dict):
+        """
+            加载状态
+        """
+        self.clear()
+        self.state.update(state_dict.get("state", dict()))
+        if state_dict.get("var", None) is not None:
+            if self.var is None:
+                self.var = state_dict["var"]
+            else:
+                self.var *= 0
+                self.var += state_dict["var"]
+
+    def state_dict(self):
+        """
+            获取状态
+        """
+        return ndl.copy_(var={"state": self.state, "var": self.var}, b_deepcopy=True, b_keep_internal_references=True)

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/computer_science/algorithm/statistician/average_accumulator.py

@@ -1,10 +1,7 @@
-import copy
-import torch
-import numpy as np
-from kevin_toolbox.computer_science.algorithm.statistician._init_var import _init_var
+from kevin_toolbox.computer_science.algorithm.statistician import Accumulator_Base
 
 
-class Average_Accumulator:
+class Average_Accumulator(Accumulator_Base):
     """
         用于计算平均值的累积器
     """
@@ -30,30 +27,13 @@ class Average_Accumulator:
                         以上三种方式，默认选用最后一种。
                         如果三种方式同时被指定，则优先级与对应方式在上面的排名相同。
         """
+        super(Average_Accumulator, self).__init__(**kwargs)
 
-        # 默认参数
-        paras = {
-            # 指定输入数据的形状、设备
-            "data_format": None,
-            "like": None,
-        }
-
-        # 获取参数
-        paras.update(kwargs)
-
-        # 校验参数
-        #
-        self.paras = paras
-        self.var = _init_var(like=paras["like"], data_format=paras["data_format"])
-        self.state = dict(
-            total_nums=0,
-        )
-
-    def add_sequence(self, var_ls):
+    def add_sequence(self, var_ls, **kwargs):
         for var in var_ls:
             self.add(var)
 
-    def add(self, var):
+    def add(self, var, **kwargs):
         """
             添加单个数据
 
@@ -61,12 +41,12 @@ class Average_Accumulator:
                 var:                数据
         """
         if self.var is None:
-            self.var = _init_var(like=var)
+            self.var = self._init_var(like=var)
         # 累积
         self.var += var
         self.state["total_nums"] += 1
 
-    def get(self):
+    def get(self, **kwargs):
         """
             获取当前累加的平均值
                 当未有累积时，返回 None
@@ -75,17 +55,10 @@ class Average_Accumulator:
             return None
         return self.var / len(self)
 
-    def clear(self):
-        self.var = _init_var(like=self.var)
-        self.state = dict(
-            total_nums=0,
-        )
-
-    def __len__(self):
-        return self.state["total_nums"]
-
 
 if __name__ == '__main__':
+    import torch
+
     seq = list(torch.tensor(range(1, 10)))
     avg = Average_Accumulator()
     for i, v in enumerate(seq):

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/computer_science/algorithm/statistician/exponential_moving_average.py

@@ -1,10 +1,7 @@
-import copy
-import torch
-import numpy as np
-from kevin_toolbox.computer_science.algorithm.statistician._init_var import _init_var
+from kevin_toolbox.computer_science.algorithm.statistician import Accumulator_Base
 
 
-class Exponential_Moving_Average:
+class Exponential_Moving_Average(Accumulator_Base):
     """
         滑动平均器
             支持为每个输入数据配置不同的权重
@@ -59,12 +56,7 @@ class Exponential_Moving_Average:
         # 校验参数
         assert isinstance(paras["keep_ratio"], (int, float,)) and 0 <= paras["keep_ratio"] <= 1
         #
-        self.paras = paras
-        self.var = _init_var(like=paras["like"], data_format=paras["data_format"])
-        self.state = dict(
-            total_nums=0,
-            bias_fix=1,
-        )
+        super(Exponential_Moving_Average, self).__init__(**paras)
 
     def add_sequence(self, var_ls, weight_ls=None):
         if weight_ls is not None:
@@ -87,7 +79,7 @@ class Exponential_Moving_Average:
                                         默认为 1
         """
         if self.var is None:
-            self.var = _init_var(like=var)
+            self.var = self._init_var(like=var)
         new_ratio = (1 - self.paras["keep_ratio"]) * weight
         keep_ratio = (1 - new_ratio)
         # 累积
@@ -113,18 +105,18 @@ class Exponential_Moving_Average:
         else:
             return self.var
 
-    def clear(self):
-        self.var = _init_var(like=self.var)
-        self.state = dict(
+    @staticmethod
+    def _init_state():
+        return dict(
             total_nums=0,
             bias_fix=1,
         )
 
-    def __len__(self):
-        return self.state["total_nums"]
-
 
 if __name__ == '__main__':
+    import torch
+    import numpy as np
+
     seq = list(torch.tensor(range(1, 10)))
     wls = np.asarray([0.1] * 5 + [0.9] + [0.1] * 4) * 0.1
     ema = Exponential_Moving_Average(keep_ratio=0.9, bias_correction=True)

kevin-toolbox-dev-1.3.0/kevin_toolbox/computer_science/algorithm/statistician/init_var/__init__.py

@@ -0,0 +1,2 @@
+from .init_by_like import init_by_like as by_like
+from .init_by_data_format import init_by_data_format as by_data_format

kevin-toolbox-dev-1.3.0/kevin_toolbox/computer_science/algorithm/statistician/init_var/init_by_data_format.py

@@ -0,0 +1,24 @@
+import torch
+import numpy as np
+
+
+def init_by_data_format(type_, shape, **kwargs):
+    """
+        构建一个与输入 var 具有相同类型、形状、设备的 0 数组
+
+        参数：
+            type_:              <str>
+                                    "numpy":        np.ndarray
+                                    "torch":        torch.tensor
+                                    "number":       float
+            shape:              <list of integers>
+            device:             <torch.device>
+            dtype:              <torch.dtype / np.dtype>
+    """
+    if type_ == "torch":
+        res = torch.zeros(size=shape, **kwargs)
+    elif type_ == "numpy":
+        res = np.zeros(shape=shape, **kwargs)
+    else:
+        res = 0.0
+    return res

kevin-toolbox-dev-1.3.0/kevin_toolbox/computer_science/algorithm/statistician/init_var/init_by_like.py

@@ -0,0 +1,20 @@
+import torch
+import numpy as np
+
+
+def init_by_like(var):
+    """
+        构建一个与输入 var 具有相同类型、形状、设备的 0 数组
+
+        参数：
+            var:                <torch.tensor / np.ndarray / int / float>
+    """
+    if torch.is_tensor(var):
+        res = torch.zeros_like(var)
+    elif isinstance(var, (np.ndarray,)):
+        res = np.zeros_like(var)
+    elif isinstance(var, (int, float, np.number,)):
+        res = 0.0
+    else:
+        raise ValueError("paras 'like' should be np.ndarray, torch.tensor or int/float")
+    return res

{kevin-toolbox-dev-1.2.7 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/data_flow/file/json_/read_json.py

@@ -19,7 +19,7 @@ def read_json(file_path, converters=None, b_use_suggested_converter=False):
                                             默认为 False。
                     注意：当 converters 非 None，此参数失效，以 converters 中的具体设置为准
     """
-    assert os.path.isfile(file_path)
+    assert os.path.isfile(file_path), f'file {file_path} not found'
     if converters is None and b_use_suggested_converter:
         converters = [unescape_tuple, unescape_non_str_dict_key]