kevin-toolbox-dev 1.4.7__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.7 → kevin-toolbox-dev-1.4.8}/kevin_toolbox/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.4.7"
+__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 1755525740 --verbose 0'
+    f'--expiration_timestamp 1756803931 --verbose 0'
 )

{kevin-toolbox-dev-1.4.7/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/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

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

@@ -0,0 +1,82 @@
+from kevin_toolbox.nested_dict_list import serializer
+from kevin_toolbox.computer_science.data_structure import Executor
+from kevin_toolbox.computer_science.algorithm.registration import Registry
+
+
+class Serializer_for_Registry_Execution:
+    """
+        用于对基于 Registry 中成员构建的执行过程进行序列化和反序列化操作
+            比如对于一个含有callable成员的 Registry，我们可以使用该 recorder 将其执行过程序列化保存下来，并在需要时恢复并执行
+
+        工作流程：
+                                recover() ---> executor ---> run to get result
+                                   ^
+                                   |
+            record(...) ---> self.record_s ---> save()
+                                   ^              |
+                                   |              v
+                                load() <---  record_file
+    """
+
+    def __init__(self):
+        self.record_s = None
+
+    def record(self, _name=None, _registry=None, *args, **kwargs):
+        """
+            将参数保存到 record_s 中
+        """
+        return self.record_name(_name, _registry).record_paras(*args, **kwargs)
+
+    def record_name(self, _name, _registry):
+        assert isinstance(_registry, (Registry,))
+        assert callable(_registry.get(name=_name, default=None))
+        self.record_s = self.record_s or dict()
+        self.record_s["name"] = _name
+        self.record_s["registry_uid"] = _registry.uid
+        return self
+
+    def record_paras(self, *args, **kwargs):
+        self.record_s = self.record_s or dict()
+        self.record_s["args"] = args
+        self.record_s["kwargs"] = kwargs
+        return self
+
+    def save(self, output_dir=None, b_pack_into_tar=False, b_allow_overwrite=False, **kwargs):
+        """
+            将 record_s 使用 ndl 持久化到文件中
+
+            参数：
+                output_dir:
+                b_pack_into_tar:
+                b_allow_overwrite:
+            其余未列出参数请参考 ndl.serializer.write 中的介绍，常用的有：
+                b_allow_overwrite
+                settings
+            等。
+        """
+        assert self.record_s is not None
+        file_path = serializer.write(var=self.record_s, output_dir=output_dir, b_pack_into_tar=b_pack_into_tar,
+                                     b_allow_overwrite=b_allow_overwrite, **kwargs)
+        return file_path
+
+    def load(self, input_path):
+        """
+            从文件中加载内容到 record_s
+        """
+        self.record_s = serializer.read(input_path=input_path)
+        return self
+
+    def recover(self, record_s=None):
+        """
+            根据 record_s 中的信息，结合 registry 构建一个执行器并返回
+        """
+        record_s = record_s or self.record_s
+        assert record_s is not None
+
+        func = Registry(uid=record_s["registry_uid"]).get(name=record_s["name"], default=None)
+        assert callable(func)
+        executor = Executor(func=func, args=record_s["args"], kwargs=record_s["kwargs"])
+        return executor
+
+
+execution_serializer = Serializer_for_Registry_Execution()

{kevin-toolbox-dev-1.4.7 → kevin-toolbox-dev-1.4.8}/kevin_toolbox/data_flow/core/cache/cache_manager_for_iterator.py

@@ -1,7 +1,7 @@
 import os
 import time
 import importlib.util
-from kevin_toolbox.developing.decorator import restore_original_work_path
+from kevin_toolbox.computer_science.algorithm.decorator import restore_original_work_path
 from kevin_toolbox.computer_science.algorithm.cache_manager import Cache_Manager
 
 if importlib.util.find_spec("cPickle") is not None:

{kevin-toolbox-dev-1.4.7 → kevin-toolbox-dev-1.4.8}/kevin_toolbox/env_info/variable_/env_vars_parser.py

@@ -26,10 +26,24 @@ class Env_Vars_Parser:
     def __call__(self, *args, **kwargs):
         return self.parse(*args, **kwargs)
 
-    def parse(self, text):
+    def parse(self, text, **kwargs):
         """
             解释并替换
+
+            参数：
+                default:        默认之。
+                                    当有设定时，若无法解释则返回该值。
+                                    否则，若无法解释将报错。
         """
+        if "default" in kwargs:
+            try:
+                return self.__parse(text=text)
+            except:
+                return kwargs["default"]
+        else:
+            return self.__parse(text=text)
+
+    def __parse(self, text):
         temp_ls = []
         for it in self.split_string(text=text):
             if isinstance(it, str):
@@ -85,4 +99,5 @@ class Env_Vars_Parser:
 
 if __name__ == '__main__':
     env_vars_parser = Env_Vars_Parser()
-    print(env_vars_parser.split_string("666/123${:VAR}/afasf/${/xxx.../xxx.json:111:222}336"))
+    # print(env_vars_parser.split_string("666/123${:VAR}/afasf/${/xxx.../xxx.json:111:222}336"))
+    print(env_vars_parser.parse("${KVT_PATCHES:for_matplotlib:common_charts:font_settings:for_non-windows-platform}"))

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

@@ -0,0 +1,20 @@
+import os
+from kevin_toolbox.computer_science.algorithm.registration import Registry
+
+SERIALIZER_BACKEND = Registry(uid="SERIALIZER_BACKEND")
+
+# 导入时的默认过滤规则
+ignore_s = [
+    {
+        "func": lambda _, __, path: os.path.basename(path) in ["temp", "test", "__pycache__",
+                                                               "_old_version"],
+        "scope": ["root", "dirs"]
+    },
+]
+
+# 从 kevin_toolbox/nested_dict_list/serializer/backends 下收集被注册的 backend
+SERIALIZER_BACKEND.collect_from_paths(
+    path_ls=[os.path.join(os.path.dirname(__file__), "backends"), ],
+    ignore_s=ignore_s,
+    b_execute_now=False
+)

{kevin-toolbox-dev-1.4.7 → kevin-toolbox-dev-1.4.8}/kevin_toolbox/nested_dict_list/serializer/write.py

@@ -250,6 +250,8 @@ def write(var, output_dir, settings=None, traversal_mode=Traversal_Mode.BFS, b_p
     if not os.path.exists(tgt_path):
         for_os.copy(src=src_path, dst=tgt_path, remove_dst_if_exists=True)
 
+    return tgt_path
+
 
 def _judge_processed_or_not(processed_s, name):
     """

kevin-toolbox-dev-1.4.8/kevin_toolbox/network/__init__.py

@@ -0,0 +1,10 @@
+import urllib3
+from urllib3.exceptions import InsecureRequestWarning
+
+# 禁用不安全请求警告（例如当 verify=False 时）
+urllib3.disable_warnings(InsecureRequestWarning)
+
+from .get_response import get_response
+from .fetch_metadata import fetch_metadata
+from .fetch_content import fetch_content
+from .download_file import download_file

kevin-toolbox-dev-1.4.8/kevin_toolbox/network/download_file.py

@@ -0,0 +1,120 @@
+import os
+import time
+from tqdm import tqdm
+from kevin_toolbox.network import fetch_metadata, fetch_content, get_response
+from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches import for_os
+from kevin_toolbox.nested_dict_list import get_hash
+
+default_option_func_s = {
+    "hash_name": lambda url, _, option_s: {"hash_name": get_hash(option_s["name"], length=12)},
+    "hash_url": lambda url, _, option_s: {"hash_url": get_hash(url, length=12)},
+    "timestamp": lambda *arg, **kwargs: {"timestamp": f'{time.time()}'},
+    "legalized_name": lambda url, _, option_s: {
+        "legalized_name": replace_illegal_chars(file_name=option_s["name"], b_is_path=False)}
+}
+
+
+def download_file(
+        output_dir, url=None, response=None, chunk_size=1024 * 10,
+        file_name=None, file_name_format="{legalized_name:.100}{suffix}", format_option_generate_func_ls=None,
+        b_allow_overwrite=False, b_display_progress=False, **kwargs
+):
+    """
+        下载文件
+            支持以下高级功能：
+                1. 自动识别文件类型并命名。
+                2. 多次重试。
+                3. TODO:断点续传（待实现）。
+
+        参数：
+            output_dir:             <path> 文件保存的目录
+            url:                    <str> 下载的 URL 地址。
+            response:               响应。
+                        以上两个参数只需要指定其一即可，建议使用后者。
+            chunk_size:             <int> 采用分块下载时，块的大小
+                                        默认为 1024 * 10
+            file_name:              <str> 文件名
+                                        默认为 None，此时将根据 file_name_format 自动生成名字。
+            file_name_format:       <str> 保存的文件的命名方式。
+                                        基本结构为：  '{<part_0>}...{<part_1>}...'
+                                        其中 {} 内将根据 part 指定的选项进行自动填充。目前支持以下几种选项：
+                                            - "name"            文件名（不含后缀）。
+                                            - "suffix"          后缀。
+                                            - "timestamp"       下载的时间戳。
+                                            - "hash_name"       文件名的hash值。
+                                            - "legalized_name"  经过合法化处理的文件名（对其中特殊符号进行了替换）。
+                                            - "hash_url"        url的hash值。
+                                        ！！注意：
+                                            "name" 该选项由于其可能含有 : 和 / 等特殊符号，当以其作为文件名时，可能会引发错误。
+                                                因此对于 windows 用户，请慎重使用该选项，对于 mac 和 linux 用户，同样也不建议使用该选项。
+                                                相较而言，"legalized_name" 是一个更好的选择。
+                                            "hash_name" 和 "hash_url" 有极低但非0的可能会发生 hash 碰撞。
+                                        综合而言：
+                                            建议使用 "legalized_name" 和 "suffix" 以及 "timestamp" 的组合。
+                                        高级设置：
+                                            1. 如果想限制文件名中某部分的长度（避免文件名过长在某些系统下引发报错），应该如何做？
+                                                本命名方式兼容 str.format() 语法，比如你可以通过 {name:.10} 来限制名字的长度不大于10个字符。
+                                            2. 如果已有的选项无法满足你的需求，如何新增选项？
+                                                本函数支持通过设置 format_option_generate_func_ls 来补充或者覆盖默认选项。
+                                        默认值为：
+                                            '{legalized_name:.100}{suffix}'
+            format_option_generate_func_ls: <list of callable> 函数列表，将使用这些函数的结果来对 file_name_format 中的选项进行补充或者覆盖。
+                                        函数需要接受 url, response, option_s（已有的选项键值对） 三个参数，并返回一个包含选项名和选项值的 dict。
+                                        默认为 None
+            b_allow_overwrite:          <boolean> 是否允许覆盖已有文件。
+            b_display_progress:         <boolean> 显示进度条。
+
+
+        返回：
+          文件完整路径（下载成功）或空字符串（失败）
+    """
+    global default_option_func_s
+    assert url is not None or response is not None
+    if url is not None:
+        response = response or get_response(url=url, **kwargs)
+    assert response is not None
+    output_dir = os.path.expanduser(output_dir)
+    #
+    metadata_s = fetch_metadata(url=url, response=response, default_name="", default_suffix="")
+    if file_name is None:
+        option_s = metadata_s.copy()
+        for k, func in default_option_func_s.items():
+            if k in file_name_format:
+                option_s.update(func(url, response, option_s))
+        if isinstance(format_option_generate_func_ls, (list, tuple,)):
+            for func in format_option_generate_func_ls:
+                assert callable(func)
+                option_s.update(func(url, response, option_s))
+        file_name = file_name_format.format(**option_s)
+    #
+    os.makedirs(output_dir, exist_ok=True)
+    #
+    file_path = os.path.join(output_dir, file_name)
+    if os.path.exists(file_path):
+        if b_allow_overwrite:
+            for_os.remove(path=file_path, ignore_errors=True)
+        else:
+            raise FileExistsError(f"target {file_path} already exists")
+
+    if metadata_s["content_length"] and b_display_progress:
+        pbar = tqdm(total=metadata_s["content_length"], unit="B", unit_scale=True, desc="下载进度")
+    else:
+        pbar = None
+
+    with open(file_path, "wb") as f:
+        for chunk in fetch_content(response=response, chunk_size=chunk_size):
+            if chunk:
+                f.write(chunk)
+                if pbar is not None:
+                    pbar.update(len(chunk))
+
+    return file_path
+
+
+# 示例用法
+if __name__ == "__main__":
+    url_ = "https://i.pinimg.com/736x/28/6a/b1/286ab1eb816dc59a1c72374c75645d80.jpg"
+    output_dir = r'./temp/123'
+    downloaded_file = download_file(url=url_, output_dir=output_dir, file_name="233.jpg", b_allow_overwrite=True,
+                                    b_display_progress=True, chunk_size=100)

kevin-toolbox-dev-1.4.8/kevin_toolbox/network/fetch_content.py

@@ -0,0 +1,55 @@
+import warnings
+from kevin_toolbox.network import get_response
+
+
+def fetch_content(url=None, response=None, decoding=None, chunk_size=None, **kwargs):
+    """
+        从 URL/response 中获取内容
+
+        参数：
+            url:                <str> 请求的 URL 地址。
+            response:           响应。
+                        以上两个参数只需要指定其一即可，建议使用后者。
+            decoding:           <str> 响应内容的解码方式
+                                    默认为 None，返回原始的字节流。
+                                    一些常用的可选值：
+                                        "utf-8"
+            chunk_size:         <int> 采用分块方式读取内容时，块的大小
+                                    默认为 None，此时不使用分块读取，而直接读取所有内容
+                        注意！当 chunk_size 非 None 时，decoding 将失效
+
+        返回：
+            当 chunk_size 为 None 时：
+                str: 请求成功后的响应内容。如果 decoding 为 None，则返回 bytes 类型数据。
+            当 chunk_size 非 None 时：
+                读取内容的生成器。
+    """
+    assert url is not None or response is not None
+    if url is not None:
+        response = response or get_response(url=url, **kwargs)
+    assert response is not None
+
+    if chunk_size is None:
+        content = response.data
+        if decoding:
+            content = content.decode(decoding)
+        return content
+    else:
+        if decoding:
+            warnings.warn(f'当 chunk_size 非 None 时，decoding 参数将失效。')
+        return __generator(response, chunk_size)
+
+
+def __generator(response, chunk_size):
+    while True:
+        chunk = response.read(chunk_size)
+        if not chunk:
+            break
+        yield chunk
+
+
+if __name__ == "__main__":
+    url_ = "https://i.pinimg.com/736x/28/6a/b1/286ab1eb816dc59a1c72374c75645d80.jpg"  # "https://www.google.com/"
+    print(len(fetch_content(url=url_, decoding=None)))
+    for i, j in enumerate(fetch_content(url=url_, chunk_size=50000)):
+        print(i, len(j))

kevin-toolbox-dev-1.4.8/kevin_toolbox/network/fetch_metadata.py

@@ -0,0 +1,64 @@
+import os
+import re
+import time
+import mimetypes
+from urllib.parse import quote
+from urllib.parse import urlsplit, unquote
+from kevin_toolbox.network import get_response
+
+
+def fetch_metadata(url=None, response=None, default_suffix=".bin", default_name=None, **kwargs):
+    """
+        从 URL/response 中获取文件名、后缀（扩展名）、大小等元信息
+
+        参数：
+            url:                <str> 请求的 URL 地址。
+            response:           响应。
+                        以上两个参数建议同时指定。
+            default_suffix:     <str> 默认后缀。
+            default_name:       <str> 默认文件名。
+                                    默认为 None，表示使用当前时间戳作为默认文件名。
+                    只有从 URL/response 中无法获取出 suffix 和 name 时才会使用上面的默认值作为填充
+
+        返回：
+            dict with keys ['content_length', 'content_type', 'content_disp', 'suffix', 'name']
+    """
+    assert url is not None or response is not None
+    if url is not None:
+        response = response or get_response(url=url, **kwargs)
+    assert response is not None
+    default_name = f'{time.time()}' if default_name is None else default_name
+
+    metadata_s = {"content_length": None, "content_type": None, "content_disp": None, "suffix": None, "name": None}
+    name, suffix = None, None
+    # 尝试直接从url中获取文件名和后缀
+    if url is not None:
+        url = quote(url, safe='/:?=&')
+        basename = unquote(os.path.basename(urlsplit(url).path))
+        name, suffix = os.path.splitext(basename)
+    # 尝试从更加可信的响应头中获取文件名和后缀
+    content_length = response.headers.get("Content-Length", None)
+    metadata_s["content_length"] = int(content_length) if content_length and content_length.isdigit() else None
+    #
+    content_type = response.headers.get("Content-Type", None)
+    metadata_s["content_type"] = content_type
+    if content_type:
+        suffix = mimetypes.guess_extension(content_type.split(";")[0].strip()) or suffix
+    #
+    content_disp = response.headers.get("Content-Disposition", None)
+    metadata_s["content_disp"] = content_disp
+    if content_disp:
+        temp_ls = re.findall('filename="([^"]+)"', content_disp)
+        if temp_ls:
+            name, temp = os.path.splitext(temp_ls[0])
+            suffix = temp or suffix
+    metadata_s["name"] = name or default_name
+    metadata_s["suffix"] = suffix or default_suffix
+
+    return metadata_s
+
+
+# 示例用法
+if __name__ == "__main__":
+    url_ = "https://i.pinimg.com/736x/28/6a/b1/286ab1eb816dc59a1c72374c75645d80.jpg"  # "https://www.google.com/"
+    print(fetch_metadata(url=url_))