nene2-python 1.8.1__tar.gz → 1.8.2__tar.gz

{nene2_python-1.8.1 → nene2_python-1.8.2}/CHANGELOG.md

@@ -5,6 +5,17 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.2] — 2026-05-20
+
+FT29〜FT30 フィールドトライアル — AsyncUseCase ドキュメント・RequestLoggingMiddleware 改善。
+
+### Added
+- `docs/how-to/async-use-case.md` — `AsyncUseCaseProtocol` + FastAPI `Depends` の DI パターンガイドを追加 (FT29)
+- `RequestLoggingMiddleware` に `extra_context: dict[str, str] | None = None` パラメータを追加し、全ログに静的フィールドを付加できるように (FT30)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-29.md`、`docs/field-trials/2026-05-field-trial-30.md`
+
+---
+
 ## [1.8.1] — 2026-05-20
 
 FT25〜FT28 フィールドトライアル — RequestId ヘルパー・structlog ログレベル・ThrottleMiddleware 改善。

{nene2_python-1.8.1 → nene2_python-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.1
+Version: 1.8.2
 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.2/docs/field-trials/2026-05-field-trial-29.md

@@ -0,0 +1,74 @@
+# FT29: AsyncUseCaseProtocol 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `AsyncUseCaseProtocol` を使った非同期 UseCase パターンの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft29-async-usecase/`
+
+---
+
+## 目的
+
+`AsyncUseCaseProtocol` の実装・FastAPI ハンドラーへの統合・並行処理の動作を検証する。
+
+---
+
+## 実施内容
+
+- 外部 API 呼び出しを模した `FetchDataUseCase` を実装
+- `asyncio.gather()` で並行実行を確認
+- Protocol 適合性と isinstance() の既知制限を検証
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_get_item_returns_200 | PASS |
+| test_slow_endpoint_returns_200 | PASS |
+| test_async_use_case_executes_correctly | PASS |
+| test_async_use_case_satisfies_protocol | PASS |
+| test_multiple_async_calls_are_independent | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_isinstance_cannot_distinguish_sync_vs_async_protocol | PASS | 既知（ADR-0010） |
+| test_no_async_usecase_base_class_provided | PASS | 軽微（設計通り） |
+| test_no_generic_di_container_for_async_use_cases | PASS | あり（ドキュメント不備） |
+
+---
+
+## 発見した摩擦点
+
+### FT29-F1: FastAPI Depends を使った AsyncUseCase DI パターンがドキュメント化されていない
+
+**概要**: `AsyncUseCaseProtocol` を FastAPI の依存性注入と統合する標準的なパターンがない。
+ユーザーは毎回自分でパターンを決める必要がある。
+
+```python
+# ユーザーが毎回書く必要があるボイラープレート
+def get_fetch_use_case() -> FetchDataUseCase:
+    return FetchDataUseCase()
+
+@app.get("/items/{item_id}")
+async def get_item(
+    item_id: int,
+    use_case: FetchDataUseCase = Depends(get_fetch_use_case),
+) -> JSONResponse:
+    result = await use_case.execute(FetchDataInput(item_id=item_id))
+    ...
+```
+
+**判断**: how-to ドキュメントに DI パターンを追記する（Issue 化）。
+
+---
+
+## まとめ
+
+`AsyncUseCaseProtocol` の基本機能（実装・FastAPI 統合・並行処理）は問題なく動作する。
+
+摩擦点:
+1. **AsyncUseCase + FastAPI DI パターンがドキュメント化されていない** → Issue 化・how-to に追記
+2. **isinstance() の sync/async 区別不可** → ADR-0010 記載の既知制限、修正不要

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-30.md

@@ -0,0 +1,66 @@
+# FT30: RequestLoggingMiddleware + structlog バインディング実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `RequestLoggingMiddleware` と structlog contextvars の実運用パターン検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft30-request-logging/`
+
+---
+
+## 目的
+
+`RequestLoggingMiddleware` と structlog の contextvars 統合を実際のアプリで検証し、
+カスタムフィールドの付加方法を確認する。
+
+---
+
+## 実施内容
+
+- `RequestLoggingMiddleware` が自動バインドするコンテキスト（request_id, method, path）を確認
+- 追加のコンテキストフィールドを渡す方法を検証
+- `clear_contextvars()` の挙動確認
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_log_test_endpoint_returns_200 | PASS |
+| test_with_user_context_returns_200 | PASS |
+| test_request_id_is_in_response_header | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_clear_contextvars_wipes_pre_bound_context | PASS | 軽微（設計上の制限） |
+| test_no_way_to_add_extra_fields_to_request_log | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT30-F1: RequestLoggingMiddleware に extra_context パラメータがない
+
+**概要**: `service_name` や `version` などの静的フィールドを全リクエストログに含めたい場合、
+`RequestLoggingMiddleware` にパラメータとして渡す方法がない。
+
+```python
+# 期待する使い方
+app.add_middleware(
+    RequestLoggingMiddleware,
+    extra_context={"service": "my-api", "version": "1.0.0"},
+)
+```
+
+**期待する解決策**: `extra_context: dict[str, str] | None = None` パラメータを追加し、
+`bind_contextvars()` に追加フィールドとして渡す。
+
+---
+
+## まとめ
+
+`RequestLoggingMiddleware` の基本機能は問題なく動作する。
+
+摩擦点:
+1. **`extra_context` パラメータがない** → Issue 化・修正対象

nene2_python-1.8.2/docs/how-to/async-use-case.md

@@ -0,0 +1,121 @@
+# How-to: AsyncUseCase と FastAPI の統合
+
+## AsyncUseCaseProtocol の基本実装
+
+`AsyncUseCaseProtocol` は Protocol（構造的部分型）なので継承不要です。
+`async def execute(self, input_: I) -> O` を実装するだけで適合します。
+
+```python
+from dataclasses import dataclass
+from nene2.use_case import AsyncUseCaseProtocol
+
+
+@dataclass(frozen=True, slots=True)
+class FetchUserInput:
+    user_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class FetchUserOutput:
+    user_id: int
+    name: str
+
+
+class FetchUserUseCase:
+    async def execute(self, input_: FetchUserInput) -> FetchUserOutput:
+        # 外部 API 呼び出し・DB アクセスなど非同期処理
+        return FetchUserOutput(user_id=input_.user_id, name="Alice")
+```
+
+---
+
+## FastAPI Depends との統合
+
+ファクトリ関数を `Depends()` に渡すのが標準パターンです。
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+
+def get_fetch_user_use_case() -> FetchUserUseCase:
+    return FetchUserUseCase()
+
+
+@app.get("/users/{user_id}")
+async def get_user(
+    user_id: int,
+    use_case: FetchUserUseCase = Depends(get_fetch_user_use_case),
+) -> JSONResponse:
+    result = await use_case.execute(FetchUserInput(user_id=user_id))
+    return JSONResponse({"user_id": result.user_id, "name": result.name})
+```
+
+---
+
+## 外部依存を持つ UseCase の DI
+
+リポジトリや外部クライアントを受け取る UseCase は、依存も Depends で注入します。
+
+```python
+class FetchUserUseCase:
+    def __init__(self, repository: UserRepositoryInterface) -> None:
+        self._repository = repository
+
+    async def execute(self, input_: FetchUserInput) -> FetchUserOutput:
+        user = await self._repository.find_by_id(input_.user_id)
+        return FetchUserOutput(user_id=user.id, name=user.name)
+
+
+def get_user_repository() -> UserRepositoryInterface:
+    return InMemoryUserRepository()
+
+
+def get_fetch_user_use_case(
+    repository: UserRepositoryInterface = Depends(get_user_repository),
+) -> FetchUserUseCase:
+    return FetchUserUseCase(repository)
+```
+
+---
+
+## 並行実行
+
+複数の AsyncUseCase を並行実行するには `asyncio.gather()` を使います。
+
+```python
+import asyncio
+
+
+@app.get("/dashboard")
+async def dashboard(
+    user_id: int,
+    fetch_user: FetchUserUseCase = Depends(get_fetch_user_use_case),
+    fetch_stats: FetchStatsUseCase = Depends(get_fetch_stats_use_case),
+) -> JSONResponse:
+    user, stats = await asyncio.gather(
+        fetch_user.execute(FetchUserInput(user_id=user_id)),
+        fetch_stats.execute(FetchStatsInput(user_id=user_id)),
+    )
+    return JSONResponse({"user": user.name, "stats": stats.count})
+```
+
+---
+
+## isinstance() の注意点
+
+`AsyncUseCaseProtocol` は `@runtime_checkable` ですが、`isinstance()` は
+`execute` 属性の存在のみを確認します（sync/async の区別はしません）。
+
+```python
+# isinstance() は sync UseCase も True を返す（false positive）
+isinstance(sync_use_case, AsyncUseCaseProtocol)  # → True
+
+# 正しい非同期確認方法
+import inspect
+inspect.iscoroutinefunction(use_case.execute)  # → True/False
+```
+
+型安全性は `mypy --strict` の静的解析で保証します。詳細は ADR-0010 を参照してください。

{nene2_python-1.8.1 → nene2_python-1.8.2}/pyproject.toml

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

{nene2_python-1.8.1 → nene2_python-1.8.2}/src/nene2/middleware/request_logging.py

@@ -18,11 +18,19 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
     Args:
         exclude_paths: Paths to skip logging for (e.g. ``["/health"]``).
             Useful for high-frequency health-check endpoints where log noise is unwanted.
+        extra_context: Additional key-value pairs bound to every request log entry
+            (e.g. ``{"service": "my-api", "version": "1.0.0"}``).
     """
 
-    def __init__(self, app: object, exclude_paths: list[str] | None = None) -> None:
+    def __init__(
+        self,
+        app: object,
+        exclude_paths: list[str] | None = None,
+        extra_context: dict[str, str] | None = None,
+    ) -> None:
         super().__init__(app)  # type: ignore[arg-type]
         self._exclude_paths = set(exclude_paths or [])
+        self._extra_context: dict[str, str] = extra_context or {}
 
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
         if request.url.path in self._exclude_paths:
@@ -34,6 +42,7 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             request_id=request_id_var.get(),
             method=request.method,
             path=request.url.path,
+            **self._extra_context,
         )
         logger.info("request.received")
         response = await call_next(request)

{nene2_python-1.8.1 → nene2_python-1.8.2}/tests/nene2/middleware/test_request_logging.py

@@ -1,5 +1,6 @@
 """Tests for RequestLoggingMiddleware."""
 
+import structlog
 from fastapi import FastAPI
 from fastapi.responses import JSONResponse
 from fastapi.testclient import TestClient
@@ -41,6 +42,42 @@ def test_logging_does_not_remove_headers() -> None:
     assert "X-Request-Id" in response.headers
 
 
+def test_extra_context_is_bound_to_structlog() -> None:
+    captured: list[dict] = []
+    app = FastAPI()
+    app.add_middleware(
+        RequestLoggingMiddleware,
+        extra_context={"service": "my-api", "version": "1.0"},
+    )
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        captured.append(dict(structlog.contextvars.get_contextvars()))
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    client.get("/ping")
+    assert captured[0]["service"] == "my-api"
+    assert captured[0]["version"] == "1.0"
+
+
+def test_extra_context_default_is_empty() -> None:
+    captured: list[dict] = []
+    app = FastAPI()
+    app.add_middleware(RequestLoggingMiddleware)  # extra_context なし
+    app.add_middleware(RequestIdMiddleware)
+
+    @app.get("/ping")
+    async def ping() -> JSONResponse:
+        captured.append(dict(structlog.contextvars.get_contextvars()))
+        return JSONResponse({"ok": True})
+
+    client = TestClient(app)
+    client.get("/ping")
+    assert "service" not in captured[0]
+
+
 def test_exclude_paths_passes_requests_through() -> None:
     """exclude_paths に指定したパスへのリクエストがミドルウェアを通過すること"""
     app = FastAPI()

{nene2_python-1.8.1 → nene2_python-1.8.2}/uv.lock

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