kevin-toolbox-dev 1.2.8__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.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.8"
+__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 1715414856 --verbose 0'
+    f'--expiration_timestamp 1718018144 --verbose 0'
 )

{kevin-toolbox-dev-1.2.8 → 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.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/nested_dict_list/serializer/__init__.py

@@ -1,2 +1,3 @@
 from .write import write
 from .read import read
+from .enum_variable import Strictness_Level

kevin-toolbox-dev-1.2.8/kevin_toolbox/nested_dict_list/serializer/variable.py → kevin-toolbox-dev-1.3.0/kevin_toolbox/nested_dict_list/serializer/enum_variable.py

@@ -1,12 +1,4 @@
-import os
 from enum import Enum
-from kevin_toolbox.computer_science.algorithm.registration import Registry
-
-SERIALIZER_BACKEND = Registry(uid="SERIALIZER_BACKEND")
-
-# 从 kevin_toolbox/nested_dict_list/serializer/backends 下收集被注册的 backend
-SERIALIZER_BACKEND.collect_from_paths(path_ls=[os.path.join(os.path.dirname(__file__), "backends"), ],
-                                      b_execute_now=False)
 
 
 class Strictness_Level(Enum):

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/nested_dict_list/serializer/read.py

@@ -3,7 +3,6 @@ import time
 from kevin_toolbox.patches import for_os
 from kevin_toolbox.data_flow.file import json_
 import kevin_toolbox.nested_dict_list as ndl
-from kevin_toolbox.nested_dict_list.serializer.variable import SERIALIZER_BACKEND
 
 
 def read(input_path, **kwargs):
@@ -13,6 +12,8 @@ def read(input_path, **kwargs):
         参数：
             input_path:             <path> 文件夹或者 .tar 文件，具体结构参考 write()
     """
+    from kevin_toolbox.nested_dict_list.serializer.variable import SERIALIZER_BACKEND
+
     assert os.path.exists(input_path)
 
     # 解压

kevin-toolbox-dev-1.3.0/kevin_toolbox/nested_dict_list/serializer/variable.py

@@ -0,0 +1,8 @@
+import os
+from kevin_toolbox.computer_science.algorithm.registration import Registry
+
+SERIALIZER_BACKEND = Registry(uid="SERIALIZER_BACKEND")
+
+# 从 kevin_toolbox/nested_dict_list/serializer/backends 下收集被注册的 backend
+SERIALIZER_BACKEND.collect_from_paths(path_ls=[os.path.join(os.path.dirname(__file__), "backends"), ],
+                                      b_execute_now=False)

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/nested_dict_list/serializer/write.py

@@ -6,7 +6,7 @@ from kevin_toolbox.data_flow.file import json_
 from kevin_toolbox.patches import for_os
 import kevin_toolbox.nested_dict_list as ndl
 from kevin_toolbox.nested_dict_list.traverse import Traversal_Mode
-from kevin_toolbox.nested_dict_list.serializer.variable import SERIALIZER_BACKEND, Strictness_Level
+from .enum_variable import Strictness_Level
 
 
 def write(var, output_dir, settings=None, traversal_mode=Traversal_Mode.BFS, b_pack_into_tar=True,
@@ -83,6 +83,7 @@ def write(var, output_dir, settings=None, traversal_mode=Traversal_Mode.BFS, b_p
                                                                                             的 backend 之后仍然无法写入
                                         默认是 "normal"
     """
+    from kevin_toolbox.nested_dict_list.serializer.variable import SERIALIZER_BACKEND
 
     #
     traversal_mode = Traversal_Mode(traversal_mode)

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/nested_dict_list/set_value.py

@@ -52,11 +52,17 @@ def set_value(var, name, value, b_force=False):
             raise ValueError(f'The location pointed to by name {name} does not exist in var')
         else:
             if method_ls[-1] in "|:":
+                # 对于字符串默认使用 dict 构建
                 value = {raw_key: value}
             else:
+                # 对于需要eval的情况
                 key = eval(raw_key)
-                assert isinstance(key, (int,)) and key >= 0
-                value = [None] * key + [value]
+                if isinstance(key, (int,)) and key >= 0:
+                    # 只有当 key 为非负整数时，才会使用 list 构建
+                    value = [None] * key + [value]
+                else:
+                    # 其他，比如当 key 为元组、浮点数等等时，则使用 dict 构建
+                    value = {key: value}
             var = set_value(var=var, name=name[:-1 - len(node_ls[-1])], value=value, b_force=b_force)
 
     return var

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/patches/for_optuna/sample_from_feasible_domain.py

@@ -2,14 +2,14 @@ import optuna
 import kevin_toolbox.nested_dict_list as ndl
 
 
-def sample_from_feasible_domain(var, trial: optuna.trial.BaseTrial, pre_name=""):
+def sample_from_feasible_domain(var, trial: optuna.trial.BaseTrial, f_p_name_builder=None, b_use_name_as_idx=True):
     """
         使用试验 trial 基于输入中的定义域 feasible_domain 部分进行参数采样和替换。
             遍历输入中的所有元素，找出符合 <feasible_domain> 格式要求的记录了参数定义域的元素，
             然后使用输入的试验实例 trial 结合参数定义域采样出对应的参数，最后用采样出来的参数替换掉原来的定义域。
 
         参数：
-            inputs:             <list/dict> 当其中的元素满足 <feasible_domain> 格式要求，将进行采样与替换。
+            var:                <list/dict> 当其中的元素满足 <feasible_domain> 格式要求，将进行采样与替换。
                                     <feasible_domain> 格式要求：
                                         1. 是一个 dictionary
                                         2. 包含 "p_type"  字段
@@ -20,15 +20,26 @@ def sample_from_feasible_domain(var, trial: optuna.trial.BaseTrial, pre_name="")
                                         更多参见 https://optuna.readthedocs.io/zh_CN/latest/reference/generated/optuna.trial.Trial.html#optuna.trial.Trial
                                         中的 suggest_xxx() 函数。
             trial:              <optuna.trial.BaseTrial> 试验
-            pre_name:           <string> 采样出的参数在试验 trial 中注册的名称的前缀
+            f_p_name_builder:   <callable> 对于采样出的参数，使用该函数构建其在试验 trial 中注册的名称。
+                                    函数类型为 def(idx, p_type): ...
+                                    其中：
+                                        idx             被采样的节点在 var 中的位置
+                                                            当 b_use_name_as_idx=False 时，
+                                                                对于列表是 index，对于字典是 key
+                                                            当为 True 时，传入的是元素在整体结构中的 name 位置，name的格式和含义参考
+                                                                name_handler.parse_name() 中的介绍
+                                        p_type          被采样的节点中的 "p_type" 字段
+                                    默认为：
+                                        lambda idx, p_type: idx
+            b_use_name_as_idx:  <boolean> 决定传入 f_p_name_builder 中的参数 idx 的形式。
 
         返回：
-            var, name_ls
+            var, node_vs_paras_s
                 var 是采样后的结果
-                name_ls 是被采样的节点名称，注意并不带 pre_name 前缀
+                node_vs_paras_s 是一个<dict>，以被采样的节点在 var 中位置的名称作为键，以对应节点在 trial 中注册的参数名为值。
 
         实例：
-            对于输入 inputs={
+            对于输入 var={
                             "thr":[
                                 "interval_thr": {
                                     "p_type": "categorical",
@@ -56,19 +67,33 @@ def sample_from_feasible_domain(var, trial: optuna.trial.BaseTrial, pre_name="")
                             ]
                         }
             可能返回的采样结果是 res={"thr":[{"interval_thr":1000}, {"iou_thr":0.6}, {"connection":lambda x:x} ], }。
-            当 pre_name="my" 时，这些参数在 trial 中注册的名称分别是 "my:thr@0:interval_thr"，"my:thr@1:iou_thr" 和 "my:thr@1:connection"。
+            当 f_p_name_builder=lambda idx, p_type: f'my{idx}' 时，
+            这些参数在 trial 中注册的名称分别是 "my:thr@0:interval_thr"，"my:thr@1:iou_thr" 和 "my:thr@1:connection"。
             特别地，
                 - 对于字典形式的 choices，其中保存在 trial 中的取值是其键 key 而非 value。
                 - 对于list形式，但含有非支持类型的  choices，其中保存在 trial 中的取值是元素的 index。
             这些名称的含义详见 get_value()。
     """
+    if f_p_name_builder is None:
+        f_p_name_builder = lambda idx, p_type: idx
+    if not b_use_name_as_idx:
+        p_name_builder = lambda idx, p_type: f_p_name_builder(ndl.name_handler.parse_name(idx)[-1][-1], p_type)
+    else:
+        p_name_builder = f_p_name_builder
 
-    name_ls=[]
+    node_vs_paras_s = dict()
+    p_name_set = set()
 
     def func(idx, v):
-        nonlocal name_ls
+        nonlocal node_vs_paras_s, p_name_builder
+
         p_type = v.pop("p_type")
+        p_name = v.pop("p_name") if "p_name" in v else f'{p_name_builder(idx, p_type)}'
+        assert p_name not in p_name_set, \
+            f"p_name={p_name} is duplicated!"
+        p_name_set.add(p_name)
         kwargs = v
+        #
         choice_values = None
         if p_type == "categorical":
             # optuna 目前的类别元素仅支持 None, bool, int, float 和 str 类型
@@ -83,14 +108,15 @@ def sample_from_feasible_domain(var, trial: optuna.trial.BaseTrial, pre_name="")
                 choice_values = kwargs["choices"]
                 kwargs["choices"] = list(kwargs["choices"].keys())
 
-        v = eval(f'trial.suggest_{p_type}(name=name, **kwargs)',
-                 {"trial": trial, "name": f'{pre_name}{idx}', "kwargs": kwargs})
+        v = eval(f'trial.suggest_{p_type}(name=name, **kwargs)', {"trial": trial, "name": p_name, "kwargs": kwargs})
         if choice_values is not None:
             v = choice_values[v]
-        name_ls.append(idx)
+
+        #
+        node_vs_paras_s[idx] = p_name
         return v
 
     var = ndl.traverse(var=var, match_cond=lambda _, __, v: isinstance(v, (dict,)) and "p_type" in v,
                        action_mode="replace", converter=func, b_use_name_as_idx=True)
 
-    return var, name_ls
+    return var, node_vs_paras_s

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/patches/for_os/__init__.py

@@ -1,3 +1,4 @@
 from .remove import remove
 from .pack import pack
 from .unpack import unpack
+from .walk import walk, Path_Ignorer, Ignore_Scope

{kevin-toolbox-dev-1.2.8 → kevin-toolbox-dev-1.3.0}/kevin_toolbox/patches/for_os/remove.py

@@ -4,13 +4,15 @@ import shutil
 
 def remove(path, ignore_errors=False):
     """
-        移除文件/文件夹
+        移除文件/文件夹/软连接
 
         返回:
             boolean 是否成功
     """
     try:
-        if os.path.isfile(path):  # 移除文件
+        if os.path.islink(path):  # 移除软连接
+            os.unlink(path)
+        elif os.path.isfile(path):  # 移除文件
             os.remove(path)
         elif os.path.isdir(path):  # 移除文件夹
             shutil.rmtree(path=path, ignore_errors=False)

kevin-toolbox-dev-1.3.0/kevin_toolbox/patches/for_os/walk.py

@@ -0,0 +1,167 @@
+import os
+from collections import defaultdict
+from enum import Enum
+
+
+class Ignore_Scope(Enum):
+    ROOT = "root"
+    DIRS = "dirs"
+    FILES = "files"
+
+
+class Path_Ignorer:
+    def __init__(self, ignore_s=None):
+        self.ignore_s = defaultdict(list)
+        try:
+            if isinstance(ignore_s, (list, tuple)):
+                for it in ignore_s:
+                    for scope in it["scope"]:
+                        scope = Ignore_Scope(scope)
+                        self.ignore_s[scope].append(it["func"])
+            elif isinstance(ignore_s, (dict,)):
+                for k, v in ignore_s.items():
+                    self.ignore_s[Ignore_Scope(k)].extend(v)
+        except:
+            raise ValueError(f'invalid ignore_s, got a {ignore_s}')
+
+    def __call__(self, scope, *args, **kwargs):
+        for func in self.ignore_s[scope]:
+            if func(*args, **kwargs):
+                return True
+        return False
+
+    def __len__(self):
+        return len(self.ignore_s)
+
+
+def walk(top, topdown=True, onerror=None, followlinks=False, ignore_s=None):
+    """
+        在 os.walk() 的基础上增加了以下功能
+            - 可以通过 ignore_s 参数来排除特定的目录和文件
+
+        参数：
+            （对于参数 top,topdown,onerror,followlinks，其用法与 os.walk() 完全相同）
+            top:                <path> 要遍历的目录
+            topdown:            <boolean> 是否从浅到深遍历
+                                    默认为 True，优先遍历完浅层目录
+            onerror:            <callable> 当遇到异常时，会调用该函数
+            followlinks:        <boolean> 是否遍历软链接目录
+                                    默认为 False，不对软链接进行进一步遍历
+            ignore_s:           <list/tuple of dict or dict> 排除规则
+                                    有两种输入方式：
+
+                                    方式 1 <list/tuple of dict>：
+                                        列表中每个字典需要具有以下键值对：
+                                            "scope":    <list/tuple of str> 该规则的作用范围
+                                                            可选值，及（满足规则时）对应效果：
+                                                                "root":         不遍历满足规则的目录
+                                                                "dirs":         将返回的三元组中第二个 dirs 部分中满足规则的部分移除
+                                                                "files":        将返回的三元组中第三个 files 部分中满足规则的部分移除
+                                            "func":     <callable> 排除规则
+                                                            当调用该函数的返回值为 True 时，执行排除。
+                                                            函数类型为 def(b_is_dir, b_is_symlink, path): ...
+                                                            其中：
+                                                                b_is_dir        是否是目录
+                                                                b_is_symlink    是否是软链接
+                                                                path            输入是对于作用范围 "root"，输入的直接就是 root，
+                                                                                对于作用范围 "dirs"，输入是 dirs 中的每个元素和 root 组成的绝对路径，
+                                                                                对于作用范围 "files"，输入是 files 中的每个元素和 root 组成的绝对路径。
+                                            注意：
+                                                - 当有多个规则时，只要满足其一即会进行排除。
+                                                - 任何规则都不会对 top 目录进行过滤，亦即对 top 的遍历是必然的。不能通过设定某个 top 满足的规则来停止对 top 的遍历。
+                                        比如，通过下面的规则就可以实现不对 basename 为 "test" 和 "temp" 的目录进行遍历和输出，
+                                        同时只保留非软连接的 .png 和 .jpg 文件：
+                                            [
+                                                {
+                                                    "func": lambda _, __, path: os.path.basename(path) in ["temp", "test"],
+                                                    "scope": ["root", "dirs"]
+                                                },
+                                                {
+                                                    "func": lambda _, b_is_symlink, path: b_is_symlink or not path.endswith((".png",".jpg")),
+                                                    "scope": ["files", ]
+                                                }
+                                            ]
+
+                                    方式 2 <dict>:
+                                        一个以 scope 为键，func 为值的字典。
+                                        延续上面的例子，其另一种等效形式为：
+                                            {
+                                                "root": [
+                                                    lambda _, __, path: os.path.basename(path) in ["temp", "test"],
+                                                ],
+                                                "dirs": [
+                                                    lambda _, __, path: os.path.basename(path) in ["temp", "test"],
+                                                ],
+                                                "files": [
+                                                    lambda _, b_is_symlink, path: b_is_symlink or not path.endswith((".png",".jpg")),
+                                                ]
+                                            }
+
+                                    方式 3 <Path_Ignorer>:
+                                        根据 ignore_s 构建的 Path_Ignorer
+
+    """
+    # 根据 ignore_s 构建 Path_Ignorer
+    path_ignorer = ignore_s if isinstance(ignore_s, (Path_Ignorer,)) else Path_Ignorer(ignore_s=ignore_s)
+
+    #
+    yield from __walk(top, topdown, onerror, followlinks, path_ignorer)
+
+
+def __walk(top, topdown, onerror, followlinks, path_ignorer):
+    #
+    top = os.fspath(top)
+    dirs, files = [], []
+    walk_dirs = []
+
+    try:
+        scandir_it = os.scandir(top)
+    except OSError as error:
+        if onerror is not None:
+            onerror(error)
+        return
+
+    with scandir_it:
+        while True:
+            try:
+                try:
+                    entry = next(scandir_it)
+                except StopIteration:
+                    break
+            except OSError as error:
+                if onerror is not None:
+                    onerror(error)
+                return
+
+            try:
+                is_dir = entry.is_dir()
+            except OSError:
+                is_dir = False
+
+            if is_dir:
+                dirs.append(entry.name)
+                walk_dirs.append(os.path.join(top, entry.name))
+            else:
+                files.append(entry.name)
+
+    # 过滤
+    if len(path_ignorer) > 0:
+        for it_ls, scope in zip([walk_dirs, dirs, files], [Ignore_Scope.ROOT, Ignore_Scope.DIRS, Ignore_Scope.FILES]):
+            for i in reversed(range(len(it_ls))):
+                path = os.path.join(top, it_ls[i]) if scope != Ignore_Scope.ROOT else it_ls[i]
+                if path_ignorer(scope, scope != Ignore_Scope.FILES, os.path.islink(path), path):
+                    it_ls.pop(i)
+
+    #
+    if topdown:
+        yield top, dirs, files
+        #
+        for new_path in walk_dirs:
+            if followlinks or not os.path.islink(new_path):
+                yield from __walk(new_path, topdown, onerror, followlinks, path_ignorer)
+    else:
+        for new_path in walk_dirs:
+            if followlinks or not os.path.islink(new_path):
+                yield from __walk(new_path, topdown, onerror, followlinks, path_ignorer)
+        #
+        yield top, dirs, files