fusion-framework (Python)

نسخه‌ی پایتونِ کلاس‌محور برای fusion-core (هسته‌ی Rust).

در این طراحی، منطق‌های اصلی مثل routing، parsing، serialization و binding پارامترهای handler در Rust انجام می‌شود. سمت پایتون فقط interface و DX باقی می‌ماند.

نصب

pip install fusion-framework

شروع سریع

from fusion_framework.api import FusionBaseApi
from fusion_framework.route import router
from fusion_framework.app import run

 
@router("/api/[module]/{id}")
class MyModule(FusionBaseApi):
    def get(self, id: int):
        # `id` طبق annotation به int تبدیل می‌شود (در Rust)
        return self.response({"ok": True, "id": id}, status=200)


if __name__ == "__main__":
    run()

تنظیمات Swagger

در fusion.<env>.json (همان فایلی که fusion init می‌سازد) بلاک swagger را ویرایش کن:

{
  "env": "dev",
  "config": {
    "swagger": {
      "enabled": true,
      "path": "/swagger",
      "title": "Fusion API Docs",
      "info": {
        "title": "Fusion API",
        "version": "1.0.0",
        "description": "My API docs",
        "contact": { "name": "API Support", "email": "support@example.com" },
        "license": { "name": "MIT" }
      },
      "servers": [{ "url": "/", "description": "Current host" }],
      "auth": {
        "persistAuthorization": true,
        "schemes": {
          "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
          "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
        },
        "global": [],
        "oauth": {
          "clientId": "",
          "appName": "Fusion API",
          "scopes": "",
          "usePkceWithAuthorizationCodeGrant": true
        }
      },
      "navbar": {
        "enabled": true,
        "showUrlInput": true
      },
      "ui": {
        "deepLinking": true,
        "docExpansion": "list",
        "filter": true,
        "tryItOutEnabled": true,
        "displayRequestDuration": true
      }
    }
  }
}

معنی کلیدها

متادیتای هر endpoint همچنان از @route(..., tags=..., desc=..., title=..., deprecated=...) می‌آید.

قرارداد Handlerها

متدهای HTTP مثل get/post/put/delete/patch را به صورت معمول پیاده کن.

1. ورودی‌ها از طریق امضای متد (def get(self, id: int, ...)) گرفته می‌شوند.
2. منبع مقدار بر اساس نام پارامتر:

• اگر نام با path params یکی باشد → از path
• اگر متد POST/PUT/PATCH باشد و نام در body JSON باشد → از body
• در غیر این صورت اگر نام در query باشد → از query

3. اگر پارامتری annotation/optional داشته باشد و وجود نداشته باشد → None ارسال می‌شود.

خطاها

from fusion_framework.http import HTTPException

raise HTTPException(404, {"detail": "not found"})

فایل‌های مهم

• fusion_framework.api.FusionBaseApi
  • view درخواست: method/path/body/headers/params/query
  • helper envelope: response(...)
• fusion_framework.route.router
  • ثبت کلاس‌ها با template مثل /api/[module]/{id}
• fusion_framework.app.run
  • settings را لود می‌کند و برنامه را mount/listen می‌کند
• پشت صحنه:
  • crates/fusion-py/src/lib.rs: PyO3 bridge
  • crates/fusion-core/src/*: routing/serialize/binding مشترک