nene2-python 1.8.5__tar.gz → 1.8.6__tar.gz

{nene2_python-1.8.5 → nene2_python-1.8.6}/CHANGELOG.md

@@ -5,6 +5,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.6] — 2026-05-20
+
+FT41〜FT42 フィールドトライアル — structlog テスト統合ドキュメント・configure_problem_details リセット関数。
+
+### Added
+- `nene2.http.reset_problem_details()` — `configure_problem_details()` で設定したグローバル状態をテスト間でリセットするヘルパー関数 (FT42)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-41.md`、`docs/field-trials/2026-05-field-trial-42.md`
+
+### Changed
+- `docs/how-to/run-tests.md` — `configure_for_testing()` + `caplog` による structlog ログキャプチャパターンを追記 (FT41)
+
+---
+
 ## [1.8.5] — 2026-05-20
 
 FT37〜FT40 フィールドトライアル — RequestSizeLimitMiddleware パスごとサイズ制限とドキュメント改善。

{nene2_python-1.8.5 → nene2_python-1.8.6}/PKG-INFO

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

@@ -0,0 +1,126 @@
+# Field Trial 41: structlog テスト統合 — configure_for_testing() + caplog ログ相関
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.5 時点
+**テーマ**: `configure_for_testing()` + pytest `caplog` でリクエスト ID をログで追跡するパターンの実運用確認
+
+---
+
+## 概要
+
+`nene2.log.configure_for_testing()` を `conftest.py` のモジュールレベルで呼び出し、
+`RequestIdMiddleware` + `RequestLoggingMiddleware` を組み合わせたアプリのログを
+pytest の `caplog` でキャプチャ・検証するパターンを実装した。
+structlog と stdlib logging の橋渡し構造における制約も確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft41-log-testing/` に以下を作成:
+
+- **`conftest.py`** — モジュールレベルで `configure_for_testing()` を呼び出し
+- **`app.py`** — `RequestIdMiddleware` / `RequestLoggingMiddleware` / `ErrorHandlerMiddleware` を積んだ FastAPI アプリ。`extra_context` パラメータで静的フィールドを全ログに付加
+- **`test_app.py`** — 正常系・ヘッダー確認・caplog キャプチャ・ミドルウェアログ確認 (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP41-1: configure_for_testing() は conftest.py のモジュールレベルで呼ぶ必要がある
+
+**分類**: 軽微な摩擦（設計通り・注意喚起）
+
+`configure_for_testing()` は structlog のグローバル設定を変更するため、
+テスト関数内で呼んでも機能するが、全テストに適用するには
+`conftest.py` のモジュールレベルで呼ぶことが重要。
+テスト関数内で呼ぶと、その関数のみに限定されず他のテストに副作用を与える可能性がある。
+
+```python
+# conftest.py — 正しいパターン
+from nene2.log import configure_for_testing
+configure_for_testing()
+```
+
+**判断**: ドキュメントに記載されたパターン通り。現行の `docs/how-to/run-tests.md` に
+明示的に記載することで摩擦を減らせる。
+
+---
+
+### FP41-2: caplog.records の LogRecord に request_id フィールドが直接ない
+
+**分類**: 設計上の制約（許容範囲）
+
+`RequestIdMiddleware` が `structlog.contextvars.bind_contextvars(request_id=...)` で
+バインドした値は、pytest の `caplog` が返す stdlib `LogRecord` に直接属性として
+アクセスできない（`record.request_id` が存在しない）。
+
+`ProcessorFormatter` を通すとメッセージ文字列に request_id が含まれるが、
+構造化フィールドとして直接取り出すことはできない。
+
+```python
+# NG — LogRecord に直接属性はない
+for record in caplog.records:
+    print(record.request_id)  # AttributeError
+
+# OK — メッセージ文字列に含まれる
+assert "request-id-test" not in " ".join(r.message for r in caplog.records)
+# (request_id の値は UUID であり、テスト側から事前に知ることはできない)
+```
+
+**判断**: structlog と stdlib logging の橋渡し構造による設計上の制約。
+`caplog` でのログ検証はメッセージ文字列ベースで行うのが現実的なアプローチ。
+`ProcessorFormatter` に対するテストを書きたい場合は structlog の `capture_logs()` を使う方法もある。
+
+---
+
+### FP41-3: caplog のキャプチャには configure_for_testing() が必須
+
+**分類**: 注意喚起（ドキュメントで対応済み）
+
+`configure_for_testing()` を呼ばない状態では、structlog のログは
+pytest の `caplog` にキャプチャされない。
+JSON レンダラーのまま stdout に出力されるため、
+テストで structlog ログを検証するには必ず `configure_for_testing()` を呼ぶ必要がある。
+
+**判断**: FT18 で実装した機能の使い方確認。`run-tests.md` に caplog との統合手順を追記する価値がある。
+
+---
+
+### FP41-4: structlog.contextvars でバインドした値はメッセージ文字列に含まれる
+
+**分類**: 摩擦なし（設計の確認）
+
+`structlog.contextvars.bind_contextvars(key="value")` でバインドした値は、
+`configure_for_testing()` の設定下では `record.message` にキー＝値形式で含まれる。
+テストで構造化フィールドを検証する場合はメッセージ文字列の部分一致で確認できる。
+
+```python
+structlog.contextvars.bind_contextvars(request_id="test-123")
+log.info("hello")
+# caplog.records[0].message → "hello request_id=test-123" (または類似形式)
+```
+
+**判断**: structlog + caplog の統合パターンとして文字列検索が現実的。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+ドキュメント追記のみ検討:
+- `docs/how-to/run-tests.md` に `configure_for_testing()` + caplog パターンを追記
+
+---
+
+## 関連
+
+- `nene2.log.configure_for_testing` (FT18, v1.8.0)
+- `nene2.middleware.RequestIdMiddleware`
+- `nene2.middleware.RequestLoggingMiddleware`
+- FT18 (configure_for_testing 実装, v1.8.0)
+- FT30 (RequestLoggingMiddleware extra_context, v1.8.2)

nene2_python-1.8.6/docs/field-trials/2026-05-field-trial-42.md

@@ -0,0 +1,137 @@
+# Field Trial 42: get_request_id() Depends + configure_problem_details() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.5 時点
+**テーマ**: `get_request_id()` を FastAPI `Depends` で注入しレスポンスに含めるパターン、および `configure_problem_details()` のプロジェクト全体設定
+
+---
+
+## 概要
+
+`nene2.middleware.get_request_id()` を `Annotated[str, Depends(get_request_id)]` 構文で
+ハンドラーに注入し、レスポンスボディに `request_id` を含めるパターンを実装した。
+`configure_problem_details()` でプロジェクト全体の Problem Details base_url を設定し、
+カスタム例外を `SimpleDomainHandler` でマッピングする構成も確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft42-request-id-depends/` に以下を作成:
+
+- **`app.py`** — `get_request_id()` Depends 注入・`configure_problem_details()` 設定・`SimpleDomainHandler` でカスタム例外マッピング
+- **`test_app.py`** — 正常系・404・Problem Details base_url・request_id 相関 (9 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP42-1: RequestIdMiddleware なしで get_request_id() を呼ぶと空文字が返る
+
+**分類**: 注意喚起（ドキュメントに記載済み）
+
+`get_request_id()` は `contextvars` を参照する。
+テスト関数から直接呼ぶ場合や `RequestIdMiddleware` を経由しない場合は `""` を返す。
+`TestClient` 経由でリクエストを送れば正しく UUID が返る。
+
+```python
+# RequestIdMiddleware なしで直接呼ぶ → ""
+from nene2.middleware import get_request_id
+assert get_request_id() == ""
+
+# TestClient 経由で呼ぶ → UUID v4
+r = client.get("/debug/request-id")
+assert len(r.json()["request_id"]) == 36
+```
+
+**判断**: ドキュメントに記載済みの動作。TestClient 経由で使うことを徹底すれば問題ない。
+
+---
+
+### FP42-2: configure_problem_details() のグローバル状態がテスト間で共有される
+
+**分類**: 軽微な摩擦（設計上の制約・テスト時の注意点）
+
+`configure_problem_details()` はモジュールレベルのグローバル変数 `_configured_base_url` を変更する。
+異なる `base_url` で複数の `create_app()` を呼ぶと最後の設定が残り、
+テスト間で state が漏れる。
+
+```python
+create_app(base_url="https://first.example.com/problems/")
+# _configured_base_url == "https://first.example.com/problems/"
+
+create_app(base_url="https://second.example.com/problems/")
+# _configured_base_url == "https://second.example.com/problems/"
+# ← first の設定は上書きされている
+```
+
+**対処**: テスト間で隔離が必要な場合、`nene2.http.problem_details._configured_base_url = None`
+で手動リセットするか、全テストで同一の base_url を使う。
+運用環境では起動時に一度だけ呼ぶ設計なので実害はない。
+
+**判断**: アプリ起動時一度だけ呼ぶ設計であり仕様通り。テスト向けに `reset_problem_details()` 関数を追加する価値があるかもしれない。
+
+---
+
+### FP42-3: SimpleDomainHandler のエラーレスポンスに request_id が自動付与されない
+
+**分類**: 設計上の制約（許容範囲・パターン提示）
+
+`ErrorHandlerMiddleware` + `SimpleDomainHandler` が生成する 404 レスポンスには
+`request_id` フィールドが自動追加されない。
+`X-Request-Id` ヘッダーは `RequestIdMiddleware` が付与するが、
+レスポンスボディへの `request_id` 付与はアプリ側で明示的に行う必要がある。
+
+エラーレスポンスに `request_id` を含めたい場合は、`problem_details_response()` を
+直接呼ぶ exception handler を登録するか、`SimpleDomainHandler` を継承して
+`request_id` を `extra` に追加するカスタム実装が必要。
+
+**判断**: `ErrorHandlerMiddleware` はドメインレイヤーに依存しない設計のため、
+`request_id` のような HTTP 横断概念を自動付与しないのは正しい。
+クライアントが `X-Request-Id` ヘッダーを参照すれば相関できる。
+
+---
+
+### FP42-4: Annotated[str, Depends(get_request_id)] 構文は問題なく動作する
+
+**分類**: 摩擦なし（良い設計の確認）
+
+Python 3.12+ 推奨の `Annotated` 構文で `get_request_id()` を注入できる。
+FastAPI の型推論も正しく動作し、`str` 型として扱われる。
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from nene2.middleware import get_request_id
+
+async def handler(
+    request_id: Annotated[str, Depends(get_request_id)],
+) -> JSONResponse:
+    return JSONResponse({"request_id": request_id})
+```
+
+**判断**: FT25 で実装した `get_request_id()` は `Annotated` + `Depends` パターンと完全に互換。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+以下のドキュメント追記を検討:
+- `docs/how-to/` に `get_request_id()` Depends パターンの how-to ガイドを追加
+
+---
+
+## 関連
+
+- `nene2.middleware.get_request_id` (FT25, v1.8.1)
+- `nene2.middleware.RequestIdMiddleware`
+- `nene2.http.configure_problem_details` (FT19, v1.8.0)
+- `nene2.middleware.SimpleDomainHandler` (FT21, v1.8.0)
+- FT19 (configure_problem_details 実装, v1.8.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)
+- FT25 (get_request_id 実装, v1.8.1)

{nene2_python-1.8.5 → nene2_python-1.8.6}/docs/how-to/run-tests.md

@@ -103,6 +103,27 @@ engine = create_engine(
 
 `StaticPool` guarantees all logical connections share the same underlying SQLite connection, so tables created in one operation are visible to the next.
 
+## Capturing structlog output with caplog
+
+Call `configure_for_testing()` at module level in `conftest.py` to route structlog through stdlib logging so pytest's `caplog` fixture can capture it.
+
+```python
+# conftest.py
+from nene2.log import configure_for_testing
+configure_for_testing()
+```
+
+Then assert on message strings in tests:
+
+```python
+def test_handler_logs(caplog: pytest.LogCaptureFixture) -> None:
+    client = TestClient(create_app())
+    client.post("/api/echo", json={"message": "hello"})
+    assert any("processing echo" in r.message for r in caplog.records)
+```
+
+**Note**: `caplog.records` returns stdlib `LogRecord` objects. Fields bound with `structlog.contextvars.bind_contextvars()` (such as `request_id`) are not directly accessible as `record.request_id` — they appear as part of the formatted message string instead.
+
 ## Coverage requirements
 
 | Scope | Target |

{nene2_python-1.8.5 → nene2_python-1.8.6}/pyproject.toml

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

{nene2_python-1.8.5 → nene2_python-1.8.6}/src/nene2/http/__init__.py

@@ -8,7 +8,11 @@ from .health import (
     HealthStatus,
 )
 from .pagination import PaginationQuery, PaginationQueryParser, PaginationResponse
-from .problem_details import configure_problem_details, problem_details_response
+from .problem_details import (
+    configure_problem_details,
+    problem_details_response,
+    reset_problem_details,
+)
 
 __all__ = [
     "AsyncCompositeHealthCheck",
@@ -21,4 +25,5 @@ __all__ = [
     "PaginationResponse",
     "configure_problem_details",
     "problem_details_response",
+    "reset_problem_details",
 ]

{nene2_python-1.8.5 → nene2_python-1.8.6}/src/nene2/http/problem_details.py

@@ -27,6 +27,27 @@ def configure_problem_details(base_url: str) -> None:
     _configured_base_url = base_url
 
 
+def reset_problem_details() -> None:
+    """Reset the base_url configured by configure_problem_details().
+
+    Intended for use in tests only. Restores the default behaviour of
+    falling back to ``PROBLEM_DETAILS_BASE_URL``.
+
+    Example::
+
+        import pytest
+        from nene2.http import reset_problem_details
+
+
+        @pytest.fixture(autouse=True)
+        def _reset():
+            yield
+            reset_problem_details()
+    """
+    global _configured_base_url  # noqa: PLW0603
+    _configured_base_url = None
+
+
 def problem_details_response(
     problem_type: str,
     title: str,

{nene2_python-1.8.5 → nene2_python-1.8.6}/tests/nene2/http/test_problem_details.py

@@ -2,16 +2,15 @@
 
 import pytest
 
-import nene2.http.problem_details as _mod
-from nene2.http import configure_problem_details, problem_details_response
+from nene2.http import configure_problem_details, problem_details_response, reset_problem_details
 
 
 @pytest.fixture(autouse=True)
 def reset_configured_base_url() -> None:
     """Reset module-level configured base_url between tests."""
-    _mod._configured_base_url = None
+    reset_problem_details()
     yield
-    _mod._configured_base_url = None
+    reset_problem_details()
 
 
 def test_problem_details_response_uses_default_base_url() -> None:
@@ -61,3 +60,17 @@ def test_problem_details_response_includes_detail_when_provided() -> None:
 def test_problem_details_response_includes_extra_fields() -> None:
     r = problem_details_response("not-found", "Not Found", 404, extra={"resource_id": 42})
     assert b'"resource_id":42' in r.body
+
+
+def test_reset_problem_details_restores_default_base_url() -> None:
+    configure_problem_details("https://custom.example.com/problems/")
+    reset_problem_details()
+    r = problem_details_response("not-found", "Not Found", 404)
+    assert b"nene2.dev/problems/not-found" in r.body
+
+
+def test_reset_problem_details_is_idempotent() -> None:
+    reset_problem_details()
+    reset_problem_details()
+    r = problem_details_response("not-found", "Not Found", 404)
+    assert b"nene2.dev/problems/not-found" in r.body

{nene2_python-1.8.5 → nene2_python-1.8.6}/uv.lock

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