nene2-python 1.8.18__tar.gz → 1.8.19__tar.gz

{nene2_python-1.8.18 → nene2_python-1.8.19}/CHANGELOG.md

@@ -5,6 +5,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.19] — 2026-05-20
+
+FT68 フィールドトライアル — SimpleDomainHandler + extra_factory 実運用検証。
+
+### Changed
+- `problem_details_response` の docstring に `extra` がトップレベルにフラットマージされることを明記 (#308) (FT68)
+- `SimpleDomainHandler` の docstring に `extra_factory` のフラットマージ動作を例示 (#308) (FT68)
+
+### Added
+- Field trial report: `docs/field-trials/2026-05-field-trial-68.md`
+
+---
+
 ## [1.8.18] — 2026-05-20
 
 FT67 フィールドトライアル — SqlAlchemyTransactionManager 実運用検証。

{nene2_python-1.8.18 → nene2_python-1.8.19}/PKG-INFO

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

@@ -0,0 +1,67 @@
+# FT68: SimpleDomainHandler + extra_factory 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: ドメイン例外ハンドラー (`SimpleDomainHandler`) + `extra_factory` の実運用確認  
+**バージョン**: v1.8.18 → v1.8.19 (ドキュメント追加)  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft68-domain-handler/`
+
+---
+
+## 概要
+
+`nene2.middleware.SimpleDomainHandler` を使って複数のドメイン例外クラスをそれぞれの
+HTTP レスポンスにマッピングし、`extra_factory` による動的フィールドを検証した。
+
+---
+
+## 実装内容
+
+- `ArticleNotFoundError`, `ArticleAccessDeniedError`, `ArticleTitleConflictError`: 独自例外クラス
+- 各例外に `SimpleDomainHandler` + `detail_factory` + `extra_factory` を設定
+- `ErrorHandlerMiddleware(domain_handlers=[...])` に渡して自動ハンドリング
+
+---
+
+## テスト結果
+
+**7/7 passed** (テスト修正後)
+
+| テスト | 結果 |
+|---|---|
+| `test_existing_article_returns_200` | PASSED |
+| `test_not_found_returns_404_with_article_id` | PASSED |
+| `test_access_denied_returns_403` | PASSED |
+| `test_title_conflict_returns_409` | PASSED |
+| `test_detail_factory_populates_detail_field` | PASSED |
+| `test_problem_details_format_compliant` | PASSED |
+| `test_successful_create_returns_201` | PASSED |
+
+---
+
+## Friction Points
+
+### FP-1: `extra_factory` のフィールドがトップレベルにフラットマージされることが不明瞭
+
+**発生箇所**: テストで `data["extra"]["article_id"]` とアクセスして `KeyError: 'extra'`
+
+**症状**:
+```python
+# 期待していた構造
+assert data["extra"]["article_id"] == 999  # → KeyError: 'extra'
+
+# 実際の構造（RFC 9457 extension members = トップレベル）
+assert data["article_id"] == 999  # ← 正しいアクセス方法
+```
+
+**原因**: `extra` という引数名が「ネストされた辞書」を連想させるが、
+実際は RFC 9457 仕様の extension members としてトップレベルにフラットマージされる。
+
+**修正**: `problem_details_response` と `SimpleDomainHandler` の docstring に
+フラットマージである旨とRFC 9457 extension members との関係を明記 (Issue #308, v1.8.19)
+
+---
+
+## 結論
+
+`SimpleDomainHandler` + `extra_factory` は実運用で問題なく使用できる。
+extra フィールドのフラットマージ動作が docstring に明記され、今後は混同を防げる。

{nene2_python-1.8.18 → nene2_python-1.8.19}/pyproject.toml

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

{nene2_python-1.8.18 → nene2_python-1.8.19}/src/nene2/http/problem_details.py

@@ -60,6 +60,19 @@ def problem_details_response(
 ) -> JSONResponse:
     """Build an RFC 9457 Problem Details JSON response.
 
+    Args:
+        problem_type: Short identifier appended to ``base_url`` for the ``type`` URI.
+        title:        Human-readable summary of the error.
+        status:       HTTP status code.
+        detail:       Optional human-readable explanation.
+        extra:        Additional fields merged **at the top level** of the response body
+                      (RFC 9457 extension members).  They are NOT nested under an
+                      ``"extra"`` key.  For example, ``extra={"item_id": 42}`` produces
+                      ``{"type": "...", "status": 404, "item_id": 42}``.
+                      Raises ``ValueError`` if any key shadows a reserved field
+                      (``type``, ``title``, ``status``, ``detail``).
+        base_url:     Override the base URL for this call only.
+
     ``base_url`` resolution order:
     1. Explicit ``base_url`` argument
     2. Value set by :func:`configure_problem_details`

{nene2_python-1.8.18 → nene2_python-1.8.19}/src/nene2/middleware/domain_exception.py

@@ -35,8 +35,11 @@ class SimpleDomainHandler:
         ]
         app.add_middleware(ErrorHandlerMiddleware, domain_handlers=handlers)
 
-    When you need a dynamic ``detail`` or ``extra`` fields derived from the exception,
-    pass an ``extra_factory`` callable::
+    When you need a dynamic ``detail`` or extra fields derived from the exception,
+    pass an ``extra_factory`` callable.  The dict returned by ``extra_factory`` is merged
+    **at the top level** of the Problem Details response (RFC 9457 extension members) —
+    the keys appear directly alongside ``type``, ``title``, etc., NOT nested under
+    an ``"extra"`` key::
 
         SimpleDomainHandler(
             PostNotFoundError,
@@ -46,6 +49,8 @@ class SimpleDomainHandler:
             detail_factory=lambda exc: str(exc),
             extra_factory=lambda exc: {"post_id": exc.post_id},
         )
+        # Response: {"type": "...", "status": 404, ..., "post_id": 123}
+        #       NOT: {"type": "...", ..., "extra": {"post_id": 123}}
     """
 
     def __init__(

{nene2_python-1.8.18 → nene2_python-1.8.19}/uv.lock

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