kevin-toolbox-dev 1.4.7__py3-none-any.whl → 1.4.9__py3-none-any.whl

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/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_))

kevin_toolbox/network/get_response.py

@@ -0,0 +1,50 @@
+import urllib3
+from urllib.parse import quote
+from kevin_toolbox.computer_science.algorithm.decorator import retry
+from kevin_toolbox.network.variable import DEFAULT_HEADERS
+
+# 全局 PoolManager 实例，设置 cert_reqs='CERT_NONE' 可关闭 SSL 证书验证
+http = urllib3.PoolManager(cert_reqs='CERT_NONE')
+
+
+def get_response(url, data=None, headers=None, method=None, retries=3, delay=0.5, b_verbose=False, stream=True,
+                 **kwargs):
+    """
+        获取 url 的响应
+
+        参数：
+            url:                <str> 请求的 URL 地址。
+            data:               <bytes, optional> 请求发送的数据，如果需要传递数据，必须是字节类型。
+            headers:            <dict> 请求头字典。
+                                    默认为 DEFAULT_HEADERS。
+            method:             <str> HTTP 请求方法，如 "GET", "POST" 等。
+            retries:            <int> 重试次数
+                                    默认重试3次
+            delay:              <int/float> 每次重试前等待的秒数。
+                                    默认0.5秒
+            b_verbose:          <boolean> 进行多次重试时是否打印详细日志信息。
+                                    默认为 False。
+
+        返回：
+            响应。 urllib3.response.HTTPResponse object
+    """
+    headers = headers or DEFAULT_HEADERS
+
+    url = quote(url, safe='/:?=&')
+    worker = retry(retries=retries, delay=delay, logger="default" if b_verbose else None)(func=__worker)
+    response = worker(url, data, headers, method, stream)
+    return response
+
+
+def __worker(url, data, headers, method, stream):
+    method = method if method is not None else "GET"
+    response = http.request(method, url, body=data, headers=headers, preload_content=not stream)
+    if response.status >= 400:
+        raise Exception(f"HTTP 请求失败，状态码：{response.status}")
+    return response
+
+
+if __name__ == "__main__":
+    url_ = "https://i.pinimg.com/736x/28/6a/b1/286ab1eb816dc59a1c72374c75645d80.jpg"  # "https://www.google.com/"
+    a = get_response(url=url_, b_verbose=True)
+    print(a)

kevin_toolbox/network/variable.py

@@ -0,0 +1,6 @@
+DEFAULT_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                  "(KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
+    "Upgrade-Insecure-Requests": "1",
+    # "Cookie": ''
+}

kevin_toolbox/patches/for_logging/build_logger.py

@@ -49,7 +49,7 @@ def build_logger(name, handler_ls, level=logging.DEBUG,
             # 输出到控制台
             handler = logging.StreamHandler()
         else:
-            raise ValueError(f'unexpected target {target}')
+            raise ValueError(f'unexpected target {details["target"]}')
         handler.setLevel(details.get("level", level))
         handler.setFormatter(logging.Formatter(details.get("formatter", formatter)))
         # 添加到logger中

kevin_toolbox/patches/for_matplotlib/color/convert_format.py

@@ -6,8 +6,6 @@ def hex_to_rgba(hex_color):
     assert len(hex_color) in (6, 8), \
         f'hex_color should be 6 or 8 characters long (not including #). but got {len(hex_color)}'
     res = list(int(hex_color[i * 2:i * 2 + 2], 16) for i in range(len(hex_color) // 2))
-    if len(res) not in (3, 4):
-        breakpoint()
     if len(res) == 4:
         res[3] /= 255
     return tuple(res)

kevin_toolbox/patches/for_matplotlib/common_charts/__init__.py

@@ -1,6 +1,51 @@
+# 在非 windows 系统下，尝试自动下载中文字体，并尝试自动设置字体
+import sys
+
+if not sys.platform.startswith("win"):
+    import os
+    from kevin_toolbox.env_info.variable_ import env_vars_parser
+
+    font_setting_s = dict(
+        b_auto_download=True,
+        download_url="https://drive.usercontent.google.com/download?id=1wd-a4-AwAXkr7mHmB9BAIcGpAcqMrbqg&export=download&authuser=0",
+        save_path="~/.kvt_data/fonts/SimHei.ttf"
+    )
+    font_setting_s.update()
+    for k, v in list(font_setting_s.items()):
+        font_setting_s[k] = env_vars_parser.parse(
+            text=f"${{KVT_PATCHES:for_matplotlib:common_charts:font_settings:for_non-windows-platform:{k}}}",
+            default=v
+        )
+    save_path = os.path.expanduser(font_setting_s["save_path"])
+
+    if font_setting_s["b_auto_download"] and not os.path.isfile(save_path):
+        from kevin_toolbox.network import download_file
+
+        print(f'检测到当前系统非 Windows 系统，尝试自动下载中文字体...')
+        download_file(
+            output_dir=os.path.dirname(save_path),
+            file_name=os.path.basename(save_path),
+            url=font_setting_s["download_url"],
+            b_display_progress=True
+        )
+
+    if os.path.isfile(save_path):
+        import matplotlib.font_manager as fm
+        import matplotlib.pyplot as plt
+
+        # 注册字体
+        fm.fontManager.addfont(save_path)
+        # 获取字体名称
+        font_name = fm.FontProperties(fname=save_path).get_name()
+
+        # 全局设置默认字体
+        plt.rcParams['font.family'] = font_name
+        plt.rcParams['axes.unicode_minus'] = False  # 解决负号 '-' 显示为方块的问题
+
 from .plot_lines import plot_lines
 from .plot_scatters import plot_scatters
 from .plot_distribution import plot_distribution
 from .plot_bars import plot_bars
 from .plot_scatters_matrix import plot_scatters_matrix
 from .plot_confusion_matrix import plot_confusion_matrix
+from .plot_from_record import plot_from_record

kevin_toolbox/patches/for_matplotlib/common_charts/plot_bars.py

@@ -1,20 +1,62 @@
-import os
-import copy
-from kevin_toolbox.computer_science.algorithm import for_seq
 import matplotlib.pyplot as plt
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.computer_science.algorithm import for_seq
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+__name = ":common_charts:plot_bars"
+
 
-# TODO 在 linux 系统下遇到中文时，尝试自动下载中文字体，并尝试自动设置字体
-# font_path = os.path.join(root_dir, "utils/SimHei.ttf")
-# font_name = FontProperties(fname=font_path)
+@COMMON_CHARTS.register(name=__name)
+def plot_bars(data_s, title, x_name, output_dir=None, output_path=None, **kwargs):
+    """
+        绘制条形图
 
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+            title:              <str> 绘图标题。
+            x_name:             <str> 以哪个 data_name 作为 x 轴。
+                                    其余数据视为需要被绘制的数据点。
+                    例子： data_s={"step":[...], "acc_top1":[...], "acc_top3":[...]}
+                        当 x_name="step" 时，将会以 step 为 x 轴绘制 acc_top1 和 acc_top3 的 bar 图。
+            x_label:            <str> x 轴的标签名称。
+                                    默认与指定的 x_name 相同。
+            y_label:            <str> y 轴的标签名称。
+                                    默认为 "value"。
+            output_dir:         <str or None> 图片输出目录。
+            output_path:        <str or None> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
 
-def plot_bars(data_s, title, x_name, y_label=None, output_dir=None, **kwargs):
-    data_s = copy.deepcopy(data_s)
+        其他可选参数：
+            dpi:                <int> 保存图像的分辨率。
+                                    默认为 200。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+
+        返回值：
+            若 output_dir 非 None，则返回图像保存的文件路径。
+    """
+    assert x_name in data_s and len(data_s) >= 2
     paras = {
-        "dpi": 200
+        "x_label": f'{x_name}',
+        "y_label": "value",
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_bars, _name=__name, _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
 
     plt.clf()
     #
@@ -26,29 +68,28 @@ def plot_bars(data_s, title, x_name, y_label=None, output_dir=None, **kwargs):
         else:
             plt.bar([j + 0.1 for j in range(len(x_all_ls))], y_ls, width=0.2, align='center', label=k)
 
-    plt.xlabel(f'{x_name}')
-    plt.ylabel(f'{y_label if y_label else "value"}')
+    plt.xlabel(paras["x_label"])
+    plt.ylabel(paras["y_label"])
     temp = for_seq.flatten_list([list(i) for i in data_s.values()])
     y_min, y_max = min(temp), max(temp)
     plt.ylim(max(min(y_min, 0), y_min - (y_max - y_min) * 0.2), y_max + (y_max - y_min) * 0.1)
-    plt.xticks(list(range(len(x_all_ls))), labels=x_all_ls)  # , fontproperties=font_name
+    plt.xticks(list(range(len(x_all_ls))), labels=x_all_ls)
     plt.title(f'{title}')
     # 显示图例
     plt.legend()
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+
+    return _output_path
 
 
 if __name__ == '__main__':
+    import os
+
     plot_bars(data_s={
         'a': [1.5, 2, 3, 4, 5],
         'b': [5, 4, 3, 2, 1],
         'c': [1, 2, 3, 4, 5]},
-        title='test', x_name='a', output_dir=os.path.join(os.path.dirname(__file__), "temp"))
+        title='test_plot_bars', x_name='a', output_dir=os.path.join(os.path.dirname(__file__), "temp"),
+        b_generate_record=True
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_confusion_matrix.py

@@ -1,26 +1,74 @@
-import os
 import numpy as np
 from sklearn.metrics import confusion_matrix
 import matplotlib.pyplot as plt
 import seaborn as sns
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_confusion_matrix"
 
-def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None, output_dir=None,
+
+@COMMON_CHARTS.register(name=__name)
+def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None, output_dir=None, output_path=None,
                           replace_zero_division_with=0, **kwargs):
     """
         计算并绘制混淆矩阵
 
         参数：
-            replace_zero_division_with:         <float> 对于在normalize时引发除0错误的矩阵元素，使用何种值进行替代
-                                                    建议使用 np.nan 或者 0
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            gt_name:            <str> 在 data_s 中表示真实标签数据的键名。
+            pd_name:            <str> 在 data_s 中表示预测标签数据的键名。
+            label_to_value_s:   <dict> 标签-取值映射字典。
+                                    如 {"cat": 0, "dog": 1}）。
+            output_dir: <str or None>
+                图像保存的输出目录。如果同时指定了 output_path，则以 output_path 为准。
+                若 output_dir 和 output_path 均未指定，则图像将直接通过 plt.show() 显示而不会保存到文件。
+
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+            replace_zero_division_with:     <float> 在归一化混淆矩阵时，如果遇到除0错误的情况，将使用该值进行替代。
+                                    建议使用 np.nan 或 0，默认值为 0。
+
+        其他可选参数：
+            dpi:                <int> 图像保存的分辨率。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            normalize:          <str or None> 指定归一化方式。
+                                    可选值包括：
+                                        "true"（按真实标签归一化）
+                                        "pred"（按预测标签归一化）
+                                        "all"（整体归一化）
+                                    默认为 None 表示不归一化。
+            b_return_cfm:       <bool> 是否在返回值中包含计算得到的混淆矩阵数据。
+                                    默认为 False。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+
+        返回值：
+            当 b_return_cfm 为 True 时，返回值可能为一个包含 (图像路径, 混淆矩阵数据) 的元组。
     """
     paras = {
         "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False,
         "normalize": None,  # "true", "pred", "all",
         "b_return_cfm": False,  # 是否输出混淆矩阵
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_confusion_matrix, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
 
     value_set = set(data_s[gt_name]).union(set(data_s[pd_name]))
     if label_to_value_s is None:
@@ -57,28 +105,27 @@ def plot_confusion_matrix(data_s, title, gt_name, pd_name, label_to_value_s=None
     plt.ylabel(f'{gt_name}')
     plt.title(f'{title}')
 
-    if output_dir is None:
-        plt.show()
-        output_path = None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
 
     if paras["b_return_cfm"]:
-        return output_path, cfm
+        return _output_path, cfm
     else:
-        return output_path
+        return _output_path
 
 
 if __name__ == '__main__':
+    import os
+
     # 示例真实标签和预测标签
     y_true = np.array([0, 1, 2, 0, 1, 2, 0, 1, 2, 5])
     y_pred = np.array([0, 2, 1, 0, 2, 1, 0, 1, 1, 5])
 
-    plot_confusion_matrix(data_s={'a': y_true, 'b': y_pred},
-                          title='test', gt_name='a', pd_name='b',
-                          label_to_value_s={"A": 5, "B": 0, "C": 1, "D": 2, "E": 3},
-                          # output_dir=os.path.join(os.path.dirname(__file__), "temp"),
-                          replace_zero_division_with=-1,
-                          normalize="all")
+    plot_confusion_matrix(
+        data_s={'a': y_true, 'b': y_pred},
+        title='test_plot_confusion_matrix', gt_name='a', pd_name='b',
+        label_to_value_s={"A": 5, "B": 0, "C": 1, "D": 2, "E": 3},
+        output_dir=os.path.join(os.path.dirname(__file__), "temp"),
+        replace_zero_division_with=-1,
+        normalize="all",
+        b_generate_record=True
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_distribution.py

@@ -1,15 +1,66 @@
-import os
 import math
 import matplotlib.pyplot as plt
 import numpy as np
-from kevin_toolbox.patches.for_os.path import replace_illegal_chars
+from kevin_toolbox.patches.for_matplotlib.common_charts.utils import save_plot, save_record, get_output_path
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
 
+__name = ":common_charts:plot_distribution"
 
-def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist", output_dir=None, **kwargs):
+
+@COMMON_CHARTS.register(name=__name)
+def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist", output_dir=None, output_path=None,
+                      **kwargs):
+    """
+        概率分布图
+            支持以下几种绘图类型：
+                  1. 数字数据，绘制概率分布图： type_ 参数为 "hist" 或 "histogram" 时。
+                  2. 字符串数据，绘制概率直方图：type_ 参数为 "category" 或 "cate" 时。
+
+        参数：
+            data_s:             <dict> 数据。
+                                    形如 {<data_name>: <data list>, ...} 的字典，
+            title:              <str> 绘图标题，同时用于保存图片的文件名。
+            x_name:             <str> 以哪个 data_name 作为待绘制数据。
+            x_name_ls:          <list or tuple> 以多个 data_name 对应的多组数据在同一图中绘制多个概率分布图。
+            type_:              <str> 指定绘图类型。
+                                    支持的取值有：
+                                        - "hist" 或 "histogram"：     需要 <data list> 为数值数据，将绘制概率分布图。
+                                                                        需要进一步指定 steps 步长参数，
+                                                                        或者 min、max、bin_nums 参数。
+                                        - "category" 或 "cate"：      需要 <data list> 为字符串数据，将绘制概率直方图。
+            output_dir:         <str> 图片输出目录。
+            output_path:        <str> 图片输出路径。
+                        以上两个只需指定一个即可，同时指定时以后者为准。
+                        当只有 output_dir 被指定时，将会以 title 作为图片名。
+                        若同时不指定，则直接调用 plt.show() 显示图像，而不进行保存。
+                        在保存为文件时，若文件名中存在路径不适宜的非法字符将会被进行替换。
+
+        其他可选参数：
+            dpi:                <int> 图像保存的分辨率。
+            suffix:             <str> 图片保存后缀。
+                                    目前支持的取值有 ".png", ".jpg", ".bmp"，默认为第一个。
+            b_generate_record:  <boolean> 是否保存函数参数为档案。
+                                    默认为 False，当设置为 True 时将会把函数参数保存成 [output_path].record.tar。
+                                    后续可以使用 plot_from_record() 函数或者 Serializer_for_Registry_Execution 读取该档案，并进行修改和重新绘制。
+                                    该参数仅在 output_dir 和 output_path 非 None 时起效。
+
+        返回值：
+            <str> 图像保存的完整文件路径。如果 output_dir 或 output_path 被指定，
+                 则图像会保存到对应位置并返回保存路径；否则可能直接显示图像，
+                 返回值依赖于 save_plot 函数的具体实现。
+    """
     paras = {
-        "dpi": 200
+        "dpi": 200,
+        "suffix": ".png",
+        "b_generate_record": False
     }
     paras.update(kwargs)
+    #
+    _output_path = get_output_path(output_path=output_path, output_dir=output_dir, title=title, **kwargs)
+    save_record(_func=plot_distribution, _name=__name,
+                _output_path=_output_path if paras["b_generate_record"] else None,
+                **paras)
+    data_s = data_s.copy()
     if x_name is not None:
         x_name_ls = [x_name, ]
     assert isinstance(x_name_ls, (list, tuple)) and len(x_name_ls) > 0
@@ -47,19 +98,17 @@ def plot_distribution(data_s, title, x_name=None, x_name_ls=None, type_="hist",
     # 显示图例
     plt.legend()
 
-    if output_dir is None:
-        plt.show()
-        return None
-    else:
-        os.makedirs(output_dir, exist_ok=True)
-        output_path = os.path.join(output_dir, f'{replace_illegal_chars(title)}.png')
-        plt.savefig(output_path, dpi=paras["dpi"])
-        return output_path
+    save_plot(plt=plt, output_path=_output_path, dpi=paras["dpi"], suffix=paras["suffix"])
+    return _output_path
 
 
 if __name__ == '__main__':
-    plot_distribution(data_s={
-        'a': [1, 2, 3, 4, 5, 3, 2, 1],
-        'c': [1, 2, 3, 4, 5, 0, 0, 0]},
-        title='test', x_name_ls=['a', 'c'], type_="category",
-        output_dir=os.path.join(os.path.dirname(__file__), "temp"))
+    import os
+
+    plot_distribution(
+        data_s={
+            'a': [1, 2, 3, 4, 5, 3, 2, 1],
+            'c': [1, 2, 3, 4, 5, 0, 0, 0]},
+        title='test_plot_distribution', x_name_ls=['a', 'c'], type_="category",
+        output_dir=os.path.join(os.path.dirname(__file__), "temp")
+    )

kevin_toolbox/patches/for_matplotlib/common_charts/plot_from_record.py

@@ -0,0 +1,21 @@
+from kevin_toolbox.patches.for_matplotlib.variable import COMMON_CHARTS
+
+
+def plot_from_record(input_path, **kwargs):
+    """
+        从 record 中恢复并绘制图像
+            支持通过 **kwargs 对其中部分参数进行覆盖
+    """
+    from kevin_toolbox.computer_science.algorithm.registration import Serializer_for_Registry_Execution
+
+    serializer = Serializer_for_Registry_Execution()
+    serializer.load(input_path)
+    serializer.record_s["kwargs"].update(kwargs)
+    return serializer.recover()()
+
+
+if __name__ == '__main__':
+    import os
+
+    plot_from_record(input_path=os.path.join(os.path.dirname(__file__), "temp/好-吧.png.record.tar"),
+                     output_dir=os.path.join(os.path.dirname(__file__), "temp/recover"))