nene2-python 1.8.39__tar.gz → 1.8.41__tar.gz

{nene2_python-1.8.39 → nene2_python-1.8.41}/PKG-INFO

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

@@ -0,0 +1,272 @@
+# FT169: typing モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `typing` モジュール — `TypedDict`・`Protocol`・`overload`・`Literal`・`TypeGuard`・`Required`/`NotRequired`
+**セキュリティ診断**: なし（169 % 3 = 2）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `typing` モジュール（Python 3.12+ の先進的な機能を含む）を
+nene2-python フレームワーク上で検証した。
+`typing` は nene2 の「strict typing」設計哲学の根幹であり、
+HTTP 境界の型安全性・ドメインモデルの不変性・プロトコルによる構造的サブタイピングを
+支える重要モジュール。
+CLAUDE.md の型安全ポリシー（`Any` 禁止・`TypedDict`・`Protocol` 活用）に直接対応する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft169-typing/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `NoteDict` (TypedDict) | 構造化辞書の型定義。`id`, `title`, `content` |
+| `NoteCreateDict` (TypedDict) | `NotRequired[str]` でオプショナルフィールドを表現 |
+| `NoteWithMetaDict` (TypedDict 継承) | `total=False` でオプショナル拡張フィールドを追加 |
+| `Serializable` (Protocol) | `@runtime_checkable` で `isinstance()` チェック可能な構造的サブタイプ |
+| `Closeable` (Protocol) | `close()` を持つリソースのプロトコル |
+| `parse_id()` (@overload) | `str` 引数 → `int \| None`、`int` 引数 → `int` の型多態性 |
+| `double()` (@overload) | `int` / `str` / `float` それぞれに異なる戻り値型 |
+| `SortOrder` / `NoteStatus` / `HttpStatusCode` (Literal) | `type` エイリアス + `Literal` で定数列挙 |
+| `is_note_dict()` (TypeGuard) | 実行時の型絞り込み関数 |
+| `build_search_params()` | `Required` / `NotRequired` を持つ `SearchQuery` TypedDict の利用例 |
+| `inspect_hints()` | `get_type_hints()` で実行時にクラスメソッドの型情報を取得 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/typing/notes` | TypedDict でノートを作成 |
+| GET | `/typing/notes` | Literal `SortOrder` でノートをソート |
+| POST | `/typing/notes/tags` | TypedDict 継承でタグを追加 |
+| GET | `/typing/parse-id` | @overload — 文字列 → int 変換 |
+| GET | `/typing/double` | @overload — 型別の倍返し |
+| POST | `/typing/search` | Required/NotRequired を持つ SearchQuery |
+| GET | `/typing/type-guard` | TypeGuard で型絞り込み |
+| GET | `/typing/protocol` | Protocol + is_serializable() |
+| POST | `/typing/close-resources` | Closeable Protocol でリソース管理 |
+| GET | `/typing/hints` | get_type_hints() でクラスのヒント取得 |
+| GET | `/typing/filter-status` | Literal[NoteStatus] でフィルタリング |
+| GET | `/typing/response` | Literal[HttpStatusCode] でレスポンス生成 |
+
+---
+
+## テスト結果
+
+**45 passed（摩擦ゼロ）**
+
+```
+45 passed in 0.86s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `type` エイリアス構文（Python 3.12+）で `Literal` を名前付き型にできる
+
+```python
+type SortOrder = Literal["asc", "desc"]
+type NoteStatus = Literal["draft", "published", "archived"]
+type HttpStatusCode = Literal[200, 201, 204, 400, 401, 403, 404, 422, 500]
+```
+
+Python 3.12 の `type` ステートメントを使うと、`Literal` に意味のある名前がつく。
+`TypeAlias` アノテーション（旧形式）より明示的で mypy --strict に通る。
+定数の列挙は Enum でなく Literal + type エイリアスが軽量な代替になる。
+
+### 観察2: `TypedDict` + `NotRequired` で HTTP BodyModel の代替が作れる
+
+```python
+class NoteCreateDict(TypedDict):
+    title: str
+    content: NotRequired[str]  # 省略可能
+```
+
+Pydantic BaseModel が必要な HTTP 境界では引き続き Pydantic を使うが、
+UseCase 内部のデータ構造・関数の引数・レポジトリの返り値には
+`TypedDict` が軽量で mypy に完全対応する。
+`total=False` よりも `NotRequired` を使う方が、どのフィールドが省略可能かが明確。
+
+### 観察3: `@runtime_checkable Protocol` で `isinstance()` による構造的型チェックが可能
+
+```python
+@runtime_checkable
+class Serializable(Protocol):
+    def to_dict(self) -> dict[str, object]: ...
+
+note = InMemoryNote(1, "Test")
+assert isinstance(note, Serializable)  # True — クラス継承不要
+```
+
+`InMemoryNote` は `Serializable` を継承していないが、`to_dict()` を持つため
+`isinstance()` が `True` を返す。
+nene2 のリポジトリパターンで「`to_dict()` を持つドメインオブジェクトなら何でも受け付ける」
+関数を書くときに有効。ただし `@runtime_checkable` はメソッドの「存在」しか確認せず、
+引数・戻り値型の一致は確認しない。
+
+### 観察4: `@overload` で引数の型による戻り値型の分岐を型安全に表現できる
+
+```python
+@overload
+def parse_id(value: str) -> int | None: ...
+@overload
+def parse_id(value: int) -> int: ...
+
+def parse_id(value: str | int) -> int | None:
+    ...
+```
+
+`parse_id(42)` のとき mypy は戻り値を `int`（`None` なし）と判断し、
+`parse_id("foo")` のとき `int | None` と判断する。
+`None` チェックを呼び出し側で毎回書く必要がなくなる箇所で効果的。
+
+### 観察5: `TypeGuard` で `Any` 型の辞書を型安全に絞り込める
+
+```python
+def is_note_dict(obj: object) -> TypeGuard[NoteDict]:
+    if not isinstance(obj, dict):
+        return False
+    return (
+        isinstance(obj.get("id"), int)
+        and isinstance(obj.get("title"), str)
+        and isinstance(obj.get("content"), str)
+    )
+
+def process_unknown(data: Any) -> str:
+    if is_note_dict(data):
+        return note_summary(data)  # mypy はここで data を NoteDict として扱う
+```
+
+外部 JSON・DB 生クエリ結果など `Any` 型を安全に使う唯一の公式手段。
+`cast()` は「信頼してキャスト」するだけだが、`TypeGuard` は実行時チェックと型絞り込みを両立する。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `TypedDict` は nene2 の UseCase Input/Output DTO の軽量代替として使える（Pydantic より軽い）
+- `Protocol` は `RepositoryInterface` の ABC 代替として `NoteRepositoryProtocol` を定義するのに有効
+- `Literal` は nene2 の `SortOrder` / `DB_ADAPTER` 等の設定値型に直接適用できる
+- `TypeGuard` は `/notes` 一覧取得の外部データを型安全に絞り込む Use Case で使える
+- CLAUDE.md の「`Any` 禁止 / `TypedDict` で Dict 構造を型付け」ポリシーと完全に整合
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`TypedDict` は `class` で辞書を型定義する概念が新しく、
+「Pydantic の `BaseModel` と何が違うの？」という混乱が起きる。
+
+**ドキュメント理解**: nene2 how-to に「HTTP 境界は Pydantic・UseCase 内部は TypedDict」の
+使い分けガイドがあれば即解決する。現時点では CLAUDE.md を読み込まないと判断できない。
+
+**事故リスク**: 低。`TypedDict` の誤用は実行時エラーにはならず、mypy が検出してくれる。
+ただし mypy なしで開発すると TypedDict の型安全の恩恵がゼロになる。
+
+**規約の使いやすさ**: `NoteDict(TypedDict)` のパターンはコピペで書ける。
+`total=False` と `NotRequired` の使い分けは最初は迷う。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`Protocol` を「インターフェース」として理解できるが、
+`@runtime_checkable` の「struct subtyping = 継承不要」は最初は驚く。
+「実行してみたら通った」という体験で理解が定着する。
+
+**コピペ可能性**: 高。`@runtime_checkable class Xxx(Protocol)` はテンプレートとして使える。
+
+**拡張時の罠**: `@runtime_checkable Protocol` はメソッドの引数・戻り値型を確認しない。
+`to_dict() -> dict[str, object]` を `to_dict() -> str` に変えても `isinstance()` は `True` を返す。
+実行時の型安全は Protocol の責務ではなく、mypy の責務であることを理解が必要。
+
+**セキュリティ的な事故リスク**: 低。typing の誤用がセキュリティインシデントに直結するケースは稀。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+TypeScript の `interface` / `type` / `as const` との対応関係が作れる。
+- TS の `interface` → Python の `TypedDict`（完全対応）
+- TS の `as const` 配列 → Python の `Literal`（概念的に近い）
+- TS の `function overloads` → Python の `@overload`（ほぼ同じ）
+- TS の `type predicate` (`is`) → Python の `TypeGuard`（同等）
+
+**エラーレスポンスの質**: 型ミスマッチは mypy が捕捉し、HTTP 境界では Pydantic が 422 を返す。
+フロントエンド開発者にとって馴染みのある体験。
+
+**事故リスク**: 低。TS の型システムの経験が直接活かせる。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `TypedDict` 活用は限定的（Django は dict よりモデルクラスを使う傾向）。
+FastAPI ユーザーにとっては Pydantic v2 が `TypedDict` をスキーマとして受け付けるため、
+境界が曖昧になりやすい。
+
+**他フレームワークとの差異**:
+- Django: ドメインは Model クラスで表現、typing との組み合わせは発展途上
+- nene2: TypedDict（UseCase 内部）+ Pydantic（HTTP 境界）の明確な使い分けが nene2 の差別化
+
+**本番投入可能性**: 問題なし。`@overload` / `TypeGuard` は FastAPI ルーターとも問題なく共存する。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] `TypedDict` フィールドに `NotRequired` を使って省略可能性を明示しているか（`total=False` は非推奨）
+- [ ] `@runtime_checkable Protocol` を型安全の唯一の砦にしていないか（mypy でも確認必須）
+- [ ] `@overload` の実装本体に型注釈が適切についているか（オーバーロードシグネチャのみ書いて本体を忘れるミス）
+- [ ] `TypeGuard` 関数が実行時チェック（isinstance 等）を実施しているか（`return True` のみは危険）
+- [ ] `cast()` には `# reason:` コメントがついているか（CLAUDE.md ポリシー）
+
+**チームでの安全なパターン**: `TypedDict` は UseCase I/O の DTO として標準化し、
+HTTP 境界は Pydantic、内部は TypedDict という二層構造を CLAUDE.md に明記する。
+
+**ツール追加の必要性**: `mypy --strict` で `TypedDict` の型チェックが網羅されるため追加不要。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 高
+- `TypedDict` + mypy の組み合わせで、実行前に型エラーが検出される
+- `TypeGuard` で `Any` 由来のデータを安全に絞り込める
+
+**設計上の負債・ドキュメント不足**:
+- CLAUDE.md の「TypedDict で Dict 構造を型付け」ポリシーは記載あるが、Pydantic との使い分けが未記載
+- nene2 の UseCase Input/Output は `dataclass(frozen=True)` で実装されているが、
+  `TypedDict` が適切な場面（JSON 応答の直接マッピング等）も存在する
+
+**Follow-up Issue 候補**: `docs: TypedDict vs Pydantic vs dataclass の使い分けガイドを how-to に追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: TypedDict vs Pydantic vs dataclass の使い分けガイドを how-to に追加` | docs |
+| 低 | `feat: NoteRepositoryProtocol を TypedDict + Protocol で再実装するサンプルを追加` | feat |
+
+---
+
+## まとめ
+
+`typing` モジュールは nene2-python の型安全設計の根幹をなす機能群。
+45 テスト全通過、摩擦ゼロ。
+
+`TypedDict` + `NotRequired` は UseCase 内部データ構造の軽量 DTO として直接使える。
+`Protocol` + `@runtime_checkable` は nene2 の `RepositoryInterface` の ABC 代替として有効で、
+継承なしの構造的サブタイピングを実現する。
+`TypeGuard` は `Any` 型データを型安全に絞り込む唯一の公式手段で、外部データ処理に必須。
+Python 3.12 の `type X = Literal[...]` 構文で定数列挙が軽量に書ける。
+

nene2_python-1.8.41/docs/field-trials/2026-05-field-trial-170.md

@@ -0,0 +1,242 @@
+# FT170: collections モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `collections` モジュール — `namedtuple`・`defaultdict`・`Counter`・`deque`・`OrderedDict`・`ChainMap`
+**セキュリティ診断**: なし（170 % 3 = 2）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `collections` モジュールを nene2-python フレームワーク上で検証した。
+`collections` は Python の基本データ構造を拡張する実用的なモジュールで、
+ドメインデータ集計・キャッシュ・グラフ探索・設定管理に直接使えるパターンを提供する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft170-collections/`
+
+### 主要機能
+
+| クラス/関数 | 概要 |
+|---|---|
+| `ApiError` (namedtuple) | エラー情報の軽量イミュータブル型。`_asdict()` で辞書変換 |
+| `group_by_first_char()` | `defaultdict(list)` でグループ集計 |
+| `count_tags()` | `defaultdict(int)` で出現頻度集計 |
+| `build_adjacency_list()` | `defaultdict(list)` でグラフ構築 |
+| `word_frequency()` / `top_n_words()` | `Counter` で単語頻度・トップN |
+| `tag_overlap()` | `Counter` の intersection で共通タグを抽出 |
+| `merge_counts()` | 複数 `Counter` を `update()` で合算 |
+| `sliding_window_max()` | `deque` で O(n) スライディングウィンドウ最大値 |
+| `recent_n()` | `deque(maxlen=n)` でリングバッファ |
+| `bfs_path()` | `deque` をキューとして BFS 最短経路探索 |
+| `LruCache` | `OrderedDict` + `move_to_end()` で O(1) LRU キャッシュ |
+| `resolve_config()` / `config_source()` | `ChainMap` で env > file > defaults の優先順位設定 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/collections/namedtuple` | namedtuple デモ（距離計算・エラー構造体） |
+| POST | `/collections/group-by` | defaultdict でグループ集計 |
+| POST | `/collections/count-tags` | defaultdict でタグ集計 |
+| GET | `/collections/word-freq` | Counter で単語頻度分析 |
+| GET | `/collections/sliding-window` | deque でスライディングウィンドウ |
+| GET | `/collections/recent` | deque(maxlen) リングバッファ |
+| POST | `/collections/bfs` | BFS グラフ探索 |
+| PUT/GET | `/collections/lru/{key}` | OrderedDict LRU キャッシュ |
+| POST | `/collections/config` | ChainMap 設定レイヤー解決 |
+
+---
+
+## テスト結果
+
+**36 passed（摩擦ゼロ）**
+
+```
+36 passed in 0.94s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `defaultdict` は「キーがなければ初期値」を明示的に設計できる
+
+```python
+result: defaultdict[str, list[str]] = defaultdict(list)
+for word in words:
+    result[word[0]].append(word)  # KeyError なし
+```
+
+`dict.setdefault()` より意図が明確で、`if key not in d:` 分岐が不要になる。
+グループ集計・グラフ隣接リスト構築・カウンタ実装の3パターンで多用できる。
+
+### 観察2: `Counter` は集合演算（`+`, `-`, `&`, `|`）が使える辞書
+
+```python
+Counter(["python", "typing", "python"]) & Counter(["python", "asyncio"])
+# → Counter({"python": 1})  — min(2,1) = 1
+```
+
+`Counter` 同士の `+` は合算、`&` は最小値、`|` は最大値。
+複数の集計結果をマージする `merge_counts()` は `Counter.update()` で自然に書ける。
+`most_common(n)` で上位 N 件を O(n log n) で取得できる。
+
+### 観察3: `deque(maxlen=n)` はリングバッファとして使える
+
+```python
+buf: deque[str] = deque(maxlen=5)
+buf.extend(["a", "b", "c", "d", "e", "f"])
+list(buf)  # → ["b", "c", "d", "e", "f"]  — 最新5件のみ保持
+```
+
+`maxlen` を指定すると、追加時に先頭から自動削除される。
+ログ末尾 N 行・最近の操作履歴・スライディングウィンドウのバッファとして最適。
+`collections.deque` は `list` と異なり先頭操作が O(1)。
+
+### 観察4: `OrderedDict.move_to_end()` で O(1) LRU キャッシュが実装できる
+
+```python
+class LruCache:
+    def get(self, key: str) -> Any:
+        if key not in self._cache:
+            return None
+        self._cache.move_to_end(key)  # 最近使用済みとしてマーク
+        return self._cache[key]
+
+    def put(self, key: str, value: Any) -> None:
+        ...
+        if len(self._cache) > self.capacity:
+            self._cache.popitem(last=False)  # 最も古いものを削除
+```
+
+`Python 3.7+` の `dict` は挿入順を保証するが、`move_to_end()` がないため
+LRU の「使用順序の更新」には `OrderedDict` が必要。
+nene2 の `TtlCache` と組み合わせた TTL+LRU キャッシュへの発展も可能。
+
+### 観察5: `ChainMap` で設定レイヤーのオーバーライドが宣言的に書ける
+
+```python
+chain = ChainMap(env_vars, file_config, defaults)
+chain["DB_HOST"]  # env_vars → file_config → defaults の優先順位で検索
+```
+
+`os.environ` + ファイル設定 + デフォルト値の優先順位解決は
+従来 `{**defaults, **file_config, **env_vars}` で実装していたが、
+`ChainMap` は元の辞書を変更せず参照のみのため副作用がない。
+`chain.maps[0]` で最優先レイヤー、`chain.new_child()` でスコープを重ねることもできる。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `Counter` はタグ・カテゴリの集計 Use Case で `GROUP BY` SQL の代替になる（小規模データ）
+- `LruCache` は nene2 の `TtlCache[V]` と組み合わせて TTL + LRU の複合キャッシュに発展できる
+- `ChainMap` は `AppSettings` の `pydantic-settings` が行っている env > file > default 解決と同じパターン
+- `deque` は WebSocket メッセージキューやストリーミングレスポンスのバッファとして適用できる
+- `namedtuple` は UseCase の軽量 Output DTO として `dataclass(frozen=True)` より軽量な選択肢になる
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`defaultdict` は「エラーが出なくなった辞書」として直感的に受け入れられる。
+`Counter` は「辞書の特殊版」として理解でき、`.most_common()` が使いやすい。
+`deque` の「両端キュー」という概念は最初はピンとこないが、`maxlen` のリングバッファ用途はすぐに理解できる。
+
+**ドキュメント理解**: `defaultdict(list)` のファクトリ関数の渡し方（`list` を呼び出さない）は最初に混乱する。
+`defaultdict(lambda: [])` との違いを最初に説明すると理解が早い。
+
+**事故リスク**: 中。`defaultdict` は存在しないキーにアクセスすると自動で作成するため、
+タイポキーが無音で `{}` や `[]` に変わり、後続処理でのデバッグが難しくなる可能性。
+
+**規約の使いやすさ**: コピペで使えるパターンが多い。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`Counter` を知らずに `dict` + `if key in d: d[key] += 1 else: d[key] = 1` を書いている。
+`Counter` を知ると即採用する。
+
+**コピペ可能性**: 高。特に `Counter(list).most_common(n)` のワンライナーは即戦力。
+
+**拡張時の罠**: `LruCache` で `OrderedDict` を使っているが、
+Python 3.7+ の `dict` で書き直そうとして `move_to_end()` がないことに気づかず壊す可能性。
+「`OrderedDict` には `move_to_end()` がある」という固有 API を README に明記するべき。
+
+**セキュリティ的な事故リスク**: 低。`collections` の誤用は機能バグには繋がるが、セキュリティリスクは低い。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+`Counter` は JavaScript の `reduce` で頻度集計するパターンと概念的に近い。
+`namedtuple` は TypeScript の `readonly struct` 的に理解できる。
+
+**エラーレスポンスの質**: `/collections/sliding-window` で `"a,b,c"` を送ると 422 が返る。
+クライアントには `{"error": "values must be comma-separated integers"}` が届き明確。
+
+**事故リスク**: 低。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `QuerySet.values().annotate(count=Count(...))` と `Counter` の使い分けが判断ポイント。
+DB に集計クエリを投げられるなら Django ORM が適切。
+インメモリ集計（小規模・一時的）には `Counter` が軽量。
+
+**本番投入可能性**: 問題なし。`LruCache` は nene2 の `TtlCache` と組み合わせて即本番投入できる。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] `defaultdict` のキーが意図せず作成されていないか（`d[key]` アクセスだけでキーが生える）
+- [ ] `Counter` の `most_common()` が `None` を返さないことを前提にしているか（空リストなら空リストを返す）
+- [ ] `LruCache` が複数リクエストからアクセスされるグローバル状態の場合、`asyncio.Lock()` が必要か確認
+- [ ] `ChainMap` の子マップへの書き込みが親マップに伝播しないことを理解しているか
+
+**チームでの安全なパターン**: グローバルな `LruCache` インスタンスは `asyncio.Lock()` でガードするか、
+スレッドセーフな実装（`threading.RLock`）に置き換える。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 中
+- `defaultdict` のキー自動生成は初心者には予期しない動作になりうる
+- `LruCache` のスレッドセーフ性は nene2 の非同期環境では注意が必要
+
+**設計上の負債・ドキュメント不足**:
+- nene2 の `TtlCache[V]` と `LruCache` の組み合わせパターンが未文書化
+- グローバルキャッシュインスタンスの非同期安全性に関する how-to がない
+
+**Follow-up Issue 候補**: `docs: キャッシュの TTL + LRU 複合パターンと非同期安全性の how-to を追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: collections.Counter をタグ集計 Use Case に適用するパターンを how-to に追加` | docs |
+| 低 | `feat: TtlCache に LRU 退去ポリシーを追加するオプションを検討` | feat |
+
+---
+
+## まとめ
+
+`collections` モジュールは nene2-python の集計・キャッシュ・探索・設定管理に直接使える実用的な機能群。
+36 テスト全通過、摩擦ゼロ。
+
+`defaultdict` / `Counter` / `deque` の三点セットは Python バックエンドの必須知識。
+`OrderedDict.move_to_end()` による LRU キャッシュは nene2 の `TtlCache` と組み合わせる価値がある。
+`ChainMap` は `pydantic-settings` が内部でやっている設定レイヤー解決と同じパターンで、
+環境別設定のオーバーライドを副作用なしに実装できる。
+

{nene2_python-1.8.39 → nene2_python-1.8.41}/pyproject.toml

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

{nene2_python-1.8.39 → nene2_python-1.8.41}/uv.lock

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