nene2-python 1.0.0__tar.gz → 1.1.0__tar.gz

{nene2_python-1.0.0 → nene2_python-1.1.0}/PKG-INFO

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

@@ -0,0 +1,170 @@
+# Field Trial 7 — bookmark: PyPI publish フロー DX 検証
+
+## Date
+
+2026-05-20
+
+## Baseline
+
+- nene2-python v1.0.0（**PyPI 経由** `uv add nene2-python`）
+- Python 3.14（uv managed）
+- プロジェクト: **bookmark** — ブックマーク管理 JSON API
+- エンティティ: `Bookmark`（id, title, url, description）
+- 5 エンドポイント: CRUD（List / Get / Create / Update / Delete）
+- InMemory リポジトリのみ（SQLite なし）
+- **目標**: `pip install nene2-python` → ゼロ設定で動く API を構築できるか
+
+## Goal
+
+1. PyPI 公開フローの DX 検証（TestPyPI → PyPI 本番）
+2. `uv add nene2-python`（PyPI 経由）でのインストールが正常に機能するか確認
+3. 公開パッケージだけを使ってブックマーク API を構築する E2E DX 検証
+
+---
+
+## Steps Taken
+
+### 1. PyPI 公開フロー
+
+#### TestPyPI
+
+- GitHub Actions OIDC（Trusted Publishing）を設定
+- `uv publish --trusted-publishing always` を使用
+- `pypa/gh-action-pypi-publish@release/v1` は Docker コンテナ内で実行されるため、
+  GitHub Actions の Docker ネットワークで DNS 解決が失敗する問題が発生
+  → `uv publish` をランナー直接実行に切り替えて解決
+
+#### PyPI 本番
+
+- TestPyPI 確認後、同一ワークフローで本番 PyPI へ publish
+- GitHub Release を自動生成（`gh release create`）
+
+### 2. プロジェクト初期化
+
+```bash
+uv init --name bookmark --no-workspace
+uv add nene2-python   # PyPI から v1.0.0 をインストール
+```
+
+追加設定不要。`nene2-python` が FastAPI・Pydantic・SQLAlchemy・structlog をすべて束ねているため、
+依存関係の解決は `uv add nene2-python` 一行で完了。
+
+### 3. ドメイン層の実装
+
+Clean Architecture の4層（entity / exceptions / repository / use_case）を独立して記述：
+
+```python
+# entity.py
+@dataclass(frozen=True, slots=True)
+class Bookmark:
+    id: int
+    title: str
+    url: str
+    description: str
+```
+
+`nene2` からインポートが必要なのは exceptions のみ：
+```python
+from nene2.http import problem_details_response
+from nene2.middleware.domain_exception import DomainExceptionHandlerProtocol
+```
+
+UseCase・Repository・Entity は nene2 に依存しないため、フレームワーク非依存のビジネスロジックとして成立。
+
+### 4. HTTP 層の実装
+
+`handler.py` で `nene2.http`・`nene2.validation` を使用：
+
+```python
+from nene2.http import PaginationQueryParser, PaginationResponse
+from nene2.validation.exceptions import ValidationError, ValidationException
+```
+
+パターンは example/note/handler.py と完全に同じ。5分で移植可能。
+
+### 5. アプリケーションファクトリ
+
+`app.py` でミドルウェアをスタックして完成：
+
+```python
+from nene2.config import AppSettings
+from nene2.middleware import (
+    ErrorHandlerMiddleware, RequestIdMiddleware,
+    RequestLoggingMiddleware, RequestSizeLimitMiddleware,
+    SecurityHeadersMiddleware,
+)
+```
+
+ミドルウェア登録は innermost-first 順で明示的（ドキュメントにコメントあり）。
+
+### 6. 動作確認
+
+```bash
+uv run uvicorn app:app --port 8090
+```
+
+```
+POST /bookmarks  {"title":"GitHub","url":"https://github.com","description":"Code hosting"}
+→ 201  {"id":1,"title":"GitHub","url":"https://github.com","description":"Code hosting"}
+
+GET  /bookmarks?limit=10&offset=0
+→ 200  {"items":[...],"limit":10,"offset":0,"total":2}
+
+GET  /bookmarks/1
+→ 200  {"id":1,...}
+
+PUT  /bookmarks/1  {"title":"GitHub Updated","url":"https://github.com","description":"World's largest code host"}
+→ 200  {"id":1,"title":"GitHub Updated",...}
+
+DELETE /bookmarks/2
+→ 204
+
+GET  /bookmarks/99
+→ 404  {"type":"https://nene2.dev/problems/not-found","title":"Not Found","status":404,"detail":"Bookmark 99 not found."}
+
+POST /bookmarks  {"title":"   ","url":"https://example.com","description":""}
+→ 422  {"type":"https://nene2.dev/problems/validation-failed","errors":[{"field":"title","message":"Title must not be empty.","code":"required"}]}
+```
+
+全エンドポイントが期待通りに動作。Problem Details（RFC 9457）レスポンスも正常。
+
+---
+
+## Friction Points
+
+### FT7-1: Docker DNS 問題（`pypa/gh-action-pypi-publish`）
+
+- **摩擦**: `pypa/gh-action-pypi-publish@release/v1` を使用すると、Docker コンテナ内で
+  `upload.test.pypi.org` の DNS 解決に失敗する
+- **深刻度**: HIGH（公開ブロック）
+- **解決策**: `uv publish --trusted-publishing always` をランナー直接実行に切り替え
+- **所要時間**: ワークフロー修正・デバッグで約 1 時間
+
+### FT7-2: `[tool.uv] dev-dependencies` → `[dependency-groups]` 変更
+
+- **摩擦**: `uv init` が生成した `pyproject.toml` に旧形式の `[tool.uv] dev-dependencies` が含まれる場合がある（uv バージョン依存）
+- **深刻度**: LOW（警告のみ）
+- **解決策**: `[dependency-groups] dev` 形式に更新
+
+### FT7-3: `InMemoryRepository` を毎回自前実装
+
+- **摩擦**: テスト用 InMemory Repository をドメインごとにゼロから書く必要がある
+- **深刻度**: LOW（パターンが明確なため機械的に書ける）
+- **検討**: `GenericInMemoryRepository[T]` のような汎用実装をフレームワークに含めるか検討余地あり
+
+---
+
+## Summary
+
+| ID     | 摩擦                                      | 深刻度 | 種別          | Follow-up |
+|--------|-------------------------------------------|--------|---------------|-----------|
+| FT7-1  | Docker DNS で pypa action が失敗          | HIGH   | インフラ      | 解決済み（uv publish に切り替え） |
+| FT7-2  | dev-dependencies フォーマット警告         | LOW    | DX            | 解決済み（PR #154） |
+| FT7-3  | InMemory Repository を毎回書く            | LOW    | フレームワーク | 検討余地あり |
+
+FT7 の主目的（PyPI 公開 → インストール → 動く API 構築）は達成。
+`uv add nene2-python` の一行でフレームワーク全体が入り、
+Clean Architecture パターンをゼロから構築するのに要した時間は **30分以内**（ドメイン4ファイル + handler + app）。
+
+**PyPI publish パイプライン（TestPyPI → PyPI → GitHub Release）は確立済み。**
+FT8 候補：MySQL/PostgreSQL アダプターの実地検証、または親子リソース（nested REST）DX 検証。

nene2_python-1.1.0/docs/field-trials/2026-05-field-trial-8.md

@@ -0,0 +1,218 @@
+# Field Trial 8 — blog: 親子リソース (Nested REST) + datetime + SQLite 複数エンティティ
+
+## Date
+
+2026-05-20
+
+## Baseline
+
+- nene2-python v1.0.0（PyPI 経由 `uv add nene2-python`）
+- Python 3.14（uv managed）
+- プロジェクト: **blog** — ブログ API（投稿 + コメント）
+- エンティティ:
+  - `Post(id, title, body, created_at: datetime)`
+  - `Comment(id, post_id, author, body, created_at: datetime)`
+- SQLite ファイル永続化（`blog.db`）
+- 8 エンドポイント: Post CRUD + コメント List/Create/Delete（Nested REST）
+
+## Goal
+
+FT1〜FT7 で未探索のパターンを一度に検証：
+
+1. **親子リソース（Nested REST）**: `GET /posts/{id}/comments`、`POST /posts/{id}/comments`
+2. **`datetime` フィールドを持つエンティティ**: `created_at` が SQLite → entity → JSON でどう流れるか
+3. **SQLite 外部キー**: 2エンティティ間の参照整合性（`ON DELETE CASCADE`）
+4. **`DatabaseHealthCheck`** の実際の動作確認
+
+---
+
+## Steps Taken
+
+### 1. プロジェクト初期化
+
+問題なし。`uv add nene2-python` 一行で完了。
+
+### 2. エンティティに `datetime` フィールドを追加
+
+```python
+@dataclass(frozen=True, slots=True)
+class Post:
+    id: int
+    title: str
+    body: str
+    created_at: datetime   # ← FT1〜FT7 で一度も使われなかったフィールド
+```
+
+FT1〜FT7 の全エンティティ（Note, Book, Task, Snippet, Wallet, City, Bookmark）は
+`created_at` を持っていない。example の Note も schema に `created_at` カラムはあるが
+エンティティ定義には含まれていない。**datetime フィールドの扱いは前例なし。**
+
+### 3. SQLite スキーマ（外部キー + `CURRENT_TIMESTAMP`）
+
+```python
+# PRAGMA foreign_keys=ON で参照整合性を有効化
+@event.listens_for(Engine, "connect")
+def _set_sqlite_pragma(dbapi_conn, _):
+    if isinstance(dbapi_conn, sqlite3.Connection):
+        dbapi_conn.execute("PRAGMA foreign_keys=ON")
+
+# comments テーブルに外部キー
+"post_id INTEGER NOT NULL REFERENCES posts(id) ON DELETE CASCADE"
+```
+
+`PRAGMA foreign_keys=ON` は example の schema.py を参照して発見。ドキュメントには記載なし。
+
+### 4. SQLAlchemy Repository での datetime 変換
+
+```python
+def _to_post(row: dict[str, Any]) -> Post:
+    return Post(
+        id=row["id"],
+        title=row["title"],
+        body=row["body"],
+        # SQLite は DATETIME を text 型で返す: "2026-05-20 12:34:56"
+        created_at=datetime.fromisoformat(str(row["created_at"])).replace(tzinfo=timezone.utc),
+    )
+```
+
+### 5. SELECT-after-INSERT パターン（DB生成タイムスタンプを取得）
+
+```python
+def save(self, title: str, body: str) -> Post:
+    new_id = self._executor.write(
+        "INSERT INTO posts (title, body) VALUES (:title, :body)",
+        {"title": title, "body": body},
+    )
+    row = self._executor.fetch_one(
+        "SELECT id, title, body, created_at FROM posts WHERE id = :id",
+        {"id": new_id},
+    )
+    if row is None:
+        raise RuntimeError(f"Row {new_id} not found after INSERT into posts")
+    return _to_post(row)
+```
+
+INSERT → `write()` → `lastrowid` → `fetch_one()` の2往復が必要。
+
+### 6. Nested REST ハンドラー
+
+```python
+@router.get("/posts/{post_id}/comments")
+async def list_comments(post_id: int, request: Request) -> JSONResponse:
+    pagination = PaginationQueryParser.parse(request)
+    output = list_comments_use_case.execute(
+        ListCommentsInput(post_id, pagination.limit, pagination.offset)
+    )
+    ...
+
+@router.post("/posts/{post_id}/comments", status_code=201)
+async def create_comment(post_id: int, body: CreateCommentBody) -> JSONResponse:
+    ...
+```
+
+FastAPI がパスパラメータ `post_id` を UseCase に渡すため、ネストの実装自体は自然。
+
+### 7. 動作確認
+
+```
+GET  /health
+→ 200  {"status":"ok","checks":{"database":"ok"}}  ← DatabaseHealthCheck 正常
+
+POST /posts  {"title":"Hello nene2","body":"First post"}
+→ 201  {"id":1,"title":"Hello nene2","body":"First post","created_at":"2026-05-19T18:39:52+00:00"}
+
+POST /posts/1/comments  {"author":"Alice","body":"Great!"}
+→ 201  {"id":1,"post_id":1,"author":"Alice","body":"Great!","created_at":"2026-05-19T18:39:52+00:00"}
+
+GET  /posts/1/comments?limit=10
+→ 200  {"items":[...],"limit":10,"offset":0,"total":1}
+
+POST /posts/999/comments  {...}
+→ 404  {"type":"...not-found","detail":"Post 999 not found."}
+
+DELETE /posts/1
+→ 204  (cascade: comments も自動削除)
+
+GET  /posts/1/comments  (削除後)
+→ 404  Post 1 not found.
+```
+
+---
+
+## Friction Points
+
+### FT8-1: SQLite `CURRENT_TIMESTAMP` が naive datetime を返す — タイムゾーン情報が失われる
+
+- **摩擦**: `CURRENT_TIMESTAMP` は UTC 時刻だが SQLite は `"2026-05-20 12:34:56"` という文字列で格納・返却する
+- `datetime.fromisoformat("2026-05-20 12:34:56")` は **naive datetime**（tzinfo なし）を返す
+- JSON にシリアライズすると `"2026-05-20T12:34:56"` — タイムゾーンが不明な時刻として API に漏れる
+- **深刻度**: MEDIUM（API 利用者が UTC か JST か判断できない）
+- **解決策**: `.replace(tzinfo=timezone.utc)` を明示的に追加
+- **nene2 の対応**: `fetch_one` / `fetch_all` の戻り値に datetime フィールドのガイダンスがない
+
+### FT8-2: `dict[str, object]` vs `dict[str, Any]` — 型注釈の落とし穴
+
+- **摩擦**: `_to_post(row: dict[str, object])` と書くと `int(row["id"])` が mypy `call-overload` エラー
+- `# type: ignore[arg-type]` を付けると「wrong error code」で `unused-ignore` が発生（二重エラー）
+- **深刻度**: MEDIUM（mypy --strict を使う場合にブロッキング）
+- **解決策**: `dict[str, Any]` を使う（`fetch_one()` の実際の戻り値型と一致）
+- **根本原因**: nene2 の「row-to-entity 変換」サンプルに datetime フィールドがない
+
+### FT8-3: SELECT-after-INSERT のボイラープレート
+
+- **摩擦**: DB 生成の `CURRENT_TIMESTAMP` を取得するために INSERT → `lastrowid` → `fetch_one` の2往復が必要
+- 毎 `save()` メソッドに同じパターンを書く（PostRepository と CommentRepository の両方）
+- `fetch_one()` は `dict | None` を返すため、`if row is None: raise RuntimeError(...)` が必要
+  - `assert row is not None` は ruff S101（本番コードで assert 禁止）で弾かれる
+- **深刻度**: LOW（機能するが冗長）
+- **検討**: `write_and_return(sql, params, select_sql)` のようなヘルパーをフレームワークに追加するか
+
+### FT8-4: if/else で異なる実装を変数に代入すると mypy エラー
+
+- **摩擦**:
+
+  ```python
+  if cfg.db_adapter == "sqlite":
+      post_repo = SqlAlchemyPostRepository(executor)
+  else:
+      post_repo = InMemoryPostRepository()  # ← mypy: Incompatible types
+  ```
+
+- `mypy --strict` が `Incompatible types in assignment` を報告
+- **解決策**: 事前に型注釈を宣言する
+
+  ```python
+  post_repo: PostRepositoryInterface
+  ```
+
+- **深刻度**: LOW（パターンを一度知れば1行で解決）
+- example の `app.py` は `_build_repositories()` 関数で隠蔽しているため、このエラーが見えにくい
+
+### FT8-5: Nested REST の `post_id` パスパラメータが DELETE で無視される — 設計の穴
+
+- **摩擦**: `DELETE /posts/{post_id}/comments/{comment_id}` の `post_id` を DELETE ハンドラーが無視する
+- `DELETE /posts/1/comments/2` が post 2 のコメント2（別ポストのコメント）を削除できてしまう
+- REST セマンティクス的には `/posts/1/comments/2` は「post 1 に属するコメント2」を指すべき
+- **深刻度**: MEDIUM（アクセス制御がある場合はセキュリティ問題になりうる）
+- **解決策**: DELETE UseCase に `post_id` を含め、コメントの `post_id` と一致するか検証する
+- **nene2 の対応**: ネストリソースの DELETE 設計についてガイダンスなし
+
+---
+
+## Summary
+
+| ID     | 摩擦                                          | 深刻度 | 種別           | 解決策                              |
+|--------|-----------------------------------------------|--------|----------------|-------------------------------------|
+| FT8-1  | SQLite naive datetime — TZ情報が失われる      | MEDIUM | 設計/DB        | `.replace(tzinfo=timezone.utc)`    |
+| FT8-2  | `dict[str, object]` vs `Any` — mypy エラー  | MEDIUM | 型安全         | `dict[str, Any]` を使う            |
+| FT8-3  | SELECT-after-INSERT ボイラープレート          | LOW    | フレームワーク | `write_and_return()` ヘルパー検討  |
+| FT8-4  | if/else 分岐での型注釈宣言が必要             | LOW    | 型安全         | `var: InterfaceType` を先に宣言    |
+| FT8-5  | Nested DELETE で `post_id` が無視される       | MEDIUM | 設計           | UseCase に `post_id` を追加して検証 |
+
+親子リソース（Nested REST）そのものの実装は **摩擦ゼロ** — FastAPI のパスパラメータが自然に機能した。
+主な摩擦は `datetime` フィールドと `mypy --strict` 周辺に集中。
+
+FT9 候補:
+- **FT8-1/FT8-3 の改善**: nene2 フレームワークに `datetime` ユーティリティ / `write_and_return()` を追加して検証
+- **MySQL/PostgreSQL**: SQLite 以外のアダプター（`RETURNING` 句が使えるので FT8-3 が解消されるか検証）
+- **HttpxMcpClient**: HTTP モードの MCP クライアントを実地検証

{nene2_python-1.0.0 → nene2_python-1.1.0}/docs/how-to/sqlalchemy-repository.md

@@ -42,9 +42,10 @@ def ensure_schema(executor: DatabaseQueryExecutorInterface) -> None:
 ### Row-to-entity helper
 
 `fetch_one` / `fetch_all` return `dict[str, Any]`.
-Use a private static method to centralise the cast and keep each query method lean.
+Use a private static method to centralise the mapping and keep each query method lean.
 
 ```python
+from typing import Any
 from .entity import Book
 from .repository import BookRepositoryInterface
 
@@ -53,20 +54,21 @@ class SqlAlchemyBookRepository(BookRepositoryInterface):
         self._executor = executor
 
     @staticmethod
-    def _to_book(row: dict[str, object]) -> Book:
+    def _to_book(row: dict[str, Any]) -> Book:
         return Book(
-            id=int(row["id"]),              # type: ignore[arg-type]
-            title=str(row["title"]),
-            author=str(row["author"]),
-            isbn=str(row["isbn"]),
-            published_year=int(row["published_year"]),  # type: ignore[arg-type]
+            id=row["id"],
+            title=row["title"],
+            author=row["author"],
+            isbn=row["isbn"],
+            published_year=row["published_year"],
         )
 ```
 
-> `# type: ignore[arg-type]` is acceptable here: SQLAlchemy returns column values as
-> `int | str | float | None | …` depending on the driver, so the cast is correct
-> but the static type is `object`. Centralising casts in `_to_entity()` keeps
-> `type: ignore` in one place and out of every query method.
+> Use `dict[str, Any]` — not `dict[str, object]`.
+> `fetch_one()` / `fetch_all()` return `dict[str, Any]`, so `row["id"]` is `Any`
+> which is assignable to `int` under `mypy --strict` without any casts.
+> Using `dict[str, object]` instead requires `# type: ignore[call-overload]`
+> and triggers follow-up `unused-ignore` errors.
 
 ### Full implementation
 
@@ -85,7 +87,7 @@ class SqlAlchemyBookRepository(BookRepositoryInterface):
 
     def count_all(self) -> int:
         row = self._executor.fetch_one("SELECT COUNT(*) AS cnt FROM books")
-        return int(row["cnt"]) if row else 0  # type: ignore[arg-type]
+        return int(row["cnt"]) if row else 0
 
     def find_by_id(self, book_id: int) -> Book | None:
         row = self._executor.fetch_one(
@@ -117,13 +119,13 @@ class SqlAlchemyBookRepository(BookRepositoryInterface):
         self._executor.write("DELETE FROM books WHERE id = :id", {"id": book_id})
 
     @staticmethod
-    def _to_book(row: dict[str, object]) -> Book:
+    def _to_book(row: dict[str, Any]) -> Book:
         return Book(
-            id=int(row["id"]),              # type: ignore[arg-type]
-            title=str(row["title"]),
-            author=str(row["author"]),
-            isbn=str(row["isbn"]),
-            published_year=int(row["published_year"]),  # type: ignore[arg-type]
+            id=row["id"],
+            title=row["title"],
+            author=row["author"],
+            isbn=row["isbn"],
+            published_year=row["published_year"],
         )
 ```
 
@@ -156,6 +158,20 @@ def _build_repository(cfg: AppSettings) -> BookRepositoryInterface:
     return InMemoryBookRepository()      # fallback for tests / local dev
 ```
 
+> Wrap the if/else branch in a helper function like `_build_repository()` that
+> returns the interface type. This is cleaner than declaring `repo: BookRepositoryInterface`
+> before an if/else block in `create_app()` — both approaches satisfy `mypy --strict`,
+> but the helper keeps `create_app()` readable.
+>
+> If you prefer inline branching, declare the type first:
+> ```python
+> repo: BookRepositoryInterface
+> if cfg.db_adapter == "sqlite":
+>     repo = SqlAlchemyBookRepository(executor)
+> else:
+>     repo = InMemoryBookRepository()
+> ```
+
 > `StaticPool` is required for SQLite in-memory databases (`DB_NAME=:memory:`) to prevent
 > SQLAlchemy from opening multiple connections — each of which would see an empty database.
 > File-based SQLite and other adapters do not need it.
@@ -192,7 +208,147 @@ if affected == 0:
 
 ---
 
-## 4. Use `InMemoryXxxRepository` in tests
+## 4. Entities with `datetime` fields
+
+When your entity has a `created_at: datetime` field backed by a database-generated
+`DEFAULT CURRENT_TIMESTAMP`, use `parse_db_datetime()` from `nene2.database`.
+
+### Why it is needed
+
+SQLite stores `CURRENT_TIMESTAMP` as a **plain string** (`"2026-05-20 12:34:56"`),
+not as a Python `datetime` object. `datetime.fromisoformat()` parses the string but
+returns a **naive** datetime (no timezone), so the JSON response leaks an ambiguous
+timestamp. `parse_db_datetime()` handles all three cases transparently:
+
+| Driver | Raw value | After `parse_db_datetime()` |
+|---|---|---|
+| SQLite | `"2026-05-20 12:34:56"` (str) | `datetime(…, tzinfo=UTC)` |
+| MySQL/PostgreSQL | naive `datetime` object | `datetime(…, tzinfo=UTC)` |
+| MySQL/PostgreSQL | aware `datetime` object | unchanged |
+
+### Schema
+
+```python
+"created_at DATETIME DEFAULT CURRENT_TIMESTAMP"
+```
+
+### SELECT-after-INSERT pattern
+
+After `write()` you only get back the `lastrowid`, not the DB-generated `created_at`.
+Do a second `fetch_one()` to retrieve the full row:
+
+```python
+from datetime import datetime
+from typing import Any
+
+from nene2.database import DatabaseQueryExecutorInterface, parse_db_datetime
+
+from .entity import Post
+
+def _to_post(row: dict[str, Any]) -> Post:
+    return Post(
+        id=row["id"],
+        title=row["title"],
+        body=row["body"],
+        created_at=parse_db_datetime(row["created_at"]),
+    )
+
+class SqlAlchemyPostRepository(PostRepositoryInterface):
+    def save(self, title: str, body: str) -> Post:
+        new_id = self._executor.write(
+            "INSERT INTO posts (title, body) VALUES (:title, :body)",
+            {"title": title, "body": body},
+        )
+        row = self._executor.fetch_one(
+            "SELECT id, title, body, created_at FROM posts WHERE id = :id",
+            {"id": new_id},
+        )
+        if row is None:
+            raise RuntimeError(f"Row {new_id} not found after INSERT into posts")
+        return _to_post(row)
+```
+
+> The `if row is None: raise RuntimeError(...)` guard is needed because `fetch_one()`
+> returns `dict | None`. The row cannot actually be `None` right after INSERT — the guard
+> exists to satisfy the type checker. Prefer `RuntimeError` over `assert`: `assert`
+> is stripped by `python -O` and flagged by ruff's S101 rule in non-test code.
+
+### InMemory repository with datetime
+
+The `InMemoryXxxRepository` should generate the timestamp in Python:
+
+```python
+from datetime import datetime, timezone
+
+def save(self, title: str, body: str) -> Post:
+    now = datetime.now(timezone.utc)
+    post = Post(id=self._next_id, title=title, body=body, created_at=now)
+    self._store[self._next_id] = post
+    self._next_id += 1
+    return post
+```
+
+### JSON serialisation
+
+`datetime.isoformat()` on a UTC-aware datetime produces `"2026-05-20T12:34:56+00:00"`.
+Return it as a string in the response dict:
+
+```python
+def _post_dict(post: Post) -> dict[str, object]:
+    return {
+        "id": post.id,
+        "title": post.title,
+        "body": post.body,
+        "created_at": post.created_at.isoformat(),   # "2026-05-20T12:34:56+00:00"
+    }
+```
+
+---
+
+## 5. Nested resources — ownership validation in DELETE
+
+When a resource is nested under a parent (e.g. `DELETE /posts/{post_id}/comments/{comment_id}`),
+always validate that the child belongs to the parent in the UseCase, not just in the database.
+
+### Wrong — ignores `post_id`
+
+```python
+# handler
+@router.delete("/posts/{post_id}/comments/{comment_id}", status_code=204)
+async def delete_comment(post_id: int, comment_id: int) -> None:
+    delete_use_case.execute(DeleteCommentInput(comment_id))  # post_id unused!
+```
+
+This allows `DELETE /posts/1/comments/5` to delete comment 5 even when it belongs to post 2.
+
+### Correct — validate ownership in the UseCase
+
+```python
+# use_case.py
+@dataclass(frozen=True, slots=True)
+class DeleteCommentInput:
+    post_id: int
+    comment_id: int
+
+class DeleteCommentUseCase:
+    def execute(self, input_: DeleteCommentInput) -> None:
+        comment = self._repository.find_by_id(input_.comment_id)
+        if comment is None or comment.post_id != input_.post_id:
+            raise CommentNotFoundException(input_.comment_id)
+        self._repository.delete(input_.comment_id)
+
+# handler
+@router.delete("/posts/{post_id}/comments/{comment_id}", status_code=204)
+async def delete_comment(post_id: int, comment_id: int) -> None:
+    delete_use_case.execute(DeleteCommentInput(post_id, comment_id))
+```
+
+> The same pattern applies to GET and PUT on nested resources:
+> always pass `post_id` into the UseCase and verify `comment.post_id == input_.post_id`.
+
+---
+
+## 6. Use `InMemoryXxxRepository` in tests
 
 Never mock the database. Use the in-memory implementation for unit tests:
 
@@ -232,7 +388,7 @@ def _make_repo() -> SqlAlchemyBookRepository:
 
 ---
 
-## 5. Atomic multi-write operations with `transactional()`
+## 7. Atomic multi-write operations with `transactional()`
 
 When a UseCase needs to write to multiple tables atomically, use `SqlAlchemyTransactionManager.transactional()` together with `_in_tx` repository methods.
 

{nene2_python-1.0.0 → nene2_python-1.1.0}/pyproject.toml

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

{nene2_python-1.0.0 → nene2_python-1.1.0}/src/nene2/database/__init__.py

@@ -4,6 +4,7 @@ from .exceptions import DatabaseConnectionException
 from .health import DatabaseHealthCheck
 from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManagerInterface
 from .sqlalchemy_executor import SqlAlchemyQueryExecutor, SqlAlchemyTransactionManager
+from .utils import parse_db_datetime
 
 __all__ = [
     "DatabaseConnectionException",
@@ -12,4 +13,5 @@ __all__ = [
     "DatabaseTransactionManagerInterface",
     "SqlAlchemyQueryExecutor",
     "SqlAlchemyTransactionManager",
+    "parse_db_datetime",
 ]