nene2-python 1.8.27__tar.gz → 1.8.28__tar.gz

{nene2_python-1.8.27 → nene2_python-1.8.28}/CHANGELOG.md

@@ -5,6 +5,18 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.27] — 2026-05-20
+
+FT81 フィールドトライアル — CORS 設定パターン検証と setup_middlewares() への CORS 統合。
+
+### Added
+- `setup_middlewares()` に `cors_allowed_origins` / `cors_allow_credentials` / `cors_allow_methods` / `cors_allow_headers` パラメーターを追加 (#348) (FT81)
+  — `CORSMiddleware` を最外側に自動配置し、OPTIONS プリフライトが確実に処理される
+  — `cors_allowed_origins=["*"]` を渡すと `ValueError` を raise（wildcard 禁止ポリシーの実装強制）
+- Field trial report: `docs/field-trials/2026-05-field-trial-81.md` (FT81)
+
+---
+
 ## [1.8.26] — 2026-05-20
 
 FT80 フィールドトライアル — LocalMcpServer + HttpxMcpClient MCP E2E 検証と list_tools() 追加。

{nene2_python-1.8.27 → nene2_python-1.8.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.27
+Version: 1.8.28
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.28/docs/field-trials/2026-05-field-trial-82.md

@@ -0,0 +1,198 @@
+# FT82: Background Tasks — FastAPI BackgroundTasks と nene2 の組み合わせ
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI BackgroundTasks を nene2 アーキテクチャと組み合わせた際の動作とパターン検証  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft82-background-tasks/`
+
+---
+
+## 概要
+
+FastAPI の `BackgroundTasks` は「レスポンス返却後に処理を実行する」仕組みで、
+メール送信・在庫更新・監査ログなどのユースケースに使う。
+nene2 のミドルウェアスタック（`setup_middlewares()`）との共存、
+例外ハンドリングの限界、UseCase への注入パターンを検証した。
+
+---
+
+## 実装パターン
+
+### 基本パターン（ハンドラーで BackgroundTasks を受け取る）
+
+```python
+from fastapi import BackgroundTasks
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(item=body.item, quantity=body.quantity))
+    # レスポンス送信後にバックグラウンドで実行される
+    background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+    background_tasks.add_task(update_inventory, output.item, output.quantity)
+    return JSONResponse({...}, status_code=201)
+```
+
+### UseCase を注入可能にするパターン（テスト用ファクトリー）
+
+```python
+def create_app_with_use_case(
+    create_order_fn: Callable[[CreateOrderInput], CreateOrderOutput]
+) -> FastAPI:
+    factory_app = FastAPI()
+    setup_middlewares(factory_app)
+
+    @factory_app.post("/orders")
+    def _create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+        output = create_order_fn(...)
+        background_tasks.add_task(send_order_confirmation, output.order_id, output.item)
+        return JSONResponse({...}, status_code=201)
+
+    return factory_app
+
+# テストでの使用
+injected_app = create_app_with_use_case(lambda _: mock_output)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: バックグラウンドタスクの例外がクライアントに見えない
+
+```python
+# バックグラウンドタスクが例外を投げても...
+def send_email(order_id: int) -> None:
+    raise SMTPConnectionError("Mail server down")
+
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(...)
+    background_tasks.add_task(send_email, output.order_id)
+    return JSONResponse({...}, status_code=201)  # ← 201 が返る
+
+# クライアントには 201 が届く（メール失敗は見えない）
+```
+
+FastAPI の設計上、レスポンスはすでに送信済みのため
+バックグラウンドタスクのエラーを HTTP レスポンスコードで伝えられない。
+エラーはサーバーログに記録されるが、クライアントには `201 Created` が届く。
+
+### 問題2: nene2 に BackgroundTasks 推奨パターンがない
+
+```python
+# UseCase にどうやって BackgroundTasks を渡すか、ドキュメントがない
+
+# ❌ UseCase の中で直接 BackgroundTasks を使う（アーキテクチャ違反）
+class CreateOrderUseCase:
+    def execute(self, input_: CreateOrderInput, bg: BackgroundTasks) -> CreateOrderOutput:
+        ...
+        bg.add_task(send_email, ...)  # UseCase が HTTP 境界に依存してしまう
+
+# ✅ ハンドラー層で BackgroundTasks を使い、UseCase は純粋に保つ
+@app.post("/orders")
+def create_order(body: OrderBody, background_tasks: BackgroundTasks) -> JSONResponse:
+    output = use_case.execute(CreateOrderInput(...))  # UseCase はクリーン
+    background_tasks.add_task(send_email, output.order_id)  # ハンドラー層で副作用
+    return JSONResponse({...})
+```
+
+正しいパターン（UseCase を純粋に保ちハンドラー層で BackgroundTasks を使う）が
+nene2 のドキュメントに記載されていない。
+
+### 問題3: バックグラウンドタスクの実行確認ができない
+
+```python
+# 「タスクをキューした」ことと「タスクが成功した」ことを HTTP で区別できない
+r = client.post("/orders/1/alert")
+# レスポンスは {"queued": True} — 成功したかどうかはわからない
+```
+
+本番運用では Celery・ARQ・FastAPI Scheduler などの外部ジョブキューが必要。
+「BackgroundTasks は軽量な one-shot 処理向け」という点がドキュメントに不足。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_create_order_returns_201                              PASSED
+test_get_order_returns_200                                 PASSED
+test_get_nonexistent_order_returns_404                     PASSED
+test_background_tasks_execute_after_response               PASSED  # TestClient は同期実行
+test_multiple_background_tasks_all_execute                 PASSED
+test_background_task_with_alert                            PASSED
+test_background_task_not_queued_on_404                     PASSED  # 404 ではタスク未実行
+test_failing_background_task_does_not_affect_response      PASSED  # 例外 → 200 のまま
+test_failing_background_task_started                       PASSED
+test_request_id_present_with_background_tasks              PASSED  # nene2 と共存
+test_security_headers_present_with_background_tasks        PASSED  # nene2 と共存
+test_validation_error_does_not_queue_background_tasks      PASSED  # 422 では未実行
+test_injectable_use_case_pattern                           PASSED  # DI パターン動作
+test_friction_background_exception_not_visible_to_client   PASSED  # 摩擦記録
+test_friction_no_nene2_background_task_pattern             PASSED  # 摩擦記録
+test_friction_background_task_cannot_return_result         PASSED  # 摩擦記録
+```
+
+---
+
+## 重要な発見: TestClient はバックグラウンドタスクを同期実行する
+
+```python
+client = TestClient(app)
+r = client.post("/orders", json={"item": "Widget", "quantity": 1})
+# TestClient はレスポンスを返す前にバックグラウンドタスクも実行する
+assert "confirmation:order_1:Widget" in notification_log  # ✅ すでに実行済み
+```
+
+`TestClient` はバックグラウンドタスクをリクエスト完了前に同期的に実行するため、
+テストでは `background_tasks.add_task()` で追加した処理を即座に検証できる。
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F82-1 | バックグラウンドタスクの例外がクライアントに見えない（FastAPI 設計上の制約） | 中 |
+| F82-2 | nene2 に BackgroundTasks 推奨パターン（UseCase との分離）のドキュメントがない | 低 |
+| F82-3 | バックグラウンドタスクは result を返せない（外部キューが必要） | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+`background_tasks.add_task(fn, arg1, arg2)` は非常にシンプルで直感的。
+FastAPI のドキュメントを読めば即座に使える。
+nene2 のミドルウェアスタックとの共存も問題なし。
+
+### 実害の深刻さ ★★☆☆☆
+
+バックグラウンド例外がクライアントに見えない問題は、
+軽量な通知タスク（メール送信）であれば許容範囲。
+ただし「注文確定」のような業務的に重要な処理を
+バックグラウンドタスクに入れるのは設計ミス — そこは UseCase に残すべき。
+
+### 修正のしやすさ ★★★★★
+
+必要なのはドキュメントのみ:
+- UseCase はクリーンに保つ（BackgroundTasks を引数に取らない）
+- ハンドラー層でのみ `background_tasks.add_task()` を呼ぶ
+- 失敗して困る処理はバックグラウンドタスクに入れない
+- TestClient はバックグラウンドタスクを同期実行する（テスト性良好）
+
+### 総合コメント
+
+FastAPI の `BackgroundTasks` は nene2 と相性が良く、
+`setup_middlewares()` のミドルウェアスタックとも完全に共存する。
+X-Request-Id・セキュリティヘッダーも正常に付与される。
+摩擦の大部分は「どう使うべきか」のドキュメント不足であり、
+フレームワークの改修は不要。
+
+---
+
+## 推奨アクション
+
+1. **docs**: BackgroundTasks パターン（UseCase との分離、TestClient の同期実行）を how-to ガイドに追加
+2. **minor**: BackgroundTasks は「失敗しても OK な副作用のみ」というガイドラインの明記

nene2_python-1.8.28/docs/field-trials/2026-05-field-trial-83.md

@@ -0,0 +1,223 @@
+# FT83: Depends() DI — FastAPI Depends を nene2 アーキテクチャで活用するパターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: UseCase・認証・Pagination の Depends 組み合わせパターンと dependency_overrides  
+**バージョン**: v1.8.27  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft83-depends-injection/`
+
+---
+
+## 概要
+
+FastAPI の `Depends()` を nene2 の UseCase + Repository パターンと組み合わせた。
+依存チェーン（Repository → UseCase → Handler）、認証 Depends、
+`PaginationQueryParser` の統合、テスト時の `dependency_overrides` による差し替えを検証した。
+`PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）という
+Pydantic ユーザーがつまずく摩擦点を発見した。
+
+---
+
+## 実装パターン
+
+### Repository → UseCase の Depends チェーン
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+def get_repo() -> InMemoryProductRepository:
+    return _repo  # シングルトン
+
+def get_list_use_case(
+    repo: Annotated[InMemoryProductRepository, Depends(get_repo)],
+) -> ListProductsUseCase:
+    return ListProductsUseCase(repo)
+
+@app.get("/products")
+def list_products(
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(...)
+    return JSONResponse(...)
+```
+
+### PaginationQueryParser + UseCase の両方を Depends
+
+```python
+@app.get("/products")
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse:
+    products, total = use_case.execute(
+        limit=pagination.limit, offset=pagination.offset
+    )
+    return JSONResponse(
+        PaginationResponse(
+            items=[...], total=total, limit=pagination.limit, offset=pagination.offset
+        ).to_dict()  # ← model_dump() ではなく to_dict()
+    )
+```
+
+### 認証 Depends（Bearer Token）
+
+```python
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+security = HTTPBearer(auto_error=False)
+
+def get_current_user(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
+) -> str | None:
+    if credentials is None:
+        return None
+    return verify_token(credentials.credentials)
+
+def require_auth(user: Annotated[str | None, Depends(get_current_user)]) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+@app.post("/products")
+def create_product(
+    body: ProductBody,
+    use_case: Annotated[CreateProductUseCase, Depends(get_create_use_case)],
+    current_user: Annotated[str, Depends(require_auth)],
+) -> JSONResponse: ...
+```
+
+### テスト時の dependency_overrides
+
+```python
+custom_repo = InMemoryProductRepository()
+custom_repo.create("Test Product", 100)
+
+app.dependency_overrides[get_repo] = lambda: custom_repo
+# テスト実行
+del app.dependency_overrides[get_repo]  # クリーンアップ
+```
+
+---
+
+## 発見した問題
+
+### 問題1: PaginationResponse.model_dump() が存在しない
+
+```python
+# ❌ Pydantic ユーザーは model_dump() を期待してしまう
+PaginationResponse(...).model_dump()  # AttributeError!
+
+# ✅ 正しいメソッド
+PaginationResponse(...).to_dict()
+```
+
+`PaginationResponse` は dataclass だが、Pydantic v2 に慣れているユーザーは
+`model_dump()` を期待して AttributeError に直面する。
+FastAPI の OpenAPI ドキュメントや response_model を使うには
+Pydantic BaseModel にするか、FastAPI の Response 型として登録する必要がある。
+
+### 問題2: Annotated[T, Depends(fn)] の記述が冗長
+
+```python
+# 現在の書き方（型情報が Annotated の外側と内側に重複）
+def list_products(
+    pagination: Annotated[PaginationQueryParser, Depends(PaginationQueryParser)],
+    use_case: Annotated[ListProductsUseCase, Depends(get_list_use_case)],
+) -> JSONResponse: ...
+
+# 理想（nene2 が型エイリアスを提供）
+type PaginationDep = Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]
+
+@app.get("/products")
+def list_products(pagination: PaginationDep, ...) -> JSONResponse: ...
+```
+
+`PaginationQueryParser` の `Annotated` エイリアスを nene2 が提供すれば
+毎回書く冗長さが解消される。
+
+### 問題3: nene2 の認証 Depends ユーティリティがない
+
+```python
+# nene2.auth に Depends ユーティリティがない
+# ユーザーは HTTPBearer + LocalTokenVerifier を手動で組み合わせる必要がある
+
+# 理想:
+from nene2.auth.deps import CurrentUser, require_auth
+# これが存在しない
+```
+
+`LocalTokenVerifier.from_env()` は実装されているが、
+FastAPI の Depends パターンに接続する `CurrentUser` 型や
+`require_auth` Depends がない。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_list_products_empty                        PASSED
+test_create_product_returns_201                  PASSED
+test_get_product_returns_200                     PASSED
+test_get_nonexistent_returns_404                 PASSED
+test_create_product_requires_auth                PASSED
+test_create_product_with_auth_succeeds           PASSED
+test_pagination_with_depends                     PASSED  # PaginationQueryParser Depends 動作
+test_pagination_second_page                      PASSED
+test_override_repo_with_custom_data              PASSED  # dependency_overrides 動作
+test_override_repo_empty                         PASSED
+test_request_id_with_depends                     PASSED  # nene2 ミドルウェアと共存
+test_security_headers_with_depends               PASSED
+test_validation_error_returns_422                PASSED
+test_friction_annotated_syntax_verbosity         PASSED  # 摩擦記録
+test_friction_use_case_chains_in_depends         PASSED  # 摩擦記録
+test_friction_no_nene2_depends_utilities         PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F83-1 | `PaginationResponse.model_dump()` が存在しない（`to_dict()` が正しい）— Pydantic ユーザー混乱 | 中 |
+| F83-2 | `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の冗長記述 | 低 |
+| F83-3 | nene2 認証の Depends ユーティリティ (`CurrentUser`, `require_auth`) がない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+`Depends()` のパターン自体は FastAPI の機能なので明確。
+ただし Repository → UseCase → Handler の3層チェーンは
+Spring/NestJS の DI に慣れたユーザーには違和感がある
+（Constructor Injection ではなく Function Injection）。
+`dependency_overrides` によるテスト差し替えは非常に優れた機能。
+
+### 実害の深刻さ ★★☆☆☆
+
+`PaginationResponse.to_dict()` を知らなければ AttributeError で即座に詰まる。
+nene2 ドキュメントに `PaginationResponse` の使い方が記載されているが、
+`model_dump()` と混同するユーザーが続出する可能性がある。
+
+### 修正のしやすさ ★★★★★
+
+- `PaginationResponse` に `model_dump()` の alias を追加（または別名で明記）
+- `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` を `PaginationDep` 型エイリアスとして公開
+- `nene2.auth.deps` モジュールに `CurrentUser` 型と `require_auth` Depends を追加
+
+### 総合コメント
+
+FastAPI の `Depends()` は nene2 のアーキテクチャと非常に相性がよく、
+Repository の差し替えも `dependency_overrides` で簡単にできる。
+主な摩擦は `PaginationResponse.to_dict()` の名前（Pydantic との不整合）と
+認証 Depends ユーティリティの欠如。どちらも小さな追加で解決できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue**: `PaginationResponse` に `model_dump()` エイリアスを追加（Pydantic ユーザー向け）
+2. **Issue**: `nene2.http` に `PaginationDep` 型エイリアスを追加（`PaginationQueryParser` の Depends）
+3. **Issue**: `nene2.auth.deps` モジュールに認証 Depends ユーティリティを追加

{nene2_python-1.8.27 → nene2_python-1.8.28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.27"
+version = "1.8.28"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}

{nene2_python-1.8.27 → nene2_python-1.8.28}/src/nene2/http/__init__.py

@@ -7,7 +7,7 @@ from .health import (
     HealthCheckProtocol,
     HealthStatus,
 )
-from .pagination import PaginationQuery, PaginationQueryParser, PaginationResponse
+from .pagination import PaginationDep, PaginationQuery, PaginationQueryParser, PaginationResponse
 from .problem_details import (
     PROBLEM_DETAILS_BASE_URL,
     configure_problem_details,
@@ -21,6 +21,7 @@ __all__ = [
     "CompositeHealthCheck",
     "HealthCheckProtocol",
     "HealthStatus",
+    "PaginationDep",
     "PaginationQuery",
     "PaginationQueryParser",
     "PaginationResponse",

{nene2_python-1.8.27 → nene2_python-1.8.28}/src/nene2/http/pagination.py

@@ -7,7 +7,7 @@ import dataclasses
 from dataclasses import dataclass, field
 from typing import Annotated, Any
 
-from fastapi import Query, Request
+from fastapi import Depends, Query, Request
 
 from nene2.validation.exceptions import ValidationError, ValidationException
 
@@ -128,3 +128,21 @@ class PaginationResponse:
         if self.total is not None:
             data["total"] = self.total
         return data
+
+    def model_dump(self) -> dict[str, Any]:
+        """Alias for :meth:`to_dict` — Pydantic-compatible name for familiarity."""
+        return self.to_dict()
+
+
+type PaginationDep = Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]
+"""Type alias for injecting :class:`PaginationQueryParser` via ``Depends``.
+
+Usage::
+
+    from nene2.http import PaginationDep
+
+    @app.get("/items")
+    def list_items(pagination: PaginationDep) -> JSONResponse:
+        items, total = use_case.execute(pagination.limit, pagination.offset)
+        ...
+"""

{nene2_python-1.8.27 → nene2_python-1.8.28}/tests/nene2/http/test_pagination.py

@@ -9,7 +9,7 @@ from fastapi import Depends, FastAPI, Request
 from fastapi.responses import JSONResponse
 from fastapi.testclient import TestClient
 
-from nene2.http import PaginationQueryParser, PaginationResponse
+from nene2.http import PaginationDep, PaginationQueryParser, PaginationResponse
 from nene2.validation.exceptions import ValidationException
 
 
@@ -125,3 +125,24 @@ def test_pagination_response_to_dict_serializes_dataclass_items() -> None:
 def test_pagination_response_to_dict_passes_through_dict_items() -> None:
     r = PaginationResponse(items=[{"id": 1}, {"id": 2}], limit=20, offset=0, total=2)
     assert r.to_dict()["items"] == [{"id": 1}, {"id": 2}]
+
+
+def test_pagination_response_model_dump_is_alias_for_to_dict() -> None:
+    """model_dump() は to_dict() の Pydantic 互換エイリアス。"""
+    r = PaginationResponse(items=[{"id": 1}], limit=10, offset=0, total=1)
+    assert r.model_dump() == r.to_dict()
+
+
+def test_pagination_dep_type_alias_usable_in_handler() -> None:
+    """PaginationDep 型エイリアスで Depends を省略して記述できる。"""
+    test_app = FastAPI()
+
+    @test_app.get("/things")
+    def list_things(pagination: PaginationDep) -> JSONResponse:
+        return JSONResponse({"limit": pagination.limit, "offset": pagination.offset})
+
+    test_client = TestClient(test_app)
+    r = test_client.get("/things?limit=5&offset=10")
+    assert r.status_code == 200
+    assert r.json()["limit"] == 5
+    assert r.json()["offset"] == 10

{nene2_python-1.8.27 → nene2_python-1.8.28}/uv.lock

@@ -925,7 +925,7 @@ wheels = [
 
 [[package]]
 name = "nene2-python"
-version = "1.8.27"
+version = "1.8.28"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },