je-editor 0.0.221__tar.gz → 0.0.223__tar.gz

{je_editor-0.0.221 → je_editor-0.0.223}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: je_editor
-Version: 0.0.221
+Version: 0.0.223
 Summary: JEditor is basic but powerful editor include GPT
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/JE-Chen/je_editor
@@ -23,8 +23,8 @@ Requires-Dist: frontengine
 Requires-Dist: pycodestyle
 Requires-Dist: jedi
 Requires-Dist: qtconsole
-Requires-Dist: langchain_openai
-Requires-Dist: langchain
+Requires-Dist: langchain_openai==1.0.0
+Requires-Dist: langchain==1.0.0
 Requires-Dist: pydantic
 Requires-Dist: watchdog
 Requires-Dist: ruff

{je_editor-0.0.221 → je_editor-0.0.223}/je_editor/__init__.py

@@ -1,4 +1,4 @@
-from je_editor.pyside_ui.browser.browser_widget import BrowserWidget
+from je_editor.pyside_ui.browser.main_browser_widget import MainBrowserWidget
 from je_editor.pyside_ui.code.code_process.code_exec import ExecManager
 from je_editor.pyside_ui.code.shell_process.shell_exec import ShellManager
 from je_editor.pyside_ui.code.syntax.python_syntax import PythonHighlighter
@@ -28,7 +28,7 @@ __all__ = [
     "JEditorRunOnShellException", "JEditorSaveFileException", "syntax_rule_setting_dict",
     "JEditorOpenFileException", "JEditorContentFileException", "syntax_extend_setting_dict",
     "JEditorCantFindLanguageException", "JEditorJsonException", "PythonHighlighter",
-    "user_setting_dict", "user_setting_color_dict", "EditorWidget", "BrowserWidget",
+    "user_setting_dict", "user_setting_color_dict", "EditorWidget", "MainBrowserWidget",
     "ExecManager", "ShellManager", "traditional_chinese_word_dict", "english_word_dict",
     "language_wrapper"
 ]

je_editor-0.0.223/je_editor/code_scan/ruff_thread.py

@@ -0,0 +1,58 @@
+import subprocess
+import threading
+import time
+from queue import Queue
+
+
+class RuffThread(threading.Thread):
+    """
+    A thread class to run Ruff (a Python linter/formatter) as a subprocess.
+    使用子執行緒執行 Ruff (Python 程式碼檢查/格式化工具)。
+    """
+
+    def __init__(self, ruff_commands: list, std_queue: Queue, stderr_queue: Queue):
+        """
+        Initialize the RuffThread.
+        初始化 RuffThread。
+
+        :param ruff_commands: list of commands to run Ruff, e.g. ["ruff", "check"]
+                              要執行的 Ruff 指令，例如 ["ruff", "check"]
+        :param std_queue: queue to store standard output
+                          用來存放標準輸出的佇列
+        :param stderr_queue: queue to store error output
+                             用來存放錯誤輸出的佇列
+        """
+        super().__init__()
+        if ruff_commands is None:
+            self.ruff_commands = ["ruff", "check"]
+        else:
+            self.ruff_commands = ruff_commands
+
+        self.ruff_process = None
+        self.std_queue = std_queue
+        self.stderr_queue = stderr_queue
+
+    def run(self):
+        """
+        Run the Ruff process in a separate thread.
+        在子執行緒中執行 Ruff 程式。
+        """
+        # 啟動子程序，捕捉 stdout 與 stderr
+        self.ruff_process = subprocess.Popen(
+            self.ruff_commands,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1
+        )
+
+        # 等待子程序結束
+        while self.ruff_process.poll() is None:
+            time.sleep(1)
+        else:
+            # 子程序結束後，讀取 stdout 與 stderr
+            for line in self.ruff_process.stdout:
+                self.std_queue.put(line.strip())
+
+            for line in self.ruff_process.stderr:
+                self.stderr_queue.put(line.strip())

je_editor-0.0.223/je_editor/code_scan/watchdog_implement.py

@@ -0,0 +1,56 @@
+import time
+from queue import Queue
+from typing import Dict
+
+from watchdog.events import FileSystemEventHandler
+
+from je_editor.code_scan.ruff_thread import RuffThread
+
+
+class RuffPythonFileChangeHandler(FileSystemEventHandler):
+    """
+    File system event handler that runs Ruff when Python files are modified.
+    當 Python 檔案被修改時，自動觸發 Ruff 檢查。
+    """
+
+    def __init__(self, ruff_commands: list = None, debounce_interval: float = 1.0):
+        """
+        :param ruff_commands: Ruff command list, e.g. ["ruff", "check"]
+        :param debounce_interval: Minimum interval (seconds) between re-runs for the same file
+                                  同一檔案觸發 Ruff 的最小間隔秒數
+        """
+        super().__init__()
+        self.ruff_commands = ruff_commands or ["ruff", "check"]
+        self.stdout_queue: Queue = Queue()
+        self.stderr_queue: Queue = Queue()
+        self.ruff_threads_dict: Dict[str, RuffThread] = {}
+        self.last_run_time: Dict[str, float] = {}
+        self.debounce_interval = debounce_interval
+
+    def _start_new_thread(self, file_path: str):
+        """Helper to start a new Ruff thread for a given file."""
+        ruff_thread = RuffThread(self.ruff_commands, self.stdout_queue, self.stderr_queue)
+        self.ruff_threads_dict[file_path] = ruff_thread
+        self.last_run_time[file_path] = time.time()
+        ruff_thread.start()
+
+    def on_modified(self, event):
+        """Triggered when a file is modified."""
+        if event.is_directory:
+            return
+
+        if not event.src_path.endswith(".py"):
+            return
+
+        now = time.time()
+        last_time = self.last_run_time.get(event.src_path, 0)
+
+        # Debounce: skip if last run was too recent
+        if now - last_time < self.debounce_interval:
+            return
+
+        ruff_thread = self.ruff_threads_dict.get(event.src_path)
+
+        if ruff_thread is None or not ruff_thread.is_alive():
+            self._start_new_thread(event.src_path)
+        # else: thread still running, skip

je_editor-0.0.223/je_editor/code_scan/watchdog_thread.py

@@ -0,0 +1,78 @@
+import threading
+import time
+import sys
+from pathlib import Path
+
+from watchdog.observers import Observer
+
+from je_editor.code_scan.watchdog_implement import RuffPythonFileChangeHandler
+
+
+class WatchdogThread(threading.Thread):
+    """
+    A thread that runs a watchdog observer to monitor file changes.
+    使用 watchdog 監控檔案變化的執行緒。
+    """
+
+    def __init__(self, check_path: str):
+        """
+        :param check_path: Path to monitor (directory or file)
+                           要監控的路徑（資料夾或檔案）
+        """
+        super().__init__(daemon=True)  # 設為 daemon，主程式結束時自動退出
+        self.check_path = Path(check_path).resolve()
+        self.ruff_handler = RuffPythonFileChangeHandler()
+        self.running = True
+        self.observer = Observer()
+
+    def run(self):
+        """Start the watchdog observer loop."""
+        if not self.check_path.exists():
+            print(f"[Error] Path does not exist: {self.check_path}", file=sys.stderr)
+            return
+
+        # 設定監控
+        self.observer.schedule(self.ruff_handler, str(self.check_path), recursive=True)
+        self.observer.start()
+        print(f"[Watchdog] Monitoring started on {self.check_path}")
+
+        try:
+            while self.running:
+                time.sleep(1)
+                # 這裡可以加上 queue 輸出處理
+                self._process_ruff_output()
+        except KeyboardInterrupt:
+            print("[Watchdog] Interrupted by user")
+        finally:
+            self.observer.stop()
+            self.observer.join()
+            print("[Watchdog] Monitoring stopped")
+
+    def stop(self):
+        """Stop the watchdog thread safely."""
+        self.running = False
+
+    def _process_ruff_output(self):
+        """Process stdout/stderr queues from Ruff threads."""
+        while not self.ruff_handler.stdout_queue.empty():
+            line = self.ruff_handler.stdout_queue.get()
+            print(f"[Ruff STDOUT] {line}")
+
+        while not self.ruff_handler.stderr_queue.empty():
+            line = self.ruff_handler.stderr_queue.get()
+            print(f"[Ruff STDERR] {line}", file=sys.stderr)
+
+
+if __name__ == '__main__':
+    # 預設監控當前目錄
+    path_to_watch = "."
+    watchdog_thread = WatchdogThread(path_to_watch)
+    watchdog_thread.start()
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("[Main] Stopping watchdog...")
+        watchdog_thread.stop()
+        watchdog_thread.join()

je_editor-0.0.223/je_editor/git_client/commit_graph.py

@@ -0,0 +1,77 @@
+import logging
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class CommitNode:
+    commit_sha: str
+    author_name: str
+    commit_date: str
+    commit_message: str
+    parent_shas: List[str]
+    lane_index: int = -1  # assigned later
+
+
+@dataclass
+class CommitGraph:
+    nodes: List[CommitNode] = field(default_factory=list)
+    index: Dict[str, int] = field(default_factory=dict)  # sha -> row
+
+    def build(self, commits: List[Dict[str, Any]], refs: Dict[str, str] | None = None) -> None:
+        """
+        Build commit graph from topo-ordered commits.
+        從 topo-order 的 commits 建立 commit graph。
+        """
+        self.nodes = [
+            CommitNode(
+                commit_sha=c["sha"],
+                author_name=c["author"],
+                commit_date=c["date"],
+                commit_message=c["message"],
+                parent_shas=c["parents"],
+            )
+            for c in commits
+        ]
+        self.index = {n.commit_sha: i for i, n in enumerate(self.nodes)}
+        self._assign_lanes()
+
+    def _assign_lanes(self) -> None:
+        """
+        Assign lanes to commits, similar to `git log --graph`.
+        分配 lanes，模擬 `git log --graph` 的效果。
+        """
+        active: Dict[int, str] = {}  # lane -> sha
+        free_lanes: List[int] = []
+
+        for node in self.nodes:
+            # Step 1: 找到 lane
+            lane_found = next((lane for lane, sha in active.items() if sha == node.commit_sha), None)
+
+            if lane_found is not None:
+                node.lane_index = lane_found
+            elif free_lanes:
+                node.lane_index = free_lanes.pop(0)
+            else:
+                node.lane_index = 0 if not active else max(active.keys()) + 1
+
+            # Step 2: 更新 active
+            # 移除舊的 sha
+            active = {lane: sha for lane, sha in active.items() if sha != node.commit_sha}
+
+            # 父節點分配 lane
+            if node.parent_shas:
+                first_parent = node.parent_shas[0]
+                active[node.lane_index] = first_parent
+                for p in node.parent_shas[1:]:
+                    pl = free_lanes.pop(0) if free_lanes else (max(active.keys()) + 1)
+                    active[pl] = p
+
+            # Step 3: 更新 free_lanes
+            if active:
+                max_lane = max(active.keys())
+                used = set(active.keys())
+                all_lanes = set(range(max_lane + 1))
+                free_lanes = sorted(set(free_lanes).union(all_lanes - used))

je_editor-0.0.221/je_editor/git_client/git.py → je_editor-0.0.223/je_editor/git_client/git_action.py

@@ -160,7 +160,7 @@ NULL_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
 # -----------------------
 # Worker thread wrapper
 # -----------------------
-class Worker(QThread):
+class GitWorker(QThread):
     """
     Runs a function in a separate thread to avoid blocking the UI.
     Emits (result, error) when done.

{je_editor-0.0.221 → je_editor-0.0.223}/je_editor/git_client/git_cli.py

@@ -11,12 +11,12 @@ class GitCLI:
         self.repo_path = Path(repo_path)
 
     def is_git_repo(self) -> bool:
-        return (self.repo_path / ".git_client").exists()
+        return (self.repo_path / ".git").exists()
 
     def _run(self, args: List[str]) -> str:
-        log.debug("git_client %s", " ".join(args))
+        log.debug("git %s", " ".join(args))
         res = subprocess.run(
-            ["git_client"] + args,
+            ["git"] + args,
             cwd=self.repo_path,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
@@ -63,4 +63,4 @@ class GitCLI:
                 "date": date,
                 "message": msg,
             })
-        return commits
+        return commits

{je_editor-0.0.221 → je_editor-0.0.223}/je_editor/pyside_ui/browser/browser_download_window.py

@@ -7,33 +7,69 @@ from je_editor.utils.multi_language.multi_language_wrapper import language_wrapp
 
 
 class BrowserDownloadWindow(QWidget):
+    """
+    A window widget to display details of a browser download.
+    瀏覽器下載視窗，用來顯示下載的詳細資訊。
+    """
 
     def __init__(self, download_instance: QWebEngineDownloadRequest):
+        """
+        Initialize the download window with a given QWebEngineDownloadRequest.
+        使用指定的 QWebEngineDownloadRequest 初始化下載視窗。
+        """
         super().__init__()
+        # 記錄初始化訊息到 logger
         jeditor_logger.info("Init BrowserDownloadWindow "
                             f"download_instance: {download_instance}")
+
+        # 設定視窗屬性：當視窗關閉時自動刪除
         self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+
+        # 建立垂直方向的 BoxLayout
         self.box_layout = QBoxLayout(QBoxLayout.Direction.TopToBottom)
+
+        # 建立文字框來顯示下載細節，並設為唯讀
         self.show_download_detail_plaintext = QPlainTextEdit()
         self.show_download_detail_plaintext.setReadOnly(True)
+
+        # 設定視窗標題，支援多語言
         self.setWindowTitle(language_wrapper.language_word_dict.get("browser_download_detail"))
+
+        # 儲存下載實例
         self.download_instance = download_instance
-        self.download_instance.isFinishedChanged.connect(self.print_finish)
-        self.download_instance.interruptReasonChanged.connect(self.print_interrupt)
-        self.download_instance.stateChanged.connect(self.print_state)
+
+        # 綁定下載事件到對應的處理函式
+        self.download_instance.isFinishedChanged.connect(self.print_finish)      # 當下載完成時
+        self.download_instance.interruptReasonChanged.connect(self.print_interrupt)  # 當下載被中斷時
+        self.download_instance.stateChanged.connect(self.print_state)            # 當下載狀態改變時
+
+        # 接受下載請求，開始下載
         self.download_instance.accept()
+
+        # 將文字框加入版面配置
         self.box_layout.addWidget(self.show_download_detail_plaintext)
         self.setLayout(self.box_layout)
 
-
     def print_finish(self):
+        """
+        Slot function triggered when download finishes.
+        當下載完成時觸發，將完成狀態輸出到 logger 與文字框。
+        """
         jeditor_logger.info("BrowserDownloadWindow Print Download is Finished")
         self.show_download_detail_plaintext.appendPlainText(str(self.download_instance.isFinished()))
 
     def print_interrupt(self):
+        """
+        Slot function triggered when download is interrupted.
+        當下載被中斷時觸發，將中斷原因輸出到 logger 與文字框。
+        """
         jeditor_logger.info("BrowserDownloadWindow Print interruptReason")
         self.show_download_detail_plaintext.appendPlainText(str(self.download_instance.interruptReason()))
 
     def print_state(self):
+        """
+        Slot function triggered when download state changes.
+        當下載狀態改變時觸發，將狀態輸出到 logger 與文字框。
+        """
         jeditor_logger.info("BrowserDownloadWindow Print State")
-        self.show_download_detail_plaintext.appendPlainText(str(self.download_instance.state()))
+        self.show_download_detail_plaintext.appendPlainText(str(self.download_instance.state()))

je_editor-0.0.223/je_editor/pyside_ui/browser/browser_serach_lineedit.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QLineEdit
+
+from je_editor.utils.logging.loggin_instance import jeditor_logger
+
+if TYPE_CHECKING:
+    # Forward declaration to avoid circular import at runtime
+    # 僅在型別檢查時匯入，避免執行時循環匯入問題
+    from je_editor.pyside_ui.browser.browser_widget import BrowserWidget
+
+
+class BrowserLineSearch(QLineEdit):
+    """
+    A custom QLineEdit widget for browser search input.
+    自訂的 QLineEdit，用於瀏覽器搜尋輸入。
+    """
+
+    def __init__(self, browser_widget: BrowserWidget):
+        """
+        Initialize the search line with a reference to the browser widget.
+        初始化搜尋輸入框，並保存瀏覽器元件的參考。
+        """
+        super().__init__()
+        # 記錄初始化訊息到 logger
+        jeditor_logger.info("Init BrowserLineSearch "
+                            f"browser_widget: {browser_widget}")
+
+        # 設定屬性：當視窗關閉時自動刪除
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+
+        # 保存瀏覽器元件的參考，用於觸發搜尋
+        self.browser = browser_widget
+
+    def keyPressEvent(self, event) -> None:
+        """
+        Handle key press events.
+        當使用者按下按鍵時觸發：
+        - 如果是 Enter 或 Return，則呼叫瀏覽器的 search() 方法。
+        - 其他情況則交由父類別處理。
+        """
+        if event.key() in [Qt.Key.Key_Enter, Qt.Key.Key_Return]:
+            jeditor_logger.info("Browser Search")
+            # 呼叫瀏覽器元件的搜尋方法
+            self.browser.search()
+
+        # 呼叫父類別的 keyPressEvent，確保其他按鍵行為正常
+        super().keyPressEvent(event)

je_editor-0.0.223/je_editor/pyside_ui/browser/browser_view.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import List, TYPE_CHECKING
+
+from PySide6.QtCore import Signal
+
+if TYPE_CHECKING:
+    from je_editor.pyside_ui.browser.browser_widget import BrowserWidget
+
+from PySide6.QtWebEngineCore import QWebEngineDownloadRequest
+from PySide6.QtWebEngineWidgets import QWebEngineView
+
+from je_editor.pyside_ui.browser.browser_download_window import BrowserDownloadWindow
+from je_editor.utils.logging.loggin_instance import jeditor_logger
+
+
+class BrowserView(QWebEngineView):
+    new_tab_requested = Signal(QWebEngineView)
+    """
+    A custom QWebEngineView that supports file downloads and manages download windows.
+    自訂的 QWebEngineView，支援檔案下載並管理下載視窗。
+    """
+
+    def __init__(self, start_url: str = "https://www.google.com/",
+                 main_widget: BrowserWidget = None, parent=None):
+        """
+        Initialize the browser view with a start URL.
+        使用指定的起始網址初始化瀏覽器視圖。
+        """
+        super().__init__(parent)
+        # 記錄初始化訊息
+        jeditor_logger.info("Init BrowserView "
+                            f"start_url: {start_url}")
+
+        # 設定初始網址
+        self.setUrl(start_url)
+
+        # 儲存下載請求的清單
+        self.download_list: List[QWebEngineDownloadRequest] = list()
+
+        # 儲存下載視窗的清單
+        self.download_window_list: List[BrowserDownloadWindow] = list()
+
+        # 綁定下載事件：當有下載請求時觸發 download_file
+        self.page().profile().downloadRequested.connect(self.download_file)
+
+        self.main_widget = main_widget
+
+
+    def download_file(self, download_instance: QWebEngineDownloadRequest):
+        """
+        Handle a new download request.
+        當有新的下載請求時觸發：
+        - 將下載請求加入清單
+        - 建立並顯示下載細節視窗
+        """
+        jeditor_logger.info("Download File "
+                            f"download_instance: {download_instance}")
+
+        # 加入下載請求到清單
+        self.download_list.append(download_instance)
+
+        # 建立下載細節視窗
+        download_detail_window = BrowserDownloadWindow(download_instance)
+
+        # 加入視窗到清單並顯示
+        self.download_window_list.append(download_detail_window)
+        download_detail_window.show()
+
+    def closeEvent(self, event) -> None:
+        """
+        Handle the close event of the browser view.
+        當瀏覽器視窗關閉時：
+        - 取消所有進行中的下載
+        - 關閉所有下載細節視窗
+        """
+        jeditor_logger.info(f"BrowserView closeEvent event: {event}")
+
+        # 取消所有下載
+        for download_instance in self.download_list:
+            download_instance.cancel()
+
+        # 關閉所有下載視窗
+        for download_window in self.download_window_list:
+            download_window.close()
+
+        # 呼叫父類別的 closeEvent，確保正常關閉
+        super().closeEvent(event)

{je_editor-0.0.221 → je_editor-0.0.223}/je_editor/pyside_ui/browser/browser_widget.py

@@ -1,60 +1,90 @@
-from PySide6.QtGui import QAction, Qt
-from PySide6.QtWidgets import QWidget, QGridLayout, QPushButton, QInputDialog
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from je_editor.pyside_ui.browser.main_browser_widget import MainBrowserWidget
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QAction
+from PySide6.QtWidgets import QWidget, QPushButton, QGridLayout, QInputDialog
 
 from je_editor.pyside_ui.browser.browser_serach_lineedit import BrowserLineSearch
-from je_editor.pyside_ui.browser.browser_view import BrowserView
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 from je_editor.utils.multi_language.multi_language_wrapper import language_wrapper
 
+from je_editor.pyside_ui.browser.browser_view import BrowserView
 
-class BrowserWidget(QWidget):
 
+class BrowserWidget(QWidget):
     def __init__(self, start_url: str = "https://www.google.com/",
-                 search_prefix: str = "https://www.google.com.tw/search?q="):
+                 search_prefix: str = "https://www.google.com.tw/search?q=",
+                 main_widget: MainBrowserWidget = None, browser_view: BrowserView = None):
+        # --- Browser setting / 瀏覽器設定 ---
         super().__init__()
-        jeditor_logger.info("Init BrowserWidget "
-                            f"start_url: {start_url} "
-                            f"search_prefix: {search_prefix}")
-        # Browser setting
-        self.browser = BrowserView(start_url)
-        self.search_prefix = search_prefix
+        self.main_widget = main_widget
+        if browser_view:
+            self.browser = browser_view
+        else:
+            self.browser = BrowserView(start_url, main_widget=main_widget)  # 內嵌的瀏覽器視圖
+        self.search_prefix = search_prefix  # 搜尋引擎前綴字串
         self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
-        # Top bar
+
+        # --- Top bar buttons / 上方工具列按鈕 ---
         self.back_button = QPushButton(language_wrapper.language_word_dict.get("browser_back_button"))
-        self.back_button.clicked.connect(self.browser.back)
+        self.back_button.clicked.connect(self.browser.back)  # 返回上一頁
+
         self.forward_button = QPushButton(language_wrapper.language_word_dict.get("browser_forward_button"))
-        self.forward_button.clicked.connect(self.browser.forward)
+        self.forward_button.clicked.connect(self.browser.forward)  # 前往下一頁
+
         self.reload_button = QPushButton(language_wrapper.language_word_dict.get("browser_reload_button"))
-        self.reload_button.clicked.connect(self.browser.reload)
+        self.reload_button.clicked.connect(self.browser.reload)  # 重新整理
+
         self.search_button = QPushButton(language_wrapper.language_word_dict.get("browser_search_button"))
-        self.search_button.clicked.connect(self.search)
+        self.search_button.clicked.connect(self.search)  # 搜尋按鈕
+
+        # URL / Search input line (custom QLineEdit)
         self.url_input = BrowserLineSearch(self)
-        # Action
+
+        # --- Action: Ctrl+F to find text / 快捷鍵 Ctrl+F 搜尋文字 ---
         self.find_action = QAction()
         self.find_action.setShortcut("Ctrl+f")
         self.find_action.triggered.connect(self.find_text)
         self.addAction(self.find_action)
-        # Layout
+
+        # --- Layout / 版面配置 ---
         self.grid_layout = QGridLayout()
         self.grid_layout.addWidget(self.back_button, 0, 0)
         self.grid_layout.addWidget(self.forward_button, 0, 1)
         self.grid_layout.addWidget(self.reload_button, 0, 2)
         self.grid_layout.addWidget(self.url_input, 0, 3)
         self.grid_layout.addWidget(self.search_button, 0, 4)
-        self.grid_layout.addWidget(self.browser, 1, 0, -1, -1)
+        self.grid_layout.addWidget(self.browser, 1, 0, -1, -1)  # 瀏覽器視圖佔滿下方
         self.setLayout(self.grid_layout)
 
     def search(self):
+        """
+        Perform a search using the text in the input line.
+        使用輸入框的文字進行搜尋，將字串附加到 search_prefix 後送出。
+        """
         jeditor_logger.info("BrowserWidget Search")
         self.browser.setUrl(f"{self.search_prefix}{self.url_input.text()}")
 
     def find_text(self):
+        """
+        Open a dialog to find text in the current page.
+        開啟輸入對話框，在當前頁面中搜尋文字。
+        - 如果按下 OK，搜尋輸入的文字
+        - 如果取消，清除搜尋
+        """
         jeditor_logger.info("BrowserWidget Find Text")
         search_box = QInputDialog(self)
         search_text, press_ok = search_box.getText(
-            self, language_wrapper.language_word_dict.get("browser_find_text"),
-            language_wrapper.language_word_dict.get("browser_find_text_input"))
+            self,
+            language_wrapper.language_word_dict.get("browser_find_text"),
+            language_wrapper.language_word_dict.get("browser_find_text_input")
+        )
         if press_ok:
             self.browser.findText(search_text)
         else:
-            self.browser.findText("")
+            self.browser.findText("")