Metadata-Version: 2.4
Name: agesuta
Version: 0.1.23
Summary: A custom logging utility and other utilities with Rich console output, file handling, Slack notification, etc.
Home-page: https://github.com/AgemameSutachi/agesuta
Author: AgemameSutachi
Author-email: sutachiagemame@gmail.com
License: MIT
Keywords: logging custom logger rich file rotation slack requests utility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: Communications :: Chat
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2025.4.26
Requires-Dist: chardet>=5.2.0
Requires-Dist: rich>=14.0.0
Requires-Dist: tzdata>=2024.1
Provides-Extra: slack
Requires-Dist: slack_sdk>=3.35.0; extra == "slack"
Requires-Dist: requests>=2.32.3; extra == "slack"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# agesuta

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

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

## インストール

ロギング機能および設定管理機能のみを使用する（オフライン環境や、余計な外部依存パッケージをインストールしたくない）場合：

```bash
pip install agesuta
```

Slack通知連携機能（`SlackPoster`）も併せて使用したい場合：

```bash
pip install agesuta[slack]
```

## 使用方法

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

```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`）が作成されます。

いずれの場合も、ファイルには`DEBUG`以上の全レベルのログメッセージが出力され、`maxBytes`/`backupCount`で指定したサイズ・世代数に基づいてローテーションされます（`showlevel`はコンソール表示のみに影響し、ファイル出力の対象レベルには影響しません）。

## 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` の場合に使用されます。日付が変わると自動的に新しい日付のファイルへ切り替わります。

## log_decorator

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

## 認証情報のマスク

ログに出力される文字列の中に、APIキーやトークンの形をしたものが含まれる場合、自動的に伏せ字へ置き換える機能です。

`CustomLogger.log_main()` を呼んでいれば、追加の設定なしで自動的に効きます。素の `logging` を使っている場合は、`install_secret_mask()` をルートロガーへ1度呼ぶことでまとめて後付けできます。個別の `Formatter` にだけ適用したい場合は、`wrap_formatter(既存のFormatter)` でラップしてください。

```python
from agesuta import install_secret_mask, wrap_formatter

# 素の logging を使っている場合、ルートロガーの全ハンドラへまとめて適用
install_secret_mask()

# 個別の Formatter にだけ適用したい場合
handler.setFormatter(wrap_formatter(handler.formatter))
```

`install_secret_mask()` は、呼んだ時点でルートロガーに存在するハンドラにだけ適用されます。あとからハンドラを追加した場合は、そのハンドラには効きません。追加のたびにもう一度呼ぶか、`wrap_formatter()` で個別に適用してください。

マスクは値の先頭6文字を残し、それ以降を `*` に置き換えます（例: `xoxb-1***...`）。先頭を残すことで、値そのものを明かさずに「どの種類の認証情報か」を障害調査で判別できます。

### 対応している形式

- URLクエリパラメータ（`?key=...`、`&access_token=...` 等）の値
- 設定ファイル形式（`slack_token: xxx`、`API_KEY = xxx`、JSON形式の `"api_key": "xxx"` 等）の値
- YouTube Data APIキー（`AIza...`）
- Slackのボット/ユーザー/アプリトークン（`xoxb-`、`xoxp-`、`xoxa-`、`xoxr-`、`xoxs-`、`xapp-`）
- OpenAI形式のシークレットキー（`sk-`）
- GitHubの個人アクセストークン（`ghp_`）
- 汎用トークン接頭辞（`tk_`）

### 拾えないもの

接頭辞や項目名を手がかりにしているため、次のような値は拾えません。

- 接頭辞を持たない値が、項目名（`password:` 等）を伴わずに単独でログへ出た場合
- 上記いずれの接頭辞・項目名にも一致しない、独自形式の認証情報

### 誤って伏せられる場合

対象は「その形式でしかありえないもの」に絞っていますが、次のような値は秘密でなくても伏せられることがあります。

- `?key=` や `&token=` に続く値（設定名やIDが入っていても対象になります）
- `password:` `api_key:` などの項目名に続く値

ログの内容を書き換える機能なので、導入前に、伏せられて困る値がログに出ていないかを確認してください。

## ライセンス

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

## 変更履歴 (0.1.20 / 2026-07-12)

公開ライブラリとしての正しさを高めるための修正を行いました。

### 修正内容
- **依存関係**: `setup.py` の `install_requires` に `tzdata` を追加。`zoneinfo` を使用するため、これが無いとタイムゾーンデータを持たない環境（Windows 等）で `import agesuta` 自体が失敗していた不具合を修正。
- **対応 Python**: `zoneinfo`（Python 3.9+）に合わせ `python_requires` を `>=3.9` に修正（従来の 3.6〜3.8 表記を是正）。
- **`com.py`**: `set_logdir(encoding=...)` が別属性に代入され効かなかった不具合を修正。未使用インポート・`bare except` の整理。
- **`configmanager.py`**: 既定引数の副作用（`config_path` のインポート時評価、可変デフォルト `type_dic={}`）を修正。設定読込時に `optionxform=str` を適用し、大文字を含むキーが書込→読戻で失われる不整合を修正。
- **`slackapi.py`**: `get_channelid` のチャンネルID判定を厳密化し、チャンネル名の誤検知を防止。未使用インポートの整理。

## Antigravityによる改善プロジェクト (2026-05-23)

ライブラリの全体的なスキャンを行い、堅牢性と使いやすさを向上させるための改善タスクを定義し、実行しました。

### 改善タスク一覧
- [x] 開発仮想環境（venv）の再作成（Python 3.13 への追従）
- [x] `com.py`: `CustomLevelRotatingFileHandler` のファイル名パースバグ修正（ファイル名に `.` が含まれる場合の崩壊防止）
- [x] `com.py`: `CustomDateRotatingFileHandler` の日付またぎ時のローテーション不整合修正（日付変更時に自動で新ファイルを作成）
- [x] `com.py`: ファイル操作時の Windows `PermissionError` に対する例外ハンドリングの強化
- [x] `com.py`: クラス/インスタンスメソッドにも対応した高度な `log_decorator` の再実装
- [x] `slackapi.py`: `get_channelid` でチャンネルIDが直接渡された際の即時返却対応（API呼び出しの削減）
- [x] `slackapi.py`: `get_channelid` のページネーション（100件超のチャンネル対応）
- [x] `slackapi.py`: 改善された `log_decorator` の適用とロギングの最適化
- [x] 全体の `black` フォーマット適用とテストコードによる動作確認
