# lifecycle

`beautyspot.lifecycle` モジュールは、データの保持期間（Retention）の解析、および関数名に基づいたポリシーの解決を担います。
現在は **完全修飾名（`module.qualname`）を優先** して解決し、マッチしない場合のみ短い関数名にフォールバックします。

::: beautyspot.lifecycle

## 主要な構成要素

### 1. Retention 解決ロジック (`parse_retention`)

ユーザーが指定した多様な形式（文字列、整数、timedelta）を、内部で扱う `timedelta` オブジェクトへと正規化します。

* **サポートされる形式**:
* **文字列**: `"7d"` (日), `"12h"` (時間), `"30m"` (分) の形式。
* **整数**: 秒単位として扱われます。
* **timedelta**: そのまま利用されます。
* **None**: `Retention.INDEFINITE` (無期限) として扱われます。


### 2. Rule クラス

特定の関数名パターンに対して適用する保持期間を定義するデータクラスです。

| 属性 | 型 | 説明 |
| --- | --- | --- |
| `pattern` | `str` | `fnmatch` 形式のワイルドカードパターン（例: `api_*`） |
| `retention` | `Union[str, int, timedelta, None]` | 適用する保持期間 |


### 3. LifecyclePolicy クラス

ルールの集合を管理し、実行時に特定の関数名に対してどのルールを適用するかを決定（Resolve）します。

* **解決アルゴリズム**: `rules` リストの **先頭から順に** パターンマッチングを行い、最初にマッチしたルールの保持期間を返します。
* **適用順序**: 完全修飾名（`module.qualname`）→ 短い関数名（`func_name`）の順でマッチングします。
* **デフォルト挙動**: マッチするルールがない場合、またはルールリストが空の場合は `Retention.INDEFINITE`（無期限）が返されます。

## 型定義と定数

### Retention クラス

* `INDEFINITE`: `None`（無期限保持を明示するためのエイリアス）。

## 注意事項

* **パターンマッチング**: 内部で `fnmatch.fnmatch` を使用しているため、大文字小文字の区別は OS のファイルシステムルールに依存する可能性があります。一貫性を保つため、関数名の命名規則をプロジェクト内で統一することを推奨します。
* **バリデーション**: `parse_retention` は、不正なフォーマット（例: `"1year"` や `"10s"` *※現状秒単位の文字指定は未サポート*）が渡された場合、`beautyspot.exceptions.ValidationError` を送出します。
