From 8dd5e4244576c21228d92b62e9d1d948634bdbbf Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Tue, 28 Apr 2026 17:38:32 +0800 Subject: [PATCH 1/2] Slim docs landing page to a WebRunner-style intro Drop the README-mirroring Highlights / Architecture diagram / Installation / Quick start / Action-list shape sections from each language's index.rst. The landing page now keeps just the project title, language switcher, a short tagline, a paragraph describing what automation_file is, the documentation-organisation paragraph, a RoadMap link, and the chapter toctrees. The dropped material already lives in its own chapter (quickstart, cli, architecture). --- docs/source.zh-CN/index.rst | 160 +++------------------------------ docs/source.zh-TW/index.rst | 160 +++------------------------------ docs/source/index.rst | 174 ++++-------------------------------- 3 files changed, 43 insertions(+), 451 deletions(-) diff --git a/docs/source.zh-CN/index.rst b/docs/source.zh-CN/index.rst index e35751c..d7ad69d 100644 --- a/docs/source.zh-CN/index.rst +++ b/docs/source.zh-CN/index.rst @@ -3,159 +3,23 @@ automation_file 语言：`English <../html/index.html>`_ | `繁體中文 <../html-zh-TW/index.html>`_ | **简体中文** -以自动化为核心的模块化框架，涵盖本地文件 / 目录 / ZIP 操作、经 SSRF 校验的 -HTTP 下载、远程存储（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、 -WebDAV、SMB、fsspec），以及通过内建 TCP / HTTP 服务器执行的 JSON 动作。 -内置 PySide6 图形界面，把每一项功能以标签页形式呈现；所有公开功能统一从 -顶层 ``automation_file`` 外观模块重新导出。 +以 JSON 动作列表为核心的模块化文件自动化框架。 -功能亮点 --------- - -**核心原语** - -* JSON 动作列表由共享的 - :class:`~automation_file.core.action_executor.ActionExecutor` 执行，支持 - 校验、dry-run、并行、DAG。 -* 路径穿越防护（:func:`~automation_file.local.safe_paths.safe_join`）、 - 对外 URL 的 SSRF 校验、默认仅绑定 loopback 的 TCP / HTTP 服务器， - 可选共享密钥验证与每动作 ACL。 -* 可靠性辅助：``retry_on_transient`` 装饰器、``Quota`` 流量与时间预算、 - 流式 checksum、可续传 HTTP 下载。 - -**后端集成** - -* 本地文件 / 目录 / ZIP / tar 操作。 -* HTTP 下载：SSRF 防护、大小 / 超时上限、重试、续传、可选 SHA-256 校验。 -* 一等公民后端：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、 - WebDAV、SMB / CIFS、fsspec — 全部自动注册。 -* 跨后端复制，使用 URI 语法（``local://``、``s3://``、``drive://``、 - ``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。 - -**事件驱动** +``automation_file`` 把本地文件 / 目录 / ZIP 操作、经 SSRF 校验的 HTTP 下载、 +远端存储后端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 +FTP、WebDAV、SMB、fsspec）以及通过内建 TCP / HTTP / MCP 服务器执行的 JSON +动作列表统合为单一框架——全部通过共享的 ``ActionRegistry`` 调度，并由 +PySide6 桌面图形界面对外呈现。 -* 文件监听触发器 ``FA_watch_*`` — 路径变动时自动执行动作列表。 -* Cron 调度（``FA_schedule_*``）采用纯标准库的 5 字段解析器， - 提供重叠保护，失败时自动通知。 -* 传输进度与取消 Token，通过 ``progress_name`` 对外暴露。 +文档按语言与内容类型拆分。每个语言手册以章节组织：入门、CLI、架构、 +本地操作、HTTP 传输、云端与 SFTP 后端、动作服务器、MCP 服务器、图形界面、 +可靠性、触发器与调度、通知、配置、DAG、插件。API 参考则是自动生成的 +Python 参考资料。 -**可观测性与集成** - -* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams / - PagerDuty，每个 Sink 独立隔离错误，并采用滑动窗口去重。 -* Prometheus 指标导出器（``start_metrics_server``）、SQLite 审计日志、 - 文件完整性监视器。 -* HTMX 网页面板（``start_web_ui``）、MCP 服务器将注册表桥接到 - Claude Desktop / MCP CLI，走 JSON-RPC 2.0。 -* PySide6 桌面 GUI（``python -m automation_file ui``）。 - -**供应链** - -* 配置文件与机密信息 — 在 ``automation_file.toml`` 声明 sink 与默认值； - ``${env:…}`` / ``${file:…}`` 引用通过 Env / File / Chained provider - 解析，避免把密钥写死在文件中。 -* 入口点插件 — 第三方包通过 - ``[project.entry-points."automation_file.actions"]`` - 注册自己的 ``FA_*`` 动作。 - -架构鸟瞰 +未来规划 -------- -.. code-block:: text - - 用户 / CLI / JSON batch - │ - ▼ - ┌─────────────────────────────────────────┐ - │ automation_file（外观） │ - │ execute_action、driver_instance、 │ - │ start_autocontrol_socket_server、 │ - │ start_http_action_server、Quota … │ - └─────────────────────────────────────────┘ - │ - ▼ - ┌──────────────┐ ┌────────────────────┐ - │ core │────▶│ ActionRegistry │ - │ executor、 │ │ （FA_* 指令） │ - │ retry、 │ └────────────────────┘ - │ quota、 │ │ - │ progress │ ▼ - └──────────────┘ ┌────────────────────┐ - │ local / remote / │ - │ server / triggers /│ - │ scheduler / ui │ - └────────────────────┘ - -完整的模块树与设计模式见 :doc:`architecture`。 - -安装 ----- - -.. code-block:: bash - - pip install automation_file - -所有后端（S3、Azure Blob、Dropbox、SFTP、PySide6）都是一等运行期 -依赖，常见使用场景不需要额外的 extras。 - -快速开始 --------- - -用 CLI 执行 JSON 动作列表： - -.. code-block:: bash - - python -m automation_file --execute_file my_actions.json - -直接从 Python 调用： - -.. code-block:: python - - from automation_file import execute_action - - execute_action([ - ["FA_create_dir", {"dir_path": "build"}], - ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], - ["FA_zip_dir", {"source": "build", "target": "build.zip"}], - ]) - -执行前先校验动作列表，或并行执行： - -.. code-block:: python - - from automation_file import executor - - problems = executor.validate(actions) - if problems: - raise SystemExit("\n".join(problems)) - executor.execute_action_parallel(actions, max_workers=4) - -启动 PySide6 图形界面： - -.. code-block:: bash - - python -m automation_file ui - -以共享密钥在 loopback 提供 HTTP 动作服务器： - -.. code-block:: python - - from automation_file import start_http_action_server - - server = start_http_action_server(port=8765, shared_secret="s3kret") - -动作列表的格式 --------------- - -一个动作是三种 list 形式之一，按名称通过注册表调度： - -.. code-block:: python - - ["FA_create_dir"] # 无参数 - ["FA_create_dir", {"dir_path": "build"}] # 关键字参数 - ["FA_copy_file", ["src.txt", "dst.txt"]] # 位置参数 - -JSON 动作列表就是上述 list 的 list。 +项目跟踪：https://github.com/Integration-Automation/FileAutomation/issues .. toctree:: :maxdepth: 2 diff --git a/docs/source.zh-TW/index.rst b/docs/source.zh-TW/index.rst index 39b4a85..3bd27a9 100644 --- a/docs/source.zh-TW/index.rst +++ b/docs/source.zh-TW/index.rst @@ -3,159 +3,23 @@ automation_file 語言：`English <../html/index.html>`_ | **繁體中文** | `简体中文 <../html-zh-CN/index.html>`_ -以自動化為核心的模組化框架，涵蓋本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的 -HTTP 下載、遠端儲存（Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP、 -WebDAV、SMB、fsspec），以及透過內建 TCP / HTTP 伺服器執行的 JSON 動作。 -內建 PySide6 圖形介面，把每一項功能以分頁形式呈現；所有公開功能統一從 -頂層 ``automation_file`` 外觀模組重新匯出。 +以 JSON 動作清單為核心的模組化檔案自動化框架。 -功能亮點 --------- - -**核心原語** - -* JSON 動作清單由共用的 - :class:`~automation_file.core.action_executor.ActionExecutor` 執行，支援 - 驗證、dry-run、平行、DAG。 -* 路徑穿越防護（:func:`~automation_file.local.safe_paths.safe_join`）、 - 對外 URL 的 SSRF 驗證、預設僅綁定 loopback 的 TCP / HTTP 伺服器， - 可選共享金鑰驗證與每動作 ACL。 -* 可靠性輔助：``retry_on_transient`` 裝飾器、``Quota`` 流量與時間上限、 - 串流式 checksum、可續傳 HTTP 下載。 - -**後端整合** - -* 本地檔案 / 目錄 / ZIP / tar 操作。 -* HTTP 下載：SSRF 防護、大小 / 逾時上限、重試、續傳、可選 SHA-256 驗證。 -* 第一方整合：Google Drive、S3、Azure Blob、Dropbox、SFTP、FTP / FTPS、 - WebDAV、SMB / CIFS、fsspec — 全部自動註冊。 -* 跨後端複製，使用 URI 語法（``local://``、``s3://``、``drive://``、 - ``sftp://``、``azure://``、``dropbox://``、``ftp://`` …）。 - -**事件驅動** +``automation_file`` 把本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的 HTTP 下載、 +遠端儲存後端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 +FTP、WebDAV、SMB、fsspec）以及透過內建 TCP / HTTP / MCP 伺服器執行的 JSON +動作清單統合為單一框架——全部透過共用的 ``ActionRegistry`` 調度，並由 +PySide6 桌面圖形介面對外呈現。 -* 檔案監看觸發器 ``FA_watch_*`` — 路徑變動時自動執行動作清單。 -* Cron 排程（``FA_schedule_*``）採用純標準函式庫的 5 欄位解析器， - 提供重疊保護，失敗時自動通知。 -* 傳輸進度與取消 Token，透過 ``progress_name`` 對外暴露。 +文件依語言與內容類型拆分。每個語言手冊以章節組織：入門、CLI、架構、 +本地操作、HTTP 傳輸、雲端與 SFTP 後端、動作伺服器、MCP 伺服器、圖形介面、 +可靠性、觸發器與排程、通知、設定、DAG、外掛。API 參考則是自動生成的 +Python 參考資料。 -**可觀測性與整合** - -* 通知 Sink — webhook / Slack / SMTP / Telegram / Discord / Teams / - PagerDuty，各 Sink 獨立隔離錯誤並採用滑動視窗去重。 -* Prometheus 指標匯出器（``start_metrics_server``）、SQLite 稽核日誌、 - 檔案完整性監視器。 -* HTMX 網頁面板（``start_web_ui``）、MCP 伺服器將註冊表橋接到 - Claude Desktop / MCP CLI，走 JSON-RPC 2.0。 -* PySide6 桌面 GUI（``python -m automation_file ui``）。 - -**供應鏈** - -* 設定檔與機敏資訊 — 在 ``automation_file.toml`` 宣告 sink 與預設值； - ``${env:…}`` / ``${file:…}`` 參考透過 Env / File / Chained provider - 解析，避免把金鑰寫死在檔案裡。 -* 進入點外掛 — 第三方套件透過 - ``[project.entry-points."automation_file.actions"]`` - 自行註冊 ``FA_*`` 動作。 - -架構鳥瞰 +未來規劃 -------- -.. code-block:: text - - 使用者 / CLI / JSON batch - │ - ▼ - ┌─────────────────────────────────────────┐ - │ automation_file（外觀） │ - │ execute_action、driver_instance、 │ - │ start_autocontrol_socket_server、 │ - │ start_http_action_server、Quota … │ - └─────────────────────────────────────────┘ - │ - ▼ - ┌──────────────┐ ┌────────────────────┐ - │ core │────▶│ ActionRegistry │ - │ executor、 │ │ （FA_* 指令） │ - │ retry、 │ └────────────────────┘ - │ quota、 │ │ - │ progress │ ▼ - └──────────────┘ ┌────────────────────┐ - │ local / remote / │ - │ server / triggers /│ - │ scheduler / ui │ - └────────────────────┘ - -完整的模組樹與設計模式請見 :doc:`architecture`。 - -安裝 ----- - -.. code-block:: bash - - pip install automation_file - -所有後端（S3、Azure Blob、Dropbox、SFTP、PySide6）皆為第一方執行期 -依賴，常見使用情境不需要額外 extras。 - -快速開始 --------- - -用 CLI 執行 JSON 動作清單： - -.. code-block:: bash - - python -m automation_file --execute_file my_actions.json - -直接從 Python 呼叫： - -.. code-block:: python - - from automation_file import execute_action - - execute_action([ - ["FA_create_dir", {"dir_path": "build"}], - ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], - ["FA_zip_dir", {"source": "build", "target": "build.zip"}], - ]) - -執行前先驗證動作清單，或以平行方式執行： - -.. code-block:: python - - from automation_file import executor - - problems = executor.validate(actions) - if problems: - raise SystemExit("\n".join(problems)) - executor.execute_action_parallel(actions, max_workers=4) - -啟動 PySide6 圖形介面： - -.. code-block:: bash - - python -m automation_file ui - -以共享金鑰在 loopback 提供 HTTP 動作伺服器： - -.. code-block:: python - - from automation_file import start_http_action_server - - server = start_http_action_server(port=8765, shared_secret="s3kret") - -動作清單的格式 --------------- - -一個動作是三種 list 形式之一，依名稱透過註冊表調度： - -.. code-block:: python - - ["FA_create_dir"] # 無參數 - ["FA_create_dir", {"dir_path": "build"}] # 關鍵字參數 - ["FA_copy_file", ["src.txt", "dst.txt"]] # 位置參數 - -JSON 動作清單就是上述 list 的 list。 +專案追蹤：https://github.com/Integration-Automation/FileAutomation/issues .. toctree:: :maxdepth: 2 diff --git a/docs/source/index.rst b/docs/source/index.rst index 044a52b..32cf289 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,162 +3,26 @@ automation_file Languages: **English** | `繁體中文 <../html-zh-TW/index.html>`_ | `简体中文 <../html-zh-CN/index.html>`_ -A modular automation framework for local file / directory / ZIP operations, -SSRF-validated HTTP downloads, remote storage (Google Drive, S3, Azure Blob, -Dropbox, SFTP, FTP, WebDAV, SMB, fsspec), and JSON-driven action execution -over embedded TCP / HTTP servers. Ships with a PySide6 GUI that exposes every -feature through tabs. All public functionality is re-exported from the -top-level ``automation_file`` facade. - -Highlights ----------- - -**Core primitives** - -* JSON action lists executed by a shared - :class:`~automation_file.core.action_executor.ActionExecutor` — validate, - dry-run, parallel, DAG. -* Path traversal guard (:func:`~automation_file.local.safe_paths.safe_join`), - SSRF validator for outbound URLs, loopback-first TCP / HTTP servers with - optional shared-secret auth and per-action ACLs. -* Reliability helpers: ``retry_on_transient`` decorator, ``Quota`` size and - time budgets, streaming checksums, resumable HTTP downloads. - -**Backends** - -* Local file / directory / ZIP / tar operations. -* HTTP downloads with SSRF protection, size / timeout caps, retries, - resumable transfers, and optional SHA-256 verification. -* First-class Google Drive, S3, Azure Blob, Dropbox, SFTP, FTP / FTPS, - WebDAV, SMB / CIFS, and fsspec backends — all auto-registered. -* Cross-backend copy through URI syntax (``local://``, ``s3://``, - ``drive://``, ``sftp://``, ``azure://``, ``dropbox://``, ``ftp://``, …). - -**Event-driven execution** - -* File-watcher triggers via ``FA_watch_*`` — run action lists on path - changes. -* Cron scheduler (``FA_schedule_*``) on a stdlib-only 5-field parser, with - overlap guard and auto-notify on failure. -* Transfer progress + cancellation tokens exposed through ``progress_name``. - -**Observability + integrations** - -* Notification sinks — webhook / Slack / SMTP / Telegram / Discord / Teams / - PagerDuty with per-sink error isolation and sliding-window dedup. -* Prometheus metrics exporter (``start_metrics_server``), SQLite audit log, - file integrity monitor. -* HTMX web UI (``start_web_ui``), MCP server bridging the registry to Claude - Desktop / MCP CLIs over JSON-RPC 2.0. -* PySide6 desktop GUI (``python -m automation_file ui``). - -**Supply chain** - -* Config + secrets — declare sinks and defaults in ``automation_file.toml``; - ``${env:…}`` / ``${file:…}`` references resolve through Env / File / - Chained providers so secrets stay out of the file. -* Entry-point plugins — third-party packages register their own ``FA_*`` - actions via ``[project.entry-points."automation_file.actions"]``. - -Architecture at a glance ------------------------- - -.. code-block:: text - - User / CLI / JSON batch - │ - ▼ - ┌─────────────────────────────────────────┐ - │ automation_file (facade) │ - │ execute_action, driver_instance, │ - │ start_autocontrol_socket_server, │ - │ start_http_action_server, Quota, … │ - └─────────────────────────────────────────┘ - │ - ▼ - ┌──────────────┐ ┌────────────────────┐ - │ core │────▶│ ActionRegistry │ - │ executor, │ │ (FA_* commands) │ - │ retry, │ └────────────────────┘ - │ quota, │ │ - │ progress │ ▼ - └──────────────┘ ┌────────────────────┐ - │ local / remote / │ - │ server / triggers /│ - │ scheduler / ui │ - └────────────────────┘ - -See :doc:`architecture` for the full module tree and design patterns. - -Installation ------------- - -.. code-block:: bash - - pip install automation_file - -All backends (S3, Azure Blob, Dropbox, SFTP, PySide6) are first-class -runtime dependencies — no extras required for common use. - -Quick start ------------ - -Run a JSON action list from the CLI: - -.. code-block:: bash - - python -m automation_file --execute_file my_actions.json - -Drive the library from Python: - -.. code-block:: python - - from automation_file import execute_action - - execute_action([ - ["FA_create_dir", {"dir_path": "build"}], - ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], - ["FA_zip_dir", {"source": "build", "target": "build.zip"}], - ]) - -Validate a batch before running it, or run actions in parallel: - -.. code-block:: python - - from automation_file import executor - - problems = executor.validate(actions) - if problems: - raise SystemExit("\n".join(problems)) - executor.execute_action_parallel(actions, max_workers=4) - -Start the PySide6 GUI: - -.. code-block:: bash - - python -m automation_file ui - -Expose the registry over a loopback HTTP server with shared-secret auth: - -.. code-block:: python - - from automation_file import start_http_action_server - - server = start_http_action_server(port=8765, shared_secret="s3kret") - -Action-list shape ------------------ - -An action is a list of one of three shapes, dispatched by name through the -registry: - -.. code-block:: python - - ["FA_create_dir"] # no-args - ["FA_create_dir", {"dir_path": "build"}] # keyword args - ["FA_copy_file", ["src.txt", "dst.txt"]] # positional args +A modular, JSON-driven file-automation framework for Python. + +``automation_file`` packages local file / directory / ZIP operations, +SSRF-validated HTTP downloads, remote storage backends (Google Drive, S3, +Azure Blob, Dropbox, OneDrive, Box, SFTP, FTP, WebDAV, SMB, fsspec), and +JSON-driven action execution over embedded TCP / HTTP / MCP servers — all +dispatched through a shared ``ActionRegistry`` and exposed through a +PySide6 desktop GUI. + +The documentation is split by language and by content type. Each language +manual is organised into chapters — Getting Started, CLI, Architecture, +Local Operations, HTTP Transfers, Cloud and SFTP Backends, Action Servers, +MCP Server, GUI, Reliability, Triggers and Scheduler, Notifications, +Configuration, DAG, and Plugins. The API Reference book holds the +auto-generated Python reference. + +RoadMap +------- -A JSON action list is simply a list of these lists. +Project tracker: https://github.com/Integration-Automation/FileAutomation/issues .. toctree:: :maxdepth: 2 From 5014eb8586d37714d5d3e854daf96e548c81304f Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Tue, 28 Apr 2026 17:41:04 +0800 Subject: [PATCH 2/2] Add Python 3.13 and 3.14 to CI matrix Extend the pytest matrix in both ci-dev.yml and ci-stable.yml from 3.10/3.11/3.12 to also cover 3.13 and 3.14. --- .github/workflows/ci-dev.yml | 2 +- .github/workflows/ci-stable.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci-dev.yml b/.github/workflows/ci-dev.yml index dcf43d3..2ec3e14 100644 --- a/.github/workflows/ci-dev.yml +++ b/.github/workflows/ci-dev.yml @@ -37,7 +37,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: [ "3.10", "3.11", "3.12" ] + python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ] steps: - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} diff --git a/.github/workflows/ci-stable.yml b/.github/workflows/ci-stable.yml index d6911e7..5c8543d 100644 --- a/.github/workflows/ci-stable.yml +++ b/.github/workflows/ci-stable.yml @@ -37,7 +37,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: [ "3.10", "3.11", "3.12" ] + python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ] steps: - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }}