higuma

0.5.0: Flask風context・session・flash・URL生成と実Flask接続を拡充しました。 対応範囲は日本語ガイド / English guideを参照してください。

Rust HTTPコアと、書き慣れたPython APIを組み合わせたWebフレームワークです。

日本語ドキュメント / English documentation

python -m pip install -U higuma

どんなフレームワークか

higumaは「アプリケーションはPythonで素直に書き、HTTPの実行基盤はRustに任せる」 ことを目的にしています。

• routing、middleware、hooks、BlueprintはFlaskに着想を得たPython API
• socket、route matching、file streaming、gzip、WebSocketはaxum / TokioベースのRustコア
• MiniJinjaによるSSRと、辞書やlistをそのまま返せるJSON API
• Python側の必須runtime dependencyはゼロ
• CPython 3.10以降で利用できるABI3 wheel

higumaはFlaskのdrop-in replacementではありません。また、higuma自体をWSGI/ASGI serverへ渡すのではなく、組み込みのRust serverで実行します。既存のWSGI/ASGIアプリは higumaのroute配下へmountできます。

Quick start

app.pyを作成します。

from higuma import Higuma, request

app = Higuma(__name__)


@app.get("/")
def index():
    return {"message": "Hello from higuma"}


@app.post("/echo")
def echo():
    return {"received": request.json}


if __name__ == "__main__":
    app.run()

起動後、http://127.0.0.1:8000 を開きます。

python app.py

CLIからも起動できます。

higuma run app:app --host 127.0.0.1 --port 8000
higuma routes app:app
higuma run app:app --processes 4 --max-connections 1024

型付きAPIでは、標準のAnnotatedとdataclassだけで入力元、制約、dependency、出力を宣言できます。

from dataclasses import dataclass
from typing import Annotated

from higuma import Body, Depends, Higuma, QueryParam

app = Higuma(__name__)


@dataclass
class Item:
    name: str
    price: float


def page_size(limit: Annotated[int, QueryParam(ge=1, le=100)] = 20):
    return limit


@app.post("/items", response_model=Item, status_code=201)
def create_item(
    item: Annotated[Item, Body()],
    limit: Annotated[int, Depends(page_size)],
):
    return item

入力はruntimeで検証・変換され、不正時は構造化された422になります。schemaは同じ宣言から OpenAPI 3.1へ反映されます。

主な機能

完全な一覧と注意点は機能ガイドおよび APIリファレンスを参照してください。

Validationについて: Annotated[..., Body()]等のmarkerとresponse_modelはruntime検証を 有効にします。従来のrequest_body=やreturn annotation単独はschema metadataです。

対応範囲

• Python: CPython 3.10以降（CIでは3.10〜3.14を検証）
• OS: Windows x86-64、Linux x86-64 / ARM64、macOS x86-64 / Apple Silicon
• Linux: manylinux wheelとmusllinux x86-64 wheelを配布
• Database: 組み込みORMはSQLiteのみ
• Protocol: 組み込みHTTP serverとWebSocket。TLSはreverse proxyで終端

wheelがないplatformではsource distributionからRust buildが必要です。公開済みの配布物は PyPIで確認できます。

Examples

examples/には、最小アプリだけでなく次の実行例があります。

• routing、async handler、型付き入力、dependency injection、class-based view
• response、cookie、file、multipart upload、streaming、SSE、background task
• Blueprint、lifespan、WebSocket、WSGI/ASGI mount、OpenAPI
• SQLite ORM、session authentication、role/permission、OAuth
• security middleware、signed token、in-process testing
• multi-process supervisor

必要な環境変数と実行コマンドはExamplesガイドに まとめています。

本番運用

higumaは活発に開発中です。本番採用前に、対象アプリケーションで負荷試験、障害試験、 security reviewを実施してください。

• debug=Falseのまま運用する
• Caddy、nginx、Cloudflare等でTLSを終端しHTTPSを強制する
• 32バイト以上の推測不能なsecretをsecret managerから読み込む
• TrustedHostMiddlewareと、正確なCORS / WebSocket Originを設定する
• ProxyHeadersMiddlewareでは直接接続するproxyだけを信頼する
• upload size、保存先、拡張子をアプリケーション側でも制限する
• SQLite fileを定期backupし、multi-process時のwrite負荷を測定する
• network timeout、request buffering、connection limitはreverse proxyでも設定する

詳しくはデプロイガイドと Security Policyを参照してください。

開発

python -m pip install -e ".[dev,docs]"
python -m pytest
python -m ruff check python tests examples
cargo test --locked --all-features
mkdocs build --strict

変更前にCONTRIBUTING.mdと、coding agent向けの SKILL.mdを確認してください。

Links

• 日本語ドキュメント
• English documentation
• PyPI
• Examples
• Changelog
• Issue tracker
• Security Policy

ライセンス

MIT License