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

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

@@ -5,6 +5,33 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [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 複数エラー実運用検証。
+
+### Fixed
+- `ValidationError.code` にスペースが含まれる場合 `ValueError` を発生させるよう修正 — `message` と `code` の混同を早期検出できるようになった (#300) (FT64)
+
+### Changed
+- `ValidationError` と `ValidationException.single()` の docstring を改善 — `message` (人間可読) と `code` (機械可読 snake_case) の違いをキーワード引数付き例で明示 (#300) (FT64)
+
+### Added
+- Field trial report: `docs/field-trials/2026-05-field-trial-64.md`
+
+---
+
 ## [1.8.16] — 2026-05-20
 
 FT63 フィールドトライアル — configure_problem_details 実運用検証 + PROBLEM_DETAILS_BASE_URL エクスポート修正。

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

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

@@ -0,0 +1,61 @@
+# FT63: configure_problem_details / PROBLEM_DETAILS_BASE_URL 実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: Problem Details 設定 API (`configure_problem_details`, `PROBLEM_DETAILS_BASE_URL`) の実運用確認  
+**バージョン**: v1.8.15 → v1.8.16 (修正含む)  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft63-problem-details-config/`
+
+---
+
+## 概要
+
+`nene2.http.configure_problem_details()` でプロジェクト全体の base_url を設定し、
+RFC 9457 Problem Details レスポンスの `type` フィールドを自社 URL に変更する
+パターンを検証した。
+
+---
+
+## 実装内容
+
+- `configure_problem_details("https://api.example.com/errors/")`: アプリ起動時にグローバル設定
+- `reset_problem_details()`: テスト間のリセット（autouse fixture）
+- per-call `base_url` 引数がグローバル設定より優先されることを確認
+- `ValidationException` 経由の 422 でも configured base_url が使われることを確認
+
+---
+
+## テスト結果
+
+**7/7 passed** (v1.8.16 で修正後)
+
+| テスト | 結果 |
+|---|---|
+| `test_default_base_url_in_type_field` | PASSED |
+| `test_custom_base_url_applied_via_configure` | PASSED |
+| `test_custom_base_url_affects_all_problem_details_in_app` | PASSED |
+| `test_reset_problem_details_restores_default` | PASSED |
+| `test_problem_details_structure_is_rfc9457_compliant` | PASSED |
+| `test_validation_exception_uses_configured_base_url` | PASSED |
+| `test_per_call_base_url_overrides_configured` | PASSED |
+
+---
+
+## Friction Points
+
+### FP-1: `PROBLEM_DETAILS_BASE_URL` が `nene2.http` からエクスポートされていない
+
+**発生箇所**: `test_app.py` で `from nene2.http import PROBLEM_DETAILS_BASE_URL` を試みた際
+
+**症状**: `ImportError: cannot import name 'PROBLEM_DETAILS_BASE_URL' from 'nene2.http'`
+
+**影響**: テストコードでデフォルト URL を文字列のハードコードを避けられない。
+定数は `problem_details.py` に定義されているが `__init__.py` に含まれていなかった。
+
+**修正**: `nene2.http.__init__` に `PROBLEM_DETAILS_BASE_URL` を追加 (Issue #296, v1.8.16)
+
+---
+
+## 結論
+
+`configure_problem_details()` は実運用で問題なく使用できる。
+`PROBLEM_DETAILS_BASE_URL` のエクスポート漏れが修正され、テストでの文字列ハードコードを避けられる。

nene2_python-1.8.18/docs/field-trials/2026-05-field-trial-64.md

@@ -0,0 +1,67 @@
+# FT64: ValidationException 複数エラー実運用検証
+
+**日付**: 2026-05-20  
+**テーマ**: 複数フィールドの `ValidationException` 集積と `ValidationError` 実運用確認  
+**バージョン**: v1.8.16 → v1.8.17 (修正含む)  
+**FTディレクトリ**: `/home/xi/docker/nene2-python-FT/ft64-multi-validation/`
+
+---
+
+## 概要
+
+`ValidationException` を使って複数フィールドのバリデーションエラーを集積し、
+一度に 422 レスポンスとして返す実運用パターンを検証した。
+
+---
+
+## 実装内容
+
+- `RegisterUserBody`: username・email・age の 3 フィールドを Pydantic で受け取る
+- `_validate_registration()`: エラーを `list[ValidationError]` に集積して `ValidationException(errors)` を raise
+- 複数エラーが一度に返されること、Problem Details 形式であることを確認
+
+---
+
+## テスト結果
+
+**7/7 passed** (v1.8.17 で修正後)
+
+| テスト | 結果 |
+|---|---|
+| `test_valid_registration_returns_201` | PASSED |
+| `test_single_invalid_email_returns_422` | PASSED |
+| `test_underage_user_returns_422` | PASSED |
+| `test_multiple_errors_returned_at_once` | PASSED |
+| `test_422_response_is_problem_details_format` | PASSED |
+| `test_errors_include_field_message_code` | PASSED |
+| `test_pydantic_validation_error_returns_422` | PASSED |
+
+---
+
+## Friction Points
+
+### FP-1: `ValidationError(field, message, code)` の引数順で `message` と `code` を混同
+
+**発生箇所**: `app.py` で `ValidationError` を直接構築した際
+
+**症状**:
+```python
+# 意図: code="invalid_email"
+ValidationError("email", "invalid_email", "メールアドレスの形式が正しくありません")
+# → message="invalid_email", code="メールアドレスの形式が正しくありません" になってしまう
+```
+
+**原因**: `(field, message, code)` の順序で、短い機械可読コードを先に書きたくなるが
+`message` が先に来るため混同が起きやすい。
+
+**修正**: 
+- `ValidationError.code` にスペースを含む場合 `ValueError` を早期発生させる (v1.8.17)
+- docstring にキーワード引数付き例を追加してどちらが何かを明確化
+
+---
+
+## 結論
+
+`ValidationException` の複数エラー集積パターンは実運用で問題なく使用できる。
+`message` と `code` の混同を防ぐ `ValueError` と docstring 改善により、
+今後は早期にミスに気づけるようになった。

nene2_python-1.8.18/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.18/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.18/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.16 → nene2_python-1.8.18}/pyproject.toml

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

{nene2_python-1.8.16 → nene2_python-1.8.18}/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.18/src/nene2/validation/exceptions.py

@@ -0,0 +1,101 @@
+"""Validation exceptions.
+
+Equivalent to PHP Nene2\\Validation\\ValidationException and ValidationError.
+Raised by handlers or use-cases to produce a 422 validation-failed Problem Details response.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationError:
+    """A single field-level validation failure.
+
+    Args:
+        field:   The input field that failed (e.g. ``"email"``).
+        message: Human-readable description shown to the user
+                 (e.g. ``"メールアドレスの形式が正しくありません"``).
+        code:    Machine-readable identifier used by API clients to handle
+                 specific errors programmatically (e.g. ``"invalid_email"``).
+                 Must not contain spaces; use ``snake_case``.
+
+    Example::
+
+        ValidationError(
+            field="email",
+            message="メールアドレスの形式が正しくありません",
+            code="invalid_email",
+        )
+    """
+
+    field: str
+    message: str
+    code: str
+
+    def __post_init__(self) -> None:
+        for attr in ("field", "message", "code"):
+            if not getattr(self, attr):
+                raise ValueError(f"ValidationError.{attr} must not be empty")
+        if " " in self.code:
+            raise ValueError(
+                f"ValidationError.code must not contain spaces (got {self.code!r}). "
+                "Use snake_case, e.g. 'invalid_email'."
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        return {"field": self.field, "message": self.message, "code": self.code}
+
+
+class ValidationException(Exception):
+    """Raised when one or more validation rules fail.
+
+    ErrorHandlerMiddleware maps this to a 422 validation-failed Problem Details response.
+
+    For a single error, use the convenience method::
+
+        raise ValidationException.single(
+            field="email",
+            message="メールアドレスの形式が正しくありません",
+            code="invalid_email",
+        )
+
+    For multiple errors accumulated during validation::
+
+        errors: list[ValidationError] = []
+        if "@" not in email:
+            errors.append(
+                ValidationError(
+                    field="email",
+                    message="メールアドレスの形式が正しくありません",
+                    code="invalid_email",
+                )
+            )
+        if age < 18:
+            errors.append(
+                ValidationError(
+                    field="age",
+                    message="18歳以上である必要があります",
+                    code="too_young",
+                )
+            )
+        if errors:
+            raise ValidationException(errors)
+
+    Note: ``message`` is a human-readable string; ``code`` is a machine-readable
+    ``snake_case`` identifier (e.g. ``"invalid_email"``, not ``"Invalid email"``).
+    """
+
+    def __init__(self, errors: list[ValidationError]) -> None:
+        super().__init__("Validation failed")
+        self.errors = errors
+
+    @classmethod
+    def single(cls, field: str, message: str, code: str) -> "ValidationException":
+        """Convenience constructor for a single validation error.
+
+        Args:
+            field:   The input field that failed (e.g. ``"email"``).
+            message: Human-readable description (e.g. ``"Invalid email address"``).
+            code:    Machine-readable ``snake_case`` identifier (e.g. ``"invalid_email"``).
+        """
+        return cls([ValidationError(field, message, code)])

{nene2_python-1.8.16 → nene2_python-1.8.18}/tests/nene2/validation/test_exceptions.py

@@ -44,3 +44,8 @@ def test_validation_exception_single() -> None:
 def test_validation_exception_single_is_validation_exception() -> None:
     exc = ValidationException.single("f", "m", "c")
     assert isinstance(exc, ValidationException)
+
+
+def test_validation_error_code_with_spaces_raises_value_error() -> None:
+    with pytest.raises(ValueError, match="must not contain spaces"):
+        ValidationError(field="email", message="Invalid email", code="invalid email")

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

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

nene2_python-1.8.16/src/nene2/validation/exceptions.py

@@ -1,52 +0,0 @@
-"""Validation exceptions.
-
-Equivalent to PHP Nene2\\Validation\\ValidationException and ValidationError.
-Raised by handlers or use-cases to produce a 422 validation-failed Problem Details response.
-"""
-
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True, slots=True)
-class ValidationError:
-    """A single field-level validation failure."""
-
-    field: str
-    message: str
-    code: str
-
-    def __post_init__(self) -> None:
-        for attr in ("field", "message", "code"):
-            if not getattr(self, attr):
-                raise ValueError(f"ValidationError.{attr} must not be empty")
-
-    def to_dict(self) -> dict[str, str]:
-        return {"field": self.field, "message": self.message, "code": self.code}
-
-
-class ValidationException(Exception):
-    """Raised when one or more validation rules fail.
-
-    ErrorHandlerMiddleware maps this to a 422 validation-failed Problem Details response.
-
-    For a single error, use the convenience method::
-
-        raise ValidationException.single("email", "invalid", "invalid_email")
-
-    For multiple errors accumulated during validation::
-
-        errors = []
-        if not valid_email:
-            errors.append(ValidationError("email", "invalid", "invalid_email"))
-        if errors:
-            raise ValidationException(errors)
-    """
-
-    def __init__(self, errors: list[ValidationError]) -> None:
-        super().__init__("Validation failed")
-        self.errors = errors
-
-    @classmethod
-    def single(cls, field: str, message: str, code: str) -> "ValidationException":
-        """Convenience constructor for a single validation error."""
-        return cls([ValidationError(field, message, code)])