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

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

@@ -5,6 +5,18 @@ 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 改善。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.29
+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-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 パターンのサンプルを追加

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

@@ -0,0 +1,194 @@
+# FT87: カスタムレスポンスヘッダー — X-Total-Count / X-RateLimit パターン検証
+
+**日付**: 2026-05-20  
+**テーマ**: JSONResponse へのカスタムヘッダー付与と nene2 ユーティリティとの統合  
+**バージョン**: v1.8.29  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft87-response-headers/`
+
+---
+
+## 概要
+
+カスタムレスポンスヘッダー（`X-Total-Count`, `X-RateLimit-Remaining`, etc.）の付与パターンを
+4種類検証した。JSONResponse コンストラクタでの直接指定が最も簡単だが、
+`problem_details_response()` に `headers` パラメーターがなく、
+エラーレスポンスにヘッダーを付けられない摩擦が発見された。
+
+---
+
+## 4パターンの比較
+
+### パターン1: JSONResponse コンストラクタ（✅ 推奨）
+
+```python
+@app.get("/items", response_model=list[ItemResponse])
+def list_items(pagination: PaginationDep) -> JSONResponse:
+    items, total = ...
+    return JSONResponse(
+        content={"items": items, "total": total},
+        headers={
+            "X-Total-Count": str(total),
+            "X-Limit": str(pagination.limit),
+        },
+    )
+```
+
+最もシンプル。nene2 スタイルと完全一致。
+
+### パターン2: `response: Response` パラメーター（❌ JSONResponse では無視）
+
+```python
+@app.get("/items")
+def list_items(response: Response) -> JSONResponse:
+    response.headers["X-Total"] = "10"  # ← 無視される
+    return JSONResponse({"items": [...]})
+```
+
+FastAPI の `response: Response` でのヘッダー設定は、
+ハンドラーが `JSONResponse` を直接返す場合は無視される。
+`JSONResponse` はそれ自体が完全なレスポンスオブジェクトのため。
+
+### パターン3: ミドルウェアで一括付与
+
+```python
+class XServerVersionMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        response = await call_next(request)
+        response.headers["X-Server-Version"] = "1.0"
+        return response
+```
+
+全レスポンスに共通ヘッダーを付ける場合に有効。
+nene2 の `SecurityHeadersMiddleware` と同様のパターン。
+
+### パターン4: PaginationResponse + ヘッダー
+
+```python
+pagination_response = PaginationResponse(
+    items=data, limit=pagination.limit, offset=pagination.offset, total=total
+)
+return JSONResponse(
+    content=pagination_response.to_dict(),
+    headers={"X-Total-Count": str(total), "X-Total-Pages": str(total_pages)},
+)
+```
+
+---
+
+## 発見した問題
+
+### 問題1: `problem_details_response()` に `headers` パラメーターがない
+
+```python
+# やりたいこと: 429 レスポンスに Retry-After ヘッダーを付ける
+return problem_details_response(
+    "rate-limited", "Rate Limited", 429, "Too many requests.",
+    headers={"Retry-After": "60", "X-RateLimit-Remaining": "0"},  # ← パラメーターが存在しない
+)
+
+# 現状の回避策（冗長）:
+body = {
+    "type": "https://nene2.dev/problems/rate-limited",
+    "title": "Rate Limited",
+    "status": 429,
+    "detail": "Too many requests.",
+}
+return JSONResponse(content=body, status_code=429,
+                   media_type="application/problem+json",
+                   headers={"Retry-After": "60"})
+```
+
+RFC 7807 / 9457 では `Retry-After`, `WWW-Authenticate`, `Location` などのヘッダーが
+エラーレスポンスに必要なケースが多い。現在は `problem_details_response()` を捨てて
+`JSONResponse` を直接構築する必要がある。
+
+### 問題2: `response: Response` パラメーターが JSONResponse と非一貫
+
+```python
+# FastAPI ドキュメントには response: Response でヘッダーを設定する方法が書かれているが、
+# JSONResponse を直接返す nene2 スタイルでは動作しない
+@app.get("/items")
+def list_items(response: Response) -> JSONResponse:
+    response.headers["X-Total"] = "10"  # ← 無視される ← 摩擦
+    return JSONResponse({"items": []})
+```
+
+FastAPI ドキュメントを読んだユーザーが試みるパターンだが、
+nene2 の JSONResponse スタイルでは動作しない。
+
+### 問題3: PaginationResponse に `page` / `total_pages` がない
+
+```python
+# ユーザーが期待するインターフェース（page-based）
+PaginationResponse(items=data, total=100, page=2, per_page=20)
+# → total_pages = 5 を自動計算してほしい
+
+# 実際のインターフェース（offset-based）
+PaginationResponse(items=data, limit=20, offset=20, total=100)
+# → page や total_pages は自分で計算する必要がある
+```
+
+`page` / `total_pages` を使いたい場合は手動計算が必要。
+Frontend に `X-Total-Pages` ヘッダーを返したいケースで毎回計算コードが必要になる。
+
+---
+
+## テスト結果（全11件パス）
+
+```
+test_list_returns_x_total_count_header                     PASSED
+test_list_returns_pagination_headers                       PASSED
+test_create_returns_x_resource_id_header                   PASSED
+test_get_item_returns_version_header                       PASSED
+test_404_does_not_have_version_header                      PASSED
+test_nene2_security_headers_preserved                      PASSED
+test_middleware_adds_server_version_to_all_responses       PASSED
+test_pagination_headers_match_body                         PASSED
+test_pagination_header_limit_value                         PASSED
+test_friction_response_param_ignored_with_json_response    PASSED
+test_friction_problem_details_response_no_custom_headers   PASSED
+```
+
+---
+
+## 摩擦ポイント一覧
+
+| ID | 内容 | 深刻度 |
+|---|---|---|
+| F87-1 | `problem_details_response()` に `headers` パラメーターがない — エラーレスポンスへのヘッダー付与が不便 | 高 |
+| F87-2 | `response: Response` パラメーターのヘッダー設定が JSONResponse では無視される（未文書） | 中 |
+| F87-3 | `PaginationResponse` に `page` / `total_pages` がなく手動計算が必要 | 低 |
+
+---
+
+## 使用感（主観評価）
+
+### 直感性 ★★★★☆
+
+JSONResponse コンストラクタへの直接指定は直感的でシンプル。
+問題は `problem_details_response()` でエラーヘッダーが付けられないこと。
+
+### 実害の深刻さ ★★★★☆
+
+429 Rate Limited + `Retry-After` ヘッダーは RFC 6585 で推奨されている組み合わせ。
+現状では `problem_details_response()` が使えず、
+RFC 9457 フォーマットと一致した手動 JSONResponse 構築が必要になる。
+
+### 修正のしやすさ ★★★★★
+
+`problem_details_response()` に `headers: dict[str, str] | None = None` を追加するだけ。
+変更は最小で後方互換性あり。
+
+### 総合コメント
+
+F87-1 はコード修正で簡単に解決できる高影響の摩擦点。
+`problem_details_response()` を nene2 のメインの エラー応答ファクトリとして機能させるなら、
+`headers` パラメーターは必須機能と言える。
+
+---
+
+## 推奨アクション
+
+1. **fix**: `problem_details_response()` に `headers: dict[str, str] | None = None` パラメーターを追加
+2. **docs**: `response: Response` パラメーターが JSONResponse と非互換であることを how-to に明記
+3. **docs**: カスタムレスポンスヘッダーの推奨パターンを how-to に追加

{nene2_python-1.8.29 → nene2_python-1.8.30}/pyproject.toml

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

{nene2_python-1.8.29 → nene2_python-1.8.30}/src/nene2/http/problem_details.py

@@ -57,6 +57,7 @@ def problem_details_response(
     extra: dict[str, Any] | None = None,
     *,
     base_url: str | None = None,
+    headers: dict[str, str] | None = None,
 ) -> JSONResponse:
     """Build an RFC 9457 Problem Details JSON response.
 
@@ -72,6 +73,9 @@ def problem_details_response(
                       Raises ``ValueError`` if any key shadows a reserved field
                       (``type``, ``title``, ``status``, ``detail``).
         base_url:     Override the base URL for this call only.
+        headers:      Additional HTTP response headers.  Useful for error-specific headers
+                      such as ``Retry-After`` (429), ``WWW-Authenticate`` (401), or
+                      ``Location`` (3xx redirects in error flows).
 
     ``base_url`` resolution order:
     1. Explicit ``base_url`` argument
@@ -96,4 +100,5 @@ def problem_details_response(
         content=body,
         status_code=status,
         media_type="application/problem+json",
+        headers=headers,
     )

{nene2_python-1.8.29 → nene2_python-1.8.30}/tests/nene2/http/test_problem_details.py

@@ -98,3 +98,26 @@ def test_extra_with_type_reserved_raises_value_error() -> None:
 def test_extra_with_status_reserved_raises_value_error() -> None:
     with pytest.raises(ValueError, match="reserved Problem Details fields"):
         problem_details_response("x", "X", 400, extra={"status": 500})
+
+
+def test_problem_details_response_with_headers() -> None:
+    r = problem_details_response("rate-limited", "Rate Limited", 429, headers={"Retry-After": "60"})
+    assert r.status_code == 429
+    assert r.headers["retry-after"] == "60"
+
+
+def test_problem_details_response_headers_with_multiple_entries() -> None:
+    r = problem_details_response(
+        "rate-limited",
+        "Rate Limited",
+        429,
+        headers={"Retry-After": "60", "X-RateLimit-Remaining": "0"},
+    )
+    assert r.headers["retry-after"] == "60"
+    assert r.headers["x-ratelimit-remaining"] == "0"
+
+
+def test_problem_details_response_headers_none_by_default() -> None:
+    r = problem_details_response("not-found", "Not Found", 404)
+    assert "retry-after" not in r.headers
+    assert r.status_code == 404

{nene2_python-1.8.29 → nene2_python-1.8.30}/uv.lock

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