je-editor 0.0.222__py3-none-any.whl → 0.0.224__py3-none-any.whl

je_editor/pyside_ui/main_ui/editor/editor_widget.py

@@ -32,11 +32,24 @@ from je_editor.utils.file.open.open_file import read_file
 
 
 class EditorWidget(QWidget):
+    """
+    EditorWidget 是主要的程式碼編輯器元件，包含：
+    - 專案檔案樹狀檢視
+    - 程式碼編輯區
+    - 執行結果、格式檢查、除錯輸出
+    - 自動儲存與檔案管理
+
+    EditorWidget is the main code editor widget, including:
+    - Project file tree view
+    - Code editing area
+    - Execution result, format check, debugger output
+    - Auto-save and file management
+    """
 
     def __init__(self, main_window: EditorMain):
         jeditor_logger.info(f"Init EditorWidget main_window: {main_window}")
         super().__init__()
-        # Init variable
+        # ---------------- Init variables 初始化變數 ----------------
         self.checker: Union[PEP8FormatChecker, None] = None
         self.current_file = None
         self.tree_view_scroll_area = None
@@ -45,41 +58,51 @@ class EditorWidget(QWidget):
         self.python_compiler = None
         self.main_window = main_window
         self.tab_manager = self.main_window.tab_widget
-        # Attr
-        # Current execute instance if none not running
+
+        # 執行相關物件 / Execution related objects
         self.exec_program: Union[None, ExecManager] = None
         self.exec_shell: Union[None, ShellManager] = None
         self.exec_python_debugger: Union[None, ExecManager] = None
-        # Autosave
+
+        # 自動儲存執行緒 / Auto-save thread
         self.code_save_thread: Union[CodeEditSaveThread, None] = None
-        # UI
+
+        # ---------------- UI 初始化 ----------------
         self.grid_layout = QGridLayout(self)
         self.setWindowTitle(language_wrapper.language_word_dict.get("application_name"))
-        # Treeview
+
+        # 建立專案檔案樹狀檢視 / Setup project tree view
         self.set_project_treeview()
-        # Use to put full ui
+
+        # 主分割器 (左：檔案樹，右：編輯器) / Main splitter (left: tree, right: editor)
         self.full_splitter = QSplitter()
         self.full_splitter.setOrientation(Qt.Orientation.Horizontal)
-        # Code edit and result QSplitter
+
+        # 編輯器分割器 (上：編輯器，下：輸出) / Editor splitter (top: editor, bottom: output)
         self.edit_splitter = QSplitter(self.full_splitter)
         self.edit_splitter.setOrientation(Qt.Orientation.Vertical)
-        # code edit and code result plaintext
+
+        # 程式碼編輯器與輸出區 / Code editor and result area
         self.code_edit = CodeEditor(self)
         self.code_result = CodeRecord()
         self.code_result_cursor = self.code_result.textCursor()
+
+        # 捲動區包裝編輯器與輸出 / Scroll areas for editor and result
         self.code_edit_scroll_area = QScrollArea()
         self.code_edit_scroll_area.setWidgetResizable(True)
         self.code_edit_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.code_edit_scroll_area.setWidget(self.code_edit)
+
         self.code_result_scroll_area = QScrollArea()
         self.code_result_scroll_area.setWidgetResizable(True)
         self.code_result_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.code_result_scroll_area.setWidget(self.code_result)
-        # Code format checker
+
+        # 格式檢查與除錯輸出 / Format check and debugger output
         self.format_check_result = CodeRecord()
-        # Debugger
         self.debugger_result = CodeRecord()
-        # Code result tab
+
+        # 輸出分頁 (執行結果 / 格式檢查 / 除錯) / Output tabs
         self.code_difference_result = QTabWidget()
         self.code_difference_result.addTab(
             self.code_result_scroll_area, language_wrapper.language_word_dict.get("editor_code_result"))
@@ -87,18 +110,21 @@ class EditorWidget(QWidget):
             self.format_check_result, language_wrapper.language_word_dict.get("editor_format_check"))
         self.code_difference_result.addTab(
             self.debugger_result, language_wrapper.language_word_dict.get("editor_debugger_input_title_label"))
-        # Edit splitter
+
+        # 加入分割器 / Add widgets to splitters
         self.edit_splitter.addWidget(self.code_edit_scroll_area)
         self.edit_splitter.addWidget(self.code_difference_result)
         self.edit_splitter.setStretchFactor(0, 3)
         self.edit_splitter.setStretchFactor(1, 1)
         self.edit_splitter.setSizes([300, 100])
+
         self.full_splitter.addWidget(self.project_treeview)
         self.full_splitter.addWidget(self.edit_splitter)
         self.full_splitter.setStretchFactor(0, 1)
         self.full_splitter.setStretchFactor(1, 3)
         self.full_splitter.setSizes([100, 300])
-        # Font
+
+        # 設定字體樣式 / Set font style
         self.code_edit.setStyleSheet(
             f"font-size: {user_setting_dict.get('font_size', 12)}pt;"
             f"font-family: {user_setting_dict.get('font', 'Lato')};"
@@ -107,15 +133,23 @@ class EditorWidget(QWidget):
             f"font-size: {user_setting_dict.get('font_size', 12)}pt;"
             f"font-family: {user_setting_dict.get('font', 'Lato')};"
         )
-        # Add to layout
+
+        # 加入主版面配置 / Add to main layout
         self.grid_layout.addWidget(self.full_splitter)
 
+    # ---------------- Project Treeview ----------------
     def set_project_treeview(self) -> None:
+        """
+        建立並設定專案檔案樹狀檢視
+        Setup and configure project file tree view
+        """
         jeditor_logger.info("EditorWidget set_project_treeview")
         self.project_treeview_model = QFileSystemModel()
         self.project_treeview_model.setRootPath(QDir.currentPath())
         self.project_treeview = QTreeView()
         self.project_treeview.setModel(self.project_treeview_model)
+
+        # 設定根目錄 (工作目錄或當前路徑) / Set root directory (working dir or current path)
         if self.main_window.working_dir is None:
             self.project_treeview.setRootIndex(
                 self.project_treeview_model.index(str(Path.cwd()))
@@ -124,53 +158,87 @@ class EditorWidget(QWidget):
             self.project_treeview.setRootIndex(
                 self.project_treeview_model.index(self.main_window.working_dir)
             )
+
+        # 包裝成可捲動區域 / Wrap in scroll area
         self.tree_view_scroll_area = QScrollArea()
         self.tree_view_scroll_area.setWidgetResizable(True)
         self.tree_view_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.tree_view_scroll_area.setWidget(self.project_treeview)
         self.grid_layout.addWidget(self.tree_view_scroll_area, 0, 0, 0, 1)
+
+        # 點擊檔案時觸發 / Connect click event
         self.project_treeview.clicked.connect(self.treeview_click)
 
     def check_is_open(self, path: Path):
+        """
+        檢查檔案是否已經開啟，如果已開啟則切換到該分頁。
+        Check if the file is already open, if yes then switch to that tab.
+        """
         jeditor_logger.info(f"EditorWidget check_is_open path: {path}")
         if file_is_open_manager_dict.get(str(path), None) is not None:
+            # 嘗試在分頁中找到對應的 EditorWidget
+            # Try to find the corresponding EditorWidget in tab manager
             widget: QWidget = self.tab_manager.findChild(EditorWidget, str(path))
             if widget is None:
+                # 如果找不到，代表之前的紀錄失效，移除紀錄
+                # If not found, remove stale record
                 file_is_open_manager_dict.pop(str(path), None)
             else:
+                # 如果找到，直接切換到該分頁
+                # If found, switch to that tab
                 self.tab_manager.setCurrentWidget(widget)
                 return False
         else:
+            # 如果檔案未開啟，加入紀錄
+            # If file not open, add to open manager dict
             file_is_open_manager_dict.update({str(path): str(path)})
             return True
 
     def open_an_file(self, path: Path) -> bool:
         """
-        :param path: open file path
-        :return: return False if file tab exists
+        開啟檔案並載入到編輯器。
+        Open a file and load it into the editor.
+
+        :param path: 檔案路徑 / File path
+        :return: 如果檔案已經開啟則回傳 False / Return False if file tab already exists
         """
         jeditor_logger.info(f"EditorWidget open_an_file path: {path}")
         if not self.check_is_open(path):
             return False
+
+        # 如果有自動儲存執行緒，暫時跳過這一輪
+        # If auto-save thread exists, skip this round
         if self.code_save_thread:
             self.code_save_thread.skip_this_round = True
+
+        # 讀取檔案內容 / Read file content
         file, file_content = read_file(str(path))
-        self.code_edit.setPlainText(
-            file_content
-        )
+        self.code_edit.setPlainText(file_content)
+
+        # 更新目前檔案資訊 / Update current file info
         self.current_file = file
         self.code_edit.current_file = file
         self.code_edit.reset_highlighter()
+
+        # 更新使用者設定中的最後開啟檔案 / Update last opened file in user settings
         user_setting_dict.update({"last_file": str(self.current_file)})
+
+        # 啟動或更新自動儲存執行緒 / Start or update auto-save thread
         if self.current_file is not None and self.code_save_thread is None:
             init_new_auto_save_thread(self.current_file, self)
         else:
             self.code_save_thread.file = self.current_file
             self.code_save_thread.skip_this_round = False
+
+        # 更新分頁標籤名稱 / Update tab title
         self.rename_self_tab()
         return True
 
     def treeview_click(self) -> None:
+        """
+        當使用者點擊檔案樹中的項目時觸發。
+        Triggered when user clicks an item in the project tree view.
+        """
         jeditor_logger.info("EditorWidget treeview_click")
         clicked_item: QFileSystemModel = self.project_treeview.selectedIndexes()[0]
         file_info: QFileInfo = self.project_treeview.model().fileInfo(clicked_item)
@@ -179,6 +247,10 @@ class EditorWidget(QWidget):
             self.open_an_file(path)
 
     def rename_self_tab(self):
+        """
+        將目前分頁的標籤名稱改為目前檔案名稱。
+        Rename the current tab to the current file name.
+        """
         jeditor_logger.info("EditorWidget rename_self_tab")
         if self.tab_manager.currentWidget() is self:
             self.tab_manager.setTabText(
@@ -186,13 +258,20 @@ class EditorWidget(QWidget):
             self.setObjectName(str(Path(self.current_file)))
 
     def check_file_format(self):
+        """
+        檢查目前檔案的程式碼格式 (僅支援 Python)。
+        Check the code format of the current file (only supports Python).
+        """
         if self.current_file:
             jeditor_logger.info("EditorWidget check_file_format")
             suffix_checker = Path(self.current_file).suffix
             if suffix_checker == ".py":
+                # 使用 PEP8 格式檢查器 / Use PEP8 format checker
                 self.checker = PEP8FormatChecker(self.current_file)
                 self.checker.check_all_format()
                 self.format_check_result.setPlainText("")
+
+                # 顯示錯誤訊息並套用顏色 / Display errors with color formatting
                 for error in self.checker.error_list:
                     text_cursor = self.format_check_result.textCursor()
                     text_format = QTextCharFormat()
@@ -201,12 +280,17 @@ class EditorWidget(QWidget):
                     text_cursor.insertBlock()
                 self.checker.error_list.clear()
             else:
+                # 非 Python 檔案，顯示提示訊息 / Show message if not Python file
                 message_box = QMessageBox()
                 message_box.setText(
                     language_wrapper.language_word_dict.get("python_format_checker_only_support_python_message"))
                 message_box.exec_()
 
     def close(self) -> bool:
+        """
+        關閉編輯器，釋放資源並移除自動儲存紀錄。
+        Close the editor, release resources, and remove auto-save records.
+        """
         jeditor_logger.info("EditorWidget close")
         if self.code_save_thread is not None:
             self.code_save_thread.still_run = False

je_editor/pyside_ui/main_ui/editor/editor_widget_dock.py

@@ -11,33 +11,60 @@ from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 class FullEditorWidget(QWidget):
+    """
+    FullEditorWidget 提供一個完整的單檔編輯器介面，
+    包含程式碼編輯區、捲動支援，以及關閉時自動儲存功能。
+
+    FullEditorWidget provides a full single-file editor interface,
+    including code editing area, scroll support, and auto-save on close.
+    """
 
     def __init__(self, current_file: str):
+        # 初始化時記錄日誌 / Log initialization
         jeditor_logger.info(f"Init FullEditorWidget current_file: {current_file}")
         super().__init__()
-        # Init variable
-        self.current_file = current_file
-        # Attr
+
+        # ---------------- Init variable 初始化變數 ----------------
+        self.current_file = current_file  # 目前編輯的檔案路徑 / Current editing file path
+
+        # ---------------- Attributes 屬性設定 ----------------
+        # 設定關閉時自動刪除物件，釋放記憶體
+        # Delete object on close to free memory
         self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
-        # UI
+
+        # ---------------- UI 初始化 ----------------
         self.grid_layout = QGridLayout(self)
         self.setWindowTitle(language_wrapper.language_word_dict.get("application_name"))
-        # code edit and code result plaintext
+
+        # 建立程式碼編輯器並放入捲動區域
+        # Create code editor and put inside scroll area
         self.code_edit = CodeEditor(self)
         self.code_edit_scroll_area = QScrollArea()
         self.code_edit_scroll_area.setWidgetResizable(True)
         self.code_edit_scroll_area.setViewportMargins(0, 0, 0, 0)
         self.code_edit_scroll_area.setWidget(self.code_edit)
+
+        # 將編輯器加入版面配置
+        # Add editor to layout
         self.grid_layout.addWidget(self.code_edit_scroll_area, 0, 0)
-        # Font
+
+        # 設定字體樣式 (從使用者設定檔讀取)
+        # Set font style (from user settings)
         self.code_edit.setStyleSheet(
             f"font-size: {user_setting_dict.get('font_size', 12)}pt;"
             f"font-family: {user_setting_dict.get('font', 'Lato')};"
         )
 
     def closeEvent(self, event) -> None:
+        """
+        覆寫 closeEvent，在關閉視窗時自動儲存檔案內容。
+        Override closeEvent to auto-save file content when closing window.
+        """
         jeditor_logger.info(f"FullEditorWidget closeEvent event: {event}")
         path = Path(self.current_file)
         if path.exists() and path.is_file():
+            # 將編輯器內容寫回檔案 / Write editor content back to file
             write_file(self.current_file, self.code_edit.toPlainText())
-        super().closeEvent(event)
+        # 呼叫父類別的 closeEvent，完成 Qt 預設流程
+        # Call parent closeEvent to complete Qt default process
+        super().closeEvent(event)

je_editor/pyside_ui/main_ui/editor/process_input.py

@@ -1,57 +1,83 @@
-from __future__ import annotations
+from __future__ import annotations  # 允許未來版本的型別註解功能 / Enable postponed evaluation of type annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING  # 用於避免循環匯入，僅在型別檢查時載入 / Used to avoid circular imports, only loaded during type checking
 
-from PySide6.QtCore import Qt
+from PySide6.QtCore import Qt  # Qt 核心模組 / Qt core module
 from PySide6.QtWidgets import QWidget, QLineEdit, QBoxLayout, QPushButton, QHBoxLayout
+# 匯入 PySide6 的 GUI 元件 / Import GUI widgets from PySide6
 
 from je_editor.utils.logging.loggin_instance import jeditor_logger
+# 專案內的日誌紀錄器 / Project's logger instance
 
 if TYPE_CHECKING:
     from je_editor.pyside_ui.main_ui.main_editor import EditorWidget
+    # 僅在型別檢查時匯入 EditorWidget，避免循環依賴 / Import only for type checking to avoid circular dependency
 
 from je_editor.utils.multi_language.multi_language_wrapper import language_wrapper
+# 多語系支援工具 / Multi-language wrapper for UI text
 
 
 class ProcessInput(QWidget):
+    """
+    ProcessInput 是一個輸入視窗，允許使用者輸入指令並傳送到不同的子程序 (program/shell/debugger)。
+    ProcessInput is an input widget that allows users to send commands to different subprocesses.
+    """
 
     def __init__(self, main_window: EditorWidget, process_type: str = "debugger"):
+        # 初始化時記錄日誌 / Log initialization
         jeditor_logger.info("Init ProcessInput "
                             f"main_window: {main_window} "
                             f"process_type: {process_type}")
         super().__init__()
-        # Attr
+
+        # 設定當視窗關閉時自動刪除資源
+        # Set attribute to delete widget on close
         self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
-        # UI setting
-        self.main_window = main_window
-        self.box_layout = QBoxLayout(QBoxLayout.Direction.TopToBottom)
-        self.command_input = QLineEdit()
-        self.send_command_button = QPushButton()
+
+        # === UI 設定 / UI Setup ===
+        self.main_window = main_window  # 儲存主視窗參考 / Store reference to main window
+        self.box_layout = QBoxLayout(QBoxLayout.Direction.TopToBottom)  # 垂直佈局 / Vertical layout
+        self.command_input = QLineEdit()  # 輸入框 / Input field
+        self.send_command_button = QPushButton()  # 傳送按鈕 / Send button
+
+        # 設定按鈕文字 (多語系) / Set button text (multi-language)
         self.send_command_button.setText(language_wrapper.language_word_dict.get("process_input_send_command"))
+
+        # 水平佈局，放置按鈕 / Horizontal layout for button
         self.box_h_layout = QHBoxLayout()
         self.box_h_layout.addWidget(self.send_command_button)
+
+        # 將元件加入主佈局 / Add widgets to main layout
         self.box_layout.addWidget(self.command_input)
         self.box_layout.addLayout(self.box_h_layout)
+
+        # 根據 process_type 設定不同的標題與功能 / Configure behavior based on process_type
         if process_type == "program":
             self.setWindowTitle(language_wrapper.language_word_dict.get("editor_program_input_title_label"))
             self.send_command_button.clicked.connect(self.program_send_command)
         elif process_type == "shell":
             self.setWindowTitle(language_wrapper.language_word_dict.get("editor_shell_input_title_label"))
             self.send_command_button.clicked.connect(self.shell_send_command)
-        else:
+        else:  # 預設為 debugger / Default: debugger
             self.setWindowTitle(language_wrapper.language_word_dict.get("editor_debugger_input_title_label"))
             self.send_command_button.clicked.connect(self.debugger_send_command)
+            # 切換主視窗的顯示頁面到 debugger 結果 / Switch main window tab to debugger result
             self.main_window.code_difference_result.setCurrentWidget(self.main_window.debugger_result)
+
+        # 設定主佈局 / Apply layout
         self.setLayout(self.box_layout)
 
+    # === Debugger 指令傳送 / Send command to debugger ===
     def debugger_send_command(self):
         jeditor_logger.info("EditorWidget debugger_send_command")
         if self.main_window.exec_python_debugger is not None:
             process_stdin = self.main_window.exec_python_debugger.process.stdin
             if process_stdin is not None:
+                # 將輸入框文字編碼後寫入子程序 stdin / Write encoded input to subprocess stdin
                 process_stdin.write(self.command_input.text().encode() + b"\n")
                 process_stdin.flush()
 
+    # === Shell 指令傳送 / Send command to shell ===
     def shell_send_command(self):
         jeditor_logger.info("EditorWidget shell_send_command")
         if self.main_window.exec_shell is not None:
@@ -60,10 +86,11 @@ class ProcessInput(QWidget):
                 process_stdin.write(self.command_input.text().encode() + b"\n")
                 process_stdin.flush()
 
+    # === Program 指令傳送 / Send command to program ===
     def program_send_command(self):
         jeditor_logger.info("EditorWidget program_send_command")
         if self.main_window.exec_program is not None:
             process_stdin = self.main_window.exec_program.process.stdin
             if process_stdin is not None:
                 process_stdin.write(self.command_input.text().encode() + b"\n")
-                process_stdin.flush()
+                process_stdin.flush()

je_editor/pyside_ui/main_ui/ipython_widget/rich_jupyter.py

@@ -1,43 +1,78 @@
-from __future__ import annotations
+from __future__ import annotations  # 啟用未來版本的型別註解功能 / Enable postponed evaluation of type annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING  # 僅在型別檢查時使用，避免循環匯入 / Used only for type checking to avoid circular imports
 
-from IPython.lib import guisupport
-from PySide6.QtWidgets import QWidget, QGridLayout
-from qtconsole.inprocess import QtInProcessKernelManager
-from qtconsole.rich_jupyter_widget import RichJupyterWidget
+from IPython.lib import guisupport  # 提供與 Qt GUI 整合的支援 / Provides support for integrating IPython with Qt GUI
+from PySide6.QtWidgets import QWidget, QGridLayout  # PySide6 視窗元件 / PySide6 widgets
+from qtconsole.inprocess import QtInProcessKernelManager  # 管理內嵌的 Jupyter kernel / Manages an in-process Jupyter kernel
+from qtconsole.rich_jupyter_widget import RichJupyterWidget  # Jupyter 富文本控制台元件 / Rich Jupyter console widget
 
-from je_editor.utils.logging.loggin_instance import jeditor_logger
+from je_editor.utils.logging.loggin_instance import jeditor_logger  # 專案內的日誌紀錄器 / Project logger
 
 if TYPE_CHECKING:
     from je_editor.pyside_ui.main_ui.main_editor import EditorMain
+    # 僅在型別檢查時匯入 EditorMain，避免循環依賴 / Import only for type checking to avoid circular dependency
 
 
 class IpythonWidget(QWidget):
+    """
+    IpythonWidget 類別
+    - 在 PySide6 GUI 中嵌入一個 Jupyter/IPython 控制台
+    - 提供互動式 Python 環境，方便在應用程式內直接執行程式碼
+    IpythonWidget class
+    - Embeds a Jupyter/IPython console inside a PySide6 GUI
+    - Provides an interactive Python environment within the application
+    """
 
     def __init__(self, main_window: EditorMain):
+        # 初始化時記錄日誌 / Log initialization
         jeditor_logger.info(f"Init IpythonWidget main_window: {main_window}")
         super().__init__()
+
+        # 建立網格佈局 / Create grid layout
         self.grid_layout = QGridLayout()
+
+        # 取得 Qt 應用程式實例 (Qt4 API，但可在 PySide6 中使用) / Get Qt application instance
         app = guisupport.get_app_qt4()
-        self.kernel_manager = QtInProcessKernelManager()
-        self.kernel_manager.start_kernel()
-        self.kernel = self.kernel_manager.kernel
+
+        # === 建立並啟動 Jupyter Kernel / Create and start Jupyter kernel ===
+        self.kernel_manager = QtInProcessKernelManager()  # 內嵌 kernel 管理器 / In-process kernel manager
+        self.kernel_manager.start_kernel()  # 啟動 kernel / Start kernel
+        self.kernel = self.kernel_manager.kernel  # 取得 kernel 實例 / Get kernel instance
+
+        # 建立 kernel client 並啟動通訊管道 / Create kernel client and start communication channels
         self.kernel_client = self.kernel_manager.client()
         self.kernel_client.start_channels()
+
+        # === 建立 Jupyter 控制台元件 / Create Jupyter console widget ===
         self.jupyter_widget = RichJupyterWidget()
         self.jupyter_widget.kernel_manager = self.kernel_manager
         self.jupyter_widget.kernel_client = self.kernel_client
+
+        # 將控制台加入佈局 (佔滿整個視窗) / Add console widget to layout (fill entire window)
         self.grid_layout.addWidget(self.jupyter_widget, 0, 0, -1, -1)
+
+        # 啟動 Qt 事件迴圈，讓 Jupyter 控制台能正常運作 / Start Qt event loop for Jupyter console
         guisupport.start_event_loop_qt4(app)
 
+        # 設定主佈局 / Apply layout
         self.setLayout(self.grid_layout)
 
     def close(self):
+        """
+        覆寫 close 方法，確保關閉時正確釋放資源
+        Override close method to properly release resources
+        """
         jeditor_logger.info("IpythonWidget close")
+
+        # 停止 kernel client 的通訊管道 / Stop kernel client channels
         if self.kernel_client:
             self.kernel_client.stop_channels()
+
+        # 重啟並關閉 kernel，確保乾淨退出 / Restart and shutdown kernel for clean exit
         if self.kernel_manager:
             self.kernel_manager.restart_kernel()
             self.kernel_manager.shutdown_kernel()
-        super().close()
+
+        # 呼叫父類別的 close 方法 / Call parent close method
+        super().close()