# agesuta

## README.txtはAIによる生成ファイルです。(README.txt is a file generated by AI.)

Python標準の`logging`モジュールをベースにしたカスタムロギングユーティリティです。`rich`による色付きコンソール出力、カスタムローテーションハンドラによるファイルロギング、ログファイルのエンコーディング処理機能を備えています。

**注記:** 現在のバージョンに含まれるカスタムファイルローテーションハンドラ（`CustomLevelRotatingFileHandler`, `CustomDateRotatingFileHandler`）は、`CustomLogger.log_main`で生成されるファイル名との間に論理的な不整合がある可能性があります。これにより、一部の設定でログファイルが正しくローテーションされない場合があります。使用には注意が必要か、ハンドラの実装を確認してください。

## インストール

```bash
pip install agesuta
```

## 使用方法

**基本的な使用例を以下に示します：**

```python
import logging
from agesuta import CustomLogger, log_decorator

# ロガーの初期設定を行うインスタンスを作成します
# これにより、ルートロガーにハンドラが設定されます
Cl_logger = CustomLogger(
    flag_datelog=False, # 日付ベースの単一ログファイルにする場合は True に設定
    dir_path="./Log",
    log_encode="utf-8",
    showlevel="INFO", # コンソール出力の最小レベル
    maxBytes=5 * 1024 * 1024, # ログファイルを5MBでローテーション
    backupCount=5 # バックアップファイルを最大5世代保持
)
Cl_logger.log_main() # ロギング設定を適用します

# 標準のlogging.getLogger()を使ってロガーインスタンスを取得します
# これは Cl_logger.log_main() で設定されたハンドラを使用します
logger = logging.getLogger(__name__)

logger.debug("これはデバッグメッセージです。")
logger.info("これは情報メッセージです。")
logger.warning("これは警告メッセージです。")
logger.error("これはエラーメッセージです。")
logger.critical("これはクリティカルメッセージです。")

# log_decorator の使用例
# from agesuta import log_decorator # パッケージ名に合わせて変更してください

# @log_decorator(logger)
# def my_function(arg1, arg2):
#     logger.info("関数の中で何か処理しています")
#     return arg1 + arg2

# result = my_function(10, 20)
# print(f"関数の結果: {result}")
```

`flag_datelog` が `False` の場合、異なるレベル（例: `my_script_0_debug.log`, `my_script_1_info.log` など）ごとに個別のログファイルが `dir_path` に作成されます。
`flag_datelog` が `True` の場合、日付を含む単一のログファイル（例: `my_script_YYYY-MM-DD.log`）が作成されます。

## CustomLogger パラメータ

- `flag_datelog` (`bool`): `True`の場合、日付ベースのログファイル命名規則（`basename_YYYY-MM-DD.log`）を使用し、`CustomDateRotatingFileHandler`を使用します。`False`（デフォルト）の場合、レベルベースのログファイル命名規則（`basename_level.log`）を使用し、`CustomLevelRotatingFileHandler`を使用します。
- `dir_path` (`str`): ログファイルが保存されるディレクトリです（デフォルト: `./Log`）。
- `log_encode` (`str`): ログファイルのエンコーディングです（デフォルト: `"utf-8"`）。初期化時に、異なるエンコーディングの既存ログファイルは変換されます。
- `maxBytes` (`int`): ログファイルがローテーションされるまでの最大バイト数です（デフォルト: `10 * 1024 * 1024` バイト、つまり 10MB）。
- `backupCount` (`int`): ローテーション後に保持するバックアップログファイルの数です（デフォルト: `10`）。
- `showlevel` (`str`): コンソール（RichHandlerを使用）に表示するログの最小レベルです。 `"DEBUG"`, `"INFO"`（デフォルト）, `"WARNING"`, `"ERROR"`, `"CRITICAL"`, `"NOTSET"` を受け付けます。大文字小文字は区別されません。
- `flag_unnecessary_loggers_to_error` (`bool`): `True`（デフォルト）の場合、一般的で詳細なサードパーティライブラリ（例: `werkzeug`, `urllib3`, `httpx` など）のロガーレベルを `ERROR` に設定し、コンソールのノイズを減らします。

## カスタムファイルハンドラ

このパッケージには、`logging.handlers.RotatingFileHandler` をベースにしたカスタムハンドラが含まれています：

- `NoColorFormatter`: ANSIエスケープシーケンスを取り除くロギングフォーマッターです。`RichHandler`使用時のプレーンテキストログファイルに有用です。
- `CustomLevelRotatingFileHandler`: サイズベースのローテーションを意図したカスタムハンドラで、`flag_datelog` が `False` の場合に使用されます。
- `CustomDateRotatingFileHandler`: 日付を意識した命名規則を持つサイズベースのローテーションを意図したカスタムハンドラで、`flag_datelog` が `True` の場合に使用されます。
**ローテーションに関する注記:** 上記で述べたように、カスタムハンドラのローテーションロジックと `CustomLogger.log_main` で生成されるファイル名との間に問題がある可能性があります。

## log_decorator

関数への入退室およびエラーを自動的に`DEBUG`レベルと`ERROR`レベルでログに記録するためのシンプルなデコレーター（`log_decorator`）が提供されています。

## ライセンス

このプロジェクトはMITライセンスの下で提供されます - 詳細については LICENSE ファイルを参照してください。
