higuma

Pythonで書き、Rustで配信する。
A Flask-inspired Python web framework with a Rust HTTP core.

日本語ドキュメント · English documentation · API reference · Examples · Releases

higumaは、書き慣れたPythonのdecorator APIに、axum / Tokioを使ったRustの実行基盤を 組み合わせたWebフレームワークです。JSON API、HTML SSR、リアルタイム通信を、 Python側の必須runtime dependencyなしで構築できます。 名前は日本のヒグマに由来します。

0.8.0 — ASGI／WSGIの公開入口を追加しました。組み込みRust serverも引き続き選べます。 ASGIのHTTP・lifespan・WebSocket、WSGIのHTTPに対応します。 対応範囲と制約 / テストガイド 変更履歴 / 機能対応表

はじめる · 型付きAPI · 機能 · フロントエンド · 対応範囲 · 運用 · 貢献する

Quick start

CPython 3.10以降でインストールできます。

python -m pip install -U higuma

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

GETの応答を確認したら、Getting startedで request、template、CLIの使い方へ進めます。

型付きAPI

型付き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へ反映されます。

型付きルートの実行例はexamples/modern_typed_api.py、 宣言と制約の詳細はAPIリファレンスを参照してください。

主な機能

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

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

CSR/SPAとフロントエンド

以下の機能にはhiguma 0.6.0以降が必要です。0.5.0から利用する場合は更新してください。

from higuma import Higuma

app = Higuma(__name__, static_folder=None)


@app.get("/api/status")
def status():
    return {"status": "ok"}


# 先にフロントエンドをビルドし、index.htmlを含む公開用フォルダを用意します。
app.mount_spa("/app", "frontend/dist")

• CSR — 深いURLの再読み込みに対応し、APIや見つからないassetをHTMLに置き換えません。
• 静的配信 — mount_static()で公開先を分離し、HTMLの再検証とassetのcacheを設定できます。
• Vite + Python HTML — ViteManifestでhash付きJS・CSSとmodulepreloadを解決します。

React / Vue等のビルド、HMR、Node SSRの実行環境はフロントエンド側で用意します。 設置パス、cookie認証、CORS、デプロイの注意は フロントエンドガイド（English）を参照してください。

ASGI／WSGIで実行する

既存ASGI基盤にはasgi_app = app.asgi_app、WSGI基盤にはwsgi_app = app.wsgi_appを公開します。 例えばASGIでは、アプリmoduleにasgi_appを定義したうえで:

python -m pip install "higuma[asgi]"
uvicorn app:asgi_app --lifespan on --ws websockets-sansio

ASGIでも同期APIとの互換処理に専用workerを使用します。WSGIには標準WebSocket／lifespanがありません。 外部server利用時の性能や接続数、proxy trust、resourceの扱いは サーバーインターフェースガイドを確認してください。 Python必須runtime依存0は維持し、ASGI server関連は任意extraです。

対応範囲

• 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で確認できます。

互換性と設計上の境界

higumaはFlaskのdrop-in replacementではありません。組み込みRust serverに加え、 0.8.0からapp.asgi_app／app.wsgi_appを外部サーバーへ渡せます。

既存のWSGI / ASGI applicationはHTTPのroute配下へmountできますが、mount先の WebSocket、ASGI lifespan、無期限streamingを提供するものではありません。 組み込みのbackground taskとrate limitはprocess-localです。耐久性のあるjobや 分散状態には外部基盤を使用してください。

詳細はFlask互換性 / English compatibility guideと 機能対応表にまとめています。

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を参照してください。

開発とコントリビューション

不具合報告、回帰テスト、ドキュメント改善、互換性の検証を歓迎します。 開発環境の準備にはRust toolchainも必要です。

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

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

CIではPython / OSのmatrix test、Rustのtest / lint、docs build、配布wheelのsmoke testを 実行します。依存関係の監査は専用workflowで 実施します。バッジは各workflowへのリンクであり、脆弱性が存在しないことの保証ではありません。

不具合はIssue trackerへ、 脆弱性は公開IssueではなくSecurity Policyの窓口へ報告してください。

Links

• 日本語ドキュメント
• English documentation
• PyPI
• Examples
• Changelog
• Issue tracker
• Security Policy
• Contributing
• ロゴ・ブランド素材

ライセンス

MIT License