Skip to main content

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 フォーマット適用とテストコードによる動作確認

Metadata

Release files for agesuta 0.1.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agesuta 0.1.24
File Size Uploaded Provenance Actions
agesuta-0.1.24.tar.gz 47.7 kB Without provenance Details for agesuta-0.1.24.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agesuta 0.1.24
File Interpreter ABI Platform Actions
agesuta-0.1.24-py3-none-any.whl Python 3 none any Details for agesuta-0.1.24-py3-none-any.whl

Total release size: 83.3 kB

Release files / agesuta-0.1.24.tar.gz

Download URL agesuta-0.1.24.tar.gz
Size 47.7 kB
Tags Source
SHA-256 checksum
How to use checksums
baa3285ab15d32e57fd4e518314babbf8891d5e9962722bbdd89c1b92bfff0d8
BLAKE2b-256 checksum
How to use checksums
770dc1b385341fba691d25daf131fc7796d879cc97755ae48af2106fa5e56840
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.14

Release files / agesuta-0.1.24-py3-none-any.whl

Download URL agesuta-0.1.24-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
725ac15fa65229d341b821181e3bb226aef376f085b9bcfe1ccf1c39ed19b84f
BLAKE2b-256 checksum
How to use checksums
8a1018ec12996a89f8a3d25632b89ae1b5e72cf9645e6d2ffaaaaaf94e2975d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.14

Security for agesuta 0.1.24

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page