nene2-python 1.8.36__tar.gz → 1.8.38__tar.gz

{nene2_python-1.8.36 → nene2_python-1.8.38}/PKG-INFO

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

@@ -0,0 +1,246 @@
+# FT166: functools モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `functools` モジュール — `lru_cache`・`cached_property`・`partial`・`wraps`・`reduce`・`cache`
+**セキュリティ診断**: なし（166 % 3 = 1）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `functools` モジュールを nene2-python フレームワーク上で検証した。
+`functools` は高階関数・デコレーター・メモ化のユーティリティを提供し、
+nene2-python の DI パターン・レスポンスキャッシュ・ミドルウェア実装に直結する。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft166-functools/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `fibonacci(n)` | `@lru_cache(maxsize=128)` でメモ化された再帰 fibonacci |
+| `expensive_computation(key)` | `@lru_cache(maxsize=32)` で文字列キーのキャッシュ |
+| `HeavyComputer` | `@cached_property` で total / average を遅延計算・キャッシュ |
+| `double / triple` | `functools.partial` で multiply の引数を固定 |
+| `greet_hello / greet_hi` | `partial` でテンプレートと記号を固定したあいさつ生成 |
+| `timing_decorator` | `@functools.wraps` でデコレーターが元の関数名・docstring を保持 |
+| `product_reduce(numbers)` | `functools.reduce` で積を計算 |
+| `flatten_reduce(nested)` | `reduce` でネストしたリストをフラット化 |
+| `collatz_steps(n)` | `@functools.cache`（unbounded）でコラッツ数列ステップ数をメモ化 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/functools/fibonacci` | lru_cache 付き fibonacci（キャッシュ統計返却） |
+| GET | `/functools/lru-cache` | 任意キーのキャッシュ統計デモ |
+| GET | `/functools/cached-property` | HeavyComputer の計算回数デモ |
+| GET | `/functools/partial` | double / triple / greet デモ |
+| GET | `/functools/wraps` | slow_add の __name__ 保持確認 |
+| POST | `/functools/reduce-product` | 整数リストの積 |
+| POST | `/functools/reduce-flatten` | ネストリストのフラット化 |
+| GET | `/functools/cache-collatz` | unbounded cache でコラッツ数列 |
+
+---
+
+## テスト結果
+
+**34 passed（摩擦ゼロ）**
+
+```
+34 passed in 0.83s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `@lru_cache` はグローバル状態 — テスト間でキャッシュを `clear` する必要がある
+
+```python
+@pytest.fixture(autouse=True)
+def clear_caches() -> None:
+    fibonacci.cache_clear()
+    expensive_computation.cache_clear()
+```
+
+`@lru_cache` の対象関数はプロセス共有のキャッシュを持つ。
+テスト間でキャッシュが汚染されるため `autouse=True` で毎回クリアする必要がある。
+nene2-python でキャッシュを使う UseCase は `cache_clear()` を lifespan の shutdown で呼ぶか、
+または `@lru_cache` をクラスメソッドに適用してインスタンス単位でスコープを制御する。
+
+### 観察2: `@cached_property` はインスタンス単位 — `lru_cache` との使い分け
+
+```python
+class HeavyComputer:
+    @functools.cached_property
+    def total(self) -> int:
+        self.compute_count += 1
+        return sum(self._data)
+```
+
+`@cached_property` はインスタンスの `__dict__` に値を保存する。
+同じインスタンスで 2 回目のアクセスは計算なし。新しいインスタンスは再計算。
+`@lru_cache` はプロセス全体で共有・引数でキー管理、`@cached_property` はインスタンスで管理。
+nene2-python での使い分け:
+- UseCase / Repository インスタンスの設定値計算 → `@cached_property`
+- 引数ベースの重い計算（ページネーション計算など）→ `@lru_cache`
+
+### 観察3: `@functools.cache` = `@lru_cache(maxsize=None)` でメモリ無制限
+
+```python
+@functools.cache  # Python 3.9+ / unbounded
+def collatz_steps(n: int) -> int: ...
+```
+
+`@cache` は `@lru_cache(maxsize=None)` の略記で、キャッシュサイズ制限なし。
+再帰的な数学関数に適しているが、引数の値域が大きい場合はメモリ枯渇に注意。
+nene2-python での用途: 設定値の解析結果など、引数の種類が少ない場合に使う。
+
+### 観察4: `functools.partial` で DI 設定をカリー化できる
+
+```python
+double = functools.partial(multiply, y=2)
+greet_hello = functools.partial(make_greeting, "Hello")
+```
+
+FastAPI の `Depends` と組み合わせる場合、`partial` でリポジトリに設定を注入できる:
+```python
+get_repo = functools.partial(NoteRepository, db_url=settings.db_url)
+Depends(get_repo)
+```
+ただし `Depends` に渡す関数はシグネチャが重要なため、`partial` が残す引数を確認すること。
+
+### 観察5: `@functools.wraps` なしのデコレーターは `__name__` を上書きする
+
+```python
+def timing_decorator(func):
+    # @functools.wraps(func) がないと:
+    def wrapper(*args, **kwargs): ...
+    return wrapper  # → slow_add.__name__ == "wrapper" になる
+
+def timing_decorator(func):
+    @functools.wraps(func)  # ← これがないと OpenAPI ルート名が壊れる
+    def wrapper(*args, **kwargs): ...
+    return wrapper
+```
+
+FastAPI はルート関数の `__name__` を operationId に使う。
+カスタムミドルウェア・デコレーターに `@functools.wraps` がないと OpenAPI スキーマが壊れる。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `@lru_cache` は `TtlCache`（FT100 で追加済み）と役割が異なる（TTL なし vs TTL あり）
+- `@cached_property` は Repository の設定パース結果のキャッシュに最適
+- `@functools.wraps` は nene2-python の `BearerTokenMiddleware` 等のデコレーターで使用が推奨される
+- `functools.reduce` は UseCase の集計ロジックに使えるが、`sum()` / リスト内包表記の方が可読性が高い場合が多い
+- `@functools.cache` は設定値の解析・静的ルックアップに適している
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`@lru_cache` は「デコレーターをつけるとキャッシュされる」という概念は分かりやすいが、
+`cache_clear()` が必要なことや、グローバル共有であることは見落としやすい。
+
+**ドキュメント理解**: `@lru_cache` のサンプルはフィボナッチが定番だが、
+「Web API の UseCase でいつ使うか」の例がないと「難しそうなやつ」で止まる。
+
+**事故リスク**: 中。`@lru_cache` をテストで使うときにキャッシュをクリアし忘れ、
+他のテストのキャッシュが漏れ込んでテストが通ったり失敗したりするフレーキーなテストが生まれる。
+
+**規約の使いやすさ**: `@functools.wraps` の必要性は理解しにくい。
+「デコレーターを作るときは必ず `@functools.wraps` をつける」という規則を覚えれば十分。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+`functools` は名前を知っていても使いこなせていないことが多い。
+`reduce` は「forループで書いた方が分かる」と言って使わない傾向がある。
+
+**コピペ可能性**: `@lru_cache(maxsize=128)` と `@functools.wraps(func)` はそのままコピペできる。
+
+**拡張時の罠**: `@lru_cache` の引数が変わったときにキャッシュが古い値を返し続ける。
+引数の型が mutable（`list`, `dict`）だと `TypeError: unhashable type` が発生することに気づかない。
+
+**セキュリティ的な事故リスク**: 低。ただし `@lru_cache` に認証情報を含む引数を渡すと
+別ユーザーのキャッシュが混入するリスクがある（BOLA の一形態）。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+`useMemo` / `useCallback` と `@lru_cache` / `@cached_property` は概念が近い。
+「同じ入力なら再計算しない」という理解はすでにある。
+
+**Python 固有概念の学習コスト**: `partial` は JS の `bind` や `curry` に近い概念。
+`reduce` は `Array.prototype.reduce` と同じ。TypeScript ユーザーには直感的。
+
+**事故リスク**: 低。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `@method_decorator` / `cache_page` との差異を理解している。
+`@functools.wraps` は既知。`@lru_cache` の eviction ポリシー（LRU）を正確に理解している。
+
+**他フレームワークとの差異**: Django は `cache.get/set` で明示的にキャッシュを管理する。
+nene2-python で `@lru_cache` を使う場合、TTL がないことを意識する必要がある。
+TTL が必要なら FT100 で追加した `TtlCache` を使う。
+
+**本番投入可能性**: 問題なし。ただしキャッシュキーのサイズとメモリ消費量の設計が必要。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] `@lru_cache` / `@cache` の引数に mutable 型（list, dict）が渡されていないか（`TypeError` になる）
+- [ ] `@lru_cache` をリクエストスコープで使っていないか（プロセス共有で期待外の値が返る）
+- [ ] `@lru_cache` に認証情報・ユーザーIDが引数に含まれる場合、BOLA にならないか
+- [ ] デコレーターに `@functools.wraps` がついているか（OpenAPI operationId の破損防止）
+- [ ] `@cache`（unbounded）を使う場合、引数の値域が有限か（メモリリーク防止）
+
+**チームでの安全なパターン**: キャッシュが必要な UseCase は `cache_clear()` を公開メソッドとして持ち、
+lifespan の shutdown / テストの teardown で明示的にクリアする規約を設ける。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 中
+- `@lru_cache` のキャッシュ汚染リスク（テスト・BOLA）をドキュメントが説明していない
+- `@functools.wraps` の必要性が CLAUDE.md に明記されていない（FastAPI との相性問題）
+
+**設計上の負債・ドキュメント不足**:
+- nene2-python のカスタムデコレーター作成時の `@functools.wraps` 使用がポリシー化されていない
+- `@lru_cache` の「リクエストスコープ不可・認証情報を引数に含めない」ルールが未文書
+
+**Follow-up Issue 候補**: `docs: functools.wraps をカスタムデコレーター規約に追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: @functools.wraps をデコレーター作成規約として CLAUDE.md に追加` | docs |
+| 低 | `docs: @lru_cache のリクエストスコープ不可・認証情報禁止をキャッシュ how-to に記載` | docs |
+
+---
+
+## まとめ
+
+`functools` は nene2-python の DI・キャッシュ・デコレーター実装に広く関連するモジュール。
+34 テスト全通過、摩擦ゼロ。
+`@cached_property` がインスタンス単位、`@lru_cache` がプロセス単位という使い分けが重要。
+`@functools.wraps` なしのデコレーターは FastAPI の operationId を破壊するため、
+カスタムデコレーター規約への追記が推奨される。

nene2_python-1.8.38/docs/field-trials/2026-05-field-trial-167.md

@@ -0,0 +1,239 @@
+# FT167: enum モジュール
+
+**日付**: 2026-05-21
+**テーマ**: `enum` モジュール — `Enum`・`StrEnum`・`IntEnum`・`Flag`・`auto()`・状態遷移・権限管理
+**セキュリティ診断**: なし（167 % 3 = 2）
+
+---
+
+## 概要
+
+Python 標準ライブラリの `enum` モジュールを nene2-python フレームワーク上で検証した。
+`enum` はドメインモデルの状態・権限・分類を型安全に表現するための中核モジュール。
+`StrEnum`（Python 3.11+）は Pydantic v2 と組み合わせて HTTP 境界での型検証に直接使える。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft167-enum/`
+
+### 主要機能
+
+| クラス/関数 | 概要 |
+|---|---|
+| `Color(Enum)` | 基本 Enum。値で参照・イテレーション |
+| `TaskStatus(StrEnum)` | `auto()` で名前を小文字化。文字列として使用可能 |
+| `Priority(IntEnum)` | 比較・算術演算が可能な整数 Enum |
+| `Permission(Flag)` | ビットフラグで権限を組み合わせ（READ / WRITE / DELETE / ADMIN） |
+| `HttpMethod(StrEnum)` | カスタムプロパティ（`is_safe`, `has_body`）付き |
+| `Task` dataclass | `TaskStatus` / `Priority` / `Permission` を持つドメインオブジェクト |
+| `transition_task()` | 許可された状態遷移のみ受け付ける型安全な状態機械 |
+| `describe_permission()` | `Flag` の組み合わせを人間可読な辞書に変換 |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| GET | `/enum/colors` | 全 Color 一覧 |
+| GET | `/enum/task-status` | TaskStatus 一覧・StrEnum 確認 |
+| POST | `/enum/transition` | 状態遷移バリデーション |
+| GET | `/enum/priority` | Priority 比較 |
+| POST | `/enum/permission` | Permission フラグ組み合わせ |
+| GET | `/enum/http-method` | HttpMethod プロパティ |
+
+---
+
+## テスト結果
+
+**32 passed（摩擦ゼロ）**
+
+```
+32 passed in 1.00s
+```
+
+---
+
+## 摩擦ポイント
+
+**今回の FT では実装上の摩擦はゼロだった。**
+
+---
+
+## 観察点
+
+### 観察1: `StrEnum` + `auto()` で名前を自動的に小文字化
+
+```python
+class TaskStatus(enum.StrEnum):
+    PENDING = enum.auto()   # → "pending"
+    RUNNING = enum.auto()   # → "running"
+```
+
+`StrEnum` の `auto()` は `_generate_next_value_()` をオーバーライドして
+メンバー名を小文字にする。つまり `TaskStatus.PENDING == "pending"` が成立し、
+JSON シリアライズ時に `.value` を呼ぶ必要がない。
+Pydantic v2 + FastAPI ではフィールドに `TaskStatus` を指定するだけで HTTP Body・レスポンスで使える。
+
+### 観察2: `Flag` でビット権限管理 — `in` 演算子でチェック
+
+```python
+class Permission(enum.Flag):
+    READ = enum.auto()       # 1
+    WRITE = enum.auto()      # 2
+    DELETE = enum.auto()     # 4
+    ADMIN = READ | WRITE | DELETE  # 7
+
+rw = Permission.READ | Permission.WRITE
+assert Permission.READ in rw      # True
+assert Permission.DELETE not in rw  # True
+```
+
+`Flag` のビット演算（`|`, `&`, `~`）は直感的で、RBAC の権限チェックに最適。
+`Permission.NONE = 0` を定義することで「権限なし」を明示的に表現できる。
+
+### 観察3: `IntEnum` は `int` として比較・ソートできる
+
+```python
+assert Priority.LOW < Priority.HIGH   # True（数値比較）
+assert Priority.LOW + Priority.MEDIUM == 6  # 算術演算も可
+sorted_priorities = sorted([Priority.HIGH, Priority.LOW])  # [LOW, HIGH]
+```
+
+DB のカラム値が整数の場合、`IntEnum` を使うと ORM との相互変換がシームレス。
+ただし算術演算の結果が `int`（Enum でない）になることに注意。
+
+### 観察4: Enum に `@property` を追加してドメインロジックをカプセル化
+
+```python
+class HttpMethod(enum.StrEnum):
+    @property
+    def is_safe(self) -> bool:
+        return self in (HttpMethod.GET,)
+
+    @property
+    def has_body(self) -> bool:
+        return self in (HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH)
+```
+
+Enum にメソッドを追加することで、`if method == "GET":` の散在を防ぎ
+ドメインロジックを 1 箇所に集約できる。`@property` との相性も良い。
+
+### 観察5: Pydantic v2 は `StrEnum` を文字列バリデーションとして扱う
+
+```python
+class TransitionBody(BaseModel):
+    current_status: TaskStatus   # "pending" / "running" / "done" / "failed" のみ許可
+    new_status: TaskStatus
+```
+
+Pydantic v2 は `StrEnum` フィールドに対して、有効な enum 値のみを受け付け、
+無効な値には自動的に 422 を返す。`Literal["pending", "running", ...]` より型安全。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `TaskStatus(StrEnum)` は nene2 の Note ドメインの `status` フィールドに直接適用できる
+- `Permission(Flag)` は `ApiKeyAuthMiddleware` の権限スコープ実装に応用可能
+- `Priority(IntEnum)` はタスクスケジューリング・DB ソートに使いやすい
+- Enum をレスポンスモデルに含める場合、FastAPI は自動的に `.value` でシリアライズする
+- `transition_task()` のようなドメイン状態機械は UseCase 内に実装するパターンが nene2 アーキテクチャと整合する
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+`Enum` の基本（`class Color(Enum): RED = "red"`）は直感的に理解できる。
+`StrEnum`・`IntEnum`・`Flag` の使い分けは最初は混乱する。
+
+**ドキュメント理解**: 「どれを使えばいいか」の判断基準がなければ基本 `Enum` だけを使い続ける。
+nene2 の how-to に「HTTP API の状態フィールドは `StrEnum` を使う」という指針があれば一発で決まる。
+
+**事故リスク**: 低。Enum の誤用は大きな事故にはつながりにくい。
+ただし `IntEnum` の算術演算結果が `int` になることを知らず、Enum メンバーを期待してバグになる可能性。
+
+**規約の使いやすさ**: `StrEnum` + `auto()` のパターンはコピペで使える。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+文字列定数の代わりに `"pending"` / `"running"` をそのまま使う習慣がある。
+`StrEnum` を知ると「これだけで typo を防げるんだ」と即採用する傾向。
+
+**コピペ可能性**: `StrEnum` + `auto()` のパターンは一度見れば再現できる。
+
+**拡張時の罠**: `Flag` の複合演算（`rw = READ | WRITE`）を見て、
+「`|` は OR だから `rw == READ or rw == WRITE` と同じ」と誤解し、
+`if rw == READ:` と書いてしまう（`in` を使わなければならない）。
+
+**セキュリティ的な事故リスク**: 中。`Permission.ADMIN = READ | WRITE | DELETE` を定義したつもりが、
+ビット演算の順序ミスで意図しない権限の組み合わせになるリスク。テストで確認が必要。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+TypeScript の `enum` / `const enum` / `union type` との比較で混乱する可能性。
+Python の `Enum` はクラスであり、TS の `enum` より強力（メソッド追加可能）。
+
+**エラーレスポンスの質**: Pydantic が `StrEnum` を自動バリデーションして 422 を返すため、
+クライアントには明確なエラーが返る。
+
+**事故リスク**: 低。TS の概念と対応関係が作れる。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Django の `CharField(choices=...)` + `TextChoices` との比較で評価する。
+`StrEnum` は `TextChoices` より汎用的で型安全性が高い。
+
+**他フレームワークとの差異**:
+- Django: `models.TextChoices` → DB のチョイスとモデルを一元管理
+- nene2-python: `StrEnum` → HTTP 境界と UseCase で型安全に使い、Repository が DB マッピングを担当
+- 関心の分離がより明確
+
+**本番投入可能性**: 問題なし。`StrEnum` は SQLAlchemy の `Enum` 型と組み合わせると完璧。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+**コードレビューチェックポイント**:
+- [ ] 状態遷移が `transition_task()` のように集約されているか（散在した `if status == "done":` を禁止）
+- [ ] `Flag` の権限チェックで `perm == Permission.READ`（完全一致）でなく `Permission.READ in perm`（部分一致）を使っているか
+- [ ] `IntEnum` の算術演算結果が `int` になることをコードが前提にしていないか
+- [ ] Enum メンバーを文字列比較（`status == "pending"`）でなく Enum 比較（`status == TaskStatus.PENDING`）しているか
+- [ ] DB に保存する Enum 値は `.value` を使って保存し、読み出し時に Enum に変換しているか
+
+**チームでの安全なパターン**: 状態遷移グラフは `dict[Status, set[Status]]` で明示的に宣言し、
+UseCase の外部に公開する（テストしやすくなる）。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+**ポリシー達成度**: 高
+
+**「初心者でも安全な API」達成度**: 高
+- Pydantic + `StrEnum` の組み合わせにより、HTTP 境界での自動バリデーションが確立される
+- 無効な状態値は 422 で自動的に拒否される
+
+**設計上の負債・ドキュメント不足**:
+- nene2 の example ドメイン（Note / Tag / Comment）に `StrEnum` を使っているフィールドがない
+- Note の `status` フィールドに `StrEnum` を導入するサンプルがあると良い
+
+**Follow-up Issue 候補**: `docs: StrEnum を使ったドメイン状態管理の how-to を追加`
+
+---
+
+## Follow-up Issues
+
+| 優先度 | タイトル | 種別 |
+|---|---|---|
+| 中 | `docs: StrEnum + Pydantic + 状態遷移パターンの how-to を追加` | docs |
+| 低 | `feat: example/note に status フィールド（StrEnum）を追加してパターンを実演` | feat |
+
+---
+
+## まとめ
+
+`enum` モジュールは nene2-python のドメインモデル設計に直接適用できる重要な機能。
+`StrEnum` + Pydantic v2 の組み合わせで HTTP 境界の自動バリデーションが完成し、
+`Flag` による権限管理は RBAC の実装基盤になる。
+32 テスト全通過、摩擦ゼロ。
+状態遷移を `dict[Status, set[Status]]` で宣言するパターンは UseCase 内で採用が推奨される。

{nene2_python-1.8.36 → nene2_python-1.8.38}/pyproject.toml

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