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

je_editor/pyside_ui/code/shell_process/shell_exec.py

@@ -23,7 +23,6 @@ from je_editor.utils.venv_check.check_venv import check_and_choose_venv
 
 
 class ShellManager(object):
-
     def __init__(
             self,
             main_window: Union[EditorWidget, None] = None,
@@ -31,36 +30,41 @@ class ShellManager(object):
             program_buffer: int = 1024,
             after_done_function: Union[None, Callable] = None
     ):
+        # 初始化 ShellManager，記錄基本設定
+        # Initialize ShellManager, log basic settings
         jeditor_logger.info(f"Init ShellManager "
                             f"main_window: {main_window} "
                             f"shell_encoding: {shell_encoding} "
                             f"program_buffer: {program_buffer} "
                             f"after_done_function: {after_done_function}")
         """
-        :param main_window: Pyside main window
-        :param shell_encoding: shell command read output encoding
-        :param program_buffer: buffer size
+        :param main_window: Pyside 主視窗 / Pyside main window
+        :param shell_encoding: shell 輸出編碼 / shell command output encoding
+        :param program_buffer: 緩衝區大小 / buffer size
         """
-        self.read_program_error_output_from_thread = None
-        self.read_program_output_from_thread = None
-        self.main_window: EditorWidget = main_window
-        self.compiler_path = None
-        self.code_result: Union[QTextEdit, None] = None
-        self.timer: Union[QTimer, None] = None
-        self.still_run_shell: bool = True
-        self.process = None
-        self.run_output_queue: queue.Queue = queue.Queue()
-        self.run_error_queue: queue.Queue = queue.Queue()
-        self.program_encoding: str = shell_encoding
-        self.program_buffer: int = program_buffer
-        self.after_done_function = after_done_function
-        self.renew_path()
-        run_instance_manager.instance_list.append(self)
+        self.read_program_error_output_from_thread = None  # 錯誤輸出讀取執行緒 / thread for reading stderr
+        self.read_program_output_from_thread = None        # 標準輸出讀取執行緒 / thread for reading stdout
+        self.main_window: EditorWidget = main_window       # 主視窗 / main window
+        self.compiler_path = None                          # Python 編譯器路徑 / Python compiler path
+        self.code_result: Union[QTextEdit, None] = None    # 顯示輸出結果的文字框 / QTextEdit for displaying results
+        self.timer: Union[QTimer, None] = None             # 定時器 / QTimer for periodic updates
+        self.still_run_shell: bool = True                  # 是否仍在執行 / flag for running state
+        self.process = None                                # 子程序物件 / subprocess object
+        self.run_output_queue: queue.Queue = queue.Queue() # 標準輸出佇列 / stdout queue
+        self.run_error_queue: queue.Queue = queue.Queue()  # 錯誤輸出佇列 / stderr queue
+        self.program_encoding: str = shell_encoding        # 編碼設定 / encoding setting
+        self.program_buffer: int = program_buffer          # 緩衝區大小 / buffer size
+        self.after_done_function = after_done_function     # 完成後的回呼函數 / callback after done
+        self.renew_path()                                  # 更新 Python 執行路徑 / renew Python path
+        run_instance_manager.instance_list.append(self)    # 註冊到執行管理器 / register instance
 
     def renew_path(self) -> None:
+        # 更新 Python 編譯器路徑
+        # Renew Python compiler path
         jeditor_logger.info("ShellManager renew_path")
         if self.main_window.python_compiler is None:
-            # Renew compiler path
+            # 如果主視窗沒有指定 Python，則使用 venv
+            # If no compiler specified, use venv
             if sys.platform in ["win32", "cygwin", "msys"]:
                 venv_path = Path(os.getcwd() + "/venv/Scripts")
             else:
@@ -70,6 +74,8 @@ class ShellManager(object):
             self.compiler_path = self.main_window.python_compiler
 
     def later_init(self) -> None:
+        # 延遲初始化，綁定輸出視窗
+        # Late initialization, bind output QTextEdit
         jeditor_logger.info("ShellManager later_init")
         if self.main_window is not None:
             self.code_result: QTextEdit = self.main_window.code_result
@@ -78,22 +84,25 @@ class ShellManager(object):
 
     def exec_shell(self, shell_command: Union[str, list]) -> None:
         """
-        :param shell_command: shell command will run
-        :return: if error return result and True else return result and False
+        執行 shell 指令
+        Execute shell command
+        :param shell_command: 要執行的指令 / command to run
+        :return: 若錯誤則回傳錯誤訊息 / return error message if failed
         """
         jeditor_logger.info(f"ShellManager exec_shell, shell_command: {shell_command}")
         try:
-            self.exit_program()
-            self.code_result.setPlainText("")
+            self.exit_program()  # 結束舊的程序 / terminate previous process
+            self.code_result.setPlainText("")  # 清空輸出視窗 / clear output window
             if sys.platform in ["win32", "cygwin", "msys"]:
                 args = shell_command
             else:
-                args = shlex.split(shell_command)
+                args = shlex.split(shell_command)  # 非 Windows 系統需分割指令 / split command for Unix-like
             text_cursor = self.code_result.textCursor()
             text_format = QTextCharFormat()
             text_format.setForeground(actually_color_dict.get("normal_output_color"))
-            text_cursor.insertText(str(args), text_format)
+            text_cursor.insertText(str(args), text_format)  # 顯示執行的指令 / show executed command
             text_cursor.insertBlock()
+            # 建立子程序 / create subprocess
             self.process = subprocess.Popen(
                 args=args,
                 stdout=subprocess.PIPE,
@@ -102,24 +111,26 @@ class ShellManager(object):
                 shell=True,
             )
             self.still_run_shell = True
-            # program output message queue thread
+            # 建立讀取標準輸出的執行緒 / thread for stdout
             self.read_program_output_from_thread = Thread(
                 target=self.read_program_output_from_process,
                 daemon=True
             )
             self.read_program_output_from_thread.start()
-            # program error message queue thread
+            # 建立讀取錯誤輸出的執行緒 / thread for stderr
             self.read_program_error_output_from_thread = Thread(
                 target=self.read_program_error_output_from_process,
                 daemon=True
             )
             self.read_program_error_output_from_thread.start()
-            # start timer
+            # 啟動定時器，每 10ms 更新一次輸出 / start QTimer for updating output
             self.timer = QTimer(self.main_window)
             self.timer.setInterval(10)
             self.timer.timeout.connect(self.pull_text)
             self.timer.start()
         except Exception as error:
+            # 若發生錯誤，顯示錯誤訊息並結束程序
+            # If error occurs, show error message and terminate process
             text_cursor = self.code_result.textCursor()
             text_format = QTextCharFormat()
             text_format.setForeground(actually_color_dict.get("error_output_color"))
@@ -130,6 +141,8 @@ class ShellManager(object):
 
     # tkinter_ui update method
     def pull_text(self) -> None:
+        # 從佇列中拉取輸出與錯誤訊息，並更新到 UI
+        # Pull stdout/stderr messages from queue and update UI
         jeditor_logger.info("ShellManager pull_text")
         try:
             if not self.run_output_queue.empty():
@@ -152,61 +165,71 @@ class ShellManager(object):
                     text_cursor.insertBlock()
         except queue.Empty:
             pass
+        # 檢查子程序是否結束 / check if process finished
         if self.process.returncode == 0:
             self.process_run_over()
         elif self.process.returncode is not None:
             self.process_run_over()
         if self.still_run_shell:
-            # poll return code
+            # 持續檢查程序狀態 / keep polling process
             self.process.poll()
-
     def process_run_over(self):
+        # 當子程序結束時呼叫，停止計時器並清理資源
+        # Called when subprocess finishes, stop timer and clean up resources
         jeditor_logger.info("ShellManager process_run_over")
-        self.timer.stop()
-        self.exit_program()
-        self.main_window.exec_shell = None
+        self.timer.stop()  # 停止定時器 / stop QTimer
+        self.exit_program()  # 結束程序並清理 / terminate process and cleanup
+        self.main_window.exec_shell = None  # 重置 main_window 的 exec_shell / reset exec_shell reference
         if self.after_done_function is not None:
-            self.after_done_function()
+            self.after_done_function()  # 執行結束後的回呼函數 / run callback if provided
 
-    # exit program change runs flag to false and clean read thread and queue and process
+    # exit program: 將執行旗標設為 False，清理執行緒、佇列與子程序
+    # exit program: set running flag to False, clean threads, queues, and subprocess
     def exit_program(self) -> None:
         jeditor_logger.info("ShellManager exit_program")
-        self.still_run_shell = False
+        self.still_run_shell = False  # 停止讀取迴圈 / stop reading loop
         if self.read_program_output_from_thread is not None:
-            self.read_program_output_from_thread = None
+            self.read_program_output_from_thread = None  # 清理 stdout 執行緒 / clear stdout thread
         if self.read_program_error_output_from_thread is not None:
-            self.read_program_error_output_from_thread = None
-        self.print_and_clear_queue()
+            self.read_program_error_output_from_thread = None  # 清理 stderr 執行緒 / clear stderr thread
+        self.print_and_clear_queue()  # 清空輸出佇列 / clear output queues
         if self.process is not None:
-            self.process.terminate()
+            self.process.terminate()  # 終止子程序 / terminate subprocess
             text_cursor = self.code_result.textCursor()
             text_format = QTextCharFormat()
             text_format.setForeground(actually_color_dict.get("normal_output_color"))
+            # 顯示退出代碼 / show exit code
             text_cursor.insertText(f"Shell command exit with code {self.process.returncode}", text_format)
             text_cursor.insertBlock()
-            self.process = None
+            self.process = None  # 清空 process 物件 / reset process object
 
     def print_and_clear_queue(self) -> None:
+        # 清空 stdout 與 stderr 佇列
+        # Reset stdout and stderr queues
         jeditor_logger.info("ShellManager print_and_clear_queue")
         self.run_output_queue = queue.Queue()
         self.run_error_queue = queue.Queue()
 
     def read_program_output_from_process(self) -> None:
+        # 從子程序讀取標準輸出並放入佇列
+        # Continuously read stdout from subprocess and put into queue
         jeditor_logger.info("ShellManager read_program_output_from_process")
         while self.still_run_shell:
             program_output_data = self.process.stdout.readline(
                 self.program_buffer) \
-                .decode(self.program_encoding, "replace")
+                .decode(self.program_encoding, "replace")  # 解碼輸出 / decode output
             if self.process:
-                self.process.stdout.flush()
-            self.run_output_queue.put_nowait(program_output_data)
+                self.process.stdout.flush()  # 清空緩衝區 / flush buffer
+            self.run_output_queue.put_nowait(program_output_data)  # 放入輸出佇列 / enqueue stdout
 
     def read_program_error_output_from_process(self) -> None:
+        # 從子程序讀取錯誤輸出並放入佇列
+        # Continuously read stderr from subprocess and put into queue
         jeditor_logger.info("ShellManager read_program_error_output_from_process")
         while self.still_run_shell:
             program_error_output_data = self.process.stderr.readline(
                 self.program_buffer) \
-                .decode(self.program_encoding, "replace")
+                .decode(self.program_encoding, "replace")  # 解碼錯誤輸出 / decode stderr
             if self.process:
-                self.process.stderr.flush()
-            self.run_error_queue.put_nowait(program_error_output_data)
+                self.process.stderr.flush()  # 清空緩衝區 / flush buffer
+            self.run_error_queue.put_nowait(program_error_output_data)  # 放入錯誤佇列 / enqueue stderr

je_editor/pyside_ui/code/syntax/python_syntax.py

@@ -4,46 +4,74 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    # 僅在型別檢查時匯入，避免循環依賴
+    # Only imported during type checking to avoid circular imports
     from je_editor.pyside_ui.code.plaintext_code_edit.code_edit_plaintext import CodeEditor
 
 from PySide6.QtCore import QRegularExpression
 from PySide6.QtGui import QSyntaxHighlighter
 from PySide6.QtGui import QTextCharFormat
 
-from je_editor.pyside_ui.code.syntax.syntax_setting import syntax_word_setting_dict, syntax_rule_setting_dict, \
+# 匯入語法設定，包括關鍵字、規則、擴展設定
+# Import syntax settings: keywords, rules, and extended settings
+from je_editor.pyside_ui.code.syntax.syntax_setting import (
+    syntax_word_setting_dict,
+    syntax_rule_setting_dict,
     syntax_extend_setting_dict
+)
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 class PythonHighlighter(QSyntaxHighlighter):
+    """
+    Python 語法高亮類別，繼承自 QSyntaxHighlighter
+    Python syntax highlighter class, inherits from QSyntaxHighlighter
+    """
+
     def __init__(self, parent=None, main_window: CodeEditor = None):
         jeditor_logger.info(f"Init PythonHighlighter parent: {parent}")
         super().__init__(parent)
 
-        self.highlight_rules = []
+        self.highlight_rules = []  # 儲存所有高亮規則 / store all highlight rules
+
+        # 判斷目前檔案副檔名，若無則預設為 .py
+        # Determine current file suffix, default to .py
         if main_window.current_file is not None:
             current_file_suffix = Path(main_window.current_file).suffix
         else:
             current_file_suffix = ".py"
-        # Basic Highlight
+
+        # -------------------------
+        # 基本語法規則 (通用)
+        # Basic highlight rules (common)
+        # -------------------------
         for rule_variable_dict in syntax_rule_setting_dict.values():
-            color = rule_variable_dict.get("color")
+            color = rule_variable_dict.get("color")  # 規則顏色 / rule color
             text_char_format = QTextCharFormat()
             text_char_format.setForeground(color)
-            for rule in rule_variable_dict.get("rules"):
+            for rule in rule_variable_dict.get("rules"):  # 正則規則 / regex rules
                 pattern = QRegularExpression(rule)
                 self.highlight_rules.append((pattern, text_char_format))
+
+        # -------------------------
+        # Python 語法高亮
+        # Python-specific highlight
+        # -------------------------
         if current_file_suffix == ".py":
-            # Python Highlight
             for rule_variable_dict in syntax_word_setting_dict.values():
                 color = rule_variable_dict.get("color")
                 text_char_format = QTextCharFormat()
                 text_char_format.setForeground(color)
-                for word in rule_variable_dict.get("words"):
+                for word in rule_variable_dict.get("words"):  # 關鍵字清單 / keyword list
+                    # 使用 \b 確保完整單字匹配 / use \b for whole word match
                     pattern = QRegularExpression(rf"\b{word}\b")
                     self.highlight_rules.append((pattern, text_char_format))
+
+        # -------------------------
+        # 其他語言的擴展高亮
+        # Extended highlight for other languages
+        # -------------------------
         else:
-            # Another Highlight
             if syntax_extend_setting_dict.get(current_file_suffix):
                 for rule_variable_dict in syntax_extend_setting_dict.get(current_file_suffix).values():
                     color = rule_variable_dict.get("color")
@@ -53,12 +81,19 @@ class PythonHighlighter(QSyntaxHighlighter):
                         pattern = QRegularExpression(rf"\b{word}\b")
                         self.highlight_rules.append((pattern, text_char_format))
             else:
+                # 若無對應規則則略過
+                # Skip if no rules found
                 pass
 
     def highlightBlock(self, text) -> None:
+        """
+        對每一行文字進行語法高亮
+        Apply syntax highlighting to each block of text
+        """
         jeditor_logger.info(f"PythonHighlighter highlightBlock text: {text}")
         for pattern, pattern_format in self.highlight_rules:
-            match_iterator = pattern.globalMatch(text)
+            match_iterator = pattern.globalMatch(text)  # 全域比對 / global regex match
             while match_iterator.hasNext():
                 match = match_iterator.next()
-                self.setFormat(match.capturedStart(), match.capturedLength(), pattern_format)
+                # 設定比對到的文字格式 / apply format to matched text
+                self.setFormat(match.capturedStart(), match.capturedLength(), pattern_format)

je_editor/pyside_ui/code/syntax/syntax_setting.py

@@ -1,27 +1,45 @@
 from PySide6.QtGui import QColor
 
+# -----------------------------
+# 基本語法規則設定 (數字、註解、字串)
+# Basic syntax rule settings (numbers, comments, strings)
+# -----------------------------
 syntax_rule_setting_dict: dict = {
     "number_rule": {
-        "rules": (r"\b[+-]?[0-9]+[lL]?\b",
-                  r"\b[+-]?0[xX][0-9A-Fa-f]+[lL]?\b",
-                  r"\b[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?\b"),
-        "color": QColor(0, 128, 255)
+        # 數字規則 (整數、十六進位、小數/科學記號)
+        # Number rules (integer, hex, float/scientific notation)
+        "rules": (
+            r"\b[+-]?[0-9]+[lL]?\b",                       # 整數 integer
+            r"\b[+-]?0[xX][0-9A-Fa-f]+[lL]?\b",            # 十六進位 hex
+            r"\b[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?\b"  # 浮點數/科學記號 float/scientific
+        ),
+        "color": QColor(0, 128, 255)  # 藍色 Blue
     },
     "comment_rule": {
+        # 註解規則 (以 # 開頭直到換行)
+        # Comment rule (starts with # until newline)
         "rules": (r"#[^\n]*",),
-        "color": QColor(0, 230, 0)
+        "color": QColor(0, 230, 0)  # 綠色 Green
     },
     "string_rule": {
+        # 字串規則 (單引號與雙引號)
+        # String rules (single and double quotes)
         "rules": (
-            r"'[^'\\]*(\\.[^'\\]*)*'",  # Single
-            r'"[^"\\]*(\\.[^"\\]*)*"',  # Double
+            r"'[^'\\]*(\\.[^'\\]*)*'",  # 單引號字串 single-quoted string
+            r'"[^"\\]*(\\.[^"\\]*)*"',  # 雙引號字串 double-quoted string
         ),
-        "color": QColor(0, 153, 0)
+        "color": QColor(0, 153, 0)  # 深綠色 Dark green
     }
 }
 
+# -----------------------------
+# 關鍵字與內建函式設定
+# Keywords and built-in functions
+# -----------------------------
 syntax_word_setting_dict: dict = {
     "keywords": {
+        # Python 保留字 (語法關鍵字)
+        # Python reserved keywords
         "words": (
             "False", "None", "True", "and", "as", "assert", "async",
             "await", "break", "class", "continue", "def", "del",
@@ -29,9 +47,11 @@ syntax_word_setting_dict: dict = {
             "global", "if", "import", "in", "is", "lambda", "nonlocal",
             "not", "or", "pass", "raise", "return", "try", "while", "with", "yield"
         ),
-        "color": QColor(255, 212, 102)
+        "color": QColor(255, 212, 102)  # 黃色 Yellow
     },
     "builtins_keyword": {
+        # Python 內建函式與型別
+        # Python built-in functions and types
         "words": (
             "abs", "aiter", "all", "any", "anext", "ascii",
             "bin", "bool", "breakpoint", "bytearray", "bytes",
@@ -55,13 +75,21 @@ syntax_word_setting_dict: dict = {
             "zip",
             "__import__"
         ),
-        "color": QColor(0, 255, 255)
+        "color": QColor(0, 255, 255)  # 青色 Cyan
     },
     "self": {
+        # Python 類別中的 self 關鍵字
+        # "self" keyword in Python classes
         "words": ("self",),
-        "color": QColor(204, 0, 204)
+        "color": QColor(204, 0, 204)  # 紫色 Purple
     }
 }
 
+# -----------------------------
+# 擴展語法設定 (其他語言可在此加入)
+# Extended syntax settings (for other languages)
+# -----------------------------
 syntax_extend_setting_dict: dict = {
-}
+    # 目前為空，可依副檔名新增規則
+    # Currently empty, can add rules for other file suffixes
+}

je_editor/pyside_ui/code/textedit_code_result/code_record.py

@@ -7,47 +7,69 @@ from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 class CodeRecord(QTextEdit):
-    # Extend QTextEdit
+    # 繼承自 QTextEdit，作為程式碼輸出紀錄區
+    # Extend QTextEdit, used as a code output record area
     def __init__(self):
         jeditor_logger.info("Init CodeRecord")
         super().__init__()
-        self.setLineWrapMode(self.LineWrapMode.NoWrap)
-        self.setReadOnly(True)
-        # Search Result
+        self.setLineWrapMode(self.LineWrapMode.NoWrap)  # 禁止自動換行 / disable line wrapping
+        self.setReadOnly(True)  # 設為唯讀 / set as read-only
+
+        # 建立搜尋錯誤的快捷動作
+        # Create search error action with shortcut
         self.search_result_action = QAction("Search Error")
         self.search_result_action.setShortcut("Ctrl+e")
         self.search_result_action.triggered.connect(
-            self.start_search_result_dialog
+            self.start_search_result_dialog  # 綁定觸發事件 / bind trigger event
         )
         self.addAction(self.search_result_action)
 
     def append(self, text: str) -> None:
+        """
+        新增文字到輸出區，若超過最大行數則清空
+        Append text to output area, clear if exceeding max lines
+        """
         jeditor_logger.info("CodeRecord append")
         max_line: int = user_setting_dict.get("max_line_of_output", 200000)
         if self.document().lineCount() >= max_line > 0:
+            # 若行數超過設定，清空內容
+            # Clear content if line count exceeds limit
             self.setPlainText("")
         super().append(text)
 
     def start_search_result_dialog(self) -> None:
+        """
+        開啟搜尋對話框，並綁定搜尋按鈕事件
+        Open search dialog and bind search button events
+        """
         jeditor_logger.info("CodeRecord start_search_result_dialog")
-        # Binding search box
-        self.search_result_box = SearchResultBox()
+        self.search_result_box = SearchResultBox()  # 建立搜尋框 / create search box
         self.search_result_box.search_back_button.clicked.connect(
-            self.find_back_text
+            self.find_back_text  # 綁定「上一個」搜尋 / bind "find previous"
         )
         self.search_result_box.search_next_button.clicked.connect(
-            self.find_next_text
+            self.find_next_text  # 綁定「下一個」搜尋 / bind "find next"
         )
-        self.search_result_box.show()
+        self.search_result_box.show()  # 顯示搜尋框 / show search box
 
     def find_next_text(self) -> None:
+        """
+        搜尋下一個符合的文字
+        Find next matching text
+        """
         jeditor_logger.info("CodeRecord find_next_text")
         if self.search_result_box.isVisible():
             text = self.search_result_box.search_input.text()
-            self.find(text)
+            self.find(text)  # 使用 QTextEdit 內建 find 方法 / use QTextEdit built-in find
 
     def find_back_text(self) -> None:
+        """
+        搜尋上一個符合的文字
+        Find previous matching text
+        """
         jeditor_logger.info("CodeRecord find_back_text")
         if self.search_result_box.isVisible():
             text = self.search_result_box.search_input.text()
-            self.find(text, QTextDocument.FindFlag.FindBackward)
+            # 使用 FindBackward 旗標往回搜尋
+            # Use FindBackward flag to search backwards
+            self.find(text, QTextDocument.FindFlag.FindBackward)