Merge pull request #41 from Integration-Automation/dev

Dev

Author: JE-Chen

.github/workflows/file_automation_dev_python3_12.yml

@@ -1,4 +1,4 @@
-name: FileAutomation Dev Python3.9
+name: FileAutomation Dev Python3.12
 
 on:
   push:

.github/workflows/file_automation_stable_python3_12.yml

@@ -1,4 +1,4 @@
-name: FileAutomation Stable Python3.9
+name: FileAutomation Stable Python3.12
 
 on:
   push:

README.md

@@ -1,31 +1,90 @@
-### FileAutomation
+# FileAutomation
 
-### Documentation
+This project provides a modular framework for file automation and Google Drive integration. 
+It supports local file and directory operations, ZIP archive handling, 
+Google Drive CRUD (create, search, upload, download, delete, share), 
+and remote execution through a TCP Socket Server.
 
-* TODO
+# Features
+## Local File and Directory Operations
+- Create, delete, copy, and rename files
+- Create, delete, and copy directories
+- Recursively search for files by extension
 
----
-> Project Kanban \
-> https://github.com/orgs/Integration-Automation/projects/2/views/1
-> * FileAutomation is used to manager files and dirs.
-> * Easily file automation.
-> * Automatically backup.
-> * Automatically download from Google Drive.
-> * Automatically upload to Google Drive.
-> * Automatically zip and unzip file.
-> * Automatically manager specify file.
-> * OS Independent.
-> * Remote automation support.
-> * Project & Template support.
-> * Detailed log file.
-> * Scheduler.
+## ZIP Archive Handling
+- Create ZIP archives
+- Extract single files or entire archives
+- Set ZIP archive passwords
+- Read archive information
+
+## Google Drive Integration
+- Upload: single files, entire directories, to root or specific folders
+- Download: single files or entire folders
+- Search: by name, MIME type, or custom fields
+- Delete: remove files from Drive
+- Share: with specific users, domains, or via public link
+- Folder Management: create new folders in Drive
+
+## Automation Executors
+- Executor: central manager for all executable functions, supports action lists
+- CallbackExecutor: supports callback functions for flexible workflows
+- PackageManager: dynamically loads packages and registers functions into executors
+
+# JSON Configuration
+- Read and write JSON-based action lists
+- Define automation workflows in JSON format
+
+# TCP Socket Server
+- Start a TCP server to receive JSON commands and execute corresponding actions
+- Supports remote control and returns execution results
+
+## Installation and Requirements
+
+- Requirements
+  - Python 3.9+
+  - Google API Client
+  - Google Drive API enabled and credentials.json downloaded
 
 
 ## install
 > pip install automation_file
 
-## Requires
-> python 3.9 or later
+# Usage
+
+1. Initialize Google Drive
+```python
+from automation_file.remote.google_drive.driver_instance import driver_instance
+
+driver_instance.later_init("token.json", "credentials.json") 
+```
+
+2. Upload a File
+```python
+from automation_file.remote.google_drive.upload.upload_to_driver import drive_upload_to_drive
+
+drive_upload_to_drive("example.txt") 
+```
+
+3. Search Files
+```python
+from automation_file.remote.google_drive.search.search_drive import drive_search_all_file
+
+files = drive_search_all_file()
+print(files)
+```
+
+4. Start TCP Server
+```python
+from automation_file.utils.socket_server.file_automation_socket_server import start_autocontrol_socket_server
+
+server = start_autocontrol_socket_server("localhost", 9943)
+```
 
-### Architecture Diagram
-![architecture_diagram](architecture_diagram/FileAutomation.drawio.png)
+# Example JSON Action
+```json
+[
+  ["FA_create_file", {"file_path": "test.txt"}],
+  ["FA_drive_upload_to_drive", {"file_path": "test.txt"}],
+  ["FA_drive_search_all_file"]
+]
+```

automation_file/local/dir/dir_process.py

@@ -1,78 +1,113 @@
 import shutil
 from pathlib import Path
 
+# 匯入自訂例外與日誌工具
+# Import custom exception and logging utility
 from automation_file.utils.exception.exceptions import DirNotExistsException
 from automation_file.utils.logging.loggin_instance import file_automation_logger
 
 
 def copy_dir(dir_path: str, target_dir_path: str) -> bool:
     """
-    Copy dir to target path (path need as dir path)
-    :param dir_path: which dir do we want to copy (str path)
-    :param target_dir_path: copy dir to this path
-    :return: True if success else False
+    複製資料夾到目標路徑
+    Copy directory to target path
+    :param dir_path: 要複製的資料夾路徑 (str)
+                     Directory path to copy (str)
+    :param target_dir_path: 複製到的目標資料夾路徑 (str)
+                            Target directory path (str)
+    :return: 成功回傳 True，失敗回傳 False
+             Return True if success, else False
     """
-    dir_path = Path(dir_path)
+    dir_path = Path(dir_path)  # 轉換為 Path 物件 / Convert to Path object
     target_dir_path = Path(target_dir_path)
-    if dir_path.is_dir():
+    if dir_path.is_dir():  # 確認來源是否為資料夾 / Check if source is a directory
         try:
+            # 複製整個資料夾，若目標已存在則允許覆蓋
+            # Copy entire directory, allow overwrite if target exists
             shutil.copytree(dir_path, target_dir_path, dirs_exist_ok=True)
             file_automation_logger.info(f"Copy dir {dir_path}")
             return True
         except shutil.Error as error:
+            # 複製失敗時記錄錯誤
+            # Log error if copy fails
             file_automation_logger.error(f"Copy dir {dir_path} failed: {repr(error)}")
     else:
+        # 若來源資料夾不存在，記錄錯誤
+        # Log error if source directory does not exist
         file_automation_logger.error(f"Copy dir {dir_path} failed: {repr(DirNotExistsException)}")
         return False
+    return False
 
 
 def remove_dir_tree(dir_path: str) -> bool:
     """
-    :param dir_path: which dir do we want to remove (str path)
-    :return: True if success else False
+    刪除整個資料夾樹
+    Remove entire directory tree
+    :param dir_path: 要刪除的資料夾路徑 (str)
+                     Directory path to remove (str)
+    :return: 成功回傳 True，失敗回傳 False
+             Return True if success, else False
     """
     dir_path = Path(dir_path)
-    if dir_path.is_dir():
+    if dir_path.is_dir():  # 確認是否為資料夾 / Check if directory exists
         try:
-            shutil.rmtree(dir_path)
+            shutil.rmtree(dir_path)  # 遞迴刪除資料夾 / Recursively delete directory
             file_automation_logger.info(f"Remove dir tree {dir_path}")
             return True
         except shutil.Error as error:
             file_automation_logger.error(f"Remove dir tree {dir_path} error: {repr(error)}")
             return False
+    return False
 
 
 def rename_dir(origin_dir_path, target_dir: str) -> bool:
     """
-    :param origin_dir_path: which dir do we want to rename (str path)
-    :param target_dir: target name as str full path
-    :return: True if success else False
+    重新命名資料夾
+    Rename directory
+    :param origin_dir_path: 原始資料夾路徑 (str)
+                            Original directory path (str)
+    :param target_dir: 新的完整路徑 (str)
+                       Target directory path (str)
+    :return: 成功回傳 True，失敗回傳 False
+             Return True if success, else False
     """
     origin_dir_path = Path(origin_dir_path)
     if origin_dir_path.exists() and origin_dir_path.is_dir():
         try:
+            # 使用 Path.rename 重新命名資料夾
+            # Rename directory using Path.rename
             Path.rename(origin_dir_path, target_dir)
             file_automation_logger.info(
                 f"Rename dir origin dir path: {origin_dir_path}, target dir path: {target_dir}")
             return True
         except Exception as error:
+            # 捕捉所有例外並記錄
+            # Catch all exceptions and log
             file_automation_logger.error(
                 f"Rename dir error:  {repr(error)}, "
                 f"Rename dir origin dir path: {origin_dir_path}, "
                 f"target dir path: {target_dir}")
     else:
+        # 若來源資料夾不存在，記錄錯誤
+        # Log error if source directory does not exist
         file_automation_logger.error(
             f"Rename dir error:  {repr(DirNotExistsException)}, "
             f"Rename dir origin dir path: {origin_dir_path}, "
             f"target dir path: {target_dir}")
         return False
+    return False
 
 
 def create_dir(dir_path: str) -> None:
     """
-    :param dir_path: create dir on dir_path
+    建立資料夾
+    Create directory
+    :param dir_path: 要建立的資料夾路徑 (str)
+                     Directory path to create (str)
     :return: None
     """
     dir_path = Path(dir_path)
+    # 若資料夾已存在則不會報錯
+    # Create directory, no error if already exists
     dir_path.mkdir(exist_ok=True)
-    file_automation_logger.info(f"Create dir {dir_path}")
+    file_automation_logger.info(f"Create dir {dir_path}")