nene2-python 1.8.8__tar.gz → 1.8.9__tar.gz

{nene2_python-1.8.8 → nene2_python-1.8.9}/CHANGELOG.md

@@ -5,6 +5,18 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.9] — 2026-05-20
+
+FT46〜FT49 フィールドトライアル — ドキュメント改善。
+
+### Added
+- Field trial reports: `docs/field-trials/2026-05-field-trial-46.md` 〜 `docs/field-trials/2026-05-field-trial-49.md`
+
+### Changed
+- `docs/how-to/run-tests.md` — SQLite 外部キー制約 (`PRAGMA foreign_keys=ON`) の注意事項を追記 (FT46)
+
+---
+
 ## [1.8.8] — 2026-05-20
 
 FT45 フィールドトライアル — SecurityHeadersMiddleware CSP バグ修正。

{nene2_python-1.8.8 → nene2_python-1.8.9}/PKG-INFO

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

@@ -0,0 +1,128 @@
+# Field Trial 46: DatabaseIntegrityException 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.8 時点
+**テーマ**: `DatabaseIntegrityException` を FastAPI エンドポイント経由で UNIQUE 制約・FK 制約違反を処理するパターンの実運用確認
+
+---
+
+## 概要
+
+`SqlAlchemyQueryExecutor` を使って SQLite への UNIQUE/FK 制約違反を発生させ、
+`DatabaseIntegrityException` を `DuplicateEmailError` / `InvalidUserReferenceError` に
+サブクラス化してドメイン例外に変換し、`SimpleDomainHandler` で HTTP レスポンスにマッピングするパターンを実装した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft46-db-integrity/` に以下を作成:
+
+- **`app.py`** — SQLite + `SqlAlchemyQueryExecutor` (Core API) を使ったユーザー/ポスト管理 API
+- **`test_app.py`** — 正常系・UNIQUE 違反 409・FK 違反 422・エラー後回復 (7 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP46-1: DatabaseIntegrityException のサブクラス化が必要
+
+**分類**: 軽微な摩擦（パターン提示）
+
+`DatabaseIntegrityException` は汎用例外のため、UNIQUE 制約違反（409）と FK 制約違反（422）を
+別の HTTP ステータスコードにマッピングするには、サブクラスを作って例外を変換する必要がある。
+
+```python
+class DuplicateEmailError(DatabaseIntegrityException): pass
+class InvalidUserReferenceError(DatabaseIntegrityException): pass
+
+try:
+    executor.write("INSERT INTO users ...", params)
+except DatabaseIntegrityException as exc:
+    raise DuplicateEmailError(str(exc)) from exc
+```
+
+**判断**: データベース例外に対してドメイン固有の意味付けをするパターンとして自然。
+`IntegrityError` のメッセージを解析して違反種別を判定する方法もあるが、
+SQLite/MySQL/PostgreSQL でメッセージ形式が異なるため移植性に課題がある。
+サブクラス + 明示的 raise パターンが最も移植性が高い。
+
+---
+
+### FP46-2: SQLite の FK 制約は PRAGMA foreign_keys=ON が必要
+
+**分類**: 注意喚起（既知事項・ドキュメント追記価値あり）
+
+SQLite のデフォルトでは外部キー制約が無効。
+`create_engine()` 後に `PRAGMA foreign_keys=ON` を実行しないと、
+FK 制約違反がスルーされて孤児レコードが挿入される。
+
+```python
+with engine.begin() as conn:
+    conn.execute(text("PRAGMA foreign_keys=ON"))
+```
+
+`StaticPool` を使う場合は最初の接続でこれを実行すれば全接続に適用される。
+
+**判断**: SQLite 特有の注意点。`docs/how-to/run-tests.md` の StaticPool セクションに追記する価値がある。
+
+---
+
+### FP46-3: 整合性エラー後もトランザクションは自動ロールバックされる
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`DatabaseIntegrityException` が発生すると `SqlAlchemyQueryExecutor.write()` 内で
+`engine.begin()` のコンテキストマネージャーがロールバックする。
+次のリクエストでは新しいトランザクションが開始されるため、セッション汚染は発生しない。
+
+**判断**: SQLAlchemy Core の設計通り。`engine.begin()` を使ったパターンは安全。
+
+---
+
+### FP46-4: SqlAlchemyQueryExecutor は SQL 文字列 API であり ORM Session ではない
+
+**分類**: 摩擦あり（設計の理解不足・初回実装で失敗）
+
+当初 `SqlAlchemyQueryExecutor.write()` に ORM の `Session` を使ったコールバックを渡そうとしたが、
+`write()` は SQL 文字列 + params を受け取る Core API であることを確認した。
+
+```python
+# NG: コールバックパターン（TransactionManager のもの）
+executor.write(lambda session: session.add(row))  # TypeError
+
+# OK: SQL 文字列パターン（QueryExecutor のもの）
+executor.write("INSERT INTO users (email) VALUES (:email)", {"email": "..."})
+```
+
+ORM (Session) を使うパターンは `SqlAlchemyTransactionManager.transactional(callback)` で、
+コールバック内では `_BoundQueryExecutor` を通じて SQL を実行する。
+直接 Session を使いたい場合はフレームワーク外で SQLAlchemy ORM を使う。
+
+**判断**: フレームワークの設計通り（SQLAlchemy Core ベース）。
+ドキュメントに Core API と ORM の違いを明記する価値がある。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+ドキュメント追記を検討:
+- `docs/how-to/run-tests.md` の StaticPool セクションに SQLite FK pragma を追記
+- `docs/how-to/` に `DatabaseIntegrityException` ハンドリングパターン how-to を追加
+
+---
+
+## 関連
+
+- `nene2.database.DatabaseIntegrityException` (FT16, v1.7.0)
+- `nene2.database.SqlAlchemyQueryExecutor`
+- `nene2.database.SqlAlchemyTransactionManager`
+- `nene2.middleware.SimpleDomainHandler` (FT21, v1.8.0)
+- FT16 (DatabaseIntegrityException 実装, v1.7.0)
+- FT17 (SqlAlchemyQueryExecutor.write() バグ修正, v1.7.0)
+- FT34 (StaticPool SQLite テスト, v1.8.4)

nene2_python-1.8.9/docs/field-trials/2026-05-field-trial-47.md

@@ -0,0 +1,93 @@
+# Field Trial 47: SqlAlchemyTransactionManager.transactional() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.8 時点
+**テーマ**: `transactional()` コールバックパターンで複数テーブルへの同一トランザクション書き込みと、失敗時のロールバックを FastAPI エンドポイント経由で確認
+
+---
+
+## 概要
+
+銀行振込（送金元残高減算 + 送金先残高増加 + 転送ログ挿入の 3 操作）を
+`SqlAlchemyTransactionManager.transactional()` の単一トランザクションで実装した。
+残高不足・存在しない口座での失敗時にすべての操作がロールバックされることを確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft47-transaction-manager/` に以下を作成:
+
+- **`app.py`** — 口座管理 + 振込 API、`SqlAlchemyTransactionManager.transactional()` で複数書き込み
+- **`test_app.py`** — 正常振込・残高更新・不足残高・存在しない口座・重複名 (7 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP47-1: コールバックは DatabaseQueryExecutorInterface を受け取る
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`transactional(callback)` のコールバックは `DatabaseQueryExecutorInterface` を引数として受け取る。
+内部的には `_BoundQueryExecutor` として同一接続にバインドされており、
+`fetch_one()` / `write()` を呼ぶことで同一トランザクション内で複数操作できる。
+
+**判断**: SQLAlchemy Core を抽象化したインターフェースが自然に機能する。
+
+---
+
+### FP47-2: ドメイン例外も transactional() を自動ロールバックさせる
+
+**分類**: 摩擦なし（良い設計の確認）
+
+コールバック内で `InsufficientFundsError` のような非 DB 例外を raise した場合、
+`engine.begin()` コンテキストマネージャーが自動でロールバックしてから例外を伝播する。
+`ErrorHandlerMiddleware` がこれを `SimpleDomainHandler` でキャッチして適切な HTTP レスポンスを返す。
+
+**判断**: 設計通り。「例外発生 = ロールバック」が保証されているため、コールバック内で
+ガード条件をチェックして素直に raise するだけで整合性が保たれる。
+
+---
+
+### FP47-3: 複数 write はすべて成功かすべてロールバックか（ACID 保証）
+
+**分類**: 摩擦なし（良い設計の確認）
+
+送金処理の 3 つの write（送金元減算 / 送金先加算 / ログ挿入）は
+`transactional()` が提供する `_BoundQueryExecutor` を通じて同一トランザクションで実行される。
+途中で例外が発生した場合、実行済みの write も含めてすべてロールバックされる。
+
+**判断**: ACID の Atomicity が正しく動作することを確認した。
+
+---
+
+### FP47-4: transactional() の戻り値はコールバックの戻り値
+
+**分類**: 摩擦なし（設計の確認）
+
+`transactional()` はジェネリクス `[T]` を使ってコールバックの戻り値型を保持する。
+コミット後の戻り値（`dict[str, object]` など）をそのまま受け取り、
+FastAPI ハンドラーで `JSONResponse` に変換できる。
+
+**判断**: 型安全なコールバックパターンが正しく動作する。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.database.SqlAlchemyTransactionManager` (FT16, v1.7.0)
+- `nene2.database.DatabaseQueryExecutorInterface`
+- `nene2.database.DatabaseIntegrityException` (FT16, v1.7.0)
+- FT16 (TransactionManager 実装, v1.7.0)
+- FT38 (トランザクション管理確認, v1.8.5)
+- FT46 (DatabaseIntegrityException 実運用, v1.8.8)

nene2_python-1.8.9/docs/field-trials/2026-05-field-trial-48.md

@@ -0,0 +1,96 @@
+# Field Trial 48: CompositeHealthCheck + AsyncCompositeHealthCheck 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.8 時点
+**テーマ**: `CompositeHealthCheck` と `AsyncCompositeHealthCheck` を `/health` エンドポイントで使い、複数コンポーネントのヘルスチェックを集約するパターンの実運用確認
+
+---
+
+## 概要
+
+同期 `CompositeHealthCheck`（DB + キャッシュ）と非同期 `AsyncCompositeHealthCheck`（DB + 外部 API）を
+`/health` と `/health/async` エンドポイントで使い、部分的な失敗時の 503 レスポンスと
+`checks` フィールドへの詳細情報付与を確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft48-health-check/` に以下を作成:
+
+- **`app.py`** — `CompositeHealthCheck` + `AsyncCompositeHealthCheck` を使った FastAPI アプリ
+- **`test_app.py`** — 正常・503・checks フィールド・エラーメッセージ確認 (7 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 11 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP48-1: http_status_code プロパティで 200/503 が自動判定される
+
+**分類**: 摩擦なし（良い設計の確認）
+
+FT31 で追加した `HealthStatus.http_status_code` プロパティが
+`CompositeHealthCheck` の結果でも正しく機能する。
+`is_healthy` が `True` なら 200、`False` なら 503 を返す。
+ハンドラーで `status_code=status.http_status_code` と書くだけで適切なステータスが返る。
+
+---
+
+### FP48-2: 空のチェックリストは "ok" を返す
+
+**分類**: 摩擦なし（エッジケース確認）
+
+`CompositeHealthCheck([])` のように空リストを渡すと、
+全チェック通過として `HealthStatus(status="ok", checks={})` を返す。
+ゼロ個のチェックは「失敗するチェックがない」として ok と見なす設計は直感的。
+
+---
+
+### FP48-3: 部分的な失敗は全コンポーネントの results を含む
+
+**分類**: 摩擦なし（良い設計の確認）
+
+失敗したコンポーネントのエラーメッセージと成功したコンポーネントの "ok" が
+`checks` フィールドに混在する。
+クライアントはどのコンポーネントが失敗したかを `checks` フィールドで判別できる。
+
+```json
+{
+  "status": "error",
+  "checks": {
+    "database": "ok",
+    "cache": "connection refused"
+  }
+}
+```
+
+---
+
+### FP48-4: AsyncCompositeHealthCheck は TestClient でも並列実行される
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`AsyncCompositeHealthCheck` は `asyncio.gather()` で並列実行するため、
+TestClient（同期コンテキスト）経由でもエンドポイント内部では asyncio が使われ、
+並列性が維持される。
+50ms の遅延を持つチェックを含む場合でも、逐次実行の 2 倍未満の時間で完了する。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.http.CompositeHealthCheck` (FT22, v1.8.0)
+- `nene2.http.AsyncCompositeHealthCheck` (FT36, v1.8.4)
+- `nene2.http.HealthStatus.http_status_code` (FT31, v1.8.3)
+- FT22 (CompositeHealthCheck 実装, v1.8.0)
+- FT31 (http_status_code プロパティ追加, v1.8.3)
+- FT36 (AsyncCompositeHealthCheck 実装, v1.8.4)

nene2_python-1.8.9/docs/field-trials/2026-05-field-trial-49.md

@@ -0,0 +1,96 @@
+# Field Trial 49: AppSettings 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.8 時点
+**テーマ**: `AppSettings` の環境変数オーバーライド・バリデーション・`db_url` プロパティ・SecretStr の動作を確認
+
+---
+
+## 概要
+
+`AppSettings` の全主要機能（環境変数オーバーライド・バリデーター・`db_url` プロパティ生成・
+SecretStr によるパスワード保護・リスト型環境変数の設定方法）を確認した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft49-app-settings/` に以下を作成:
+
+- **`test_settings.py`** — AppSettings の全機能確認 (13 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP49-1: db_password は SecretStr のため repr に平文が出ない
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`db_password: SecretStr` のため、`repr(settings)` や `print(settings)` で
+パスワードが平文で出力されない。ログに誤ってパスワードが漏洩しない設計。
+
+実際の値が必要な場合は `settings.db_password.get_secret_value()` を使う。
+`db_url` プロパティが内部で呼んでいるので、通常は直接呼ぶ必要はない。
+
+**判断**: セキュリティ上の重要な設計。
+
+---
+
+### FP49-2: リスト型環境変数は JSON 配列形式で設定する
+
+**分類**: 軽微な摩擦（注意喚起）
+
+`bearer_tokens`・`api_keys`・`cors_origins` などのリスト型フィールドを
+環境変数で設定する場合、pydantic-settings は JSON 配列形式を期待する:
+
+```bash
+# OK: JSON 配列形式
+export BEARER_TOKENS='["token-a", "token-b"]'
+
+# NG: カンマ区切り（動作しない）
+export BEARER_TOKENS="token-a,token-b"
+```
+
+`LocalTokenVerifier.from_env()` (FT11) はカンマ区切りをサポートしているが、
+`AppSettings.bearer_tokens` 自体は JSON 配列形式が必要。
+
+**判断**: pydantic-settings の仕様通り。NENE2 の `README` や設定リファレンスドキュメントに
+明記する価値がある。
+
+---
+
+### FP49-3: app_env は "local" / "test" / "production" のみ
+
+**分類**: 摩擦なし（設計の確認）
+
+`validate_app_env` バリデーターで "staging" など他の値を拒否する。
+デプロイ環境を厳密に 3 種類に限定することで設定ミスを防ぐ。
+
+---
+
+### FP49-4: log_level は大文字に自動正規化される
+
+**分類**: 摩擦なし（良い設計の確認）
+
+`validate_log_level` バリデーターで "debug" → "DEBUG" に変換される。
+大文字・小文字を気にせずに設定できる。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+ドキュメント追記を検討:
+- `docs/reference/configuration.md` にリスト型環境変数の設定方法を明記
+
+---
+
+## 関連
+
+- `nene2.config.AppSettings`
+- FT11 (LocalTokenVerifier.from_env, v1.4.0)
+- FT26 (setup_logging log_level パラメータ, v1.8.1)

{nene2_python-1.8.8 → nene2_python-1.8.9}/docs/how-to/run-tests.md

@@ -103,6 +103,17 @@ 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.
 
+**SQLite foreign-key enforcement**: SQLite disables foreign-key constraints by default. Enable them with `PRAGMA foreign_keys=ON` right after the engine is created:
+
+```python
+from sqlalchemy import text
+
+with engine.begin() as conn:
+    conn.execute(text("PRAGMA foreign_keys=ON"))
+```
+
+With `StaticPool`, one call applies to the single shared connection, so all subsequent operations see FK constraints enforced.
+
 ## 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.

{nene2_python-1.8.8 → nene2_python-1.8.9}/pyproject.toml

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

{nene2_python-1.8.8 → nene2_python-1.8.9}/uv.lock

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