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

kevin-toolbox-dev-1.4.11/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.1
+Name: kevin-toolbox-dev
+Version: 1.4.11
+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.11 （2025-04-16）【bug fix】
+
+  - nested_dict_list
+    - 【bug fix】fix bug in value_parser.replace_identical_with_reference()
+      - bug 描述：该函数的 _forward 中是通过 get_nodes 来获取各层节点，并记录节点的 id 和 level，这就导致某些节点由于其下具有不同长度的到叶节点的路径，因此节点会同时属于多个 level，最终导致其在 id_to_height_s 中被记录为有多个高度，这进一步导致其无法通过后面“具有相同 id 的节点所处的高度应该相同”的检验条件。
+      - 解决：
+        - 修复了 replace_identical_with_reference() 中的 _forward 部分，仅记录每个节点的最大高度。
+        - 去除了“具有相同 id 的节点所处的高度应该相同”的检验条件。
+  - computer_science.algorithm.redirector
+    - 【bug fix】fix bug in Redirectable_Sequence_Fetcher，将 _randomly_idx_redirector 中的 rng.choices 改为 rng.choice
+  - 添加了对应的测试用例。
+
+
+

kevin-toolbox-dev-1.4.11/README.md

@@ -0,0 +1,41 @@
+# 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.11 （2025-04-16）【bug fix】
+
+  - nested_dict_list
+    - 【bug fix】fix bug in value_parser.replace_identical_with_reference()
+      - bug 描述：该函数的 _forward 中是通过 get_nodes 来获取各层节点，并记录节点的 id 和 level，这就导致某些节点由于其下具有不同长度的到叶节点的路径，因此节点会同时属于多个 level，最终导致其在 id_to_height_s 中被记录为有多个高度，这进一步导致其无法通过后面“具有相同 id 的节点所处的高度应该相同”的检验条件。
+      - 解决：
+        - 修复了 replace_identical_with_reference() 中的 _forward 部分，仅记录每个节点的最大高度。
+        - 去除了“具有相同 id 的节点所处的高度应该相同”的检验条件。
+  - computer_science.algorithm.redirector
+    - 【bug fix】fix bug in Redirectable_Sequence_Fetcher，将 _randomly_idx_redirector 中的 rng.choices 改为 rng.choice
+  - 添加了对应的测试用例。
+

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

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

kevin-toolbox-dev-1.4.11/kevin_toolbox/computer_science/algorithm/cache_manager/__init__.py

@@ -0,0 +1,2 @@
+from .cache_manager_wto_strategy import Cache_Manager_wto_Strategy
+from .cache_manager import Cache_Manager

{kevin-toolbox-dev-1.4.9 → kevin-toolbox-dev-1.4.11}/kevin_toolbox/computer_science/algorithm/cache_manager/cache/cache_base.py

@@ -12,6 +12,7 @@ class Cache_Base(ABC):
             - 判断是否命中 has()
             - 获取缓存已占空间 len()
             - 清空所有内容 clear()
+            - 加载和保存状态 load_state_dict(), state_dict()
         等方法。
 
         对外提供：
@@ -21,6 +22,7 @@ class Cache_Base(ABC):
             - 判断是否命中 has()
             - 获取缓存已占空间 len()
             - 清空所有内容 clear()
+            - 加载和保存状态 load_state_dict(), state_dict()
         等接口。
     """
 
@@ -69,6 +71,14 @@ class Cache_Base(ABC):
     def clear(self):
         pass
 
+    @abstractmethod
+    def load_state_dict(self, state_dict):
+        pass
+
+    @abstractmethod
+    def state_dict(self, b_deepcopy=True):
+        pass
+
     def __getitem__(self, key):
         # self[key]
         return self.read(key=key)

{kevin-toolbox-dev-1.4.9 → kevin-toolbox-dev-1.4.11}/kevin_toolbox/computer_science/algorithm/cache_manager/cache/memo_cache.py

@@ -30,6 +30,23 @@ class Memo_Cache(Cache_Base):
     def clear(self):
         self.cache_s.clear()
 
+    def load_state_dict(self, state_dict):
+        """
+            加载状态
+        """
+        self.clear()
+        self.cache_s.update(state_dict["cache_s"])
+
+    def state_dict(self, b_deepcopy=True):
+        """
+            获取状态
+        """
+        temp = {"cache_s": self.cache_s}
+        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
+
 
 # 添加其他别名
 for name in [":in_memory:Memo", ":in_memory:MC", ":in_memory:memory"]:

{kevin-toolbox-dev-1.4.9 → kevin-toolbox-dev-1.4.11}/kevin_toolbox/computer_science/algorithm/cache_manager/cache_manager.py

@@ -2,9 +2,10 @@ import time
 from .strategy import Strategy_Base
 from .cache import Cache_Base
 from .variable import CACHE_STRATEGY_REGISTRY, CACHE_BUILDER_REGISTRY
+from .cache_manager_wto_strategy import Cache_Manager_wto_Strategy
 
 
-class Cache_Manager:
+class Cache_Manager(Cache_Manager_wto_Strategy):
     """
         缓存管理器
 
@@ -14,6 +15,7 @@ class Cache_Manager:
             - 删除并返回条目 pop(key)
             - 判断是否有该条目 has()
             - 清空所有内容 clear()
+            - 加载和保存状态 load_state_dict(), state_dict()
 
         并支持以下用法：
             通过 len(.) 获取缓存大小，通过 in 操作符判断是否有某个条目
@@ -95,29 +97,7 @@ class Cache_Manager:
         self.cache = cache  # type:Cache_Base
         self.metadata_s = dict()  # 保存条目的相关信息
 
-    def add(self, key, value, b_allow_overwrite=True):
-        """
-            以 key 为查询键，将 value 添加到缓存中
-
-            参数:
-                key:
-                value:
-                b_allow_overwrite:      <boolean> 是否允许覆写缓存中已有的条目
-                                            默认为 True
-        """
-        # 判断是否需要进行覆写
-        if self.cache.has(key=key):
-            if id(value) != id(self.cache.read(key=key)):
-                if b_allow_overwrite:
-                    self.__remove_of_cache(key=key)
-                else:
-                    raise KeyError(f'key: {key} already exists, modification of existing entries is prohibited')
-            else:
-                return
-        # 记录到缓存
-        self.__write_of_cache(key=key, value=value)
-
-    def __write_of_cache(self, key, value):
+    def _write_of_cache(self, key, value):
         """
             向缓存中新增不存在的条目
         """
@@ -143,9 +123,9 @@ class Cache_Manager:
         assert len(suggest_keys) == len(self.cache) - self.paras["refactor_size"], \
             f'expect {len(self.cache) - self.paras["refactor_size"]} deletion suggestions, but got {len(suggest_keys)}'
         for key in suggest_keys:
-            self.__remove_of_cache(key=key)
+            self._remove_of_cache(key=key)
 
-    def __remove_of_cache(self, key):
+    def _remove_of_cache(self, key):
         """
             从缓存中删除存在的条目
         """
@@ -154,43 +134,7 @@ class Cache_Manager:
         # 通知策略管理器
         self.strategy.notified_by_remove_of_cache(key=key, metadata=metadata)
 
-    def get(self, key, b_add_if_not_found=False, default_factory=None, **kwargs):
-        """
-            获取 key 对应的值
-
-            参数:
-                key:                    <hashable>
-                default:                默认值
-                                            当 key 在缓存中不存在时返回
-                default_factory:        <callable> 用于产生默认值的函数
-                                            当 key 在缓存中不存在时返回该函数的结果
-                                            使用该参数相对于 default 能延迟默认值的产生（如果不需要用到默认值就不生成），提高效率
-                        注意！！上面两个参数同时指定时，将以前者为准。
-                b_add_if_not_found:     <boolean> 当 key 在缓存中不存在时，是否添加到缓存中
-                                            默认为 False
-        """
-        if self.cache.has(key=key):
-            value = self.__read_of_cache(key=key)
-        elif "default" in kwargs or callable(default_factory):
-            value = kwargs["default"] if "default" in kwargs else default_factory()
-            if b_add_if_not_found:
-                self.__write_of_cache(key=key, value=value)
-        else:
-            raise KeyError(key)
-        return value
-
-    def pop(self, key):
-        """
-            从缓存中删除 key 对应的条目，并返回该条目的值
-        """
-        if self.cache.has(key=key):
-            value = self.__read_of_cache(key=key)
-            self.__remove_of_cache(key=key)
-        else:
-            raise KeyError(key)
-        return value
-
-    def __read_of_cache(self, key):
+    def _read_of_cache(self, key):
         """
             读取缓存中 已经存在的 条目
         """
@@ -205,20 +149,26 @@ class Cache_Manager:
 
         return value
 
-    def has(self, key):
-        """
-            判断 key 是否在缓存中
-                注意！！不会更新 metadata
-        """
-        return self.cache.has(key=key)
-
     def clear(self):
         self.cache.clear()
         self.metadata_s.clear()
         self.strategy.notified_by_clear_of_cache()
 
-    def __len__(self):
-        return len(self.cache)
+    # ---------------------- 用于保存和加载状态 ---------------------- #
+    def load_state_dict(self, state_dict):
+        """
+            加载状态
+        """
+        self.clear()
+        self.cache.load_state_dict(state_dict=state_dict["cache"])
+        self.metadata_s.update(state_dict["metadata_s"])
 
-    def __contains__(self, key):
-        return self.has(key)
+    def state_dict(self, b_deepcopy=True):
+        """
+            获取状态
+        """
+        temp = {"cache": self.cache.state_dict(b_deepcopy=False), "metadata_s": self.metadata_s}
+        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

kevin-toolbox-dev-1.4.11/kevin_toolbox/computer_science/algorithm/cache_manager/cache_manager_wto_strategy.py

@@ -0,0 +1,157 @@
+from .cache import Cache_Base
+from .variable import CACHE_BUILDER_REGISTRY
+
+
+class Cache_Manager_wto_Strategy:
+    """
+        不绑定任何策略的缓存管理器
+
+        提供以下接口：
+            - 添加条目 add(key, value, b_allow_overwrite)
+            - 获取条目 get(key, b_add_if_not_found, default_factory, default)
+            - 删除并返回条目 pop(key)
+            - 判断是否有该条目 has()
+            - 清空所有内容 clear()
+            - 加载和保存状态 load_state_dict(), state_dict()
+
+        并支持以下用法：
+            通过 len(.) 获取缓存大小，通过 in 操作符判断是否有某个条目
+    """
+
+    def __init__(self, **kwargs):
+        """
+            参数：
+                cache:                  <str/dict/Cache_Base> 缓存种类
+        """
+        # 默认参数
+        paras = {
+            "cache": ":in_memory:Memo",
+        }
+
+        # 获取参数
+        paras.update(kwargs)
+
+        # 校验参数
+        # cache
+        assert isinstance(paras["cache"], (str, dict, Cache_Base)), \
+            "cache must be a string, dict of paras or a Cache_Base object"
+        if isinstance(paras["cache"], str):
+            cache = CACHE_BUILDER_REGISTRY.get(name=paras["cache"])()
+        elif isinstance(paras["cache"], dict):
+            cache = CACHE_BUILDER_REGISTRY.get(name=paras["cache"]["name"])(**paras["cache"].get("paras", dict()))
+        else:
+            cache = paras["cache"]
+
+        self.paras = paras
+        self.cache = cache  # type:Cache_Base
+
+    def _write_of_cache(self, key, value):
+        """
+            向缓存中新增不存在的条目
+        """
+        #
+        self.cache.write(key=key, value=value)
+
+    def _remove_of_cache(self, key):
+        """
+            从缓存中删除存在的条目
+        """
+        self.cache.remove(key=key)
+
+    def _read_of_cache(self, key):
+        """
+            读取缓存中 已经存在的 条目
+        """
+        return self.cache.read(key=key)
+
+    def add(self, key, value, b_allow_overwrite=True):
+        """
+            以 key 为查询键，将 value 添加到缓存中
+
+            参数:
+                key:
+                value:
+                b_allow_overwrite:      <boolean> 是否允许覆写缓存中已有的条目
+                                            默认为 True
+        """
+        # 判断是否需要进行覆写
+        if self.cache.has(key=key):
+            if id(value) != id(self.cache.read(key=key)):
+                if b_allow_overwrite:
+                    self._remove_of_cache(key=key)
+                else:
+                    raise KeyError(f'key: {key} already exists, modification of existing entries is prohibited')
+            else:
+                return
+        # 记录到缓存
+        self._write_of_cache(key=key, value=value)
+
+    def get(self, key, b_add_if_not_found=False, default_factory=None, **kwargs):
+        """
+            获取 key 对应的值
+
+            参数:
+                key:                    <hashable>
+                default:                默认值
+                                            当 key 在缓存中不存在时返回
+                default_factory:        <callable> 用于产生默认值的函数
+                                            当 key 在缓存中不存在时返回该函数的结果
+                                            使用该参数相对于 default 能延迟默认值的产生（如果不需要用到默认值就不生成），提高效率
+                        注意！！上面两个参数同时指定时，将以前者为准。
+                b_add_if_not_found:     <boolean> 当 key 在缓存中不存在时，是否添加到缓存中
+                                            默认为 False
+        """
+        if self.cache.has(key=key):
+            value = self._read_of_cache(key=key)
+        elif "default" in kwargs or callable(default_factory):
+            value = kwargs["default"] if "default" in kwargs else default_factory()
+            if b_add_if_not_found:
+                self._write_of_cache(key=key, value=value)
+        else:
+            raise KeyError(key)
+        return value
+
+    def pop(self, key):
+        """
+            从缓存中删除 key 对应的条目，并返回该条目的值
+        """
+        if self.cache.has(key=key):
+            value = self._read_of_cache(key=key)
+            self._remove_of_cache(key=key)
+        else:
+            raise KeyError(key)
+        return value
+
+    def has(self, key):
+        """
+            判断 key 是否在缓存中
+                注意！！不会更新 metadata
+        """
+        return self.cache.has(key=key)
+
+    def clear(self):
+        self.cache.clear()
+
+    # ---------------------- 用于保存和加载状态 ---------------------- #
+    def load_state_dict(self, state_dict):
+        """
+            加载状态
+        """
+        self.clear()
+        self.cache.load_state_dict(state_dict=state_dict["cache"])
+
+    def state_dict(self, b_deepcopy=True):
+        """
+            获取状态
+        """
+        temp = {"cache": self.cache.state_dict(b_deepcopy=False)}
+        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
+
+    def __len__(self):
+        return len(self.cache)
+
+    def __contains__(self, key):
+        return self.has(key)

{kevin-toolbox-dev-1.4.9 → kevin-toolbox-dev-1.4.11}/kevin_toolbox/computer_science/algorithm/for_seq/__init__.py

@@ -1,3 +1,4 @@
 from .get_subsets import get_subsets
 from .flatten_list import flatten_list
 from .chunk_generator import chunk_generator
+from .sample_subset_most_evenly import sample_subset_most_evenly

kevin-toolbox-dev-1.4.11/kevin_toolbox/computer_science/algorithm/for_seq/sample_subset_most_evenly.py

@@ -0,0 +1,52 @@
+import math
+from kevin_toolbox.patches.for_numpy.random import get_rng
+
+
+def sample_subset_most_evenly(inputs, ratio=None, nums=None, seed=None, rng=None, b_shuffle_the_tail=True):
+    """
+        对列表按给定比例or数量进行采样，并返回一个新的列表，并保证列表中每个元素在新列表中的占比尽量相近
+            说明：
+                根据 ratio/nums 的值，将输入列表重复复制并可能随机打乱尾部元素以保证每个元素都有等概率被选取，
+                生成一个新列表，其长度约为 len(inputs) * ratio  nums。
+                以 ratio 为例：
+                    - 当 ratio 为整数时，返回原列表重复多次的结果；
+                    - 当 ratio 为非整数时，除了重复复制整数倍部分外，
+                      还会从打乱后的列表中随机选取部分元素以达到目标长度。
+
+        参数：
+            inputs:             <iterable> 输入列表或其他可迭代对象
+            ratio:              <float> 采样比例，
+                                    采样后新列表长度约为 len(inputs) * ratio
+            nums:               <int> 采样数量。
+            b_shuffle_the_tail: <boolean> 是否对尾部进行随机打乱
+                                    默认为 True
+            seed:               <int, optional> 随机种子，用于生成确定性随机数
+                                    默认为 None
+            rng:                <Random, optional> 随机数生成器实例
+                        仅在b_shuffle_the_tail=True时，以上两个参数起效，且仅需指定一个即可。
+
+    """
+    if nums is None:
+        assert ratio is not None
+        nums = math.ceil(len(inputs) * ratio)
+    assert nums >= 0
+    if len(inputs) == 0 or nums == 0:
+        return []
+
+    inputs = list(inputs)
+    temp = inputs.copy()
+    if b_shuffle_the_tail:
+        rng = get_rng(seed=seed, rng=rng)
+        rng.shuffle(temp)
+
+    outputs = [] + inputs * math.floor(nums / len(inputs)) + temp[:nums % len(inputs)]
+    return outputs
+
+
+if __name__ == '__main__':
+    print(sample_subset_most_evenly(range(5), ratio=8 / 5, seed=114, b_shuffle_the_tail=False))
+    print(sample_subset_most_evenly(range(5), ratio=8 / 5, seed=114, b_shuffle_the_tail=True))
+
+    #
+    print(sample_subset_most_evenly(range(5), nums=8, seed=114, b_shuffle_the_tail=False))
+    print(sample_subset_most_evenly(range(5), nums=8, seed=114, b_shuffle_the_tail=True))

kevin-toolbox-dev-1.4.11/kevin_toolbox/computer_science/algorithm/redirector/__init__.py

@@ -0,0 +1 @@
+from .redirectable_sequence_fetcher import Redirectable_Sequence_Fetcher