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

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

@@ -5,6 +5,31 @@ 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 実運用検証。
+
+### Changed
+- `SqlAlchemyQueryExecutor` の docstring に SQLite `:memory:` + `StaticPool` の注意書きを追加 (#305) (FT67)
+
+### Added
+- Field trial reports: `docs/field-trials/2026-05-field-trial-65.md` 〜 `2026-05-field-trial-67.md` (FT65〜FT67)
+
+---
+
 ## [1.8.17] — 2026-05-20
 
 FT64 フィールドトライアル — ValidationException 複数エラー実運用検証。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.17
+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-65.md

@@ -0,0 +1,54 @@
+# FT65: DatabaseHealthCheck 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: DB接続ヘルスチェック (`DatabaseHealthCheck`) と `CompositeHealthCheck` の組み合わせ実運用確認  
+**バージョン**: v1.8.17  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft65-db-health/`
+
+---
+
+## 概要
+
+`nene2.database.DatabaseHealthCheck` を `SqlAlchemyQueryExecutor` と組み合わせ、
+`CompositeHealthCheck` に渡して FastAPI の `/health` エンドポイントで利用するパターンを検証した。
+SQLite in-memory DB（正常）と存在しない DB（異常）の両方を確認。
+
+---
+
+## 実装内容
+
+- `SqlAlchemyQueryExecutor(create_engine("sqlite:///:memory:"))`: SQLite in-memory DB
+- `DatabaseHealthCheck(executor)`: `SELECT 1` で接続確認
+- `CompositeHealthCheck([db_health])`: 集約して `/health` で返却
+- 存在しない DB パスで 503 になることも確認
+
+---
+
+## テスト結果
+
+**4/4 passed**
+
+| テスト | 結果 |
+|---|---|
+| `test_healthy_db_returns_200` | PASSED |
+| `test_broken_db_returns_503` | PASSED |
+| `test_direct_database_health_check` | PASSED |
+| `test_in_memory_db_composite_check` | PASSED |
+
+---
+
+## Friction Points
+
+なし。`DatabaseHealthCheck` → `CompositeHealthCheck` → FastAPI の流れは直感的で問題なし。
+
+**特筆点**:
+- `DatabaseHealthCheck` の `SELECT 1` は軽量で本番運用に適している
+- DB 接続失敗時は例外をキャッチして `status="error"` を返す設計で、
+  ヘルスエンドポイント自体が 500 になることがない
+
+---
+
+## 結論
+
+`DatabaseHealthCheck` は実運用で問題なく使用できる。
+`SqlAlchemyQueryExecutor` と `CompositeHealthCheck` の組み合わせが自然に機能する。

nene2_python-1.8.19/docs/field-trials/2026-05-field-trial-66.md

@@ -0,0 +1,52 @@
+# FT66: AppSettings 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: 型付き設定オブジェクト (`AppSettings`) の実運用確認  
+**バージョン**: v1.8.17  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft66-app-settings/`
+
+---
+
+## 概要
+
+`nene2.config.AppSettings` を直接インスタンス化し、環境変数によるオーバーライド・
+バリデーション・`db_url` プロパティ・`SecretStr` の動作を検証した。
+
+---
+
+## 実装内容
+
+- `AppSettings()`: デフォルト値確認
+- `monkeypatch.setenv()`: 環境変数でのオーバーライド
+- 不正値（`APP_ENV=staging`、`LOG_LEVEL=VERBOSE`）でのバリデーション確認
+- `db_url` プロパティで SQLAlchemy URL 生成を確認
+- `CORS_ORIGINS` の JSON リスト形式パース確認
+
+---
+
+## テスト結果
+
+**10/10 passed**
+
+---
+
+## Friction Points
+
+### FP-1 (軽微): `str(SecretStr(""))` が `""` を返す
+
+**発生箇所**: `assert str(settings.db_password) != ""` テストが失敗
+
+**症状**: 空の `SecretStr("")` を `str()` に渡すと `""` が返る（マスクされない）。
+非空 `SecretStr("secret")` は `**********` が返る。
+
+**原因**: Pydantic の設計上の挙動で、空文字列は空文字列のまま。
+`repr()` では `SecretStr('')` と表示される。
+
+**対応**: テストを `get_secret_value() == ""` で修正。フレームワーク側は変更不要。
+
+---
+
+## 結論
+
+`AppSettings` は実運用で問題なく使用できる。
+環境変数からの自動パース（bool・int・list[str] の JSON 形式）が便利。

nene2_python-1.8.19/docs/field-trials/2026-05-field-trial-67.md

@@ -0,0 +1,75 @@
+# FT67: SqlAlchemyTransactionManager 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: トランザクション管理 (`SqlAlchemyTransactionManager`) の実運用確認  
+**バージョン**: v1.8.17 → v1.8.18 (ドキュメント追加)  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft67-transaction-manager/`
+
+---
+
+## 概要
+
+`nene2.database.SqlAlchemyTransactionManager` を使って口座振替アプリを実装し、
+`transactional()` コールバック API・ロールバック動作・コミット確認を検証した。
+
+---
+
+## 実装内容
+
+- SQLite in-memory DB に `accounts` テーブルを作成
+- `transactional(callback)`: 振替処理を 1 トランザクションで実行
+- 残高不足時は `ValueError` を raise → ロールバック
+- GET `/accounts/{name}` と POST `/transfers` エンドポイント
+
+---
+
+## テスト結果
+
+**7/7 passed** (StaticPool 修正後)
+
+| テスト | 結果 |
+|---|---|
+| `test_get_existing_account` | PASSED |
+| `test_get_nonexistent_account_returns_404` | PASSED |
+| `test_successful_transfer` | PASSED |
+| `test_insufficient_balance_returns_422` | PASSED |
+| `test_transaction_rollback_on_error` | PASSED |
+| `test_transfer_to_nonexistent_account` | PASSED |
+| `test_transactional_commits_on_success` | PASSED |
+
+---
+
+## Friction Points
+
+### FP-1: SQLite `:memory:` と `SqlAlchemyQueryExecutor` の接続分離問題
+
+**発生箇所**: `setup_db()` でテーブル作成後、`executor.fetch_one()` が `no such table: accounts` エラー
+
+**症状**:
+```
+DatabaseConnectionException: (sqlite3.OperationalError) no such table: accounts
+```
+
+**原因**: SQLAlchemy のデフォルトコネクションプールでは `sqlite:///:memory:` への接続ごとに
+新しいインメモリDBが生成される。`setup_db()` と `executor.fetch_one()` が別DBを参照する。
+
+**修正**:
+```python
+from sqlalchemy.pool import StaticPool
+
+engine = create_engine(
+    "sqlite:///:memory:",
+    connect_args={"check_same_thread": False},
+    poolclass=StaticPool,
+)
+```
+
+`SqlAlchemyQueryExecutor` の docstring に注意書きを追加 (Issue #305, v1.8.18)。
+
+---
+
+## 結論
+
+`SqlAlchemyTransactionManager.transactional()` は実運用で問題なく使用できる。
+コールバック内の例外でロールバックが正しく機能することも確認。
+SQLite in-memory DB 使用時の `StaticPool` 要件はドキュメント化済み。

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.17 → nene2_python-1.8.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.17"
+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.17 → nene2_python-1.8.19}/src/nene2/database/sqlalchemy_executor.py

@@ -14,7 +14,23 @@ from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManag
 
 
 class SqlAlchemyQueryExecutor(DatabaseQueryExecutorInterface):
-    """Execute queries using SQLAlchemy Core (connection-per-call, no ORM)."""
+    """Execute queries using SQLAlchemy Core (connection-per-call, no ORM).
+
+    .. note:: SQLite in-memory databases
+
+        When using ``sqlite:///:memory:`` in tests, each new connection receives
+        a separate empty database.  To share one in-memory DB across all
+        connections (including ``setup_db`` / schema creation) use
+        ``StaticPool``::
+
+            from sqlalchemy.pool import StaticPool
+
+            engine = create_engine(
+                "sqlite:///:memory:",
+                connect_args={"check_same_thread": False},
+                poolclass=StaticPool,
+            )
+    """
 
     def __init__(self, engine: Engine) -> None:
         self._engine = engine

{nene2_python-1.8.17 → 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.17 → 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.17 → nene2_python-1.8.19}/uv.lock

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