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

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)

je_editor/utils/logging/loggin_instance.py

@@ -1,27 +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
 
-    # redirect logging stderr output to queue
+    功能：
+    - 將日誌輸出到檔案 (支援檔案大小輪替)
+    - 預設檔名為 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):
+                 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
-        self.setLevel(logging.DEBUG)
+        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)
 
 
-# File handler
+# 建立檔案處理器並加入到 JEditor logger
+# Create file handler and add it to JEditor logger
 file_handler = JEditorLoggingHandler()
-jeditor_logger.addHandler(file_handler)
-
-
+jeditor_logger.addHandler(file_handler)

je_editor/utils/multi_language/multi_language_wrapper.py

@@ -4,26 +4,51 @@ from je_editor.utils.multi_language.traditional_chinese import traditional_chine
 
 
 class LanguageWrapper(object):
+    """
+    功能說明 (Function Description):
+    - 提供一個語言包裝器，用來管理目前使用的語言與對應的字典。
+    - A language wrapper to manage the current language and its corresponding dictionary.
+    """
 
-    def __init__(
-            self
-    ):
+    def __init__(self):
+        # 初始化時記錄日誌
+        # Log initialization
         jeditor_logger.info("Init LanguageWrapper")
+
+        # 預設語言為 English
+        # Default language is English
         self.language: str = "English"
+
+        # 可選語言字典對照表
+        # Mapping of available languages to their word dictionaries
         self.choose_language_dict = {
             "English": english_word_dict,
             "Traditional_Chinese": traditional_chinese_word_dict
         }
+
+        # 根據目前語言選擇對應字典
+        # Select the dictionary based on current language
         self.language_word_dict: dict = self.choose_language_dict.get(self.language)
 
     def reset_language(self, language) -> None:
+        """
+        重設語言 (Reset the language)
+        :param language: "English" 或 "Traditional_Chinese"
+        """
         jeditor_logger.info(f"LanguageWrapper reset_language language: {language}")
+
+        # 檢查輸入是否為支援的語言
+        # Check if the input language is supported
         if language in [
             "English",
             "Traditional_Chinese"
         ]:
+            # 更新語言與對應字典
+            # Update language and corresponding dictionary
             self.language = language
             self.language_word_dict = self.choose_language_dict.get(self.language)
 
 
-language_wrapper = LanguageWrapper()
+# 建立一個全域的 LanguageWrapper 實例
+# Create a global instance of LanguageWrapper
+language_wrapper = LanguageWrapper()

je_editor/utils/redirect_manager/redirect_manager_class.py

@@ -6,54 +6,90 @@ from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 class RedirectStdOut(logging.Handler):
-
-    # redirect logging std output to queue
+    """
+    功能說明 (Function Description):
+    - 將標準輸出 (stdout) 重導向到 queue
+    - Redirect standard output (stdout) to a queue
+    """
 
     def __init__(self):
         super().__init__()
 
     def write(self, content_to_write) -> None:
+        # 將輸出內容放入 RedirectManager 的 stdout queue
+        # Put output content into RedirectManager's stdout queue
         redirect_manager_instance.std_out_queue.put(content_to_write)
 
     def emit(self, record: logging.LogRecord) -> None:
+        # 將 logging 訊息格式化後放入 stdout queue
+        # Put formatted logging record into stdout queue
         redirect_manager_instance.std_out_queue.put(self.format(record))
 
 
 class RedirectStdErr(logging.Handler):
-
-    # redirect logging stderr output to queue
+    """
+    功能說明 (Function Description):
+    - 將標準錯誤輸出 (stderr) 重導向到 queue
+    - Redirect standard error (stderr) to a queue
+    """
 
     def __init__(self):
         super().__init__()
 
     def write(self, content_to_write) -> None:
+        # 將錯誤輸出內容放入 RedirectManager 的 stderr queue
+        # Put error output content into RedirectManager's stderr queue
         redirect_manager_instance.std_err_queue.put(content_to_write)
 
     def emit(self, record: logging.LogRecord) -> None:
+        # 將 logging 訊息格式化後放入 stderr queue
+        # Put formatted logging record into stderr queue
         redirect_manager_instance.std_err_queue.put(self.format(record))
 
 
 class RedirectManager(object):
-    # Redirect all output to queue
+    """
+    功能說明 (Function Description):
+    - 管理 stdout 與 stderr 的重導向
+    - 提供 set_redirect 與 restore_std 方法
+    - Manage redirection of stdout and stderr
+    - Provides set_redirect and restore_std methods
+    """
+
     def __init__(self):
         jeditor_logger.info("Init RedirectManager")
+        # 建立 stdout 與 stderr 的 queue
+        # Create queues for stdout and stderr
         self.std_err_queue = queue.Queue()
         self.std_out_queue = queue.Queue()
 
     @staticmethod
     def set_redirect() -> None:
         """
-        :return: None
+        啟用重導向
+        Redirect stdout and stderr to queues
         """
         jeditor_logger.info("RedirectManager set_redirect")
         redirect_out = RedirectStdOut()
         redirect_err = RedirectStdErr()
+
+        # 將 sys.stdout / sys.stderr 指向自訂 handler
+        # Redirect sys.stdout / sys.stderr to custom handlers
         sys.stdout = redirect_out
         sys.stderr = redirect_err
+
+        # 建立一個 logger 並綁定 stderr handler
+        # Create a logger and bind stderr handler
         default_logger = logging.getLogger("JEditor_RedirectManager")
         default_logger.addHandler(redirect_err)
-        skip_logger_list = ["JEditor", "FrontEngine",
-                            "AutomationIDE", "TestPioneer", "langchain", "langchain_core", "langchain_openai"]
+
+        # 過濾掉不需要重導向的 logger
+        # Skip specific loggers from being redirected
+        skip_logger_list = [
+            "JEditor", "FrontEngine",
+            "AutomationIDE", "TestPioneer",
+            "langchain", "langchain_core", "langchain_openai"
+        ]
         for name in logging.root.manager.loggerDict.keys():
             if name in skip_logger_list:
                 continue
@@ -63,12 +99,14 @@ class RedirectManager(object):
     @staticmethod
     def restore_std() -> None:
         """
-        reset redirect
-        :return: None
+        重設 stdout 與 stderr
+        Restore stdout and stderr to default
         """
         jeditor_logger.info("RedirectManager restore_std")
         sys.stdout = sys.__stdout__
         sys.stderr = sys.__stderr__
 
 
-redirect_manager_instance = RedirectManager()
+# 建立全域 RedirectManager 實例
+# Create a global instance of RedirectManager
+redirect_manager_instance = RedirectManager()

je_editor/utils/venv_check/check_venv.py

@@ -1,28 +1,58 @@
 import shutil
 from pathlib import Path
 
+# 匯入自訂錯誤訊息與例外類別
+# Import custom error messages and exception class
+from je_editor.utils.exception.exception_tags import compiler_not_found_error
+from je_editor.utils.exception.exceptions import JEditorExecException
+from je_editor.utils.logging.loggin_instance import jeditor_logger
+
+
+import shutil
+from pathlib import Path
+
+# 匯入自訂錯誤訊息與例外類別
+# Import custom error messages and exception class
 from je_editor.utils.exception.exception_tags import compiler_not_found_error
 from je_editor.utils.exception.exceptions import JEditorExecException
 from je_editor.utils.logging.loggin_instance import jeditor_logger
 
 
 def check_and_choose_venv(venv_path: Path) -> str:
+    """
+    功能說明 (Function Description):
+    檢查虛擬環境 (venv) 路徑，並嘗試尋找可用的 Python 編譯器。
+    Check the virtual environment (venv) path and try to find a usable Python interpreter.
+
+    :param venv_path: 虛擬環境的路徑 / path to the virtual environment
+    :return: Python 編譯器的完整路徑 / full path to the Python interpreter
+    :raise JEditorExecException: 若找不到 Python 編譯器 / if no Python interpreter is found
+    """
+
     jeditor_logger.info(f"check_venv.py check_and_choose_venv venv_path: {venv_path}")
-    compiler_path = None
+
+    # 如果 venv_path 是資料夾且存在
+    # If venv_path is a directory and exists
     if venv_path.is_dir() and venv_path.exists():
-        compiler_path = shutil.which(
-            cmd="python3",
-            path=str(venv_path)
-        )
-    if compiler_path is None:
-        compiler_path = shutil.which(
-            cmd="python",
-            path=str(venv_path)
-        )
-    else:
-        compiler_path = shutil.which(cmd="python")
-    if compiler_path is None:
-        compiler_path = shutil.which(cmd="python")
+        # 先嘗試在該路徑下尋找 python3
+        # Try to find python3 in the given path
+        compiler_path = shutil.which("python3", path=str(venv_path))
+        if compiler_path:
+            return compiler_path
+
+        # 如果找不到 python3，再找 python
+        # If python3 not found, try python
+        compiler_path = shutil.which("python", path=str(venv_path))
+        if compiler_path:
+            return compiler_path
+
+    # 如果 venv_path 無效或都找不到，最後再嘗試系統預設的 python3 或 python
+    # If venv_path is invalid or no interpreter found, try system default python3 or python
+    compiler_path = shutil.which("python3") or shutil.which("python")
+
+    # 如果還是找不到，拋出例外
+    # If still not found, raise exception
     if compiler_path is None:
         raise JEditorExecException(compiler_not_found_error)
-    return compiler_path
+
+    return compiler_path

{je_editor-0.0.222.dist-info → je_editor-0.0.224.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: je_editor
-Version: 0.0.222
+Version: 0.0.224
 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