Update docstrings

更新与完善docstrings，使符合 Sphinx 风格；

dev_scripts/clear_cache.py

@@ -1,3 +1,6 @@
+"""各种清理函数，如清理 Python 编译缓存、PyInstaller 打包中间文件与输出文件等
+"""
+
 import os
 from pathlib import Path
 from shutil import rmtree

src/Py2exe-GUI.py

@@ -1,8 +1,7 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
-"""
+"""程序入口脚本
-程序入口脚本
 由于整个程序作为单一 Python 包发布，直接运行 py2exe_gui.__main__.py 会导致相对导入错误
 需要在包外留有这个显式的入口模块来提供“通过运行某个 .py 文件启动程序”功能和 PyInstaller 打包入口脚本
 

src/py2exe_gui/Constants/app_constants.py

@@ -1,6 +1,8 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""应用程序级常量与部分全局变量"""
+
 from .runtime_info import RUNTIME_INFO
 
 APP_URLs = {
@@ -14,9 +16,7 @@ if RUNTIME_INFO.language_code == "zh_CN":
 
 
 class AppConstant:
-    """
+    """应用程序级的常量"""
-    应用程序级的常量
-    """
 
     NAME = "Py2exe-GUI"
     VERSION = "0.2.1"

src/py2exe_gui/Constants/packaging_constants.py

@@ -1,18 +1,14 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
-"""
+"""PyInstaller 打包相关的常量"""
-打包相关的常量
-"""
 
 import enum
 
 
 @enum.unique
 class PyInstOpt(enum.IntFlag):
-    """
+    """PyInstaller 命令行选项枚举类"""
-    PyInstaller 命令行选项枚举类
-    """
 
     script_path = enum.auto()
     icon_path = enum.auto()

src/py2exe_gui/Constants/python_env_constants.py

@@ -1,14 +1,14 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""Python 环境相关常量"""
+
 import enum
 
 
 @enum.unique
 class PyEnvType(enum.IntFlag):
-    """
+    """Python 解释器（环境）类型，如系统解释器、venv 虚拟环境等"""
-    Python 解释器（环境）类型，如系统解释器、venv 虚拟环境等 \n
-    """
 
     system = enum.auto()  # 系统解释器
     venv = enum.auto()  # venv 虚拟环境  https://docs.python.org/3/library/venv.html

src/py2exe_gui/Widgets/add_data_widget.py

@@ -1,6 +1,9 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""此模块主要包含用于提供 PyInstaller `--add-data` 和 `--add-binary` 功能的窗口类 `AddDataWindow`
+"""
+
 import sys
 from pathlib import Path
 from typing import Optional
@@ -21,9 +24,7 @@ from PySide6.QtWidgets import (
 
 
 class AddDataWindow(QWidget):
-    """
+    """用于提供 PyInstaller --add-data 和 --add-binary 功能的窗口"""
-    用于提供 PyInstaller --add-data 和 --add-binary 功能的窗口
-    """
 
     # 类型别名
     data_item = tuple[Path, str]  # 数据条目，第一项为在文件系统中的路径，第二项为捆绑后环境中的路径
@@ -31,11 +32,15 @@ class AddDataWindow(QWidget):
     # 自定义信号
     data_selected = Signal(list)  # 用户在添加数据窗口完成所有编辑后，提交的信号
 
-    def __init__(self, parent: Optional[QWidget] = None):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        """
+        :param parent: 父控件对象
+        """
+
         super().__init__(parent)
 
         # 工作目录，应由主界面提供，默认为入口脚本所在目录；各种文件处理将以此作为相对路径起点
-        self._work_dir: Path = Path(".").resolve()
+        self._work_dir: Path = Path(".").absolute()
 
         # 浏览系统文件/目录的文件对话框
         self.data_browse_dlg = QFileDialog(self)
@@ -59,9 +64,7 @@ class AddDataWindow(QWidget):
         self._connect_slots()
 
     def _setup_ui(self) -> None:
-        """
+        """处理 UI 内容"""
-        处理 UI 内容 \n
-        """
 
         self.setWindowTitle("添加文件")
         self.setMinimumWidth(550)
@@ -88,10 +91,9 @@ class AddDataWindow(QWidget):
         self.ok_btn.setText("确定")
         self.cancel_btn.setText("取消")
 
+    # noinspection DuplicatedCode
     def _setup_layout(self) -> None:
-        """
+        """构建与设置布局管理器"""
-        构建与设置布局管理器 \n
-        """
 
         btn_group_box = QVBoxLayout()
         btn_group_box.addWidget(self.new_btn)
@@ -116,13 +118,12 @@ class AddDataWindow(QWidget):
         self.setLayout(main_layout)
 
     def _connect_slots(self) -> None:
-        """
+        """构建各槽函数、连接信号"""
-        构建各槽函数、连接信号 \n
-        """
 
         @Slot()
-        def handle_new_btn():
+        def handle_new_btn() -> None:
-            # “新建”按钮槽函数
+            """“新建”按钮槽函数"""
+
             row_count = self.item_table.rowCount()
             source_item = QTableWidgetItem("")
             source_item.setFlags(
@@ -136,13 +137,15 @@ class AddDataWindow(QWidget):
             )  # 自动选中新建行的第一列
 
         @Slot()
-        def handle_delete_btn():
+        def handle_delete_btn() -> None:
-            # “删除”按钮槽函数
+            """“删除”按钮槽函数"""
+
             self.item_table.removeRow(self.item_table.currentRow())
 
         @Slot()
-        def handel_browse_btn():
+        def handel_browse_btn() -> None:
-            # “浏览文件”按钮槽函数
+            """“浏览文件”按钮槽函数"""
+
             if (
                 self.item_table.currentRow() == -1
                 or self.item_table.currentColumn() == 1
@@ -153,8 +156,9 @@ class AddDataWindow(QWidget):
             self.data_browse_dlg.open()
 
         @Slot()
-        def handle_browse_dir_btn():
+        def handle_browse_dir_btn() -> None:
-            # “浏览文件夹”按钮槽函数
+            """“浏览文件夹”按钮槽函数"""
+
             if (
                 self.item_table.currentRow() == -1
                 or self.item_table.currentColumn() == 1
@@ -165,9 +169,9 @@ class AddDataWindow(QWidget):
             self.data_dir_browse_dlg.open()
 
         @Slot(str)
-        def handle_browse_selected(file_path: str):
+        def handle_browse_selected(file_path: str) -> None:
-            """
+            """处理文件对话框获取到用户打开文件/目录的槽函数
-            处理文件对话框获取到用户打开文件/目录的槽函数 \n
+
             :param file_path: 用户打开的文件/目录路径
             """
 
@@ -175,7 +179,7 @@ class AddDataWindow(QWidget):
             current_row = self.item_table.currentRow()
 
             # SOURCE 列设置为操作系统绝对路径
-            source_item = QTableWidgetItem(str(path.resolve()))
+            source_item = QTableWidgetItem(str(path.absolute()))
             source_item.setFlags(
                 Qt.ItemFlag.ItemIsEnabled | Qt.ItemFlag.ItemIsSelectable
             )
@@ -192,8 +196,8 @@ class AddDataWindow(QWidget):
                 self.item_table.setItem(current_row, 1, QTableWidgetItem("."))
 
         @Slot()
-        def handle_ok_btn():
+        def handle_ok_btn() -> None:
-            # “确定”按钮槽函数
+            """“确定”按钮槽函数"""
 
             # 删掉所有空白行
             row = 0
@@ -218,8 +222,9 @@ class AddDataWindow(QWidget):
         self.cancel_btn.clicked.connect(self.close)
 
     def _submit(self) -> list[data_item]:
-        """
+        """将当前界面上的所有配置项转换为 data_item 列表，准备提交给主界面和打包流使用
-        将当前界面上的所有配置项转换为 data_item 列表，准备提交给主界面和打包流使用 \n
+
+        :return: `data-item` 列表
         """
 
         all_data_item_list = []
@@ -231,19 +236,24 @@ class AddDataWindow(QWidget):
         return all_data_item_list
 
     def set_work_dir(self, work_dir_path: Path) -> None:
+        """设置工作目录并更新相关文件对话框路径起点
+
+        :param work_dir_path: 新的工作目录路径
+        """
+
         self._work_dir = work_dir_path
         self.data_browse_dlg.setDirectory(str(work_dir_path))
         self.data_dir_browse_dlg.setDirectory(str(work_dir_path))
 
     def load_data_item_list(self, all_data_item_list: list[data_item]) -> None:
-        """
+        """从 `all_data_item_list` 列表加载待添加的数据文件至界面控件
-        从 data_item 列表加载待添加的数据文件至界面控件
+
         :param all_data_item_list: 保存数据条目的列表
         """
 
         self.item_table.setRowCount(len(all_data_item_list))
         for row, data_item in enumerate(all_data_item_list):
-            source_item = QTableWidgetItem(str(data_item[0].resolve()))
+            source_item = QTableWidgetItem(str(data_item[0].absolute()))
             source_item.setFlags(
                 Qt.ItemFlag.ItemIsEnabled | Qt.ItemFlag.ItemIsSelectable
             )

src/py2exe_gui/Widgets/center_widget.py

@@ -1,6 +1,14 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""此模块主要包含主界面中央控件类
+
+CenterWidget 是主要类，定义了各种界面控件及其大部分信号与槽功能
+
+WinMacCenterWidget 继承自 CenterWidget，额外添加了仅 Windows 和 macOS 平台才支持的
+PyInstaller 功能所对应的控件及其槽函数
+"""
+
 from pathlib import Path
 
 from PySide6 import QtCore
@@ -29,9 +37,7 @@ from .pyinstaller_option_widget import load_pyinst_options
 
 
 class CenterWidget(QWidget):
-    """
+    """主界面的中央控件"""
-    主界面的中央控件
-    """
 
     # 自定义信号
     option_selected = QtCore.Signal(tuple)  # 用户通过界面控件选择选项后发射此信号
@@ -39,7 +45,7 @@ class CenterWidget(QWidget):
 
     def __init__(self, parent: QMainWindow) -> None:
         """
-        :param parent: 父控件对象，应为主程序主窗口 \n
+        :param parent: 父控件对象，应为主程序主窗口
         """
 
         super().__init__(parent)
@@ -95,9 +101,7 @@ class CenterWidget(QWidget):
         self._set_layout()
 
     def _setup_ui(self) -> None:
-        """
+        """设置各种控件的属性"""
-        设置各种控件的属性 \n
-        """
 
         self.script_path_label.setText("待打包脚本：")
         self.script_path_le.setReadOnly(True)
@@ -144,14 +148,12 @@ class CenterWidget(QWidget):
             self.clean_checkbox.setToolTip(opt["--clean"])
 
     def _connect_slots(self) -> None:
-        """
+        """定义、连接信号与槽"""
-        定义、连接信号与槽 \n
-        """
 
         @QtCore.Slot(str)
         def script_file_selected(file_path: str) -> None:
-            """
+            """脚本文件完成选择的槽函数
-            脚本文件完成选择的槽函数 \n
+
             :param file_path: 脚本文件路径
             """
 
@@ -159,18 +161,16 @@ class CenterWidget(QWidget):
 
         @QtCore.Slot()
         def project_name_selected() -> None:
-            """
+            """输出程序名称完成输入的槽"""
-            输出程序名称完成输入的槽 \n
-            """
 
             project_name: str = self.project_name_le.text()
             self.option_selected.emit((PyInstOpt.out_name, project_name))
 
         @QtCore.Slot(int)
         def one_fd_selected(btn_id: int) -> None:
-            """
+            """选择输出至单文件/单目录的槽
-            选择输出至单文件/单目录的槽 \n
+
-            :param btn_id: fd_group按钮组中按钮的id
+            :param btn_id: `fd_group` 按钮组中按钮的 id
             """
 
             if btn_id == 0:
@@ -182,18 +182,14 @@ class CenterWidget(QWidget):
 
         @QtCore.Slot()
         def handle_add_data_btn_clicked() -> None:
-            """
+            """用户在界面点击添加数据按钮的槽函数"""
-            用户在界面点击添加数据按钮的槽函数 \n
-            """
 
             self.add_data_dlg.load_data_item_list(self.data_item_list)
             self.add_data_dlg.show()
 
         @QtCore.Slot(list)
         def add_data_selected(data_item_list: list) -> None:
-            """
+            """用户完成了添加数据操作的槽函数"""
-            用户完成了添加数据操作的槽函数 \n
-            """
 
             self.data_item_list = data_item_list
             self.parent_widget.statusBar().showMessage("添加数据文件已更新")
@@ -201,18 +197,14 @@ class CenterWidget(QWidget):
 
         @QtCore.Slot()
         def handle_add_binary_btn_clicked() -> None:
-            """
+            """用户在界面点击添加二进制文件按钮的槽函数"""
-            用户在界面点击添加二进制文件按钮的槽函数 \n
-            """
 
             self.add_binary_dlg.load_data_item_list(self.binary_item_list)
             self.add_binary_dlg.show()
 
         @QtCore.Slot(list)
         def add_binary_selected(binary_item_list: list) -> None:
-            """
+            """用户完成了添加二进制文件操作的槽函数"""
-            用户完成了添加二进制文件操作的槽函数 \n
-            """
 
             self.binary_item_list = binary_item_list
             self.parent_widget.statusBar().showMessage("添加二进制文件已更新")
@@ -220,15 +212,14 @@ class CenterWidget(QWidget):
 
         @QtCore.Slot()
         def handle_hidden_import_btn_clicked() -> None:
-            """
+            """点击隐式导入按钮的槽函数"""
-            点击隐式导入按钮的槽函数 \n
+
-            """
             self.hidden_import_dlg.show()
 
         @QtCore.Slot(list)
         def hidden_import_selected(hidden_import_list: list[str]) -> None:
-            """
+            """用户完成了隐式导入编辑操作的槽函数
-            用户完成了隐式导入编辑操作的槽函数 \n
+
             :param hidden_import_list: 隐式导入项列表
             """
 
@@ -238,8 +229,8 @@ class CenterWidget(QWidget):
 
         @QtCore.Slot(bool)
         def clean_selected(selected: bool) -> None:
-            """
+            """选择了清理缓存复选框的槽
-            选择了清理缓存复选框的槽 \n
+
             :param selected: 是否勾选了 clean 复选框
             """
 
@@ -264,10 +255,9 @@ class CenterWidget(QWidget):
         self.hidden_import_dlg.items_selected.connect(hidden_import_selected)
         self.clean_checkbox.toggled.connect(clean_selected)
 
+    # noinspection DuplicatedCode
     def _set_layout(self) -> None:
-        """
+        """设置布局管理器"""
-        设置布局管理器 \n
-        """
 
         script_layout = QGridLayout()
         script_layout.addWidget(self.script_path_label, 0, 0, 1, 2)
@@ -310,8 +300,8 @@ class CenterWidget(QWidget):
 
     @QtCore.Slot(tuple)
     def handle_option_set(self, option: tuple[PyInstOpt, str]) -> None:
-        """
+        """处理option_set信号的槽，根据已经成功设置的选项调整界面
-        处理option_set信号的槽，根据已经成功设置的选项调整界面 \n
+
         :param option: 选项键值对
         """
 
@@ -321,7 +311,7 @@ class CenterWidget(QWidget):
             script_path = Path(option_value)
             self.script_path_le.setText(script_path.name)
             self.parent_widget.statusBar().showMessage(
-                f"打开脚本路径：{str(script_path.resolve())}"
+                f"打开脚本路径：{str(script_path.absolute())}"
             )
             self.add_data_dlg.set_work_dir(script_path.parent)
             self.add_binary_dlg.set_work_dir(script_path.parent)
@@ -332,8 +322,8 @@ class CenterWidget(QWidget):
 
     @QtCore.Slot(PyInstOpt)
     def handle_option_error(self, option: PyInstOpt) -> None:
-        """
+        """处理option_error信号的槽，重置设置失败的选项对应的界面，并向用户发出警告
-        处理option_error信号的槽，重置设置失败的选项对应的界面，并向用户发出警告 \n
+
         :param option: 选项
         """
 
@@ -445,10 +435,9 @@ class WinMacCenterWidget(CenterWidget):
         self.icon_file_dlg.fileSelected.connect(icon_file_selected)
         self.console_checkbox.toggled.connect(console_selected)
 
+    # noinspection DuplicatedCode
     def _set_layout(self) -> None:
-        """
+        """设置布局管理器"""
-        设置布局管理器 \n
-        """
 
         super()._set_layout()
 
@@ -462,8 +451,8 @@ class WinMacCenterWidget(CenterWidget):
 
     @QtCore.Slot(tuple)
     def handle_option_set(self, option: tuple[PyInstOpt, str]) -> None:
-        """
+        """处理option_set信号的槽，根据已经成功设置的选项调整界面
-        处理option_set信号的槽，根据已经成功设置的选项调整界面 \n
+
         :param option: 选项键值对
         """
 
@@ -473,19 +462,19 @@ class WinMacCenterWidget(CenterWidget):
 
         if option_key == PyInstOpt.script_path:
             script_path = Path(option_value)
-            self.icon_file_dlg.setDirectory(str(script_path.parent.resolve()))
+            self.icon_file_dlg.setDirectory(str(script_path.parent.absolute()))
 
         elif option_key == PyInstOpt.icon_path:
             icon_path = Path(option_value)
             self.icon_path_le.setText(icon_path.name)
             self.parent_widget.statusBar().showMessage(
-                f"打开图标路径：{str(icon_path.resolve())}"
+                f"打开图标路径：{str(icon_path.absolute())}"
             )
 
     @QtCore.Slot(PyInstOpt)
     def handle_option_error(self, option: PyInstOpt) -> None:
-        """
+        """处理option_error信号的槽，重置设置失败的选项对应的界面，并向用户发出警告
-        处理option_error信号的槽，重置设置失败的选项对应的界面，并向用户发出警告 \n
+
         :param option: 选项
         """
 

src/py2exe_gui/Widgets/dialog_widgets.py

@@ -1,6 +1,9 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""此模块集中处理数个对话框(QDialog)控件
+"""
+
 import warnings
 from typing import Optional
 
@@ -21,9 +24,7 @@ from ..Utilities import QtFileOpen
 
 
 class ScriptFileDlg(QFileDialog):
-    """
+    """用于获取入口脚本文件的对话框"""
-    用于获取入口脚本文件的对话框
-    """
 
     def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
@@ -43,9 +44,7 @@ class ScriptFileDlg(QFileDialog):
 
 
 class IconFileDlg(QFileDialog):
-    """
+    """用于获取应用图标文件的对话框"""
-    用于获取应用图标文件的对话框
-    """
 
     def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
@@ -65,9 +64,7 @@ class IconFileDlg(QFileDialog):
 
 
 class AboutDlg(QMessageBox):
-    """
+    """用于显示关于信息的对话框"""
-    用于显示关于信息的对话框
-    """
 
     def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
@@ -85,8 +82,8 @@ class AboutDlg(QMessageBox):
 
     @property
     def about_text(self) -> str:
-        """
+        """返回本程序的关于信息文本
-        返回本程序的关于信息文本 \n
+
         :return: 关于信息
         """
 
@@ -102,9 +99,7 @@ class AboutDlg(QMessageBox):
 
 
 class PkgBrowserDlg(QDialog):
-    """
+    """浏览已安装的所有包的对话框"""
-    浏览已安装的所有包的对话框
-    """
 
     def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
@@ -119,9 +114,7 @@ class PkgBrowserDlg(QDialog):
         self._setup_ui()
 
     def _setup_ui(self) -> None:
-        """
+        """处理 UI"""
-        处理 UI \n
-        """
 
         self.setWindowTitle("已安装的包")
         self.setWindowIcon(QIcon(QPixmap(":/Icons/Python_128px")))
@@ -142,9 +135,10 @@ class PkgBrowserDlg(QDialog):
         self.setLayout(main_layout)
 
     def load_pkg_list(self, pkg_list: list[dict[str, str]]) -> None:
-        """
+        """从后端加载包数据，存储到实例属性 pkg_list 中
-        从后端加载包数据，存储到实例属性 pkg_list 中 \n
+
         self.pkg_list 形如 [("black", "23.12.1"), ...]
+
         :param pkg_list: 已安装的包列表，形如 [{"name": "black", "version": "23.12.1"}, {}, ...]
         """
 
@@ -157,9 +151,7 @@ class PkgBrowserDlg(QDialog):
         self._pkg_table_update()
 
     def _pkg_table_update(self) -> None:
-        """
+        """更新包列表控件显示内容"""
-        更新包列表控件显示内容 \n
-        """
 
         self.pkg_table.setRowCount(len(self.pkg_list))
         for row, pkg in enumerate(self.pkg_list):

src/py2exe_gui/Widgets/multi_item_edit_widget.py

@@ -1,6 +1,13 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""此模块包含一组供用户编辑多个文本条目的控件，用于实现 PyInstaller 的 --hidden-import 等可以多次调用的选项
+
+`MultiItemEditWindow` 是最主要的类，提供一个左侧有条目展示与编辑、右侧有删减条目按钮的窗口
+
+`MultiPkgEditWindow` 继承自 `MultiItemEditWindow`，多了一个浏览当前 Python 环境中已安装 Python 包的功能
+"""
+
 from typing import Optional
 
 from PySide6.QtCore import Qt, Signal, Slot
@@ -18,13 +25,11 @@ from .dialog_widgets import PkgBrowserDlg
 
 
 class MultiItemEditWindow(QWidget):
-    """
+    """用于添加多个条目的窗口控件，实现如 --hidden-import、--collect-submodules 等功能"""
-    用于添加多个条目的窗口控件，实现如 --hidden-import、--collect-submodules 等功能 \n
-    """
 
     items_selected = Signal(list)  # 用户在添加条目窗口完成所有编辑后，提交的信号.完整数据类型为 list[str]
 
-    def __init__(self, parent: Optional[QWidget] = None):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
         :param parent: 父控件对象
         """
@@ -34,6 +39,7 @@ class MultiItemEditWindow(QWidget):
         # 条目列表控件
         self.item_list_widget = QListWidget(self)
 
+        # 可选中且可编辑
         self._QListWidgetItem_flag = (
             Qt.ItemFlag.ItemIsEnabled
             | Qt.ItemFlag.ItemIsSelectable
@@ -52,10 +58,8 @@ class MultiItemEditWindow(QWidget):
         self._setup_layout()
         self._connect_slots()
 
-    def _setup_ui(self):
+    def _setup_ui(self) -> None:
-        """
+        """处理 UI"""
-        处理 UI \n
-        """
 
         self.setWindowIcon(QIcon(QPixmap(":/Icons/Py2exe-GUI_icon_72px")))
 
@@ -66,10 +70,8 @@ class MultiItemEditWindow(QWidget):
         self.cancel_btn.setText("取消")
 
     # noinspection DuplicatedCode
-    def _setup_layout(self):
+    def _setup_layout(self) -> None:
-        """
+        """构建与设置布局管理器"""
-        构建与设置布局管理器 \n
-        """
 
         btn_group_boxlayout = QVBoxLayout()
         self.btn_group_boxlayout = btn_group_boxlayout
@@ -93,23 +95,27 @@ class MultiItemEditWindow(QWidget):
         self.setLayout(main_layout)
 
     def _connect_slots(self) -> None:
-        """
+        """构建各槽函数、连接信号"""
-        构建各槽函数、连接信号 \n
-        """
 
         @Slot()
-        def handle_new_btn():
+        def handle_new_btn() -> None:
+            """新建按钮点击的槽函数"""
+
             new_item = QListWidgetItem("")
             new_item.setFlags(self._QListWidgetItem_flag)
             self.item_list_widget.addItem(new_item)
             self.item_list_widget.editItem(new_item)
 
         @Slot()
-        def handle_delete_btn():
+        def handle_delete_btn() -> None:
+            """删除按钮点击的槽函数"""
+
             self.item_list_widget.takeItem(self.item_list_widget.currentRow())
 
         @Slot()
-        def handle_ok_btn():
+        def handle_ok_btn() -> None:
+            """确定按钮点击的槽函数，将用户编辑好的条目列表以信号方式传出，并自身关闭窗口"""
+
             self.items_selected.emit(self._submit())
             self.close()
 
@@ -120,9 +126,10 @@ class MultiItemEditWindow(QWidget):
         self.ok_btn.clicked.connect(handle_ok_btn)
 
     def _submit(self) -> list[str]:
-        """
+        """将控件界面内容整理为字符串列表，准备提交
-        将控件界面内容整理为字符串列表，准备提交 \n
+
-        会自动删去空白行 \n
+        会自动删去空白行
+
         :return: 条目列表
         """
 
@@ -138,8 +145,8 @@ class MultiItemEditWindow(QWidget):
         return item_list
 
     def load_items(self, items: list[str]) -> None:
-        """
+        """从给定的条目列表加载界面控件，用于打开先前已保存过的条目
-        从给定的条目列表加载界面控件，用于打开先前已保存过的条目
+
         :param items: 条目列表
         """
 
@@ -152,13 +159,13 @@ class MultiItemEditWindow(QWidget):
 
 
 class MultiPkgEditWindow(MultiItemEditWindow):
-    """
+    """用于添加多个Python模块条目的窗口控件，实现如 --hidden-import 等选项
-    用于添加多个Python模块条目的窗口控件，实现如 --hidden-import 等选项 \n
+
     相比MultiItemEditWindow，主要是多了一个浏览当前 Python 环境中所有已安装第三方包
-    并将包名作为条目添加的功能 \n
+    并将包名作为条目添加的功能
     """
 
-    def __init__(self, parent: Optional[QWidget] = None):
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
         """
         :param parent: 父控件对象
         """
@@ -167,23 +174,20 @@ class MultiPkgEditWindow(MultiItemEditWindow):
         self.pkg_browser_dlg = PkgBrowserDlg()
         super().__init__(parent)
 
-    def _setup_ui(self):
+    def _setup_ui(self) -> None:
-        """
+        """处理 UI"""
-        处理 UI \n
-        """
 
         super()._setup_ui()
         self.browse_pkg_button.setText("浏览包(&B)")
 
-    def _setup_layout(self):
+    def _setup_layout(self) -> None:
+        """构建与设置布局管理器"""
+
         super()._setup_layout()
         self.btn_group_boxlayout.insertWidget(2, self.browse_pkg_button)
 
     def _connect_slots(self) -> None:
-        """
+        """构建各槽函数、连接信号"""
-        构建各槽函数、连接信号 \n
-        """
 
         super()._connect_slots()
-
         self.browse_pkg_button.clicked.connect(self.pkg_browser_dlg.exec)

src/py2exe_gui/Widgets/pyinstaller_option_widget.py

@@ -1,6 +1,12 @@
 # Licensed under the GPLv3 License: https://www.gnu.org/licenses/gpl-3.0.html
 # For details: https://github.com/muziing/Py2exe-GUI/blob/main/README.md#license
 
+"""本模块主要用于加载、解析、界面显示 PyInstaller 选项的详细描述
+
+`load_pyinst_options()` 函数用于从数据文件中读取并解析 PyInstaller 命令选项信息，按运行时平台筛选后返回；
+`PyinstallerOptionTable` 类是用于显示 PyInstaller 命令行选项的表格控件
+"""
+
 import warnings
 
 import yaml
@@ -12,8 +18,8 @@ from ..Utilities import QtFileOpen
 
 
 def load_pyinst_options() -> dict[str, str]:
-    """
+    """从数据文件中读取并解析 PyInstaller 命令选项信息，按运行时平台筛选后返回
-    从数据文件中读取并解析 PyInstaller 命令选项信息，按运行时平台筛选后返回 \n
+
     :return: 选项信息字典，{option: description}
     """
 
@@ -40,9 +46,7 @@ def load_pyinst_options() -> dict[str, str]:
 
 
 class PyinstallerOptionTable(QTableWidget):
-    """
+    """用于显示 PyInstaller 命令行选项的表格控件"""
-    用于显示 PyInstaller 命令行选项的表格控件
-    """
 
     def __init__(self) -> None:
         super().__init__()
@@ -60,9 +64,7 @@ class PyinstallerOptionTable(QTableWidget):
         self.horizontalHeader().setSectionResizeMode(1, QHeaderView.ResizeMode.Stretch)
 
     def _set_items(self) -> None:
-        """
+        """为表格控件中填充条目"""
-        为表格控件中填充条目 \n
-        """
 
         for index, (option, description) in enumerate(self.option_dict.items()):
             self.setItem(index, 0, QTableWidgetItem(option))