je-editor 0.0.221__py3-none-any.whl → 0.0.223__py3-none-any.whl

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/code_scan/ruff_thread.py

@@ -5,27 +5,54 @@ 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)
+            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:
-                print(line.strip())
-            for line in self.ruff_process.stderr:
-                print(line.strip())
-
-
+                self.std_queue.put(line.strip())
 
+            for line in self.ruff_process.stderr:
+                self.stderr_queue.put(line.strip())

je_editor/code_scan/watchdog_implement.py

@@ -1,4 +1,6 @@
+import time
 from queue import Queue
+from typing import Dict
 
 from watchdog.events import FileSystemEventHandler
 
@@ -6,29 +8,49 @@ from je_editor.code_scan.ruff_thread import RuffThread
 
 
 class RuffPythonFileChangeHandler(FileSystemEventHandler):
-
-    def __init__(self, ruff_commands: list = None):
-        super(RuffPythonFileChangeHandler, self).__init__()
-        self.ruff_commands = ruff_commands
-        self.stdout_queue = Queue()
-        self.stderr_queue = Queue()
-        self.ruff_threads_dict = dict()
+    """
+    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 event.src_path.endswith(".py"):
-            if self.ruff_threads_dict.get(event.src_path) is None:
-                ruff_thread = RuffThread(self.ruff_commands, self.stdout_queue, self.stderr_queue)
-                self.ruff_threads_dict.update({event.src_path: ruff_thread})
-                ruff_thread.start()
-            else:
-                ruff_thread = self.ruff_threads_dict.get(event.src_path)
-                if not ruff_thread.is_alive():
-                    ruff_thread = RuffThread(self.ruff_commands, self.stdout_queue, self.stderr_queue)
-                    self.ruff_threads_dict.update({event.src_path: ruff_thread})
-                    ruff_thread.start()
-                else:
-                    pass
 
+        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/code_scan/watchdog_thread.py

@@ -1,5 +1,7 @@
 import threading
 import time
+import sys
+from pathlib import Path
 
 from watchdog.observers import Observer
 
@@ -7,27 +9,70 @@ 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):
-        super().__init__()
-        self.check_path = check_path
+        """
+        :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):
-        observer = Observer()
-        observer.schedule(self.ruff_handler, str(self.check_path), recursive=True)
-        observer.start()
+        """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:
-            observer.stop()
+            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__':
-    watchdog_thread = WatchdogThread("")
+    # 預設監控當前目錄
+    path_to_watch = "."
+    watchdog_thread = WatchdogThread(path_to_watch)
     watchdog_thread.start()
-    while True:
-        time.sleep(1)
 
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("[Main] Stopping watchdog...")
+        watchdog_thread.stop()
+        watchdog_thread.join()

je_editor/git_client/commit_graph.py

@@ -1,6 +1,6 @@
 import logging
 from dataclasses import dataclass, field
-from typing import List, Dict
+from typing import List, Dict, Any
 
 log = logging.getLogger(__name__)
 
@@ -14,13 +14,17 @@ class CommitNode:
     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], refs: Dict[str, str]) -> None:
-        # commits are topo-ordered by git_client log --topo-order; we keep it.
+    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"],
@@ -28,61 +32,46 @@ class CommitGraph:
                 commit_date=c["date"],
                 commit_message=c["message"],
                 parent_shas=c["parents"],
-            ) for c in commits
+            )
+            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:
         """
-        Simple lane assignment similar to 'git_client log --graph' lanes.
-        Greedy: reuse freed lanes; parents may create new lanes.
+        Assign lanes to commits, similar to `git log --graph`.
+        分配 lanes，模擬 `git log --graph` 的效果。
         """
         active: Dict[int, str] = {}  # lane -> sha
         free_lanes: List[int] = []
 
-        for i, node in enumerate(self.nodes):
-            # If any active lane points to this commit, use that lane
-            lane_found = None
-            for lane, sha in list(active.items()):
-                if sha == node.commit_sha:
-                    lane_found = lane
-                    break
+        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 None:
-                if free_lanes:
-                    node.lane_index = free_lanes.pop(0)
-                else:
-                    node.lane_index = 0 if not active else max(active.keys()) + 1
-            else:
+            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
 
-            # Update active: current node consumes its lane, parents occupy lanes
-            # Remove the current sha from any lane that pointed to it
-            for lane, sha in list(active.items()):
-                if sha == node.commit_sha:
-                    del active[lane]
+            # Step 2: 更新 active
+            # 移除舊的 sha
+            active = {lane: sha for lane, sha in active.items() if sha != node.commit_sha}
 
-            # First parent continues in the same lane; others go to free/new lanes
+            # 父節點分配 lane
             if node.parent_shas:
-                first = node.parent_shas[0]
-                active[node.lane_index] = first
-                # Side branches
+                first_parent = node.parent_shas[0]
+                active[node.lane_index] = first_parent
                 for p in node.parent_shas[1:]:
-                    # Pick a free lane or new one
-                    if free_lanes:
-                        pl = free_lanes.pop(0)
-                    else:
-                        pl = 0 if not active else max(active.keys()) + 1
+                    pl = free_lanes.pop(0) if free_lanes else (max(active.keys()) + 1)
                     active[pl] = p
 
-            # Any lane whose target no longer appears in the future will be freed later
-            # We approximate by freeing lanes when a target didn't appear in the next rows;
-            # but for minimal viable, free when lane not reassigned by parents this row.
-            used_lanes = set(active.keys())
-            # Collect gaps below max lane as free lanes to reuse
-            max_lane = max(used_lanes) if used_lanes else -1
-            present = set(range(max_lane + 1))
-            missing = sorted(list(present - used_lanes))
-            # Merge missing into free_lanes maintaining order
-            free_lanes = sorted(set(free_lanes + missing))
+            # 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/git_client/{git.py → 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/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/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/pyside_ui/browser/browser_serach_lineedit.py

@@ -8,20 +8,44 @@ 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()
-        super().keyPressEvent(event)
+
+        # 呼叫父類別的 keyPressEvent，確保其他按鍵行為正常
+        super().keyPressEvent(event)

je_editor/pyside_ui/browser/browser_view.py

@@ -1,4 +1,11 @@
-from typing import List
+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
@@ -8,28 +15,74 @@ 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/"):
-        super().__init__()
+    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)