je-editor 0.0.104__py3-none-any.whl → 0.0.228__py3-none-any.whl

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/exception/exception_tags.py

@@ -5,32 +5,32 @@ je_editor_error: str = "JEditor error"
 """
 init exception
 """
-je_editor_init_error: str = "JEditor can't init"
-je_editor_init_exec_manager_exception: str = "JEditor can't init program manager"
+je_editor_init_error: str = "JEditor failed to initialize"
+je_editor_init_exec_manager_exception: str = "JEditor failed to initialize the program manager"
 """
 exec exception
 """
-je_editor_exec_error: str = "JEditor exec error"
+je_editor_exec_error: str = "JEditor execution error"
 file_not_fond_error: str = "File not found"
 compiler_not_found_error: str = "Compiler not found"
 """
 shell exception
 """
-je_editor_shell_error: str = "JEditor run on shell error"
+je_editor_shell_error: str = "JEditor shell execution error"
 """
 file exception
 """
-je_editor_save_file_error: str = "JEditor save file error"
-je_editor_open_file_error: str = "JEditor open file error"
+je_editor_save_file_error: str = "JEditor failed to save file"
+je_editor_open_file_error: str = "JEditor failed to open file"
 """
 json exception
 """
-cant_reformat_json_error: str = "Can't reformat json is type right?"
-wrong_json_data_error: str = "Can't parser json"
-cant_find_json_error: str = "cant find json file"
-cant_save_json_error: str = "cant save json file"
+cant_reformat_json_error: str = "Cannot reformat JSON: is the type correct?"
+wrong_json_data_error: str = "Failed to parse JSON"
+cant_find_json_error: str = "Can't find JSON file"
+cant_save_json_error: str = "Can't save JSON file"
 """
 content data error
 """
-content_set_compiler_error: str = "When set compiler using content make an error"
+content_set_compiler_error: str = "Error setting compiler using content"
 je_editor_content_file_error: str = "JEditor content file error"

je_editor/utils/file/open/open_file.py

@@ -1,35 +1,51 @@
 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):
+def read_file(file_path: str) -> list[Path | str] | None:
     """
-    use to check file is exist and open
-    :param file: 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.
     """
-    lock = Lock()
+
+    # 記錄日誌，方便除錯與追蹤
+    # Log the file path for debugging and tracking
+    jeditor_logger.info(f"open_file.py read_file file_path: {file_path}")
+
+    lock = Lock()  # 建立一個執行緒鎖 / Create a thread lock
     try:
-        lock.acquire()
-        if file != "" and file is not None:
-            file_path = Path(file)
-            if file_path.exists() and file_path.is_file():
-                with open(file, "r+") as open_read_file:
-                    return [file, open_read_file.read()]
+        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 and content
     except JEditorOpenFileException:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorOpenFileException
     finally:
+        # 確保鎖一定會被釋放
+        # Ensure the lock is always released
         lock.release()
-
-
-

je_editor/utils/file/save/save_file.py

@@ -1,28 +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, content):
+def write_file(file_path: str, content: str) -> None:
     """
-    :param file: 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.
     """
-    lock = Lock()
-    content = str(content)
+
+    # 記錄日誌，方便除錯與追蹤
+    # 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()  # 建立一個執行緒鎖 / Create a thread lock
+    content = str(content)  # 確保內容為字串 / Ensure content is a string
+
     try:
-        lock.acquire()
-        if file != "" and file is not None:
-            with open(file, "w+") as file_to_write:
-                file_to_write.write(content)
+        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)  # 寫入內容 / Write content
     except JEditorSaveFileException:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorSaveFileException
     finally:
+        # 確保鎖一定會被釋放
+        # Ensure the lock is always released
         lock.release()
-

je_editor/utils/json/json_file.py

@@ -1,42 +1,63 @@
 import json
 from pathlib import Path
 from threading import Lock
+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) -> list:
+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
     """
-    _lock.acquire()
+    jeditor_logger.info(f"json_file.py read_json json_file_path: {json_file_path}")
+    _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, user_setting_dict: dict) -> None:
+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 user_setting_dict dict include user setting
+    功能說明 (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)
     """
-    _lock.acquire()
+    jeditor_logger.info("json_file.py write_json "
+                        f"json_save_path: {json_save_path} "
+                        f"data_to_output: {data_to_output}")
+    _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(user_setting_dict, indent=4))
+            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,26 +3,62 @@ 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
+from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
-def __process_json(json_string: str, **kwargs):
+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):
+def reformat_json(json_string: str, **kwargs) -> str:
+    """
+    功能說明 (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:
+        # 捕捉自訂例外並重新拋出
+        # Catch custom exception and re-raise
         raise JEditorJsonException(cant_reformat_json_error)

je_editor/utils/logging/loggin_instance.py

@@ -0,0 +1,57 @@
+import logging
+from logging.handlers import RotatingFileHandler
+
+# 設定 root logger 的最低層級為 DEBUG
+# Set the root logger level to DEBUG
+logging.root.setLevel(logging.DEBUG)
+
+# 建立一個名為 "JEditor" 的 logger
+# Create a logger named "JEditor"
+jeditor_logger = logging.getLogger("JEditor")
+
+# 設定 JEditor logger 的層級為 WARNING (只會輸出 WARNING 以上的訊息)
+# Set the JEditor logger level to WARNING (only WARNING and above will be logged)
+jeditor_logger.setLevel(logging.WARNING)
+
+# 定義日誌格式：時間 | logger 名稱 | 等級 | 訊息
+# Define log format: time | logger name | level | message
+formatter = logging.Formatter('%(asctime)s | %(name)s | %(levelname)s | %(message)s')
+
+
+class JEditorLoggingHandler(RotatingFileHandler):
+    """
+    自訂的 Logging Handler，繼承自 RotatingFileHandler
+    Custom Logging Handler, inherits from RotatingFileHandler
+
+    功能：
+    - 將日誌輸出到檔案 (支援檔案大小輪替)
+    - 預設檔名為 JEditor.log
+    """
+
+    # redirect logging stderr output to queue (註解說明，但目前未實作)
+    # 註解提到要將 stderr 輸出導向 queue，但目前程式碼僅繼承 RotatingFileHandler
+
+    def __init__(self, filename: str = "JEditor.log", mode="w",
+                 maxBytes: int = 1073741824, backupCount: int = 0):
+        """
+        :param filename: 日誌檔案名稱 / log file name
+        :param mode: 檔案開啟模式 (預設 w 覆寫) / file open mode (default "w" overwrite)
+        :param maxBytes: 單一檔案最大大小 (預設 1GB) / max file size (default 1GB)
+        :param backupCount: 保留的備份檔案數量 / number of backup files to keep
+        """
+        super().__init__(filename=filename, mode=mode, maxBytes=maxBytes, backupCount=backupCount)
+        self.formatter = formatter  # 設定日誌格式 / set log formatter
+        self.setLevel(logging.DEBUG)  # 設定 handler 層級為 DEBUG / set handler level to DEBUG
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        實際輸出日誌的方法，這裡直接呼叫父類別的 emit
+        Method to emit log records, here just call parent emit
+        """
+        super().emit(record)
+
+
+# 建立檔案處理器並加入到 JEditor logger
+# Create file handler and add it to JEditor logger
+file_handler = JEditorLoggingHandler()
+jeditor_logger.addHandler(file_handler)