diff --git a/docs/source.zh-CN/index.rst b/docs/source.zh-CN/index.rst index d7ad69d..2933ab6 100644 --- a/docs/source.zh-CN/index.rst +++ b/docs/source.zh-CN/index.rst @@ -1,66 +1,215 @@ +############### automation_file -=============== +############### + +**以 JSON 动作列表为核心的模块化文件自动化框架。** + +``automation_file`` 把本地文件 / 目录 / ZIP / tar 操作、经 SSRF 校验且 +可续传的 HTTP 下载、十一种远端存储后端（Google Drive、S3、Azure Blob、 +Dropbox、OneDrive、Box、SFTP、FTP / FTPS、WebDAV、SMB、fsspec）、 +通过内建 TCP / HTTP / MCP 服务器执行的 JSON 动作列表、cron 调度器、 +文件监控触发器、通知扇出、审计日志、AES-256-GCM 文件加密、Prometheus +指标，以及 PySide6 桌面图形界面，全部统合为单一框架——一切通过共享的 +``ActionRegistry`` 调度，并由单一 ``automation_file`` 门面对外呈现。 + +* **PyPI**：https://pypi.org/project/automation_file/ +* **GitHub**：https://github.com/Integration-Automation/FileAutomation +* **Issue / 未来规划**：https://github.com/Integration-Automation/FileAutomation/issues +* **许可**：MIT 语言：`English <../html/index.html>`_ | `繁體中文 <../html-zh-TW/index.html>`_ | **简体中文** -以 JSON 动作列表为核心的模块化文件自动化框架。 +.. contents:: 本页目录 + :local: + :depth: 1 + +---- + +安装 +==== + +.. code-block:: bash + + pip install automation_file + +每个后端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 +FTP、WebDAV、SMB、fsspec）以及 PySide6 图形界面均为一级运行时依赖 +包——无需记住任何可选 extra。 + +第一份动作 +========== + +一个动作是三种 JSON 形态之一——``[name]``、``[name, {kwargs}]`` 或 +``[name, [args]]``。动作列表是动作的数组。共享的执行器会按序运行， +并返回每条动作的结果映射。 + +.. code-block:: python + + from automation_file import execute_action + + results = execute_action([ + ["FA_create_dir", {"dir_path": "build"}], + ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], + ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}], + ]) + +同一份列表可从 CLI（``python -m automation_file run actions.json``）、 +Loopback TCP / HTTP 服务器、MCP 主机，以及图形界面的 **JSON 动作** 分页 +直接执行——无需改写。可参考 :doc:`usage/quickstart` 了解校验、Dry-run +与并行执行；:doc:`usage/cli` 介绍 argparse 派发器；:doc:`architecture` +说明注册器与执行器如何协作。 + +---- + +提供哪些功能 +============ + +**本地操作**\ （:doc:`usage/local`） + 文件 / 目录 / ZIP / tar / 压缩档操作、``safe_join`` 路径穿越防护、 + 感知 OS 索引的 ``fast_find``、流式 ``file_checksum`` 与 + ``find_duplicates``、``sync_dir`` rsync 风格镜像、目录差异比对、 + 文本 patch、JSON / YAML / CSV / JSONL / Parquet 编辑、MIME 检测、 + 模板渲染、回收站发送 / 还原、文件版本控制、条件式执行 + （``FA_if_exists`` / ``FA_if_newer`` / ``FA_if_size_gt``）、变量替换 + （``${env:…}`` / ``${date:%Y-%m-%d}`` / ``${uuid}``）、带超时的 shell + 子进程，以及 AES-256-GCM 文件加密。 + +**HTTP 传输**\ （:doc:`usage/transfer`） + ``download_file`` 通过 ``validate_http_url`` 校验每个 URL（拒绝 + ``file://`` / ``ftp://`` / 私有 / loopback / link-local / 保留地址）， + 设下大小与超时上限，支持通过 ``Range:`` 续传到 ``.part``， + 传输后比对 ``expected_sha256``，并可整合进度注册器，提供实时传输 + 快照与协作式取消。 + +**云端与远端存储**\ （:doc:`usage/cloud`） + Google Drive（OAuth2）、S3（boto3）、Azure Blob、Dropbox、OneDrive、 + Box、SFTP（paramiko + ``RejectPolicy``）、FTP / FTPS、WebDAV、SMB / + CIFS 与 fsspec 桥接——皆由 ``build_default_registry()`` 自动注册， + 并通过各自的共享单例访问。``copy_between`` 可按 URI 前缀在任意两个 + 后端间搬运数据。 + +**动作服务器**\ （:doc:`usage/servers`） + 默认仅绑定 loopback 的 TCP 与 HTTP 服务器，接受 JSON 动作列表，可 + 选择启用共享密钥认证、服务端 ``ActionACL`` 白名单、 + ``GET /healthz`` / ``GET /readyz`` 健康检查、``GET /openapi.json``、 + ``GET /progress`` WebSocket，以及带类型的 ``HTTPActionClient`` SDK。 + +**MCP 服务器**\ （:doc:`usage/mcp`） + ``MCPServer`` 通过 stdio 上的换行分隔 JSON-RPC 2.0，把注册器桥接到 + 任意 Model Context Protocol 主机（Claude Desktop、Claude Code、MCP + CLI）。每个 ``FA_*`` 动作会变成带自动生成输入 schema 的 MCP 工具。 + +**桌面图形界面**\ （:doc:`usage/gui`） + PySide6 分页控制界面——Home、Local、Transfer、Progress、JSON 动作、 + Triggers、Scheduler、Servers，加上每个云端后端各一个分页——共享 + 相同的单例，并通过 ``ActionWorker`` 在全局线程池上派工。 -``automation_file`` 把本地文件 / 目录 / ZIP 操作、经 SSRF 校验的 HTTP 下载、 -远端存储后端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 -FTP、WebDAV、SMB、fsspec）以及通过内建 TCP / HTTP / MCP 服务器执行的 JSON -动作列表统合为单一框架——全部通过共享的 ``ActionRegistry`` 调度，并由 -PySide6 桌面图形界面对外呈现。 +**可靠性**\ （:doc:`usage/reliability`） + ``retry_on_transient`` 带上限的指数退避、``Quota`` 大小与时间预算、 + ``CircuitBreaker``、``RateLimiter``、``FileLock`` / ``SQLiteLock``、 + 持久化的 ``ActionQueue``、SQLite ``AuditLog``、用于周期清单比对的 + ``IntegrityMonitor``，以及带类型的 ``FileAutomationException`` 层级。 -文档按语言与内容类型拆分。每个语言手册以章节组织：入门、CLI、架构、 -本地操作、HTTP 传输、云端与 SFTP 后端、动作服务器、MCP 服务器、图形界面、 -可靠性、触发器与调度、通知、配置、DAG、插件。API 参考则是自动生成的 -Python 参考资料。 +**触发器与调度**\ （:doc:`usage/events`） + 文件监控触发器（``FA_watch_*``）会在文件系统事件发生时运行动作列表； + cron 风格调度器（``FA_schedule_*``）按调度周期性运行动作列表，并具 + 重叠保护——两者均会在失败时回退到通知。 -未来规划 --------- +**通知**\ （:doc:`usage/notifications`） + Slack、Email（SMTP）、Discord、Telegram、Microsoft Teams、PagerDuty + 与通用 Webhook 接收端，由 ``NotificationManager`` 组合，具备每接收端 + 错误隔离与滑动窗口去重。 -项目跟踪：https://github.com/Integration-Automation/FileAutomation/issues +**配置与机密信息**\ （:doc:`usage/config`） + 在 ``automation_file.toml`` 中声明接收端与默认值；``${env:…}`` / + ``${file:…}`` 引用通过链式 ``EnvSecretProvider`` / ``FileSecretProvider`` + 解析；``ConfigWatcher`` 会轮询并热重载文件，无需重启。 + +**DAG 动作执行器**\ （:doc:`usage/dag`） + 以 DAG 形式运行动作列表，可声明依赖、进行拓扑式并行展开、按分支 + 跳过失败节点。 + +**可观测性** + ``start_metrics_server()`` 把每个动作以 Prometheus 计数器与直方图 + 对外暴露；``start_web_ui()`` 提供仅依赖标准库的 HTMX 仪表板， + 呈现健康状态、进度与注册器。 + +**插件**\ （:doc:`usage/plugins`） + 第三方包可通过 ``[project.entry-points."automation_file.actions"]`` + 注册自家 ``FA_*`` 动作；``PackageLoader`` 会导入一个 Python 包， + 并把其顶层成员以 ``_`` 名称注册进注册器。 + +---- + +阅读顺序 +======== + +文档按语言与内容类型拆分。手册按典型读者旅程组织——安装、操作本地、 +串接远端存储、对外开服务器、规模化自动化，最后深入可靠性、配置与 +组合执行。API 参考则是每个公开模块的自动生成 Python 参考。 + +.. toctree:: + :maxdepth: 1 + :caption: 入门 + + usage/quickstart + usage/cli + architecture .. toctree:: - :maxdepth: 2 - :caption: 手册 - - 第 1 章 — 入门 - 第 2 章 — CLI - 第 3 章 — 架构 - 第 4 章 — 本地操作 - 第 5 章 — HTTP 传输 - 第 6 章 — 云端与 SFTP 后端 - 第 7 章 — 动作服务器 - 第 8 章 — MCP 服务器 - 第 9 章 — 图形界面 - 第 10 章 — 可靠性 - 第 11 章 — 触发器与调度 - 第 12 章 — 通知 - 第 13 章 — 配置与机密信息 - 第 14 章 — DAG 动作执行器 - 第 15 章 — 插件 + :maxdepth: 1 + :caption: 文件与存储操作 + + usage/local + usage/transfer + usage/cloud .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :caption: 服务器与界面 + + usage/servers + usage/mcp + usage/gui + +.. toctree:: + :maxdepth: 1 + :caption: 运行时控制 + + usage/reliability + usage/events + usage/notifications + usage/config + +.. toctree:: + :maxdepth: 1 + :caption: 组合与扩展 + + usage/dag + usage/plugins + +.. toctree:: + :maxdepth: 1 :caption: API 参考 - 第 A 章 — 核心 - 第 B 章 — 本地操作 - 第 C 章 — 远端操作 - 第 D 章 — 服务器 - 第 E 章 — 客户端 SDK - 第 F 章 — 触发器 - 第 G 章 — 调度器 - 第 H 章 — 通知 - 第 I 章 — 进度与取消 - 第 J 章 — 项目脚手架 - 第 K 章 — 图形界面 - 第 L 章 — 工具 + api/core + api/local + api/remote + api/server + api/client + api/trigger + api/scheduler + api/notify + api/progress + api/project + api/ui + api/utils -索引 ---- +索引 +==== + * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/source.zh-TW/index.rst b/docs/source.zh-TW/index.rst index 3bd27a9..762fed9 100644 --- a/docs/source.zh-TW/index.rst +++ b/docs/source.zh-TW/index.rst @@ -1,66 +1,215 @@ +############### automation_file -=============== +############### + +**以 JSON 動作清單為核心的模組化檔案自動化框架。** + +``automation_file`` 把本地檔案 / 目錄 / ZIP / tar 操作、經 SSRF 驗證且 +可續傳的 HTTP 下載、十一種遠端儲存後端（Google Drive、S3、Azure Blob、 +Dropbox、OneDrive、Box、SFTP、FTP / FTPS、WebDAV、SMB、fsspec）、 +透過內建 TCP / HTTP / MCP 伺服器執行的 JSON 動作清單、cron 排程器、 +檔案監控觸發器、通知扇出、稽核紀錄、AES-256-GCM 檔案加密、Prometheus +指標，以及 PySide6 桌面圖形介面，全部統合為單一框架——一切透過共用的 +``ActionRegistry`` 調度，並由單一 ``automation_file`` 門面對外呈現。 + +* **PyPI**：https://pypi.org/project/automation_file/ +* **GitHub**：https://github.com/Integration-Automation/FileAutomation +* **Issue / 未來規劃**：https://github.com/Integration-Automation/FileAutomation/issues +* **授權**：MIT 語言：`English <../html/index.html>`_ | **繁體中文** | `简体中文 <../html-zh-CN/index.html>`_ -以 JSON 動作清單為核心的模組化檔案自動化框架。 +.. contents:: 本頁目錄 + :local: + :depth: 1 + +---- + +安裝 +==== + +.. code-block:: bash + + pip install automation_file + +每個後端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 +FTP、WebDAV、SMB、fsspec）以及 PySide6 圖形介面皆為一級執行階段相依 +套件——不需要記住任何選用 extra。 + +第一份動作 +========== + +一個動作是三種 JSON 形狀之一——``[name]``、``[name, {kwargs}]`` 或 +``[name, [args]]``。動作清單是動作的陣列。共用的執行器會依序執行，並 +回傳每筆動作的結果對應表。 + +.. code-block:: python + + from automation_file import execute_action + + results = execute_action([ + ["FA_create_dir", {"dir_path": "build"}], + ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], + ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}], + ]) + +同一份清單可從 CLI（``python -m automation_file run actions.json``）、 +Loopback TCP / HTTP 伺服器、MCP 主機，以及圖形介面的 **JSON 動作** 分頁 +直接執行——不需改寫。可參考 :doc:`usage/quickstart` 了解驗證、Dry-run +與平行執行；:doc:`usage/cli` 介紹 argparse 派發器；:doc:`architecture` +說明註冊器與執行器如何協作。 + +---- + +提供哪些功能 +============ + +**本地操作**\ （:doc:`usage/local`） + 檔案 / 目錄 / ZIP / tar / 壓縮檔操作、``safe_join`` 路徑穿越防護、 + 感知 OS 索引的 ``fast_find``、串流式 ``file_checksum`` 與 + ``find_duplicates``、``sync_dir`` rsync 風格鏡像、目錄差異比對、 + 文字 patch、JSON / YAML / CSV / JSONL / Parquet 編輯、MIME 偵測、 + 樣板渲染、垃圾桶送回 / 還原、檔案版本控制、條件式執行 + （``FA_if_exists`` / ``FA_if_newer`` / ``FA_if_size_gt``）、變數替換 + （``${env:…}`` / ``${date:%Y-%m-%d}`` / ``${uuid}``）、有逾時的 shell + 子行程，以及 AES-256-GCM 檔案加密。 + +**HTTP 傳輸**\ （:doc:`usage/transfer`） + ``download_file`` 透過 ``validate_http_url`` 驗證每個 URL（拒絕 + ``file://`` / ``ftp://`` / 私有 / loopback / link-local / 保留位址）， + 設下大小與逾時上限，支援透過 ``Range:`` 續傳到 ``.part``， + 傳輸後比對 ``expected_sha256``，並可整合進度註冊器，提供即時傳輸 + 快照與協作式取消。 + +**雲端與遠端儲存**\ （:doc:`usage/cloud`） + Google Drive（OAuth2）、S3（boto3）、Azure Blob、Dropbox、OneDrive、 + Box、SFTP（paramiko + ``RejectPolicy``）、FTP / FTPS、WebDAV、SMB / + CIFS 與 fsspec 橋接——皆由 ``build_default_registry()`` 自動註冊， + 並透過各自的共享單例存取。``copy_between`` 可依 URI 前綴在任兩個 + 後端間搬資料。 + +**動作伺服器**\ （:doc:`usage/servers`） + 預設僅綁定 loopback 的 TCP 與 HTTP 伺服器，接受 JSON 動作清單，可 + 選擇啟用共享密鑰驗證、伺服器端 ``ActionACL`` 白名單、 + ``GET /healthz`` / ``GET /readyz`` 健康檢查、``GET /openapi.json``、 + ``GET /progress`` WebSocket，以及帶型別的 ``HTTPActionClient`` SDK。 + +**MCP 伺服器**\ （:doc:`usage/mcp`） + ``MCPServer`` 透過 stdio 上的換行分隔 JSON-RPC 2.0，把註冊器橋接到 + 任何 Model Context Protocol 主機（Claude Desktop、Claude Code、MCP + CLI）。每個 ``FA_*`` 動作會變成具自動產生輸入 schema 的 MCP 工具。 + +**桌面圖形介面**\ （:doc:`usage/gui`） + PySide6 分頁控制介面——Home、Local、Transfer、Progress、JSON 動作、 + Triggers、Scheduler、Servers，加上每個雲端後端各一個分頁——共享 + 相同的單例，並透過 ``ActionWorker`` 在全域執行緒池上派工。 -``automation_file`` 把本地檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的 HTTP 下載、 -遠端儲存後端（Google Drive、S3、Azure Blob、Dropbox、OneDrive、Box、SFTP、 -FTP、WebDAV、SMB、fsspec）以及透過內建 TCP / HTTP / MCP 伺服器執行的 JSON -動作清單統合為單一框架——全部透過共用的 ``ActionRegistry`` 調度，並由 -PySide6 桌面圖形介面對外呈現。 +**可靠性**\ （:doc:`usage/reliability`） + ``retry_on_transient`` 帶有上限的指數退避、``Quota`` 大小與時間預算、 + ``CircuitBreaker``、``RateLimiter``、``FileLock`` / ``SQLiteLock``、 + 持久化的 ``ActionQueue``、SQLite ``AuditLog``、用於週期清單比對的 + ``IntegrityMonitor``，以及帶型別的 ``FileAutomationException`` 階層。 -文件依語言與內容類型拆分。每個語言手冊以章節組織：入門、CLI、架構、 -本地操作、HTTP 傳輸、雲端與 SFTP 後端、動作伺服器、MCP 伺服器、圖形介面、 -可靠性、觸發器與排程、通知、設定、DAG、外掛。API 參考則是自動生成的 -Python 參考資料。 +**觸發器與排程**\ （:doc:`usage/events`） + 檔案監控觸發器（``FA_watch_*``）會在檔案系統事件發生時執行動作清單； + cron 風格排程器（``FA_schedule_*``）依排程定期執行動作清單，並具備 + 重疊保護——兩者皆會在失敗時回退到通知。 -未來規劃 --------- +**通知**\ （:doc:`usage/notifications`） + Slack、Email（SMTP）、Discord、Telegram、Microsoft Teams、PagerDuty + 與通用 Webhook 接收端，由 ``NotificationManager`` 組合，具備每接收端 + 錯誤隔離與滑動視窗去重。 -專案追蹤：https://github.com/Integration-Automation/FileAutomation/issues +**設定與機敏資訊**\ （:doc:`usage/config`） + 在 ``automation_file.toml`` 裡宣告接收端與預設值；``${env:…}`` / + ``${file:…}`` 參照透過鏈式 ``EnvSecretProvider`` / ``FileSecretProvider`` + 解析；``ConfigWatcher`` 會輪詢並熱重載檔案，無需重啟。 + +**DAG 動作執行器**\ （:doc:`usage/dag`） + 以 DAG 形式執行動作清單，可宣告依賴、進行拓撲式平行展開、依分支 + 略過失敗節點。 + +**可觀測性** + ``start_metrics_server()`` 把每個動作以 Prometheus 計數器與直方圖 + 對外曝光；``start_web_ui()`` 提供僅依賴標準函式庫的 HTMX 儀表板， + 呈現健康狀態、進度與註冊器。 + +**外掛**\ （:doc:`usage/plugins`） + 第三方套件可透過 ``[project.entry-points."automation_file.actions"]`` + 註冊自家 ``FA_*`` 動作；``PackageLoader`` 會匯入一個 Python 套件， + 並把其頂層成員以 ``_`` 名稱註冊進註冊器。 + +---- + +閱讀順序 +======== + +文件依語言與內容類型拆分。手冊依典型讀者旅程組織——安裝、操作本地、 +串接遠端儲存、對外開伺服器、規模化自動化，最後深入可靠性、設定與 +組合執行。API 參考則是每個公開模組的自動生成 Python 參考。 + +.. toctree:: + :maxdepth: 1 + :caption: 入門 + + usage/quickstart + usage/cli + architecture .. toctree:: - :maxdepth: 2 - :caption: 手冊 - - 第 1 章 — 入門 - 第 2 章 — CLI - 第 3 章 — 架構 - 第 4 章 — 本地操作 - 第 5 章 — HTTP 傳輸 - 第 6 章 — 雲端與 SFTP 後端 - 第 7 章 — 動作伺服器 - 第 8 章 — MCP 伺服器 - 第 9 章 — 圖形介面 - 第 10 章 — 可靠性 - 第 11 章 — 觸發器與排程 - 第 12 章 — 通知 - 第 13 章 — 設定與機敏資訊 - 第 14 章 — DAG 動作執行器 - 第 15 章 — 外掛 + :maxdepth: 1 + :caption: 檔案與儲存操作 + + usage/local + usage/transfer + usage/cloud .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :caption: 伺服器與介面 + + usage/servers + usage/mcp + usage/gui + +.. toctree:: + :maxdepth: 1 + :caption: 執行階段控制 + + usage/reliability + usage/events + usage/notifications + usage/config + +.. toctree:: + :maxdepth: 1 + :caption: 組合與擴充 + + usage/dag + usage/plugins + +.. toctree:: + :maxdepth: 1 :caption: API 參考 - 第 A 章 — 核心 - 第 B 章 — 本地操作 - 第 C 章 — 遠端操作 - 第 D 章 — 伺服器 - 第 E 章 — 客戶端 SDK - 第 F 章 — 觸發器 - 第 G 章 — 排程器 - 第 H 章 — 通知 - 第 I 章 — 進度與取消 - 第 J 章 — 專案腳手架 - 第 K 章 — 圖形介面 - 第 L 章 — 工具 + api/core + api/local + api/remote + api/server + api/client + api/trigger + api/scheduler + api/notify + api/progress + api/project + api/ui + api/utils -索引 ---- +索引 +==== + * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/source/index.rst b/docs/source/index.rst index 32cf289..78a4e9c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,68 +1,225 @@ +############### automation_file -=============== +############### + +**A modular, JSON-driven file-automation framework for Python.** + +``automation_file`` packages local file / directory / ZIP / tar operations, +SSRF-validated and resumable HTTP downloads, eleven remote storage backends +(Google Drive, S3, Azure Blob, Dropbox, OneDrive, Box, SFTP, FTP / FTPS, +WebDAV, SMB, fsspec), JSON-driven action execution over embedded TCP / HTTP / +MCP servers, a cron-style scheduler, file-watcher triggers, notification +fanout, an audit log, AES-256-GCM file encryption, Prometheus metrics, and a +PySide6 desktop GUI — all dispatched through one shared ``ActionRegistry`` +and exposed from a single ``automation_file`` facade. + +* **PyPI** — https://pypi.org/project/automation_file/ +* **GitHub** — https://github.com/Integration-Automation/FileAutomation +* **Issues / RoadMap** — https://github.com/Integration-Automation/FileAutomation/issues +* **License** — MIT Languages: **English** | `繁體中文 <../html-zh-TW/index.html>`_ | `简体中文 <../html-zh-CN/index.html>`_ -A modular, JSON-driven file-automation framework for Python. +.. contents:: On this page + :local: + :depth: 1 + +---- + +Install +======= + +.. code-block:: bash + + pip install automation_file + +Every backend (Google Drive, S3, Azure Blob, Dropbox, OneDrive, Box, SFTP, +FTP, WebDAV, SMB, fsspec) and the PySide6 GUI are first-class runtime +dependencies — no optional extras to remember. + +First action +============ + +An action is one of three JSON shapes — ``[name]``, ``[name, {kwargs}]``, or +``[name, [args]]``. An action list is an array of actions. The shared +executor runs them in order and returns a per-action result map. + +.. code-block:: python + + from automation_file import execute_action + + results = execute_action([ + ["FA_create_dir", {"dir_path": "build"}], + ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}], + ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}], + ]) + +The same list runs from the CLI (``python -m automation_file run actions.json``), +over a loopback TCP / HTTP server, through an MCP host, or from the GUI's +**JSON actions** tab — no rewrite needed. See :doc:`usage/quickstart` for +validation, dry-run, and parallel execution; :doc:`usage/cli` for the +argparse dispatcher; :doc:`architecture` for how the registry and executor +fit together. + +---- + +What it gives you +================= + +**Local operations** (:doc:`usage/local`) + File / directory / ZIP / tar / archive ops, ``safe_join`` path-traversal + guard, OS-index-aware ``fast_find``, streaming ``file_checksum`` and + ``find_duplicates``, ``sync_dir`` rsync-style mirror, directory diffs, + text patches, JSON / YAML / CSV / JSONL / Parquet edits, MIME detection, + templates, trash send / restore, file versioning, conditional execution + (``FA_if_exists`` / ``FA_if_newer`` / ``FA_if_size_gt``), variable + substitution (``${env:…}`` / ``${date:%Y-%m-%d}`` / ``${uuid}``), shell + subprocess with timeout, and AES-256-GCM file encryption. + +**HTTP transfers** (:doc:`usage/transfer`) + ``download_file`` validates every URL through ``validate_http_url`` + (rejects ``file://`` / ``ftp://`` / private / loopback / link-local / + reserved targets), enforces size and timeout caps, supports resumable + ``Range:`` downloads to ``.part``, verifies an + ``expected_sha256`` after transfer, and integrates with the progress + registry for live transfer snapshots and cooperative cancellation. + +**Cloud and remote storage** (:doc:`usage/cloud`) + Google Drive (OAuth2), S3 (boto3), Azure Blob, Dropbox, OneDrive, Box, + SFTP (paramiko + ``RejectPolicy``), FTP / FTPS, WebDAV, SMB / CIFS, and a + fsspec bridge — all auto-registered by ``build_default_registry()`` and + reachable from one shared singleton each. ``copy_between`` moves data + between any two backends via URI prefixes. + +**Action servers** (:doc:`usage/servers`) + Loopback-only TCP and HTTP servers that accept JSON action lists, with + optional shared-secret authentication, server-side ``ActionACL`` allow + lists, ``GET /healthz`` / ``GET /readyz`` probes, ``GET /openapi.json``, + a ``GET /progress`` WebSocket, and a typed ``HTTPActionClient`` SDK. + +**MCP server** (:doc:`usage/mcp`) + ``MCPServer`` bridges the registry to any Model Context Protocol host + (Claude Desktop, Claude Code, MCP CLIs) over newline-delimited JSON-RPC + 2.0 on stdio. Every ``FA_*`` action becomes an MCP tool with an + auto-generated input schema. + +**Desktop GUI** (:doc:`usage/gui`) + A PySide6 tabbed control surface — Home, Local, Transfer, Progress, JSON + actions, Triggers, Scheduler, Servers, plus one tab per cloud backend — + sharing the same singletons and dispatching through ``ActionWorker`` on + the global thread pool. -``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. +**Reliability** (:doc:`usage/reliability`) + ``retry_on_transient`` with capped exponential back-off, ``Quota`` size + and time budgets, ``CircuitBreaker``, ``RateLimiter``, ``FileLock`` / + ``SQLiteLock``, persistent ``ActionQueue``, SQLite ``AuditLog``, + ``IntegrityMonitor`` for periodic manifest verification, and a typed + ``FileAutomationException`` hierarchy. -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. +**Triggers and scheduler** (:doc:`usage/events`) + File-watcher triggers (``FA_watch_*``) run an action list on a + filesystem event; the cron-style scheduler (``FA_schedule_*``) runs an + action list on a recurring schedule with overlap protection — both fall + back to notifications on failure. -RoadMap -------- +**Notifications** (:doc:`usage/notifications`) + Slack, Email (SMTP), Discord, Telegram, Microsoft Teams, PagerDuty, and + generic webhook sinks composed by a ``NotificationManager`` with + per-sink error isolation and sliding-window dedup. -Project tracker: https://github.com/Integration-Automation/FileAutomation/issues +**Configuration and secrets** (:doc:`usage/config`) + Declare sinks and defaults in ``automation_file.toml``; ``${env:…}`` / + ``${file:…}`` references are resolved through chained ``EnvSecretProvider`` + / ``FileSecretProvider``; ``ConfigWatcher`` polls and hot-reloads the + file without restart. + +**DAG action executor** (:doc:`usage/dag`) + Run action lists as a DAG with declared dependencies, topological + parallel fan-out, and per-branch skip-on-failure. + +**Observability** + ``start_metrics_server()`` exposes Prometheus counters and histograms + for every action; ``start_web_ui()`` serves a stdlib-only HTMX dashboard + for health, progress, and the registry. + +**Plugins** (:doc:`usage/plugins`) + Third-party packages register their own ``FA_*`` actions through + ``[project.entry-points."automation_file.actions"]``; ``PackageLoader`` + imports a Python package and registers its top-level members as + ``_``. + +---- + +Reading order +============= + +The docs are split by language and by content type. The manual follows a +typical reader journey — install, drive locally, reach remote storage, +expose servers, automate at scale — then dives into reliability, +configuration, and composition. The API reference is the auto-generated +Python reference for every public module. .. toctree:: - :maxdepth: 2 - :caption: Manual - - Chapter 1 — Getting Started - Chapter 2 — CLI - Chapter 3 — Architecture - Chapter 4 — Local Operations - Chapter 5 — HTTP Transfers - Chapter 6 — Cloud and SFTP Backends - Chapter 7 — Action Servers - Chapter 8 — MCP Server - Chapter 9 — GUI - Chapter 10 — Reliability - Chapter 11 — Triggers and Scheduler - Chapter 12 — Notifications - Chapter 13 — Configuration and Secrets - Chapter 14 — DAG Action Executor - Chapter 15 — Plugins + :maxdepth: 1 + :caption: Get started + + usage/quickstart + usage/cli + architecture .. toctree:: - :maxdepth: 2 - :caption: API Reference - - Chapter A — Core - Chapter B — Local Operations - Chapter C — Remote Operations - Chapter D — Server - Chapter E — Client SDK - Chapter F — Triggers - Chapter G — Scheduler - Chapter H — Notifications - Chapter I — Progress and Cancellation - Chapter J — Project Scaffolding - Chapter K — Graphical User Interface - Chapter L — Utils + :maxdepth: 1 + :caption: File and storage operations + + usage/local + usage/transfer + usage/cloud + +.. toctree:: + :maxdepth: 1 + :caption: Servers and surfaces + + usage/servers + usage/mcp + usage/gui + +.. toctree:: + :maxdepth: 1 + :caption: Run-time controls + + usage/reliability + usage/events + usage/notifications + usage/config + +.. toctree:: + :maxdepth: 1 + :caption: Composition and extensions + + usage/dag + usage/plugins + +.. toctree:: + :maxdepth: 1 + :caption: API reference + + api/core + api/local + api/remote + api/server + api/client + api/trigger + api/scheduler + api/notify + api/progress + api/project + api/ui + api/utils + +---- Indices -------- +======= * :ref:`genindex` * :ref:`modindex`