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

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

@@ -5,6 +5,31 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.29] — 2026-05-20
+
+FT84 フィールドトライアル — 認証 Depends ユーティリティ検証と make_require_auth() 追加。
+
+### Added
+- `nene2.auth` に `make_require_auth(verifier)` Depends ファクトリーを追加 (#359) (FT84)
+  — `TokenVerifierProtocol` を FastAPI の `Depends` に接続するボイラープレートを解消
+  — 有効トークンで token 文字列を返し、未認証・無効トークンで 401 を raise
+- Field trial report: `docs/field-trials/2026-05-field-trial-84.md` (FT84)
+
+---
+
+## [1.8.28] — 2026-05-20
+
+FT83 フィールドトライアル — Depends() DI パターン検証と PaginationResponse / PaginationDep 改善。
+
+### Added
+- `PaginationResponse.model_dump()` を `to_dict()` の Pydantic 互換エイリアスとして追加 (#355) (FT83)
+  — Pydantic v2 ユーザーが `model_dump()` を期待して AttributeError になる問題を解消
+- `PaginationDep` 型エイリアスを `nene2.http` に追加 (#355) (FT83)
+  — `Annotated[PaginationQueryParser, Depends(PaginationQueryParser)]` の省略形
+- Field trial report: `docs/field-trials/2026-05-field-trial-83.md` (FT83)
+
+---
+
 ## [1.8.27] — 2026-05-20
 
 FT81 フィールドトライアル — CORS 設定パターン検証と setup_middlewares() への CORS 統合。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.28
+Version: 1.8.30
 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.30/docs/field-trials/2026-05-field-trial-84.md

@@ -0,0 +1,151 @@
+# FT84: 認証 Depends ユーティリティ — CurrentUser / require_auth パターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: nene2.auth に認証 Depends ユーティリティがない摩擦点と make_require_auth 設計検証  
+**バージョン**: v1.8.28  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft84-auth-depends/`
+
+---
+
+## 概要
+
+`LocalTokenVerifier` と `TokenVerifierProtocol` は実装されているが、
+FastAPI の Depends パターンに接続するユーティリティがない。
+ユーザーは `HTTPBearer` → `verify()` → 未認証 401 を毎プロジェクトで手組みする必要がある。
+`make_require_auth(verifier)` ファクトリーを追加することで解消できる。
+
+---
+
+## 発見した問題
+
+### 問題1: 認証 Depends を毎回手組みする必要がある
+
+```python
+# 現状: プロジェクトごとに以下のコードを書く必要がある (50+ 行のボイラープレート)
+
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from nene2.auth import LocalTokenVerifier
+
+security = HTTPBearer(auto_error=False)
+_verifier = LocalTokenVerifier.from_env("BEARER_TOKENS")
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials | None = Depends(security),
+) -> str | None:
+    if credentials is None:
+        return None
+    if not _verifier.verify(credentials.credentials):
+        return None
+    return credentials.credentials
+
+def require_auth(user: str | None = Depends(get_current_user)) -> str:
+    if user is None:
+        raise HTTPException(status_code=401)
+    return user
+
+# ハンドラーで使う
+@app.post("/items")
+def create(body: ItemBody, user: str = Depends(require_auth)) -> JSONResponse: ...
+```
+
+### 問題2: 任意認証パターンが冗長
+
+```python
+# 未認証でも通るが user を取得したいパターン
+def optional_auth(user: str | None = Depends(get_current_user)) -> str | None:
+    return user  # None = 未認証、str = ユーザーID
+
+@app.get("/feed")
+def get_feed(user: str | None = Depends(optional_auth)) -> JSONResponse:
+    if user:
+        return JSONResponse({"personalized": True})
+    return JSONResponse({"personalized": False})
+```
+
+### 問題3: TokenVerifierProtocol を Depends で直接使えない
+
+```python
+# こういう書き方をしたくなるが Depends は callable を期待する
+@app.post("/items")
+def create(
+    body: ItemBody,
+    token: Annotated[str, Depends(LocalTokenVerifier.from_env("TOKENS"))],  # ← 機能しない
+) -> JSONResponse: ...
+```
+
+---
+
+## テスト結果（全12件パス）
+
+```
+test_public_endpoint_no_auth                     PASSED
+test_create_item_with_valid_token                PASSED
+test_create_item_without_token_returns_401       PASSED
+test_create_item_with_invalid_token_returns_401  PASSED
+test_get_me_returns_user_info                    PASSED
+test_delete_item_authenticated                   PASSED
+test_delete_item_unauthenticated_returns_401     PASSED
+test_request_id_present_on_401                  PASSED  # nene2 ミドルウェアと共存
+test_security_headers_present_on_401            PASSED  # nene2 ミドルウェアと共存
+test_friction_boilerplate_for_auth_depends       PASSED  # 摩擦記録
+test_friction_optional_auth_pattern_verbose      PASSED  # 摩擦記録
+test_friction_verifier_not_injectable_as_depends PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F84-1 | 認証 Depends ボイラープレートを毎プロジェクトで手組みする必要がある | 中 |
+| F84-2 | 任意認証（Optional User）パターンが冗長 | 低 |
+| F84-3 | `TokenVerifierProtocol` を Depends で直接使えない | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+「nene2 でトークン認証を追加する」という操作に必要なステップが多すぎる。
+`BearerTokenMiddleware` は全経路に認証を入れるには便利だが、
+「このエンドポイントだけ認証を要求」パターンに Depends ユーティリティがない。
+FastAPI の HTTPBearer を使う方法は FastAPI のドキュメントを参照しなければわからない。
+
+### 実害の深刻さ ★★★☆☆
+
+認証は多くのプロジェクトで必要。毎回 50 行のボイラープレートを書くのは
+DRY 原則に反する。バグが入りやすく、テスト漏れにもつながる。
+
+### 修正のしやすさ ★★★★★
+
+`make_require_auth(verifier)` 関数を `nene2.auth` に追加するだけ:
+
+```python
+def make_require_auth(verifier: TokenVerifierProtocol) -> Callable[..., str]:
+    security = HTTPBearer(auto_error=False)
+    def get_current_user(credentials: ... = Depends(security)) -> str | None:
+        if credentials is None or not verifier.verify(credentials.credentials):
+            return None
+        return credentials.credentials
+    def require_auth(user: str | None = Depends(get_current_user)) -> str:
+        if user is None:
+            raise HTTPException(status_code=401)
+        return user
+    return require_auth
+```
+
+### 総合コメント
+
+nene2 の認証機能は「ミドルウェアで全経路を保護する」ユースケースは
+`BearerTokenMiddleware` でカバーされている。
+不足しているのは「特定エンドポイントのみ認証を要求する」ユースケース。
+`make_require_auth()` を追加することで「nene2 だけで完結」できる。
+
+---
+
+## 推奨アクション
+
+1. **Issue #358**: `nene2.auth` に `make_require_auth(verifier)` ファクトリーを追加
+   — `require_auth = make_require_auth(LocalTokenVerifier.from_env("TOKENS"))` パターンを実現

nene2_python-1.8.30/docs/field-trials/2026-05-field-trial-85.md

@@ -0,0 +1,207 @@
+# FT85: OpenAPI スキーマ品質 — JSONResponse と response_model の摩擦
+
+**日付**: 2026-05-20  
+**テーマ**: JSONResponse を返すと OpenAPI スキーマが Any になる問題と正しいパターン検証  
+**バージョン**: v1.8.29  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft85-openapi-schema/`
+
+---
+
+## 概要
+
+nene2 のハンドラーは `JSONResponse` を返すが、`response_model` を省略すると
+OpenAPI スキーマに型情報が含まれず Swagger UI が使いにくくなる。
+CLAUDE.md には「`response_model` で明示（`Any` 返却禁止）」と書かれているが、
+`JSONResponse` との組み合わせ方が示されていない。
+3つのパターン（response_model なし / あり / Pydantic 直返し）を検証した。
+
+---
+
+## 3パターンの比較
+
+### パターン1: response_model なし（❌ 非推奨）
+
+```python
+@app.get("/articles/{article_id}")
+def get_article(article_id: int) -> JSONResponse:
+    return JSONResponse({"article_id": 1, "title": "..."})
+```
+
+- OpenAPI スキーマ: `{}` または `{"title": "Response"}`（型情報なし）
+- Swagger UI: レスポンス例なし、フィールド定義なし
+- 型安全性: なし
+
+### パターン2: response_model あり（✅ nene2 推奨）
+
+```python
+class ArticleResponse(BaseModel):
+    article_id: int = Field(description="記事 ID")
+    title: str = Field(max_length=200, description="記事タイトル")
+    ...
+
+@app.get(
+    "/articles/{article_id}",
+    response_model=ArticleResponse,
+    responses={404: {"description": "Article not found"}},
+    summary="記事を取得する",
+    tags=["articles"],
+)
+def get_article(article_id: int) -> JSONResponse:
+    if article_id not in _articles:
+        return problem_details_response(...)  # nene2 パターン維持
+    return JSONResponse({...})
+```
+
+- OpenAPI スキーマ: `ArticleResponse` の完全な型情報
+- Swagger UI: フィールド説明・型・例が表示される
+- nene2 の `problem_details_response()` と共存可能
+
+### パターン3: Pydantic モデルを直接返す
+
+```python
+@app.get("/articles/{article_id}", response_model=ArticleResponse)
+def get_article(article_id: int) -> ArticleResponse:
+    if article_id not in _articles:
+        raise HTTPException(404, "Not found")  # ← nene2 スタイルではない
+    return ArticleResponse(...)
+```
+
+- OpenAPI スキーマ: 最も完全
+- 型安全性: 最高（戻り値が検証される）
+- 問題: nene2 の `problem_details_response()` が使えない
+
+---
+
+## 発見した問題
+
+### 問題1: JSONResponse + response_model の組み合わせが未文書
+
+```python
+# nene2 ユーザーはこれが正しい書き方だと知らない
+@app.get("/articles/{id}", response_model=ArticleResponse)
+def get_article(id: int) -> JSONResponse:  # ← 戻り値型と response_model が一致しない
+    return JSONResponse({...})
+
+# response_model は OpenAPI スキーマ生成のみに使われ、
+# JSONResponse の内容は response_model でバリデーションされない
+```
+
+`response_model` と `JSONResponse` の組み合わせは動作するが、
+FastAPI は `JSONResponse` の内容を `response_model` で検証しない。
+「`response_model` を指定すれば内容も検証される」と誤解するユーザーがいる。
+
+### 問題2: Pydantic レスポンスモデルと Domain dataclass の二重定義
+
+```python
+@dataclass(frozen=True, slots=True)
+class Article:
+    article_id: int
+    title: str
+    body: str
+    author: str
+
+class ArticleResponse(BaseModel):
+    article_id: int = Field(description="記事 ID")
+    title: str = Field(max_length=200, description="記事タイトル")
+    body: str = Field(...)
+    author: str = Field(...)
+```
+
+Domain オブジェクトと API スキーマオブジェクトを両方定義する必要があり、
+フィールドを変更すると両方を更新しなければならない。
+
+### 問題3: problem_details_response() と Pydantic 直返しの非一貫性
+
+```python
+# パターン2 (JSONResponse): nene2 スタイルの 404
+@app.get("/articles/{id}", response_model=ArticleResponse)
+def get_article_v2(id: int) -> JSONResponse:
+    if id not in _articles:
+        return problem_details_response("not-found", ..., 404, ...)  # ✅ RFC 9457
+    return JSONResponse({...})
+
+# パターン3 (Pydantic 直返し): FastAPI スタイルの 404
+@app.get("/articles/{id}", response_model=ArticleResponse)
+def get_article_v3(id: int) -> ArticleResponse:
+    if id not in _articles:
+        raise HTTPException(404)  # ❌ {"detail": "Not found"} になる（nene2 スタイルではない）
+    return ArticleResponse(...)
+```
+
+Pydantic モデルを直接返す場合は `problem_details_response()` を使えず、
+`HTTPException` を raise する必要がある。
+これは nene2 の Problem Details ポリシーと矛盾する。
+
+---
+
+## テスト結果（全16件パス）
+
+```
+test_no_schema_create_returns_201                     PASSED
+test_no_schema_get_returns_200                        PASSED
+test_no_schema_openapi_get_has_no_response_schema     PASSED  # スキーマなし確認
+test_with_schema_create_returns_201                   PASSED
+test_with_schema_get_returns_200                      PASSED
+test_with_schema_list_returns_200                     PASSED
+test_with_schema_openapi_has_response_schema          PASSED  # スキーマあり確認
+test_with_schema_openapi_has_tags                     PASSED  # tags 反映
+test_with_schema_openapi_has_summary                  PASSED  # summary 反映
+test_with_schema_404_returns_problem_details          PASSED  # nene2 404 と共存
+test_pydantic_return_get_returns_200                  PASSED
+test_pydantic_return_openapi_has_schema               PASSED
+test_friction_json_response_loses_schema              PASSED  # 摩擦記録
+test_friction_response_model_does_not_validate        PASSED  # 摩擦記録
+test_friction_problem_details_and_pydantic_conflict   PASSED  # 摩擦記録
+test_friction_duplicate_type_definition               PASSED  # 摩擦記録
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F85-1 | `JSONResponse` + `response_model` の正しい組み合わせ方がドキュメントに未記載 | 中 |
+| F85-2 | Domain dataclass と Pydantic レスポンスモデルの二重定義が避けられない | 低 |
+| F85-3 | Pydantic 直返しパターンでは `problem_details_response()` が使えない（HTTPException と非一貫） | 中 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★☆☆
+
+`JSONResponse` + `response_model` のパターンは直感的ではない。
+「`JSONResponse` を返すと戻り値型が `JSONResponse` なのに `response_model=ArticleResponse` と
+書く」という不整合に戸惑う。FastAPI のドキュメントを読めば理解できるが、
+nene2 のコンテキストでの説明がない。
+
+### 実害の深刻さ ★★★☆☆
+
+`response_model` を省略すると Swagger UI に型情報が出ず、
+API クライアント（TypeScript, Kotlin 等）の自動生成コードに型が付かない。
+実際の運用では非常に不便で、フロントエンドチームから「なぜ型がないの?」と言われる。
+
+### 修正のしやすさ ★★★★★
+
+コード修正は不要。必要なのはドキュメントだけ:
+- nene2 how-to: `JSONResponse` + `response_model` の正しいパターン例
+- `response_model` がバリデーションではなく OpenAPI スキーマ生成のみに使われることの説明
+- `problem_details_response()` との共存パターン
+
+### 総合コメント
+
+「`JSONResponse` を使いながら完全な OpenAPI スキーマを生成する」パターンは
+FastAPI の機能で実現できるが、nene2 のドキュメントに記載がない。
+CLAUDE.md には「`response_model` で明示」と書かれているが、
+例コード（example app）が `response_model` を使っていない矛盾もある。
+コード修正なしでドキュメントだけで対応できる摩擦点。
+
+---
+
+## 推奨アクション
+
+1. **docs**: how-to ガイドに「OpenAPI スキーマを整備する」記事を追加
+   — `response_model=PydanticModel` + `def handler() -> JSONResponse` パターン
+   — `problem_details_response()` との共存例
+2. **refactor**: `example/` ハンドラーに `response_model` を追加して CLAUDE.md ポリシーに準拠させる

nene2_python-1.8.30/docs/field-trials/2026-05-field-trial-86.md

@@ -0,0 +1,171 @@
+# FT86: Lifespan イベント — startup/shutdown とリソース共有パターン
+
+**日付**: 2026-05-20  
+**テーマ**: FastAPI lifespan context manager でのリソース初期化・クリーンアップと nene2 との共存  
+**バージョン**: v1.8.29  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft86-lifespan/`
+
+---
+
+## 概要
+
+FastAPI の `lifespan` パラメーターを使った起動時リソース初期化（DBプール、キャッシュ）と
+`app.state` 経由でハンドラーへの注入パターンを検証。
+nene2 の `setup_middlewares()` との共存は問題なし。
+テスト時の `TestClient` の挙動と状態分離に摩擦あり。
+
+---
+
+## 実装パターン
+
+### パターン: lifespan + app.state + Depends
+
+```python
+from contextlib import asynccontextmanager
+from collections.abc import AsyncGenerator
+from fastapi import FastAPI, Depends, Request
+from typing import Annotated
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    # startup
+    cache = InMemoryCache()
+    db_pool = DatabasePool()
+    db_pool.connect()
+    app.state.cache = cache
+    app.state.db_pool = db_pool
+
+    yield  # アプリ実行
+
+    # shutdown
+    db_pool.disconnect()
+    cache.clear()
+
+app = FastAPI(lifespan=lifespan)
+setup_middlewares(app)  # nene2 ミドルウェアと共存 ✅
+
+# Depends でリソースを注入
+def get_cache(request: Request) -> InMemoryCache:
+    return request.app.state.cache  # type: ignore[return-value]
+
+CacheDep = Annotated[InMemoryCache, Depends(get_cache)]
+
+@app.get("/cache/{key}", response_model=CacheEntryResponse)
+def get_entry(key: str, cache: CacheDep) -> JSONResponse:
+    return JSONResponse({"key": key, "value": cache.get(key)})
+```
+
+---
+
+## 発見した問題
+
+### 問題1: TestClient の with ブロック必須が直感的でない
+
+```python
+# ❌ lifespan が実行されない — app.state.cache が未設定
+client = TestClient(app)
+client.get("/cache/greeting")  # → AttributeError → 500
+
+# ✅ 正しい使い方
+with TestClient(app) as client:
+    client.get("/cache/greeting")  # → 200
+```
+
+`TestClient(app)` だけでは lifespan の startup が実行されない。
+`with` ブロックで包む必要があるが、nene2 ドキュメントに記載がない。
+
+### 問題2: テスト間の状態分離が保証されない
+
+```python
+# テスト A: with TestClient(app) を実行 → startup → app.state.cache が設定される
+with TestClient(app) as client:
+    ...  # startup が実行され app.state に値がセットされる
+
+# テスト B: with なしで実行 → 前のテストの app.state.cache が残っている
+client = TestClient(app)
+client.get("/status")  # app.state が残っているため 200 になる（本来は 500 のはず）
+```
+
+pytest が同一プロセスで `app` モジュールを共有するため、
+前のテストで設定された `app.state` が次のテストに引き継がれる。
+テスト順序によって結果が変わる不安定なテストスイートになりやすい。
+
+### 問題3: app.state の型安全性がない
+
+```python
+# mypy では Any になる
+cache = request.app.state.cache  # type: ignore[return-value]
+```
+
+`Starlette.State` は動的アトリビューとを持つ `__slots__` なしのオブジェクト。
+mypy は型を推論できず、`type: ignore` コメントが必要になる。
+
+---
+
+## テスト結果（全11件パス）
+
+```
+test_lifespan_startup_initializes_resources      PASSED
+test_lifespan_cache_has_initial_value            PASSED
+test_lifespan_cache_missing_key_returns_null     PASSED
+test_lifespan_cache_set_and_get                  PASSED
+test_lifespan_db_query_uses_pool                 PASSED
+test_lifespan_db_query_count_increments          PASSED
+test_lifespan_cache_shared_across_requests       PASSED
+test_no_lifespan_status_returns_false            PASSED
+test_friction_testclient_requires_with_block     PASSED
+test_friction_app_state_no_type_safety           PASSED
+test_friction_lifespan_error_handling            PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F86-1 | `TestClient` を `with` ブロックで使わないと lifespan が実行されず 500 になる | 高 |
+| F86-2 | テスト間で `app.state` が引き継がれてテスト順序依存になる | 中 |
+| F86-3 | `app.state` へのアクセスが型安全でなく `type: ignore` が必要 | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★☆☆☆
+
+`lifespan` パラメーターと `yield` 境界は直感的だが、
+TestClient の `with` ブロック必須は知らないとハマる。
+「なぜ `client.get()` が 500 を返すのか」のデバッグに時間がかかる。
+`AttributeError: 'State' object has no attribute 'cache'` が
+nene2 の `ErrorHandlerMiddleware` に吸収されて 500 になるため
+エラーメッセージが見えにくい（`APP_DEBUG=true` なら見える）。
+
+### 実害の深刻さ ★★★★☆
+
+テスト間の状態分離問題は CI で「時々落ちる」テストを生む。
+テスト実行順序が変わった（pytest-randomly 導入、テスト追加）タイミングで
+突然失敗するため、原因特定が難しい。
+
+### 修正のしやすさ ★★★★☆
+
+コード修正なし、ドキュメント追加のみで対応できる:
+- how-to: `TestClient` を `with` ブロックで使う方法
+- how-to: テスト間の状態分離のための `pytest.fixture` パターン
+- how-to: `app.state` の型安全なアクセスパターン（typed wrapper）
+
+### 総合コメント
+
+lifespan + nene2 の組み合わせ自体は問題なく動く。
+`setup_middlewares()` との共存も完全。
+主な摩擦はテスト方法の周知不足であり、ドキュメントで解決できる。
+
+---
+
+## 推奨アクション
+
+1. **docs**: how-to ガイドに「lifespan でリソースを管理する」記事を追加
+   - `TestClient` は必ず `with` ブロックで使うことを明示
+   - テスト間の状態分離パターン（`pytest.fixture` + `with TestClient`）
+   - `app.state` の型安全なアクセスパターン（`get_or_raise` helper）
+2. **docs**: nene2 example/ に lifespan パターンのサンプルを追加