agesuta

agesuta

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

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

インストール

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

pip install agesuta

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

pip install agesuta[slack]

使用方法

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

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) でラップしてください。

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)

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

改善タスク一覧

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