nene2-python 1.8.56__tar.gz → 1.8.58__tar.gz

{nene2_python-1.8.56 → nene2_python-1.8.58}/PKG-INFO

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

@@ -0,0 +1,299 @@
+# FT186: functools
+
+**日付**: 2026-05-21
+**テーマ**: functools モジュール — キャッシュ・部分適用・デコレーター・比較・ディスパッチ
+**セキュリティ診断**: あり（186 % 3 = 0）
+**クラッカーペンテスト**: なし（186 % 4 = 2）
+
+---
+
+## 概要
+
+Python 標準ライブラリ `functools` は高階関数・関数オブジェクトのユーティリティ集である。
+`lru_cache`・`cache`（メモ化）、`partial`（部分適用）、`reduce`（畳み込み）、`wraps`（デコレーターメタデータ保持）、`total_ordering`（比較演算子補完）、`singledispatch`（型ディスパッチ）、`cached_property`（インスタンスレベルキャッシュ）を検証した。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft186-functools/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `fibonacci(n)` | `lru_cache` でメモ化したフィボナッチ数列 |
+| `fibonacci_safe(n)` | 上限チェック付きフィボナッチ（DoS 対策）|
+| `get_fibonacci_cache_stats()` | キャッシュ統計取得 |
+| `factorial(n)` | `functools.cache` で無制限メモ化した階乗 |
+| `power(base, exponent)` / `square` / `cube` | `partial` で指数固定関数 |
+| `make_multiplier(factor)` | `partial` で乗数固定の乗算関数を生成 |
+| `product(numbers)` | `reduce` でリストの積 |
+| `flatten_once(nested)` | `reduce` で1段階展開 |
+| `timing_decorator(func)` | `@wraps` でメタデータ保持するタイミングデコレーター |
+| `retry(max_attempts)` | `@wraps` を使ったリトライデコレーターファクトリ |
+| `Version` | `@total_ordering` + `dataclass` でセマンティックバージョン比較 |
+| `latest_version(versions)` | `reduce` + `Version` で最新バージョン検出 |
+| `serialize(value)` | `singledispatch` で型別シリアライズ |
+| `DataProcessor` | `cached_property` でコストの高い計算をキャッシュ |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/fibonacci` | lru_cache フィボナッチ |
+| POST | `/factorial` | cache 階乗 |
+| POST | `/power` | partial square/cube |
+| POST | `/multiply` | partial 乗算 |
+| POST | `/product` | reduce 積 |
+| POST | `/flatten` | reduce 展開 |
+| POST | `/version/latest` | total_ordering + reduce 最新バージョン |
+| POST | `/serialize` | singledispatch シリアライズ |
+| POST | `/stats` | cached_property 統計 |
+
+---
+
+## テスト結果
+
+**64 passed**
+
+```
+64 passed in 0.36s
+```
+
+mypy --strict: Success  
+ruff check: All checks passed  
+pip-audit: PYSEC-2025-183 (PyJWT via mcp transitive dep — 許容済み)
+
+---
+
+## 摩擦ポイント
+
+### F-1: `base**exponent` の戻り値型が `Any`（mypy --strict）（深刻度: 低）
+
+**事象**: `return base**exponent` をそのまま返すと `Returning Any from function declared to return "float"` エラー。Python の `**` 演算子は型に応じて `int | float | complex` を返すため、mypy が型推論できない。
+
+**原因**: `float ** float` の演算子オーバーロードが `float` ではなく `Any` として型付けされている（typeshed の制約）。
+
+**対応**: `return float(base**exponent)` と明示的にキャストすることで解決。
+
+---
+
+## 観察点
+
+### 観察1: `lru_cache` の `maxsize` と DoS 対策
+
+```python
+@functools.lru_cache(maxsize=256)
+def fibonacci(n: int) -> int:
+    ...
+
+def fibonacci_safe(n: int) -> int:
+    if n > 90:
+        raise ValueError(...)
+    return fibonacci(n)
+```
+
+`lru_cache` は入力値ごとにキャッシュエントリを作成する。`maxsize=None`（= `functools.cache`）の場合、引数のバリエーションが多い用途では無制限にメモリを使い続ける可能性がある。入力値を `fibonacci_safe` でサニタイズしてから `lru_cache` 付き関数を呼ぶことで、キャッシュの肥大化を防ぐ。
+
+### 観察2: `functools.cache` vs `lru_cache(maxsize=None)`
+
+```python
+@functools.cache        # Python 3.9+
+def factorial(n: int) -> int: ...
+
+@functools.lru_cache(maxsize=None)  # Python 3.2+
+def factorial(n: int) -> int: ...
+```
+
+`functools.cache` は `lru_cache(maxsize=None)` の簡易エイリアスで、`cache_info()` / `cache_clear()` メソッドを持つ点は同じ。`lru_cache` より書きやすく、上限なしキャッシュが明示的。
+
+### 観察3: `@wraps` なしでメタデータが失われる問題
+
+```python
+# wraps なし — name が "wrapper" になる
+def bad_decorator(func):
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    return wrapper
+
+# wraps あり — name が元の関数名を保持
+def good_decorator(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+    return wrapper
+```
+
+`@wraps` を省くと `__name__`・`__doc__`・`__annotations__` が全てラッパーのものに置き換わる。pytest の `--tb=short` でも関数名が `wrapper` と表示され、デバッグが困難になる。
+
+### 観察4: `total_ordering` と `frozen=True` の組み合わせ
+
+`@functools.total_ordering` と `@dataclass(frozen=True)` を組み合わせる場合、`@dataclass(eq=False)` を指定しないと `dataclass` が自動生成する `__eq__` が `total_ordering` の `__eq__` を上書きしてしまう可能性がある。今回は `__eq__` と `__lt__` を明示的に実装したため問題なし。
+
+### 観察5: `singledispatch` と `bool` 型のディスパッチ順序
+
+```python
+@serialize.register(bool)
+def _serialize_bool(value: bool) -> str: ...
+
+@serialize.register(int)
+def _serialize_int(value: int) -> str: ...
+```
+
+Python では `bool` は `int` のサブクラス。`@register(int)` を先に登録すると `True`/`False` も `int` ハンドラーで処理される。`bool` を意図的に分岐させたい場合は `@register(bool)` を先（または明示的に）登録する必要がある。
+
+---
+
+## セキュリティ診断（FT186 % 3 = 0）
+
+### 1. OWASP API Security Top 10 (2023)
+
+#### API6: Unrestricted Access to Sensitive Business Flows — DoS via lru_cache
+
+**状況**: `fibonacci(n)` に上限なく大きな `n` を渡せた場合、計算時間 + キャッシュメモリの両面で DoS が成立する。
+
+**対策**: `fibonacci_safe(n)` が Pydantic の `le=90` と合わせて二重に入力を制限している。FastAPI の `Field(ge=0, le=90)` による検証は HTTP 境界で確実に発動する。**問題なし**。
+
+#### API4: Unrestricted Resource Consumption
+
+**状況**: `/stats` エンドポイントは `list[int]` を最大 1000 要素受け取る。`cached_property` はインスタンスごとにキャッシュするため、毎リクエストで新たな `DataProcessor` インスタンスが生成され、キャッシュは1リクエスト内のみで有効。メモリは GC に依存するが、1000 要素程度ならリスクは低い。**問題なし**。
+
+**状況**: `/flatten` は `list[list[int]]` を最大 50 要素受け取り `reduce` で結合するが、内側リストの要素数に上限がない。理論上、巨大な内側リストを送れる。
+
+**判定**: **MEDIUM** — 内側リストに個別の `max_length` が設定されていない（F-2 として記録）。
+
+### 2. インジェクション攻撃
+
+`functools` API は外部入力を直接評価する機能を持たないため、インジェクションリスクはない。`singledispatch` の型ルーティングも実行コードを動的生成しない。**問題なし**。
+
+### 3. 認証・認可
+
+今回のエンドポイントは認証不要の計算 API のため対象外。**問題なし**。
+
+### 4. 入力バリデーション
+
+| フィールド | 制約 | 評価 |
+|---|---|---|
+| `FibRequest.n` | `ge=0, le=90` | ✅ |
+| `FactorialRequest.n` | `ge=0, le=20` | ✅ |
+| `PowerRequest.operation` | `max_length=10` | ✅ |
+| `ProductRequest.numbers` | `max_length=100` | ✅ |
+| `FlattenRequest.nested` | `max_length=50` (外側のみ) | ⚠️ 内側なし |
+| `VersionRequest.versions` | `max_length=50` | ✅ |
+| `StatsRequest.data` | `max_length=1000` | ✅ |
+
+### 5. 情報漏洩
+
+`retry` デコレーターがリトライ失敗時に元の例外を `raise` するため、内部エラーメッセージがそのまま上位に伝播する。FastAPI の `ErrorHandlerMiddleware` がない場合、500 レスポンスに内部エラーが含まれる可能性がある。FT のサンドボックスでは許容範囲内。**問題なし**（本番実装では `ErrorHandlerMiddleware` を追加すること）。
+
+pip-audit: PYSEC-2025-183 (PyJWT via mcp — 許容済み、修正版待ち)
+
+### 6. Python/FastAPI 固有
+
+#### ReDoS
+
+`Version.parse()` は `.split(".")` と `int()` のみを使用。正規表現を使用しないため ReDoS リスクなし。**問題なし**。
+
+#### functools.cache の無制限メモリ使用
+
+`factorial` は `functools.cache`（無制限）を使用しているが、`FactorialRequest.n` が `le=20` で制限されているため、キャッシュエントリは最大 21 個。**問題なし**。
+
+#### singledispatch の型安全性
+
+`singledispatch` は実行時型チェックを行うため、Pydantic で検証済みの型が渡される限り不正ディスパッチは発生しない。**問題なし**。
+
+### セキュリティ診断まとめ
+
+| カテゴリ | 結果 | 備考 |
+|---|---|---|
+| OWASP API Top 10 | 条件付き合格 | F-2 /flatten 内側リスト上限なし |
+| インジェクション | 合格 | |
+| 認証・認可 | 対象外 | |
+| 入力バリデーション | 条件付き合格 | F-2 参照 |
+| 情報漏洩 | 合格 | ErrorHandlerMiddleware 推奨 |
+| Python/FastAPI 固有 | 合格 | |
+
+**診断結果: 条件付き合格**（MEDIUM 1件 — 次 FT までに修正推奨）
+
+---
+
+## Follow-up Issues
+
+### F-2: `/flatten` 内側リストの要素数に上限なし（深刻度: MEDIUM）
+
+**事象**: `FlattenRequest.nested: list[list[int]]` の外側は `max_length=50` で制限されているが、内側リストの要素数に上限がない。悪意のある入力で内側に大量要素を持つリストを送ることができる。
+
+**対応**: Pydantic の `Annotated[list[int], Field(max_length=1000)]` を使って内側リストにも上限を設定する。
+
+---
+
+## DX Review — 6ペルソナ
+
+### 1. 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+「関数をキャッシュする」という概念が `@lru_cache` によって視覚的に分かりやすく表現されている。デコレーター1行で劇的に高速化できる体験は印象的。
+
+**ドキュメント理解**: `partial` の「引数を固定した新しい関数を作る」という概念は直感的。しかし `reduce` の「畳み込み」は初見では理解しにくく、`sum()` や `max()` で代替できる場合が多い旨を添えた方が親切。
+
+**事故リスク**: 低 — ただし `lru_cache(maxsize=None)` は上限なしキャッシュであることを知らないと、長時間稼働するプロセスでメモリが肥大化するリスクがある（サンドボックスでは `fibonacci_safe` で回避済み）。
+
+**規約の使いやすさ**: `@wraps` の必要性（デバッグ時の関数名保持）を理解するまでは省略しがち。テストで `__name__` を確認するパターンを見ることで習得できる。
+
+### 2. ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`lru_cache` のコピペ利用は頻繁。`maxsize` を適切に設定することを忘れがちで、`None` のまま運用してメモリリークを引き起こすケースがある。
+
+**コピペ可能性**: `timing_decorator` と `retry` はそのまま転用できるユーティリティとして高い実用性。
+
+**拡張時の罠**: `total_ordering` + `dataclass(frozen=True)` の組み合わせで `__eq__` を省略するとデフォルトの `dataclass` が生成した `__eq__` が使われ、`total_ordering` の期待と異なる場合がある（観察4参照）。
+
+**事故リスク**: 中（lru_cache の maxsize 設定忘れ）
+
+### 3. フロントエンド寄り（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+TypeScript の `useMemo` / `useCallback` に近い概念として `lru_cache` / `partial` を理解できる。`singledispatch` は TypeScript のオーバーロードと比べてコードが分散するが、`@register` で後から拡張できる点は優れている。
+
+**エラーレスポンスの質**: `/version/latest` の `400 Bad Request` + `detail` に無効バージョン文字列を含めるのは適切。
+
+**Python 固有概念の学習コスト**: `reduce` は TS では `Array.prototype.reduce` があるので理解しやすいが、Python 3 での `reduce` の立ち位置（`functools.reduce` に格下げされた経緯）を知ると設計哲学が掴める。
+
+**事故リスク**: 低
+
+### 4. バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+`cached_property` は Django モデルの `@property` + 手動キャッシュより洗練されている。リクエストごとに新インスタンスを作成するケースでは「1リクエスト内のみ有効なキャッシュ」として機能するため、副作用なく使いやすい。
+
+**他フレームワークとの差異**: Django の `django.utils.functional.cached_property` は非スレッドセーフだが、`functools.cached_property` も非スレッドセーフ（Python 3.12 以前）。スレッドセーフが必要な場合は明示的なロックが必要。
+
+**nene2 の薄さへの評価**: `functools` は nene2 フレームワークと独立しているため、どの FastAPI プロジェクトでも直接適用できる内容として評価が高い。
+
+**事故リスク**: 低
+
+### 5. シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- `lru_cache` の `maxsize` が適切か（サービスの想定入力範囲に合っているか）
+- `cache`（無制限）を使う場合、入力バリエーションが有限であることが保証されているか
+- `@wraps` が全てのデコレーター実装に付いているか
+- `singledispatch` のデフォルト実装が意図した型を処理するか（意図しない型が来たときの挙動）
+- `total_ordering` で `__eq__` と `__lt__` の両方が実装されているか
+
+**チームでの安全なパターン**: `retry` デコレーターはチーム共有のユーティリティとして使えるが、リトライ間隔（`sleep`）・バックオフ・特定例外のみリトライなど実装が必要な場合は `tenacity` ライブラリの使用を推奨する。
+
+**事故リスク**: 低
+
+### 6. 設計者（nene2-python 設計ポリシー目線）
+
+**CLAUDE.md ポリシー整合性**:
+- `dataclass(frozen=True, slots=True)`: `CacheStats` / `Version` で適用済み ✅
+- Pydantic は HTTP 境界のみ: `app.py` の Request/Response モデルのみ ✅
+- `create_app()` はファイル末尾: 適用済み ✅
+- `max_length` 指定: 外側リストには設定済み（F-2: 内側リスト未設定）⚠️
+- セキュリティ診断実施: FT186 % 3 = 0 → 診断実施 ✅
+
+**初心者でも安全な API 達成度**: `fibonacci_safe` による DoS 防御ラッパーパターン（上限チェック → メモ化関数呼び出し）は安全なキャッシュ利用の模範として機能している。Pydantic の `le=` と `fibonacci_safe` の両方で二重バリデーションしている点も good practice。
+
+---
+
+*バージョン: v1.8.57*

nene2_python-1.8.58/docs/field-trials/2026-05-field-trial-187.md

@@ -0,0 +1,261 @@
+# FT187: collections
+
+**日付**: 2026-05-21
+**テーマ**: collections モジュール — Counter・defaultdict・deque・ChainMap・NamedTuple・OrderedDict
+**セキュリティ診断**: なし（187 % 3 = 1）
+**クラッカーペンテスト**: なし（187 % 4 = 3）
+
+---
+
+## 概要
+
+Python 標準ライブラリ `collections` は汎用コンテナ型の拡張集である。
+`Counter`（頻度カウント）、`defaultdict`（デフォルト値付き辞書）、`deque`（両端キュー）、`ChainMap`（複数辞書のビュー）、`NamedTuple`（型付き名前付きタプル）、`OrderedDict`（挿入順序保持辞書）の主要 6 型を検証した。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft187-collections/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `word_frequency(text)` | Counter で単語頻度を集計 |
+| `top_n_words(text, n)` | `most_common(n)` で上位 N 単語を取得 |
+| `character_frequency(text)` | 文字頻度を集計（空白除外）|
+| `merge_counters(a, b)` | Counter の `+` 演算子でマージ |
+| `subtract_counters(a, b)` | Counter の `-` 演算子で差分（正の値のみ）|
+| `group_by_length(words)` | defaultdict でワード長別グループ化 |
+| `build_inverted_index(docs)` | defaultdict で転置インデックス構築 |
+| `count_nested(items, sep)` | ネスト defaultdict でカテゴリ別集計 |
+| `BoundedHistory` | `deque(maxlen=N)` でサイズ制限付き履歴 |
+| `sliding_window_average(values, window)` | deque + maxlen でスライディング平均 |
+| `rotate_list(items, steps)` | `deque.rotate()` でリストをローテーション |
+| `resolve_config(*layers)` | ChainMap で設定レイヤーを優先順解決 |
+| `get_with_override(base, override, key)` | ChainMap で override 優先の値取得 |
+| `Coordinate` | `typing.NamedTuple` で型付き座標 |
+| `deduplicate_preserving_order(items)` | OrderedDict で順序保持重複除去 |
+| `LruDict` | OrderedDict を使った LRU キャッシュ |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/counter/words` | 単語頻度集計 |
+| POST | `/counter/top` | 上位 N 単語 |
+| POST | `/counter/chars` | 文字頻度集計 |
+| POST | `/counter/merge` | カウンターマージ |
+| POST | `/counter/subtract` | カウンター差分 |
+| POST | `/defaultdict/group` | 長さ別グループ化 |
+| POST | `/defaultdict/index` | 転置インデックス |
+| POST | `/defaultdict/nested` | ネストカウント |
+| POST | `/deque/sliding-window` | スライディング平均 |
+| POST | `/deque/rotate` | リストローテーション |
+| POST | `/chainmap/resolve` | 設定レイヤー解決 |
+| POST | `/ordereddict/deduplicate` | 順序保持重複除去 |
+| POST | `/namedtuple/coordinates` | 座標パース |
+| POST | `/ordereddict/lru` | LRU キャッシュ操作 |
+
+---
+
+## テスト結果
+
+**56 passed**
+
+```
+56 passed in 0.35s
+```
+
+mypy --strict: Success  
+ruff check: All checks passed  
+pip-audit: PYSEC-2025-183 (PyJWT via mcp transitive dep — 許容済み)
+
+---
+
+## 摩擦ポイント
+
+### F-1: `parse_coordinates` の引数型に `dict[str, float | str]` を使うと mypy エラー（深刻度: 低）
+
+**事象**: `parse_coordinates(raw: list[dict[str, float | str]])` を定義し、呼び出し側で `[{"latitude": c.latitude, ...}]` を渡したところ、mypy が `Argument 1 has incompatible type "list[dict[str, object]]"` エラーを出した。辞書リテラルの型が `dict[str, object]` として推論されるため。
+
+**原因**: Python の辞書リテラル `{"latitude": 35.0, "label": "A"}` は `dict[str, float | str]` ではなく `dict[str, object]` として推論される（値の型が異なる場合）。
+
+**対応**: 入力専用のデータクラス `RawCoordinate(dataclass(frozen=True, slots=True))` を定義して型安全な引数にした。`dict` を渡す代わりに `RawCoordinate` オブジェクトを渡す。
+
+```python
+@dataclass(frozen=True, slots=True)
+class RawCoordinate:
+    latitude: float
+    longitude: float
+    label: str = ""
+
+def parse_coordinates(raw: list[RawCoordinate]) -> list[Coordinate]:
+    return [Coordinate(latitude=r.latitude, ...) for r in raw]
+```
+
+---
+
+## 観察点
+
+### 観察1: Counter の算術演算子
+
+```python
+a = Counter({"x": 5, "y": 2})
+b = Counter({"x": 3, "y": 4})
+
+a + b  # {"x": 8, "y": 6}  — 合計
+a - b  # {"x": 2}           — 差分（正の値のみ残る）
+a & b  # {"x": 3, "y": 2}  — 最小値（intersection）
+a | b  # {"x": 5, "y": 4}  — 最大値（union）
+```
+
+`Counter` は `dict` のサブクラスで算術演算子が使えるため、集合演算的な使い方ができる。`-` の結果は正の値のみ（負になったキーは除外）になる点が直感と異なる場合がある。
+
+### 観察2: defaultdict のネスト — `lambda` を使ったデフォルト値
+
+```python
+# ネストした defaultdict
+result: defaultdict[str, defaultdict[str, int]] = \
+    defaultdict(lambda: defaultdict(int))
+
+# 使用例
+result["fruit"]["apple"] += 1
+```
+
+`lambda: defaultdict(int)` でネストした自動生成が可能。ただし `lambda` の型は mypy で推論が難しいため、明示的な型注釈が必要になる場合がある。
+
+### 観察3: deque の `maxlen` による自動エビクション
+
+```python
+dq = deque(maxlen=3)
+dq.append(1)  # [1]
+dq.append(2)  # [1, 2]
+dq.append(3)  # [1, 2, 3]
+dq.append(4)  # [2, 3, 4] — 左端の 1 が自動除去
+```
+
+`deque(maxlen=N)` は満杯時に反対側の要素を自動除去する。スライディングウィンドウ・LRU 的な「最近 N 件だけ保持」のユースケースに適している。`appendleft` を使うと最新が先頭になる（`BoundedHistory` パターン）。
+
+### 観察4: ChainMap の「先頭優先」セマンティクス
+
+```python
+chain = ChainMap(override, base)
+chain["key"]  # override の値を優先（なければ base を参照）
+chain["new"] = "value"  # 先頭の override に追加（base は変更されない）
+```
+
+`ChainMap` は辞書のコピーを作らずビューを提供する。環境変数 → 設定ファイル → デフォルト値という優先順位を持つ設定解決に適している。`new_child()` で新しいスコープを作成することも可能。
+
+### 観察5: `typing.NamedTuple` vs `collections.namedtuple`
+
+```python
+# collections.namedtuple — フィールド名のみ、型なし
+Point = namedtuple("Point", ["x", "y"])
+
+# typing.NamedTuple — 型付きフィールド、デフォルト値、メソッド定義可
+class Coordinate(NamedTuple):
+    latitude: float
+    longitude: float
+    label: str = ""
+    def distance_to(self, other: "Coordinate") -> float: ...
+```
+
+`typing.NamedTuple` は型安全でデフォルト値・メソッドを持てるため、`dataclass` の代替として不変の小さな値オブジェクトに使える。ただし `frozen=True` の `dataclass` と異なり、継承で問題が生じやすいため、単純な値型に限定するのが無難。
+
+### 観察6: OrderedDict を使った LRU キャッシュ
+
+```python
+cache = OrderedDict()
+
+def get(key):
+    cache.move_to_end(key)  # アクセスで MRU 端へ移動
+    return cache[key]
+
+def put(key, value):
+    if len(cache) >= capacity:
+        cache.popitem(last=False)  # LRU 端（先頭）から除去
+    cache[key] = value
+```
+
+Python 3.2+ の `dict` は挿入順序保持が保証されているが、`OrderedDict` は `move_to_end()` と `popitem(last=False/True)` を持ち、LRU 実装が簡潔に書ける。
+
+---
+
+## Follow-up Issues
+
+今回の FT では実装上の重大な摩擦はなかった。F-1 は mypy --strict での型推論の限界によるものであり、`dataclass` を入力型として導入することで解決した。
+
+GitHub Issues: なし
+
+---
+
+## DX Review — 6ペルソナ
+
+### 1. 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`Counter` は「リストの頻度を数える」という非常に頻繁に必要とされる操作をワンライナーで実現できる。`most_common(n)` の使いやすさは特に印象的で、手書きのループより明快。
+
+**ドキュメント理解**: `defaultdict` の「キーが存在しなければデフォルト値を自動生成する」という動作は、通常の辞書で `KeyError` に何度もぶつかった後に習得するパターン。デモのネスト例は実用的で理解しやすい。
+
+**事故リスク**: 低 — ただし `Counter` の `-` が「負値を除外する」挙動を知らないと驚く。テストで明示したことで習得しやすい。
+
+**規約の使いやすさ**: `LruDict` のパターン（`move_to_end` + `popitem`）は初心者には高度だが、「なぜ OrderedDict を使うのか」が実例で見えると理解が進む。
+
+### 2. ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`Counter.most_common()` はログ解析・アクセス集計でそのまま使えるため実務価値が高い。`defaultdict(list)` による転置インデックスも業務で頻繁に必要になる。
+
+**コピペ可能性**: `BoundedHistory`（deque + maxlen）・`LruDict`・`resolve_config`（ChainMap）はそのまま流用できるユーティリティ。
+
+**拡張時の罠**: `ChainMap` の `chain["key"] = value` は先頭辞書のみ変更する。「両方の辞書を更新したい」場合は `ChainMap` は不適切。
+
+**事故リスク**: 低
+
+### 3. フロントエンド寄り（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+TypeScript では `Map<string, number>` や `Record<string, number>` で表現するものが Python では `Counter` / `defaultdict` に対応する。`ChainMap` は TS にない概念だが、React の Context や CSS カスケードと近いセマンティクスで理解できる。
+
+**エラーレスポンスの質**: `/deque/sliding-window` の `window=0` に対する 422 バリデーションエラーは適切。FastAPI の `Field(ge=1)` が自動で機能している。
+
+**Python 固有概念の学習コスト**: `NamedTuple` は TypeScript のインターフェースに近い。デフォルト値・メソッド定義できる点は TS の interface と同じ感覚で理解できる。
+
+**事故リスク**: 低
+
+### 4. バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+`Counter` の算術演算子や `defaultdict` のネストは Django の `annotate()` / `aggregate()` では難しいデータ変換を純粋 Python で行う際に重宝する。`ChainMap` は Django の設定（`DJANGO_SETTINGS_MODULE` → デフォルト設定）と類似のパターン。
+
+**他フレームワークとの差異**: `LruDict` は `functools.lru_cache` と比べて「任意の引数に対応する柔軟性」と「キャッシュの明示的管理」がメリット。
+
+**nene2 の薄さへの評価**: `collections` は nene2 フレームワークと独立しているため、ドメインロジック層の実装にそのまま使えるコレクション群として評価が高い。
+
+**事故リスク**: 低
+
+### 5. シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- `defaultdict` が「サービス境界を超える」ケースに注意（外部に返す前に `dict(dd)` で変換しているか）
+- `Counter` の `subtract()` メソッドと `-` 演算子の違い（`subtract` は負値を保持、`-` は正値のみ）
+- `deque` に `maxlen` が設定されているか（無制限 deque は意図しないメモリ増大の原因）
+- `ChainMap` の変更は先頭辞書のみに反映されることを把握しているか
+
+**チームでの安全なパターン**: `BoundedHistory`（maxlen 付き deque）は監査ログ・エラー履歴の実装に、`resolve_config`（ChainMap）は設定オーバーライドに使えるチーム共有ユーティリティ。
+
+**事故リスク**: 低
+
+### 6. 設計者（nene2-python 設計ポリシー目線）
+
+**CLAUDE.md ポリシー整合性**:
+- `dataclass(frozen=True, slots=True)`: `DequeSnapshot`・`RawCoordinate` で適用済み ✅
+- Pydantic は HTTP 境界のみ: `app.py` の Request/Response モデルのみ ✅
+- `create_app()` はファイル末尾: 適用済み ✅（FT182 の教訓）
+- `max_length` 指定: 全文字列・リストフィールドに設定済み ✅
+- 型安全: `dict[str, float | str]` の問題を `RawCoordinate` dataclass で解決 ✅
+
+**初心者でも安全な API 達成度**: `BoundedHistory` が「maxlen を必ず指定して使う」パターンを示し、`LruDict` が「容量が決まっている場合のみ OrderedDict LRU を使う」ことを Pydantic の `le=100` で強制している設計は初心者でも誤用しにくい。
+
+---
+
+*バージョン: v1.8.58*

{nene2_python-1.8.56 → nene2_python-1.8.58}/docs/field-trials/INDEX.md

@@ -219,12 +219,14 @@
 | [FT183](2026-05-field-trial-183.md) | smtplib モジュール — SMTP 送信・STARTTLS・ヘッダーインジェクション防御 | 🔒 | [#513](https://github.com/hideyukiMORI/nene2-python/issues/513) [#514](https://github.com/hideyukiMORI/nene2-python/issues/514) |
 | [FT184](2026-05-field-trial-184.md) | urllib.request モジュール — URL フェッチ・Basic 認証・SSRF 防御 | 🔍 | [#516](https://github.com/hideyukiMORI/nene2-python/issues/516) [#517](https://github.com/hideyukiMORI/nene2-python/issues/517) |
 | [FT185](2026-05-field-trial-185.md) | contextlib モジュール — コンテキストマネージャー・リソース管理・エラー抑制 | | |
+| [FT186](2026-05-field-trial-186.md) | functools モジュール — キャッシュ・部分適用・デコレーター・比較・ディスパッチ | 🔒 | [#520](https://github.com/hideyukiMORI/nene2-python/issues/520) |
+| [FT187](2026-05-field-trial-187.md) | collections モジュール — Counter・defaultdict・deque・ChainMap・NamedTuple・OrderedDict | | |
 
 ---
 
 ## セキュリティ診断実施済み一覧（🔒）
 
-FT3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48, 51, 54, 57, 60, 63, 66, 69, 72, 75, 78, 81, 84, 87, 90, 93, 96, 99, 102, 105, 108, 111, 114, 117, 120, 121, 124, 127, 130, 133, 136, 139, 142, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172, 174, 177, 180, 183
+FT3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48, 51, 54, 57, 60, 63, 66, 69, 72, 75, 78, 81, 84, 87, 90, 93, 96, 99, 102, 105, 108, 111, 114, 117, 120, 121, 124, 127, 130, 133, 136, 139, 142, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172, 174, 177, 180, 183, 186
 
 合計: **62件**（183 FT 中 約 34%）
 
@@ -234,4 +236,4 @@ FT172, FT176, FT180, FT184
 
 ---
 
-*最終更新: 2026-05-21 (FT185 / v1.8.56)*
+*最終更新: 2026-05-21 (FT187 / v1.8.58)*

{nene2_python-1.8.56 → nene2_python-1.8.58}/docs/todo/current.md

@@ -1,14 +1,14 @@
 # TODO — current
 
 最終更新: 2026-05-21
-現状: **v1.8.56 安定版 / フィールドトライアルループ継続中（FT185 完了）**
+現状: **v1.8.58 安定版 / フィールドトライアルループ継続中（FT187 完了）**
 
 ---
 
 ## 状態サマリー
 
-v1.8.56 完了済み。FT185（contextlib / コンテキストマネージャー・リソース管理・エラー抑制）を含む FT185 件を実施済み。
-フィールドトライアルループは FT186 以降も継続中。
+v1.8.58 完了済み。FT187（collections / Counter・defaultdict・deque・ChainMap・NamedTuple・OrderedDict）を含む FT187 件を実施済み。
+フィールドトライアルループは FT188 以降も継続中。
 
 ---
 
@@ -22,6 +22,7 @@ v1.8.56 完了済み。FT185（contextlib / コンテキストマネージャー
 
 | Issue | 内容 | 優先度 |
 |---|---|---|
+| [#520](https://github.com/hideyukiMORI/nene2-python/issues/520) | [FT186] /flatten エンドポイントの内側リスト要素数に上限を追加 | 中 |
 | [#517](https://github.com/hideyukiMORI/nene2-python/issues/517) | [FT184] DNS リバインディング攻撃への対策検討（TTL0 + IP 切り替え） | 低 |
 | [#516](https://github.com/hideyukiMORI/nene2-python/issues/516) | [FT184] fetch_safe のリダイレクト SSRF 対策（Location ヘッダー先の IP 検証） | 中 |
 | [#514](https://github.com/hideyukiMORI/nene2-python/issues/514) | [FT183] SmtpConfig.password を SecretStr に変更 | 低 |
@@ -40,6 +41,8 @@ v1.8.56 完了済み。FT185（contextlib / コンテキストマネージャー
 
 | バージョン | 主な内容 |
 |---|---|
+| v1.8.58 | FT187: collections — Counter・defaultdict・deque・ChainMap・NamedTuple・OrderedDict |
+| v1.8.57 | FT186: functools — キャッシュ・部分適用・デコレーター・比較・ディスパッチ（診断実施） |
 | v1.8.56 | FT185: contextlib — コンテキストマネージャー・リソース管理・エラー抑制 |
 | v1.8.55 | FT184: urllib.request — URL フェッチ・Basic 認証・SSRF 防御（クラッカーペンテスト実施） |
 | v1.8.54 | FT183: smtplib — SMTP 送信・STARTTLS・ヘッダーインジェクション防御（診断実施） |
@@ -59,12 +62,12 @@ v1.8.56 完了済み。FT185（contextlib / コンテキストマネージャー
 
 ## フィールドトライアル進捗
 
-**実施済み**: FT1〜FT185（全 185 件）
+**実施済み**: FT1〜FT187（全 187 件）
 
 索引: [`docs/field-trials/INDEX.md`](../field-trials/INDEX.md)
 
 **次のアクション**:
-- FT185 以降を継続（FT186 は 186 % 4 = 2 → ペンテストなし、186 % 3 = 0 → セキュリティ診断あり）
+- FT187 以降を継続（FT188 は 188 % 4 = 0 → クラッカーペンテストあり、188 % 3 = 2 → 診断なし）
 
 ---
 

{nene2_python-1.8.56 → nene2_python-1.8.58}/pyproject.toml

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