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

je_editor/pyside_ui/main_ui/system_tray/extend_system_tray.py

@@ -1,11 +1,15 @@
 from __future__ import annotations
+# 啟用未來註解功能，允許型別提示使用字串前向參照
+# Enable future annotations, allowing forward references in type hints
 
 from typing import TYPE_CHECKING
-
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 if TYPE_CHECKING:
     from je_editor.pyside_ui.main_ui.main_editor import EditorMain
+    # 僅在型別檢查時匯入 EditorMain，避免循環依賴
+    # Import EditorMain only for type checking
+
 import sys
 
 from PySide6.QtGui import QAction
@@ -14,38 +18,71 @@ from je_editor.utils.multi_language.multi_language_wrapper import language_wrapp
 
 
 class ExtendSystemTray(QSystemTrayIcon):
+    """
+    擴充系統匣功能，提供隱藏、最大化、還原、關閉等操作
+    Extend system tray functionality with hide, maximize, restore, and close actions
+    """
 
     def __init__(self, main_window: EditorMain):
+        # 初始化並記錄日誌
+        # Initialize and log
         jeditor_logger.info(f"Init ExtendSystemTray main_window: {main_window}")
         super().__init__(parent=main_window)
+
+        # 建立右鍵選單
+        # Create context menu
         self.menu = QMenu()
         self.main_window = main_window
+
+        # === 隱藏主視窗 / Hide main window ===
         self.hide_main_window_action = QAction(
             language_wrapper.language_word_dict.get("system_tray_hide"))
         self.hide_main_window_action.triggered.connect(self.main_window.hide)
         self.menu.addAction(self.hide_main_window_action)
+
+        # === 最大化主視窗 / Maximize main window ===
         self.maximized_main_window_action = QAction(
             language_wrapper.language_word_dict.get("system_tray_maximized"))
         self.maximized_main_window_action.triggered.connect(self.main_window.showMaximized)
         self.menu.addAction(self.maximized_main_window_action)
+
+        # === 還原主視窗 / Restore main window ===
         self.normal_main_window_action = QAction(
             language_wrapper.language_word_dict.get("system_tray_normal"))
         self.normal_main_window_action.triggered.connect(self.main_window.showNormal)
         self.menu.addAction(self.normal_main_window_action)
+
+        # === 關閉應用程式 / Close application ===
         self.close_main_window_action = QAction(
             language_wrapper.language_word_dict.get("system_tray_close"))
         self.close_main_window_action.triggered.connect(self.close_all)
         self.menu.addAction(self.close_main_window_action)
+
+        # 設定選單到系統匣圖示
+        # Attach menu to system tray icon
         self.setContextMenu(self.menu)
+
+        # 綁定點擊事件 (例如雙擊)
+        # Connect click events (e.g., double-click)
         self.activated.connect(self.clicked)
 
     def close_all(self):
+        """
+        關閉應用程式：隱藏圖示、關閉主視窗並結束程式
+        Close the application: hide tray icon, close main window, and exit program
+        """
         jeditor_logger.info("ExtendSystemTray close_all")
         self.setVisible(False)
         self.main_window.close()
         sys.exit(0)
 
     def clicked(self, reason):
+        """
+        處理系統匣點擊事件
+        Handle system tray click events
+        """
         if reason == self.ActivationReason.DoubleClick:
+            # 如果是雙擊，最大化主視窗
+            # If double-click, maximize the main window
             jeditor_logger.info("ExtendSystemTray DoubleClick")
-            self.main_window.showMaximized()
+            self.main_window.showMaximized()

je_editor/start_editor.py

@@ -8,10 +8,35 @@ from je_editor.pyside_ui.main_ui.main_editor import EditorMain
 
 
 def start_editor(debug_mode: bool = False) -> None:
+    """
+    功能說明 (Function Description):
+    啟動編輯器主程式，建立 QApplication 實例，套用主題，並顯示主視窗。
+    Start the main editor application, create QApplication instance, apply theme, and show main window.
+
+    :param debug_mode: 是否啟用除錯模式 / whether to enable debug mode
+    """
+
+    # 嘗試取得現有的 QCoreApplication 實例
+    # Try to get an existing QCoreApplication instance
     new_editor = QCoreApplication.instance()
+
+    # 如果沒有現有實例，建立新的 QApplication
+    # If no instance exists, create a new QApplication
     if new_editor is None:
         new_editor = QApplication(sys.argv)
+
+    # 建立主視窗，傳入 debug_mode
+    # Create the main editor window, passing debug_mode
     window = EditorMain(debug_mode)
+
+    # 套用 qt-material 主題 (dark amber)
+    # Apply qt-material theme (dark amber)
     apply_stylesheet(new_editor, theme='dark_amber.xml')
+
+    # 最大化顯示主視窗
+    # Show the main window maximized
     window.showMaximized()
-    sys.exit(new_editor.exec())
+
+    # 啟動事件迴圈，並在結束時退出程式
+    # Start the event loop and exit the program when it ends
+    sys.exit(new_editor.exec())

je_editor/utils/encodings/python_encodings.py

@@ -1,99 +1,102 @@
+# 定義一個 Python 支援的文字編碼清單
+# Define a list of text encodings supported by Python
+
 python_encodings_list = [
-    'ascii',
-    'big5',
-    'big5hkscs',
-    'cp037',
-    'cp273',
-    'cp424',
-    'cp437',
-    'cp500',
-    'cp720',
-    'cp737',
-    'cp775',
-    'cp850',
-    'cp852',
-    'cp855',
-    'cp856',
-    'cp857',
-    'cp858',
-    'cp860',
-    'cp861',
-    'cp862',
-    'cp863',
-    'cp864',
-    'cp865',
-    'cp866',
-    'cp869',
-    'cp874',
-    'cp875',
-    'cp932',
-    'cp949',
-    'cp950',
-    'cp1006',
-    'cp1026',
-    'cp1125',
-    'cp1140',
-    'cp1250',
-    'cp1251',
-    'cp1252',
-    'cp1253',
-    'cp1254',
-    'cp1255',
-    'cp1256',
-    'cp1257',
-    'cp1258',
-    'euc_jp',
-    'euc_jis_2004',
-    'euc_jisx0213',
-    'euc_kr',
-    'gb2312',
-    'gbk',
-    'gb18030',
-    'hz',
-    'iso2022_jp',
-    'iso2022_jp_1',
-    'iso2022_jp_2',
-    'iso2022_jp_2004',
-    'iso2022_jp_3',
-    'iso2022_jp_ext',
-    'iso2022_kr',
-    'latin_1',
-    'iso8859_2',
-    'iso8859_3',
-    'iso8859_4',
-    'iso8859_5',
-    'iso8859_6',
-    'iso8859_7',
-    'iso8859_8',
-    'iso8859_9',
-    'iso8859_10',
-    'iso8859_11',
-    'iso8859_13',
-    'iso8859_14',
-    'iso8859_15',
-    'iso8859_16',
-    'johab',
-    'koi8_r',
-    'koi8_t',
-    'koi8_u',
-    'kz1048',
-    'mac_cyrillic',
-    'mac_greek',
-    'mac_iceland',
-    'mac_latin2',
-    'mac_roman',
-    'mac_turkish',
-    'ptcp154',
-    'shift_jis',
-    'shift_jis_2004',
-    'shift_jisx0213',
-    'utf_32',
-    'utf_32_be',
-    'utf_32_le',
-    'utf_16',
-    'utf_16_be',
-    'utf_16_le',
-    'utf_7',
-    'utf_8',
-    'utf_8_sig'
-]
+    'ascii',        # ASCII 編碼 (基本的英文字符集, 7-bit) / Basic English character set
+    'big5',         # Big5 編碼 (繁體中文常用, 台灣/香港) / Traditional Chinese encoding (Taiwan/HK)
+    'big5hkscs',    # Big5-HKSCS (香港增補字集) / Big5 with Hong Kong Supplementary Character Set
+    'cp037',        # IBM EBCDIC US/Canada / IBM mainframe encoding
+    'cp273',        # IBM EBCDIC Germany / 德國 EBCDIC 編碼
+    'cp424',        # IBM EBCDIC Hebrew / 希伯來文編碼
+    'cp437',        # 原始 IBM PC 編碼 (DOS Latin US) / Original IBM PC encoding
+    'cp500',        # IBM EBCDIC International / 國際版 EBCDIC
+    'cp720',        # 阿拉伯文 (DOS) / Arabic (DOS)
+    'cp737',        # 希臘文 (DOS) / Greek (DOS)
+    'cp775',        # 波羅的海語系 (DOS) / Baltic languages (DOS)
+    'cp850',        # 西歐語系 (DOS) / Western Europe (DOS)
+    'cp852',        # 中歐語系 (DOS) / Central Europe (DOS)
+    'cp855',        # 西里爾字母 (DOS) / Cyrillic (DOS)
+    'cp856',        # 希伯來文 (DOS) / Hebrew (DOS)
+    'cp857',        # 土耳其文 (DOS) / Turkish (DOS)
+    'cp858',        # 西歐語系 (含歐元符號) / Western Europe with Euro sign
+    'cp860',        # 葡萄牙文 (DOS) / Portuguese (DOS)
+    'cp861',        # 冰島文 (DOS) / Icelandic (DOS)
+    'cp862',        # 希伯來文 (DOS) / Hebrew (DOS)
+    'cp863',        # 加拿大法文 (DOS) / Canadian French (DOS)
+    'cp864',        # 阿拉伯文 (DOS) / Arabic (DOS)
+    'cp865',        # 北歐語系 (DOS) / Nordic languages (DOS)
+    'cp866',        # 俄文 (DOS) / Russian (DOS)
+    'cp869',        # 希臘文 (DOS) / Greek (DOS)
+    'cp874',        # 泰文 (Windows) / Thai (Windows)
+    'cp875',        # IBM EBCDIC Greek / 希臘文 EBCDIC
+    'cp932',        # 日文 Shift_JIS (Windows) / Japanese Shift_JIS (Windows)
+    'cp949',        # 韓文 (Windows) / Korean (Windows)
+    'cp950',        # 繁體中文 Big5 (Windows) / Traditional Chinese Big5 (Windows)
+    'cp1006',       # 烏爾都文 (Urdu) / Urdu
+    'cp1026',       # IBM EBCDIC Turkish / 土耳其文 EBCDIC
+    'cp1125',       # 烏克蘭文 (DOS) / Ukrainian (DOS)
+    'cp1140',       # EBCDIC with Euro / EBCDIC 含歐元符號
+    'cp1250',       # 中歐語系 (Windows) / Central Europe (Windows)
+    'cp1251',       # 西里爾字母 (Windows) / Cyrillic (Windows)
+    'cp1252',       # 西歐語系 (Windows, 常見) / Western Europe (Windows, very common)
+    'cp1253',       # 希臘文 (Windows) / Greek (Windows)
+    'cp1254',       # 土耳其文 (Windows) / Turkish (Windows)
+    'cp1255',       # 希伯來文 (Windows) / Hebrew (Windows)
+    'cp1256',       # 阿拉伯文 (Windows) / Arabic (Windows)
+    'cp1257',       # 波羅的海語系 (Windows) / Baltic (Windows)
+    'cp1258',       # 越南文 (Windows) / Vietnamese (Windows)
+    'euc_jp',       # 日文 EUC 編碼 / Japanese EUC encoding
+    'euc_jis_2004', # 日文 EUC (JIS 2004) / Japanese EUC (JIS 2004)
+    'euc_jisx0213', # 日文 EUC (JIS X 0213) / Japanese EUC (JIS X 0213)
+    'euc_kr',       # 韓文 EUC 編碼 / Korean EUC encoding
+    'gb2312',       # 簡體中文 (舊標準) / Simplified Chinese (older standard)
+    'gbk',          # 簡體中文 (擴展) / Simplified Chinese (extended)
+    'gb18030',      # 簡體中文 (最新國標) / Simplified Chinese (latest national standard)
+    'hz',           # HZ-GB-2312 (簡體中文, 郵件常用) / Simplified Chinese (email encoding)
+    'iso2022_jp',   # 日文 ISO-2022-JP / Japanese ISO-2022-JP
+    'iso2022_jp_1', # 日文 ISO-2022-JP-1 / Japanese ISO-2022-JP-1
+    'iso2022_jp_2', # 日文 ISO-2022-JP-2 / Japanese ISO-2022-JP-2
+    'iso2022_jp_2004', # 日文 ISO-2022-JP-2004 / Japanese ISO-2022-JP-2004
+    'iso2022_jp_3', # 日文 ISO-2022-JP-3 / Japanese ISO-2022-JP-3
+    'iso2022_jp_ext', # 日文 ISO-2022-JP-EXT / Japanese ISO-2022-JP-EXT
+    'iso2022_kr',   # 韓文 ISO-2022-KR / Korean ISO-2022-KR
+    'latin_1',      # ISO-8859-1 (西歐語系, 常見) / Western Europe (very common)
+    'iso8859_2',    # 中歐語系 / Central Europe
+    'iso8859_3',    # 南歐語系 / South Europe
+    'iso8859_4',    # 北歐語系 / North Europe
+    'iso8859_5',    # 西里爾字母 / Cyrillic
+    'iso8859_6',    # 阿拉伯文 / Arabic
+    'iso8859_7',    # 希臘文 / Greek
+    'iso8859_8',    # 希伯來文 / Hebrew
+    'iso8859_9',    # 土耳其文 / Turkish
+    'iso8859_10',   # 北歐語系 / Nordic
+    'iso8859_11',   # 泰文 / Thai
+    'iso8859_13',   # 波羅的海語系 / Baltic
+    'iso8859_14',   # 凱爾特語 / Celtic
+    'iso8859_15',   # 西歐語系 (含歐元) / Western Europe with Euro
+    'iso8859_16',   # 東歐語系 / Eastern Europe
+    'johab',        # 韓文 Johab 編碼 / Korean Johab encoding
+    'koi8_r',       # 俄文 KOI8-R / Russian KOI8-R
+    'koi8_t',       # 塔吉克文 KOI8-T / Tajik KOI8-T
+    'koi8_u',       # 烏克蘭文 KOI8-U / Ukrainian KOI8-U
+    'kz1048',       # 哈薩克文 / Kazakh
+    'mac_cyrillic', # Mac OS 西里爾字母 / Mac Cyrillic
+    'mac_greek',    # Mac OS 希臘文 / Mac Greek
+    'mac_iceland',  # Mac OS 冰島文 / Mac Icelandic
+    'mac_latin2',   # Mac OS 中歐語系 / Mac Central Europe
+    'mac_roman',    # Mac OS 西歐語系 / Mac Roman
+    'mac_turkish',  # Mac OS 土耳其文 / Mac Turkish
+    'ptcp154',      # 中亞語系 (西里爾字母) / Central Asian Cyrillic
+    'shift_jis',  # 日文 Shift JIS 編碼 (常見於 Windows 與網頁) / Japanese Shift JIS encoding (commonly used in Windows & web)
+    'shift_jis_2004',  # 日文 Shift JIS (JIS 2004 標準) / Japanese Shift JIS (JIS 2004 standard)
+    'shift_jisx0213',  # 日文 Shift JIS (JIS X 0213 擴展) / Japanese Shift JIS (JIS X 0213 extension)
+    'utf_32',  # UTF-32 (依平台大小端序, 4 bytes per char) / UTF-32 (platform-dependent endianness, 4 bytes per char)
+    'utf_32_be',  # UTF-32 Big Endian / UTF-32 大端序
+    'utf_32_le',  # UTF-32 Little Endian / UTF-32 小端序
+    'utf_16',  # UTF-16 (依平台大小端序, 2 or 4 bytes per char) / UTF-16 (platform-dependent endianness)
+    'utf_16_be',  # UTF-16 Big Endian / UTF-16 大端序
+    'utf_16_le',  # UTF-16 Little Endian / UTF-16 小端序
+    'utf_7',  # UTF-7 (為電子郵件設計, 已過時) / UTF-7 (designed for email, obsolete)
+    'utf_8',  # UTF-8 (最常用, 網頁與跨平台標準) / UTF-8 (most common, web & cross-platform standard)
+    'utf_8_sig'  # UTF-8 with BOM (Byte Order Mark) / UTF-8 含 BOM 標記
+]

je_editor/utils/file/open/open_file.py

@@ -2,34 +2,51 @@ import typing
 from pathlib import Path
 from threading import Lock
 
+# 匯入自訂例外與日誌工具
+# Import custom exception and logging utility
 from je_editor.utils.exception.exceptions import JEditorOpenFileException
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
-def read_file(file_path: str) -> typing.List[typing.Union[str, str]]:
+def read_file(file_path: str) -> list[Path | str] | None:
     """
-    use to check file is exist and open
-    :param file_path: the file we want to read its whole file path
-    :return: read's file and file content
-    try
-        lock thread
-        find file is exist ? and is file ?
-        if both is true
-            try to open it and read
-            return file and content
-    finally
-        release lock
+    功能說明 (Function Description):
+    用來檢查檔案是否存在並嘗試開啟，讀取其內容。
+    Used to check if a file exists and open it to read its content.
+
+    :param file_path: 檔案完整路徑 / the full path of the file to read
+    :return: [檔案路徑, 檔案內容] / [file path, file content]
+
+    流程 (Logic):
+    1. 嘗試鎖定執行緒 (避免多執行緒同時存取)
+       Try to lock the thread (prevent concurrent access).
+    2. 檢查檔案路徑是否為空，並確認檔案存在且為檔案。
+       Check if file path is not empty, exists, and is a file.
+    3. 若條件成立，嘗試以 UTF-8 編碼開啟檔案並讀取內容。
+       If true, open the file with UTF-8 encoding and read content.
+    4. 最後釋放鎖。
+       Finally, release the lock.
     """
+
+    # 記錄日誌，方便除錯與追蹤
+    # Log the file path for debugging and tracking
     jeditor_logger.info(f"open_file.py read_file file_path: {file_path}")
-    lock = Lock()
+
+    lock = Lock()  # 建立一個執行緒鎖 / Create a thread lock
     try:
-        lock.acquire()
-        if file_path != "" and file_path is not None:
-            file_path = Path(file_path)
-            if file_path.exists() and file_path.is_file():
+        lock.acquire()  # 嘗試鎖定資源 / Acquire the lock
+        if file_path != "" and file_path is not None:  # 確認路徑不為空 / Ensure path is not empty
+            file_path = Path(file_path)  # 轉換為 Path 物件 / Convert to Path object
+            if file_path.exists() and file_path.is_file():  # 檢查檔案存在且為檔案 / Check file existence
+                # 以讀寫模式開啟檔案 (UTF-8 編碼)
+                # Open file in read+write mode with UTF-8 encoding
                 with open(file_path, "r+", encoding="utf-8") as open_read_file:
-                    return [file_path, open_read_file.read()]
+                    return [file_path, open_read_file.read()]  # 回傳檔案路徑與內容 / Return file path and content
     except JEditorOpenFileException:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorOpenFileException
     finally:
-        lock.release()
+        # 確保鎖一定會被釋放
+        # Ensure the lock is always released
+        lock.release()

je_editor/utils/file/save/save_file.py

@@ -1,31 +1,52 @@
 from threading import Lock
 
+# 匯入自訂例外與日誌工具
+# Import custom exception and logging utility
 from je_editor.utils.exception.exceptions import JEditorSaveFileException
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 def write_file(file_path: str, content: str) -> None:
     """
-    :param file_path: file we want to write
-    :param content: content write in file
-    try
-        lock thread
-        if file not empty string
-            write content to file
-    finally
-        release lock
+    功能說明 (Function Description):
+    將指定內容寫入檔案，並確保在多執行緒環境下安全操作。
+    Write the given content into a file, ensuring thread safety.
+
+    :param file_path: 要寫入的檔案路徑 / the file path to write
+    :param content: 要寫入的內容 / the content to write
+
+    流程 (Logic):
+    1. 嘗試鎖定執行緒 (避免多執行緒同時存取檔案)
+       Try to lock the thread (prevent concurrent file access).
+    2. 檢查檔案路徑是否為空字串或 None。
+       Check if file path is not empty or None.
+    3. 若條件成立，開啟檔案並以 UTF-8 編碼寫入內容。
+       If valid, open the file and write content with UTF-8 encoding.
+    4. 最後釋放鎖。
+       Finally, release the lock.
     """
+
+    # 記錄日誌，方便除錯與追蹤
+    # Log the file path and content for debugging and tracking
     jeditor_logger.info("save_file.py write_file "
                         f"file_path: {file_path} "
                         f"content: {content}")
-    lock = Lock()
-    content = str(content)
+
+    lock = Lock()          # 建立一個執行緒鎖 / Create a thread lock
+    content = str(content) # 確保內容為字串 / Ensure content is a string
+
     try:
-        lock.acquire()
-        if file_path != "" and file_path is not None:
+        lock.acquire()  # 嘗試鎖定資源 / Acquire the lock
+        if file_path != "" and file_path is not None:  # 確認路徑有效 / Ensure path is valid
+            # 以寫入模式開啟檔案 (UTF-8 編碼)
+            # Open file in write+read mode with UTF-8 encoding
             with open(file_path, "w+", encoding="utf-8") as file_to_write:
-                file_to_write.write(content)
+                file_to_write.write(content)  # 寫入內容 / Write content
     except JEditorSaveFileException:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorSaveFileException
     finally:
-        lock.release()
+        # 確保鎖一定會被釋放
+        # Ensure the lock is always released
+        lock.release()

je_editor/utils/json/json_file.py

@@ -1,48 +1,63 @@
 import json
 from pathlib import Path
 from threading import Lock
-from typing import Union
+from typing import Union, Any
 
+# 匯入自訂錯誤訊息與例外類別
+# Import custom error messages and exception class
 from je_editor.utils.exception.exception_tags import cant_find_json_error
 from je_editor.utils.exception.exception_tags import cant_save_json_error
 from je_editor.utils.exception.exceptions import JEditorJsonException
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
+# 全域鎖，確保多執行緒存取 JSON 檔案時的安全性
+# Global lock to ensure thread safety when accessing JSON files
 _lock = Lock()
 
 
-def read_json(json_file_path: str) -> Union[list, dict]:
+def read_json(json_file_path: str) -> Any | None:
     """
-    use to read action file
-    :param json_file_path json file's path to read
+    功能說明 (Function Description):
+    讀取 JSON 檔案並回傳其內容。
+    Read a JSON file and return its content.
+
+    :param json_file_path: JSON 檔案路徑 / path to the JSON file
+    :return: list 或 dict，取決於 JSON 結構 / list or dict depending on JSON structure
     """
     jeditor_logger.info(f"json_file.py read_json json_file_path: {json_file_path}")
-    _lock.acquire()
+    _lock.acquire()  # 嘗試鎖定資源 / Acquire the lock
     try:
         file_path = Path(json_file_path)
-        if file_path.exists() and file_path.is_file():
-            with open(json_file_path) as read_file:
-                return json.loads(read_file.read())
+        if file_path.exists() and file_path.is_file():  # 確認檔案存在且為檔案 / Ensure file exists
+            with open(json_file_path) as read_file:     # 開啟檔案 (預設 UTF-8)
+                return json.loads(read_file.read())     # 載入 JSON 並回傳 / Load JSON and return
     except JEditorJsonException:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorJsonException(cant_find_json_error)
     finally:
-        _lock.release()
+        _lock.release()  # 確保鎖一定會被釋放 / Ensure the lock is always released
 
 
 def write_json(json_save_path: str, data_to_output: Union[list, dict]) -> None:
     """
-    use to save action file
-    :param json_save_path  json save path
-    :param data_to_output data to output
+    功能說明 (Function Description):
+    將資料寫入 JSON 檔案。
+    Write data into a JSON file.
+
+    :param json_save_path: JSON 檔案儲存路徑 / path to save the JSON file
+    :param data_to_output: 要輸出的資料 (list 或 dict) / data to output (list or dict)
     """
     jeditor_logger.info("json_file.py write_json "
                         f"json_save_path: {json_save_path} "
                         f"data_to_output: {data_to_output}")
-    _lock.acquire()
+    _lock.acquire()  # 嘗試鎖定資源 / Acquire the lock
     try:
+        # 以寫入模式開啟檔案，並將資料轉換為 JSON 格式 (縮排 4 格)
+        # Open file in write mode and dump data as JSON (indent=4)
         with open(json_save_path, "w+") as file_to_write:
             file_to_write.write(json.dumps(data_to_output, indent=4))
     except JEditorJsonException:
         raise JEditorJsonException(cant_save_json_error)
     finally:
-        _lock.release()
+        _lock.release()  # 確保鎖一定會被釋放 / Ensure the lock is always released

je_editor/utils/json_format/json_process.py

@@ -3,6 +3,8 @@ import sys
 from json import dumps
 from json import loads
 
+# 匯入自訂錯誤訊息與例外類別
+# Import custom error messages and exception class
 from je_editor.utils.exception.exception_tags import cant_reformat_json_error
 from je_editor.utils.exception.exception_tags import wrong_json_data_error
 from je_editor.utils.exception.exceptions import JEditorJsonException
@@ -10,24 +12,53 @@ from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 def __process_json(json_string: str, **kwargs) -> str:
+    """
+    功能說明 (Function Description):
+    嘗試將輸入的 JSON 字串重新格式化 (pretty print)。
+    Try to reformat the input JSON string (pretty print).
+
+    :param json_string: JSON 格式字串 / JSON formatted string
+    :param kwargs: 額外參數傳給 json.dumps / extra arguments for json.dumps
+    :return: 格式化後的 JSON 字串 / formatted JSON string
+    """
     try:
+        # 嘗試先將字串解析為 JSON，再重新輸出為縮排格式
+        # Try to parse string into JSON, then dump with indentation
         return dumps(loads(json_string), indent=4, sort_keys=True, **kwargs)
     except json.JSONDecodeError as error:
+        # 如果 JSON 格式錯誤，輸出錯誤訊息到 stderr 並拋出例外
+        # If JSON format is invalid, print error to stderr and raise exception
         print(wrong_json_data_error, file=sys.stderr)
         raise error
     except TypeError:
+        # 如果輸入不是合法 JSON 字串，嘗試直接將物件轉為 JSON
+        # If input is not a valid JSON string, try dumping the object directly
         try:
             return dumps(json_string, indent=4, sort_keys=True, **kwargs)
         except TypeError:
+            # 若仍失敗，拋出自訂例外
+            # If still fails, raise custom exception
             raise JEditorJsonException(wrong_json_data_error)
 
 
 def reformat_json(json_string: str, **kwargs) -> str:
-    # Make json pretty
+    """
+    功能說明 (Function Description):
+    對外提供的 JSON 格式化函式，會呼叫內部的 __process_json。
+    Public function to reformat JSON string, calls __process_json internally.
+
+    :param json_string: JSON 格式字串 / JSON formatted string
+    :param kwargs: 額外參數傳給 json.dumps / extra arguments for json.dumps
+    :return: 格式化後的 JSON 字串 / formatted JSON string
+    """
+    # 記錄日誌，方便除錯與追蹤
+    # Log the input string and kwargs for debugging and tracking
     jeditor_logger.info(f"json_process.py reformat_json "
                         f"json_string: {json_string} "
                         f"kwargs: {kwargs}")
     try:
         return __process_json(json_string, **kwargs)
     except JEditorJsonException:
-        raise JEditorJsonException(cant_reformat_json_error)
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
+        raise JEditorJsonException(cant_reformat_json_error)