logging --- イベントロギング

このモジュールは、標準 Python の logging パッケージの軽量なサブセットを MicroPython 向けに適応させたものです。階層的に命名された Logger オブジェクトによるレベル付きロギング、少数のハンドラ（StreamHandler、FileHandler）、Formatter を介した printf 形式のフォーマット、およびルートロガーを操作する関数に相当するモジュールレベルの便利関数をサポートします。

このモジュールは CPython の馴染みのある API に十分近く準拠しているため、標準ライブラリ向けに書かれた単純なアプリケーションはそのまま動作するはずです。フィルタ、複数プロセスのロック、設定ファイル形式、およびほとんどのハンドラクラスは提供されません。

レベル定数

logging.CRITICAL: int

数値 50。回復不能なエラーに使用します。

logging.ERROR: int

数値 40。深刻な問題に使用します。

logging.WARNING: int

数値 30。新たに設定されたルートロガーのデフォルトレベルです。

logging.INFO: int

数値 20。確認メッセージに使用します。

logging.DEBUG: int

数値 10。きめ細かい診断出力に使用します。

logging.NOTSET: int

数値 0。レベルが設定されていないロガーを示します（その場合の実効レベルはルートロガーまたは WARNING から継承されます）。

関数

logging.getLogger(name: str | None = None) → Logger

name で登録された Logger を返し、初回使用時に作成します。name が None の場合はルートロガーが返されます。name="root" を指定した（または name を指定しない）最初の呼び出しでは、暗黙的に basicConfig が呼び出され、sys.stderr に書き込むデフォルトの StreamHandler が割り当てられます。

logging.log(level: int, msg: str, *args) → None

ルートロガーで level のメッセージをログ出力します。args は printf 形式の % フォーマットを使って msg に埋め込まれます。単一の dict 引数はマッピングとして使用されます。

logging.debug(msg: str, *args) → None

getLogger().debug(msg, *args) と同等です。

logging.info(msg: str, *args) → None

getLogger().info(msg, *args) と同等です。

logging.warning(msg: str, *args) → None

getLogger().warning(msg, *args) と同等です。

logging.error(msg: str, *args) → None

getLogger().error(msg, *args) と同等です。

logging.critical(msg: str, *args) → None

getLogger().critical(msg, *args) と同等です。

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

getLogger().exception(msg, *args, exc_info=exc_info) と同等です。メッセージを ERROR でログ出力し、exc_info が真の場合は加えて現在の例外のトレースバックをフォーマットします。exc_info 自体が BaseException の場合はその例外のトレースバックが使用され、それ以外の場合は利用可能であれば sys.exc_info() が参照されます。

logging.shutdown() → None

既知のすべてのロガーに割り当てられたすべてのハンドラを閉じ、ロガーを破棄します。sys.atexit フックが利用可能な場合は、それを通じて自動的に登録されます。

logging.addLevelName(level: int, name: str) → None

テキストの name を数値の level に関連付け、Formatter が %(levelname)s を介してレンダリングできるようにします。

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

ルートロガーを単一のハンドラで設定します。

filename が指定された場合は、filemode と encoding を使って FileHandler が作成されます。それ以外の場合は、stream（デフォルトは sys.stderr）に書き込む StreamHandler が使用されます。

format と datefmt は新しい Formatter にそのまま渡されます。

level はハンドラのレベルとルートロガーのレベルの両方を設定します。

ルートロガーにすでにハンドラがある場合、この関数は何もしません。ただし force が True の場合は、既存のハンドラが閉じられて置き換えられます。

クラス

class logging.Logger(name: str, level: int = NOTSET)

名前付きのロガーです。同じ名前に対して getLogger が同じインスタンスを返せるよう、ロガーは直接ではなく getLogger を介して構築してください。

name: str

ロガーのドット区切りの名前。

level: int

設定された数値レベル。0（NOTSET）は「継承」を意味します。

handlers: list

このロガーに割り当てられた Handler インスタンスのリスト。空の場合、メッセージはルートロガーのハンドラにディスパッチされます。

setLevel(level: int) → None

ロガーのしきい値レベルを設定します。

isEnabledFor(level: int) → bool

level のメッセージがこのロガーによって処理される場合は True を返します。

getEffectiveLevel() → int

次のうち最初の非ゼロ値を返します。このロガーのレベル、ルートロガーのレベル、または WARNING。

log(level: int, msg: str, *args) → None

msg を level でログ出力します。args は % 演算子で msg に埋め込まれます。最初の位置引数が dict の場合はマッピングとして使用されます。

debug(msg: str, *args) → None

msg を DEBUG でログ出力します。

info(msg: str, *args) → None

msg を INFO でログ出力します。

warning(msg: str, *args) → None

msg を WARNING でログ出力します。

error(msg: str, *args) → None

msg を ERROR でログ出力します。

critical(msg: str, *args) → None

msg を CRITICAL でログ出力します。

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

msg を ERROR でログ出力し、exc_info が真の場合はフォーマットされたトレースバックを追加します。exc_info が BaseException インスタンスの場合はその例外のトレースバックがレンダリングされ、それ以外の場合は sys.exc_info() を介して現在の例外が参照されます。

addHandler(handler: Handler) → None

handler をこのロガーに割り当てます。

hasHandlers() → bool

このロガーにハンドラが割り当てられている場合は True を返します。

class logging.Handler(level: int = NOTSET)

すべてのハンドラの基底クラスです。サブクラスは emit() を実装します。

level: int

ハンドラのしきい値レベル。

formatter: 'Formatter | None'

現在の Formatter、または None。

setLevel(level: int) → None

ハンドラのしきい値レベルを設定します。

setFormatter(formatter: Formatter) → None

formatter をこのハンドラに割り当てます。

format(record: LogRecord) → str

設定されたフォーマッタを使って record をレンダリングします。

close() → None

ハンドラが保持しているリソースを解放します。shutdown から、また FileHandler が閉じられる際に呼び出されます。

class logging.StreamHandler(stream=None)

フォーマットされたレコードに続けて self.terminator（デフォルトは "\n"）を stream に書き込むハンドラです。stream のデフォルトは sys.stderr です。

stream

出力先のストリームオブジェクト。

terminator: str

フォーマットされた各レコードの後に追加される文字列。デフォルトは "\n" です。

emit(record: LogRecord) → None

record のレベルがハンドラのしきい値を満たす場合に、それを stream に書き込みます。

close() → None

下層のストリームが flush メソッドを公開している場合に、それをフラッシュします。

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

指定された mode と encoding で filename を開き、フォーマットされたレコードをそこに書き込む StreamHandler のサブクラスです。下層のファイルは close() で閉じられます。

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

LogRecord インスタンスを文字列にレンダリングします。

fmt は printf 形式のテンプレートです。認識されるキーは %(name)s、%(message)s、%(msecs)d、%(asctime)s、%(levelname)s です。未設定の場合は "%(levelname)s:%(name)s:%(message)s" がデフォルトとなります。

datefmt は %(asctime)s をレンダリングするために使用される time.strftime のテンプレートです。デフォルトは "%Y-%m-%d %H:%M:%S" です。

usesTime() → bool

フォーマットテンプレートが asctime を参照している場合は True を返します。

formatTime(datefmt: str, record: LogRecord) → str | None

record.ct を time.strftime と datefmt を使ってフォーマットします。time.strftime が利用できないプラットフォームでは None を返します。

format(record: LogRecord) → str

record をレンダリングします。テンプレートが asctime を使用している場合は、まず formatTime() が呼び出されて record.asctime が設定されます。

class logging.LogRecord

Logger からそのハンドラへ渡されるデータのコンテナです。インスタンスは set() を介して値が設定されます。ロガーの実装ではアロケーションを減らすため、ロガーごとに単一のレコードを再利用します。

name: str

発生元のロガーの名前。

levelno: int

このレコードの数値レベル。

levelname: str

テキストのレベル名。

message: str

完全にフォーマットされたログメッセージ。

ct: float

time.time() が返す作成時刻。

msecs: int

ct のミリ秒成分。

asctime: str | None

人間が読めるタイムスタンプ。Formatter によって遅延的に設定されます。

set(name: str, level: int, message: str) → None

指定された値でレコードを初期化し、現在の時刻を取得します。