color-logger-utils 0.1.0
Dependency-injection friendly logging utilities with colorized console output.
License: MIT
Requires Python: >=3.10

# 📘 color-logger-utils

**color-logger-utils** は、環境変数でログレベル・ログファイルを柔軟に切り替えられる
**依存注入フレンドリーな Python ログユーティリティ**です。

* ✔ **カラー付きコンソール出力（ANSI Escape）**
* ✔ **LOG_LEVEL / LOG_FILE_PATH で挙動を完全制御**
* ✔ **既存ロガーがある場合は再設定せず “尊重” して再利用**
* ✔ **DI（依存注入）デコレーターで logger を自動注入**
* ✔ **ログディレクトリは自動作成され、初期設定不要**

Python 標準 `logging` を使ったまま、**最小限のコード変更で強力なロギング基盤**を導入できます。

---

# 🚀 Installation

```bash
uv add color-logger-utils
# または
pip install color-logger-utils
```

---

# 🔧 Quick Start

## 1. シンプルにロガーを取得して使う

```python
from logger_utils.logger_factory import get_logger

logger = get_logger("my-app")

logger.info("Hello world!")
logger.debug("This will be hidden unless LOG_LEVEL=DEBUG")
```

---

## 2. デコレーターで logger を自動注入

```python
from logger_utils import with_logger

@with_logger(name="my-service")
def main(logger):
    logger.info("Injected logger works!")

main()
```

関数が `logger` 引数を受け取れる場合、自動的に渡されます。

---

# 🌱 Environment Variables

color-logger-utils の挙動は、**環境変数で完全に制御できます**。

---

## 🔸 `LOG_LEVEL`

ログレベルを指定します。

```bash
export LOG_LEVEL=DEBUG
```

サポート値（大文字・小文字問わず）:

| 値              | 対応レベル            |
| -------------- | ---------------- |
| DEBUG          | logging.DEBUG    |
| INFO           | logging.INFO     |
| WARN / WARNING | logging.WARNING  |
| ERROR          | logging.ERROR    |
| CRITICAL       | logging.CRITICAL |
| 不正な値           | INFO にフォールバック    |

内部では `map_level()` で安全にマッピングされます。

---

## 🔸 `LOG_FILE_PATH`

ログ出力パスを制御します。

```bash
export LOG_FILE_PATH=/var/log/my_app/
```

挙動は以下のように分岐します：

| LOG_FILE_PATH の値  | 解釈                       |
| ----------------- | ------------------------ |
| 未設定 / 空文字         | `logs/app.log` を使用（自動作成） |
| 既存ディレクトリ          | `その中の app.log` を使用       |
| `/` or `\` で終わるパス | ディレクトリ扱い → `app.log` を付与 |
| ファイルパス            | そのファイルに出力                |

内部では `_resolve_log_path_from_env()` が全てハンドルします。

---

# 🧠 Design & Behavior

## ✔ 既存ロガーを尊重して再設定しない

`logging.getLogger(name)` にすでにハンドラが付いている場合：

* **環境変数を無視**
* **既存設定をそのまま利用**

という「安全な挙動」を取ります。

これにより、アプリやフレームワーク側でロギング設定を行っている場合も、
本ライブラリが壊すことはありません。

---

## ✔ DI（依存注入）デコレーターの仕組み

```python
@with_logger(name="service")
def fn(logger):
    logger.info("ok")
```

* `logger` 引数がある → kwargs に自動注入
* ない → その関数の **モジュール全体に `logger` を注入**

という 2 段構えの実装になっています。

---

## ✔ カラー付きコンソール出力

`custom_formatter.py` により、ログレベルに応じて ANSI カラーが付与されます。

例：

* DEBUG → 灰色
* INFO → 青 / 緑
* WARNING → 黄色
* ERROR → 赤
* CRITICAL → 赤背景

> ⚠️ **注意（Windows）:**
> 古い Windows コンソールでは ANSI カラーが無効な場合があります。
> Windows Terminal / PowerShell では問題ありません。

---

# 🧪 Testing

このパッケージは pytest を前提としています。

## 実行

```bash
uv run pytest
```

## テストポリシー（仕様と一致）

✔ `map_level` が文字列／レベル番号／不正値を期待通り扱う
✔ `LOG_FILE_PATH` の全分岐（未設定 / ディレクトリ / ファイル）
✔ `with_logger` が logger を注入する
✔ 既存ロガーがいる場合の再利用
✔ ログ出力パスが自動生成される

---

# 📂 Project Structure

標準的な **src レイアウト** を採用しています。

```text
project/
├── pyproject.toml
├── README.md
├── src/
│   └── logger_utils/
│       ├── __init__.py
│       ├── constants.py
│       ├── custom_formatter.py
│       ├── level_mapper.py
│       ├── logger_factory.py
│       └── logger_injector.py
└── tests/
    ├── test_level_mapper.py
    ├── test_log_path_resolver.py
    └── test_with_logger.py
```

---

# 📦 Release

PyPI 公開は次の通り。

```bash
uv build
uv publish --token pypi-xxxx
```

---

# 📄 License

MIT License