color-logger-utils 0.1.0

Dependency-injection friendly logging utilities with colorized console output.

📘 color-logger-utils

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

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

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

---

🚀 Installation

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

---

🔧 Quick Start

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

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 を自動注入

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

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

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

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

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（依存注入）デコレーターの仕組み

@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 を前提としています。

実行

uv run pytest

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

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

---

📂 Project Structure

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

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 公開は次の通り。

uv build
uv publish --token pypi-xxxx

---

📄 License

MIT License