"logging" --- Python 用ロギング機能
***********************************

**ソースコード:** Lib/logging/__init__.py


Important
^^^^^^^^^

このページには、リファレンス情報だけが含まれています。チュートリアルは
、以下のページを参照してください

* 基本チュートリアル

* 上級チュートリアル

* ロギングクックブック

======================================================================

このモジュールは、アプリケーションやライブラリのための柔軟なエラーログ
記録 (logging) システムを実装するための関数やクラスを定義しています。

標準ライブラリモジュールとしてログ記録 API が提供される利点は、すべて
の Python モジュールがログ記録に参加できることであり、これによってあな
たが書くアプリケーションのログにサードパーティーのモジュールが出力する
メッセージを含ませることができます。

もっとも単純な例:

   >>> import logging
   >>> logging.warning('Watch out!')
   WARNING:root:Watch out!

このモジュールは、多くの機能性と柔軟性を提供します。ロギングに慣れてい
ないなら、使い方を理解する最良の方法はチュートリアルを読むことです (**
右上のリンクを参照してください**)。

モジュールで定義されている基本的なクラスと関数を、以下に列挙します。

* ロガーは、アプリケーションコードが直接使うインターフェースを公開しま
  す。

* ハンドラは、(ロガーによって生成された) ログ記録を適切な送信先に送り
  ます。

* フィルタは、どのログ記録を出力するかを決定する、きめ細かい機能を提供
  します。

* フォーマッタは、ログ記録が最終的に出力されるレイアウトを指定します。


ロガーオブジェクト
==================

ロガーには以下のような属性とメソッドがあります。 ロガーを直接インスタ
ンス化することは *絶対に* してはならず、常にモジュール関数
"logging.getLogger(name)" を介してインスタンス化することに注意してくだ
さい。 同じ name で "getLogger()" を複数回呼び出すと、常に同じロガー・
オブジェクトへの参照が返されます。

"name" は "foo.bar.baz" のようにピリオドで分割された (ただし単なるプレ
ーンな "foo" もありえます) 潜在的に階層的な値です。階層リスト中でより
下位のロガーは、上位のロガーの子です。例えば、"foo" という名前を持つロ
ガーがあるとき、"foo.bar", "foo.bar.baz", "foo.bam" という名前を持つロ
ガーはすべて "foo" の子孫です。ロガー名の階層は Python パッケージ階層
と類似していて、推奨される構築方法 "logging.getLogger(__name__)" を使
用してロガーをモジュール単位で構成すれば、Python パッケージ階層と同一
になります。これは、モジュールの中では "__name__" が Python パッケージ
名前空間におけるモジュール名だからです。

class logging.Logger

   propagate

      この属性が真と評価された場合、このロガーに記録されたイベントは、
      このロガーに取り付けられた全てのハンドラに加え、上位 (祖先) ロガ
      ーのハンドラにも渡されます。 メッセージは、祖先ロガーのハンドラ
      に直接渡されます - 今問題にしている祖先ロガーのレベルもフィルタ
      も、どちらも考慮されません。

      この値の評価結果が偽になる場合、ロギングメッセージは祖先ロガーの
      ハンドラに渡されません。

      具体的な例で説明します: "A.B.C" という名前のロガーの propagate
      属性が真と評価された場合、
      "logging.getLogger('A.B.C').error(...)" のようなメソッドの呼び出
      しを通じて "A.B.C" に記録された全てのイベントは、 [ログレベルと
      フィルタの設定を満たした場合に限り] 最初に "A.B.C" に接続された
      ハンドラに渡され、その後 "A.B", "A" という名前のロガー、そしてル
      ートロガーという順番で各ロガーに接続されたハンドラに渡されます。
      この連鎖構造において "A.B.C", "A.B", "A" のいずれかの
      "propagate" 属性が偽に設定された場合、そのロガーがイベントを処理
      する最後のロガーとなり、その時点でイベントの伝播は止まります。

      コンストラクタはこの属性を "True" に設定します。

      注釈:

        ハンドラを、あるロガー *と* その祖先のロガーに接続した場合、同
        一レコードが複数回発行される場合があります。一般的に、ハンドラ
        を複数のロガーに接続する必要はありません。propagate 設定が
        "True" のままになっていれば、ロガーの階層において最上位にある
        適切なロガーにハンドラを接続するだけで、そのハンドラは全ての子
        孫ロガーが記録する全てのイベントを確認することができます。一般
        的なシナリオでは、ハンドラをルートロガーに対してのみ接続し、残
        りは propagate にすべて委ねます。

   setLevel(level)

      このロガーの閾値を *level* に設定します。 *level* よりも深刻でな
      いログメッセージは無視されます; 深刻さが *level* 以上のログメッ
      セージは、ハンドラのレベルが *level* より上に設定されていない限
      り、このロガーに取り付けられているハンドラによって投げられます。

      ロガーが生成された際、レベルは "NOTSET" (これによりすべてのメッ
      セージについて、ロガーがルートロガーであれば処理される、そうでな
      くてロガーが非ルートロガーの場合には親ロガーに委譲させる) に設定
      されます。 ルートロガーは "WARNING" レベルで生成されることに注意
      してください。

      「親ロガーに委譲」という用語の意味は、もしロガーのレベルが
      NOTSET ならば、祖先ロガーの系列の中を NOTSET 以外のレベルの祖先
      を見つけるかルートに到達するまで辿っていく、ということです。

      もし NOTSET 以外のレベルの祖先が見つかったなら、その祖先のレベル
      が探索を開始したロガーの実効レベルとして扱われ、ログイベントがど
      のように処理されるかを決めるのに使われます。

      ルートに到達した場合、ルートのレベルが NOTSET ならばすべてのメッ
      セージは処理されます。そうでなければルートのレベルが実効レベルと
      して使われます。

      レベルの一覧については ロギングレベル を参照してください。

      バージョン 3.2 で変更: *level* パラメータは、 "INFO" のような整
      数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるよ
      うになりました。ただし、レベルは内部で整数として保存されますし、
      "getEffectiveLevel()" や "isEnabledFor()" といったメソッドは、整
      数を返し、また渡されるものと期待します。

   isEnabledFor(level)

      深刻度が *lvl* のメッセージが、このロガーで処理されることになっ
      ているかどうかを示します。このメソッドはまず、
      "logging.disable(level)" で設定されるモジュールレベルの深刻度レ
      ベルを調べ、次にロガーの実効レベルを "getEffectiveLevel()" で調
      べます。

   getEffectiveLevel()

      このロガーの実効レベルを示します。 "NOTSET" 以外の値が
      "setLevel()" で設定されていた場合、その値が返されます。そうでな
      い場合、 "NOTSET" 以外の値が見つかるまでロガーの階層をルートロガ
      ーの方向に追跡します。見つかった場合、その値が返されます。返され
      る値は整数で、典型的には "logging.DEBUG", "logging.INFO" 等のう
      ち一つです。

   getChild(suffix)

      このロガーの子であるロガーを、接頭辞によって決定し、返します。従
      って、"logging.getLogger('abc').getChild('def.ghi')" は、
      "logging.getLogger('abc.def.ghi')" によって返されるのと同じロガ
      ーを返すことになります。これは簡便なメソッドで、親ロガーがリテラ
      ルでなく "__name__" などを使って名付けられているときに便利です。

      バージョン 3.2 で追加.

   debug(msg, *args, **kwargs)

      レベル "DEBUG" のメッセージをこのロガーで記録します。 *msg* はメ
      ッセージの書式文字列で、 *args* は *msg* に文字列書式化演算子を
      使って取り込むための引数です。 (これは、書式化文字列の中でキーワ
      ードを使い、引数として単一の辞書を渡すことができる、ということを
      意味します。) *args* が提供されない場合は *msg* の%フォーマット
      は実行されません。

      *kwargs* のうち、 *exc_info*, *stack_info*, *stacklevel*,
      *extra* という4つのキーワード引数の中身を調べます。

      *exc_info* は、この値の評価値が false でない場合、例外情報がロギ
      ングメッセージに追加されます。もし例外情報をあらわすタプル
      ("sys.exc_info()" 関数によって戻されるフォーマットにおいて)、ま
      たは、例外情報をあらわすインスタンスが与えられていれば、それが使
      用されることになります。それ以外の場合には、 "sys.exc_info()" を
      呼び出して例外情報を取得します。

      2つ目の省略可能なキーワード引数は *stack_info* で、デフォルトは
      "False" です。真の場合、実際のロギング呼び出しを含むスタック情報
      がロギングメッセージに追加されます。これは *exc_info* 指定によっ
      て表示されるスタック情報と同じものではないことに注意してください
      : 前者はカレントスレッド内での、一番下からロギング呼び出しまでの
      スタックフレームですが、後者は例外に呼応して、例外ハンドラが見つ
      かるところまで巻き戻されたスタックフレームの情報です。

      *exc_info* とは独立に *stack_info* を指定することもできます (例
      えば、例外が上げられなかった場合でも、コード中のある地点にどのよ
      うに到着したかを単に示すために)。スタックフレームは、次のような
      ヘッダー行に続いて表示されます:

         Stack (most recent call last):

      これは、例外フレームを表示する場合に使用される "Traceback (most
      recent call last):" を模倣します。

      3番目のオプションキーワード引数は *stacklevel* で、デフォルトは
      "1" です。もしこれが1よりも大きい場合は、 "LogRecord" 内で行番号
      と関数名を算出する時に、指定されたスタックフレームの数をスキップ
      します。これはログヘルパー内部で使われる場合、関数名、ファイル名
      、行番号はそのヘルパーの情報ではなく、そのヘルパーを呼び出した呼
      び出し元のものになります。このパラメータの名前は "warnings" モジ
      ュールと同じものになります。

      4番目のキーワード引数は *extra* で、当該ログイベント用に作られる
      "LogRecord" の __dict__ にユーザー定義属性を加えるのに使われる辞
      書を渡すために用いられます。これらの属性は好きなように使えます。
      たとえば、ログメッセージの一部にすることもできます。以下の例を見
      てください:

         FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
         logging.basicConfig(format=FORMAT)
         d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
         logger = logging.getLogger('tcpserver')
         logger.warning('Protocol problem: %s', 'connection reset', extra=d)

      これは以下のような出力を行います

         2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

      *extra* に渡される辞書のキーはロギングシステムで使われているもの
      と衝突してはいけません。 (ロギングシステムが使うキーの詳細につい
      ては LogRecord 属性 の節を参照してください。)

      これらの属性をログメッセージに使うことにしたなら、少し注意が必要
      です。上の例では、 'clientip' と 'user' が "LogRecord" の属性辞
      書に含まれていることを期待した書式文字列で "Formatter" がセット
      アップされています。もしこれらが欠けていると、書式化例外が発生し
      てしまうためメッセージはログに残りません。したがってこの場合、常
      にこれらのキーを含む *extra* 辞書を渡す必要があります。

      このようなことは煩わしいかもしれませんが、この機能は限定された場
      面で使われるように意図しているものなのです。たとえば同じコードが
      いくつものコンテキストで実行されるマルチスレッドのサーバで、興味
      のある条件が現れるのがそのコンテキストに依存している (上の例で言
      えば、リモートのクライアント IP アドレスや認証されたユーザ名など
      )、というような場合です。そういった場面では、それ用の
      "Formatter" が特定の "Handler" と共に使われるというのはよくある
      ことです。

      このロガー (および "Logger.propagate" 属性を考慮した上で実効的に
      イベントが伝播する祖先のロガー) にハンドラが接続されていない場合
      、メッセージは "lastResort" に設定されたハンドラーに送られます。

      バージョン 3.2 で変更: *stack_info* パラメータが追加されました。

      バージョン 3.5 で変更: *exc_info* パラメータは例外インスタンスを
      受け入れることが可能です。

      バージョン 3.8 で変更: *stacklevel* 引数が追加されました。

   info(msg, *args, **kwargs)

      レベル "INFO" のメッセージをこのロガーで記録します。引数は
      "debug()" と同じように解釈されます。

   warning(msg, *args, **kwargs)

      レベル "WARNING" のメッセージをこのロガーで記録します。引数は
      "debug()" と同じように解釈されます。

      注釈:

        "warning" と機能的に等価な古いメソッド "warn" があります。
        "warn" は廃止予定なので使わないでください - 代わりに "warning"
        を使ってください。

   error(msg, *args, **kwargs)

      レベル "ERROR" のメッセージをこのロガーで記録します。引数は
      "debug()" と同じように解釈されます。

   critical(msg, *args, **kwargs)

      レベル "CRITICAL" のメッセージをこのロガーで記録します。引数は
      "debug()" と同じように解釈されます。

   log(level, msg, *args, **kwargs)

      整数で表したレベル *level* のメッセージをこのロガーで記録します
      。その他の引数は "debug()" と同じように解釈されます。

   exception(msg, *args, **kwargs)

      レベル "ERROR" のメッセージをこのロガーで記録します。引数は
      "debug()" と同じように解釈されます。例外情報がログメッセージに追
      加されます。このメソッドは例外ハンドラからのみ呼び出されるべきで
      す。

   addFilter(filter)

      指定されたフィルタ *filter* をこのロガーに追加します。

   removeFilter(filter)

      指定されたフィルタ *filter* をこのロガーから取り除きます。

   filter(record)

      レコードに対してこのロガーのフィルタを適用し、レコードが処理され
      るべき場合に "True" を返します。フィルタのいずれかの値が偽を返す
      まで、それらは順番に試されていきます。いずれも偽を返さなければ、
      レコードは処理される(ハンドラに渡される)ことになります。ひとつで
      も偽を返せば、発生したレコードはもはや処理されることはありません
      。

   addHandler(hdlr)

      指定されたハンドラ *hdlr* をこのロガーに追加します。

   removeHandler(hdlr)

      指定されたハンドラ *hdlr* をこのロガーから取り除きます。

   findCaller(stack_info=False, stacklevel=1)

      呼び出し元のソースファイル名と行番号を調べます。ファイル名と行番
      号、関数名、スタック情報を 4 要素のタプルで返します。
      *stack_info* が "True" でなければ、スタック情報は "None" が返さ
      れます。

      *stacklevel* パラメータは "debug()" や他のAPIを呼び出すコードか
      ら渡されます。もしこれが1よりも大きい場合は、その超過分は返す値
      を決定する前にスタックフレームをスキップする数として利用されます
      。これは通常、ログAPIをヘルパーやラッパー経由で呼び出す場合に便
      利です。こうすることで、イベントログに記録される情報はヘルパーや
      ラッパーのコードではなく、それらを呼び出しているコードのものとな
      ります。

   handle(record)

      レコードを、このロガーおよびその上位ロガー (ただし *propagate*
      の値が false になったところまで) に関連付けられているすべてのハ
      ンドラに渡して処理します。このメソッドは、ローカルで生成されたレ
      コードだけでなく、ソケットから受信した unpickle されたレコードに
      対しても同様に用いられます。 "filter()" によって、ロガーレベルで
      のフィルタが適用されます。

   makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

      このメソッドは、特殊な "LogRecord" インスタンスを生成するために
      サブクラスでオーバライドできるファクトリメソッドです。

   hasHandlers()

      このロガーにハンドラが設定されているかどうかを調べます。 そのた
      めに、このロガーとロガー階層における祖先からハンドラを探します。
      ハンドラが見つかれば "True" 、そうでなければ "False" を返します
      。 このメソッドは、'propagate' 属性が偽に設定されたロガーを見つ
      けると、さらに上位の探索をやめます。そのロガーが、ハンドラが存在
      するかどうかチェックされる最後のロガーになります。

      バージョン 3.2 で追加.

   バージョン 3.7 で変更: ロガーの pickle 化と unpickle 化ができるよう
   になりました。


ロギングレベル
==============

ログレベルの数値は以下の表のように与えられています。これらは基本的に自
分でレベルを定義したい人のためのもので、定義するレベルを既存のレベルの
間に位置づけるためには具体的な値が必要になります。もし数値が他のレベル
と同じだったら、既存の値は上書きされその名前は失われます。

+----------------+-----------------+
| レベル         | 数値            |
|================|=================|
| "CRITICAL"     | 50              |
+----------------+-----------------+
| "ERROR"        | 40              |
+----------------+-----------------+
| "WARNING"      | 30              |
+----------------+-----------------+
| "INFO"         | 20              |
+----------------+-----------------+
| "DEBUG"        | 10              |
+----------------+-----------------+
| "NOTSET"       | 0               |
+----------------+-----------------+


ハンドラオブジェクト
====================

ハンドラ (Handler) は以下の属性とメソッドを持ちます。 "Handler" は直接
インスタンス化されることはありません; このクラスはより便利なサブクラス
の基底クラスとして働きます。しかしながら、サブクラスにおける
"__init__()" メソッドでは、 "Handler.__init__()" を呼び出す必要があり
ます。

class logging.Handler

   __init__(level=NOTSET)

      レベルを設定して、 "Handler" インスタンスを初期化します。空のリ
      ストを使ってフィルタを設定し、 I/O 機構へのアクセスを直列化する
      ために ("createLock()" を使って) ロックを生成します。

   createLock()

      スレッドセーフでない背後の I/O 機能に対するアクセスを直列化する
      ために用いられるスレッドロック (thread lock) を初期化します。

   acquire()

      "createLock()" で生成されたスレッドロックを獲得します。

   release()

      "acquire()" で獲得したスレッドロックを解放します。

   setLevel(level)

      このハンドラに対する閾値を *level* に設定します。 *level* よりも
      深刻でないログメッセージは無視されます。 ハンドラが生成された際
      、レベルは "NOTSET" (すべてのメッセージが処理される) に設定され
      ます。

      レベルの一覧については ロギングレベル を参照してください。

      バージョン 3.2 で変更: *level* パラメータは、 "INFO" のような整
      数定数の代わりに 'INFO' のようなレベルの文字列表現も受け付けるよ
      うになりました。

   setFormatter(fmt)

      このハンドラの "Formatter" を *fmt* に設定します。

   addFilter(filter)

      指定されたフィルタ *filter* をこのハンドラに追加します。

   removeFilter(filter)

      指定されたフィルタ *filter* をこのハンドラから除去します。

   filter(record)

      レコードに対してこのハンドラのフィルタを適用し、レコードが処理さ
      れるべき場合に "True" を返します。フィルタのいずれかの値が偽を返
      すまで、それらは順番に試されていきます。いずれも偽を返さなければ
      、レコードは発行されることになります。ひとつでも偽を返せば、ハン
      ドラはレコードを発行しません。

   flush()

      すべてのログ出力がフラッシュされるようにします。このクラスのバー
      ジョンではなにも行わず、サブクラスで実装するためのものです。

   close()

      ハンドラで使われているすべてのリソースの後始末を行います。このバ
      ージョンでは何も出力せず、 "shutdown()" が呼ばれたときに閉じられ
      たハンドラを内部リストから削除します。サブクラスではオーバライド
      された "close()" メソッドからこのメソッドが必ず呼ばれるようにし
      てください。

   handle(record)

      ハンドラに追加されたフィルタの条件に応じて、指定されたログレコー
      ドを出力します。このメソッドは I/O スレッドロックの獲得/解放を伴
      う実際のログ出力をラップします。

   handleError(record)

      このメソッドは "emit()" の呼び出し中に例外に遭遇した際にハンドラ
      から呼び出されます。モジュールレベル属性 "raiseExceptions" が
      "False" の場合、例外は暗黙のまま無視されます。ほとんどの場合、こ
      れがロギングシステムの望ましい動作です - というのは、ほとんどの
      ユーザはロギングシステム自体のエラーは気にせず、むしろアプリケー
      ションのエラーに興味があるからです。しかしながら、望むならこのメ
      ソッドを自作のハンドラと置き換えることもできます。 *record* には
      、例外発生時に処理されていたレコードが入ります。
      (*raiseExceptions* のデフォルト値は "True" です。これは開発中は
      その方が便利だからです)。

   format(record)

      レコードに対する書式化を行います - フォーマッタが設定されていれ
      ば、それを使います。そうでない場合、モジュールにデフォルト指定さ
      れたフォーマッタを使います。

   emit(record)

      指定されたログ記録レコードを実際にログ記録する際のすべての処理を
      行います。このメソッドはサブクラスで実装されることを意図しており
      、そのためこのクラスのバージョンは "NotImplementedError" を送出
      します。

      警告:

        このメソッドはハンドラレベルのロックを取得した後で呼び出されま
        す。また、ロックはこのメソッドがリターンした後で解放されます。
        このメソッドをオーバーライドする場合、ロックを取得する可能性の
        ある logging API の他の関数やメソッドの呼び出しに注意してくだ
        さい。そのような実装はデッドロックを引き起こす可能性があります
        。特に以下の点に注意してください:

        * ロギングを構成するための API はモジュールレベルのロックを取
          得し、その後ハンドラを構成する際に個々のハンドラに対してハン
          ドラレベルのロックを取得します。

        * 多くのロギング API はモジュールレベルのロックを取得します。
          そのような API がこのメソッドから呼ばれた場合、他のスレッド
          からロギングを構成するための API 呼び出しが行われたときにデ
          ッドロックに陥る可能性があります。これは他のスレッドがハンド
          ラレベルのロックを取得する *前に* モジュールレベルのロックを
          取得しようとする一方で、 (このメソッドはハンドラレベルのロッ
          クが既に取得された状態で呼び出されているため) このメソッドを
          呼び出したスレッドはハンドラレベルのロックを取得した *後で*
          モジュールレベルのロックを取得しようとするためです。

標準として含まれているハンドラについては、 "logging.handlers" を参照し
てください。


フォーマッタオブジェクト
========================

"Formatter" オブジェクトは以下の属性とメソッドを持っています。
"Formatter" は "LogRecord" を (通常は) 人間か外部のシステムで解釈でき
る文字列に変換する役割を担っています。基底クラスの "Formatter" では書
式文字列を指定することができます。何も指定されなかった場合、ロギングコ
ール中のメッセージ以外の情報だけを持つ "'%(message)s'" の値が使われま
す。フォーマットされた出力に情報の要素 (タイムスタンプなど) を追加した
いなら、このまま読み進めてください。

Formatter は "LogRecord" 属性の知識を利用できるような書式文字列を用い
て初期化することができます。例えば、上で言及したデフォルト値では、ユー
ザによるメッセージと引数はあらかじめフォーマットされて、 "LogRecord"
の *message* 属性に入っていることを利用しています。この書式文字列は、
Python 標準の % を使った変換文字列で構成されます。文字列整形に関する詳
細は printf 形式の文字列書式化 を参照してください。

"LogRecord" の便利なマッピングキーは、 LogRecord 属性 の節で与えられま
す。

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

   "Formatter" クラスの新たなインスタンスを返します。インスタンスは全
   体としてのメッセージに対する書式文字列と、メッセージの日付/時刻部分
   のための書式文字列を伴って初期化されます。 *fmt* が指定されない場合
   、 "'%(message)s'" が使われます。 *datefmt* が指定されない場合、
   "formatTime()" ドキュメントで解説されている書式が使われます。

   *style* パラメータは '%',  '{', '$' のうちのいずれかで、書式文字列
   がどのようにデータとマージされるかを決めます: %-format 、
   "str.format()" 、 "string.Template" のうちのどれかが使用されます。
   この引数は *fmt* のフォーマット文字列（例えば "'%(message)s'" や
   "{message}" ）にのみ適用され、 "Logger.debug" などに渡される実際の
   ログメッセージには現れることはありません。ログメッセージに使用する
   { および $ 形式のフォーマットの情報は 固有の書式化スタイルをアプリ
   ケーション全体で使う を参照してください。

   *defaults* パラメーターはカスタムフィールドとして使用されるデフォル
   トの値です。例: "logging.Formatter('%(ip)s %(message)s',
   defaults={"ip": None})"

   バージョン 3.2 で変更: *style* パラメータが追加されました。

   バージョン 3.8 で変更: *validate* パラメータが追加されました。style
   とfmtが不正だったりミスマッチだっった場合に "ValueError" を送出しま
   す。例: "logging.Formatter('%(asctime)s - %(message)s', style='{')"
   。

   バージョン 3.10 で変更: *defaults* パラメータが追加されました。

   format(record)

      レコードの属性辞書が、文字列を書式化する演算で被演算子として使わ
      れます。書式化された結果の文字列を返します。辞書を書式化する前に
      、二つの準備段階を経ます。レコードの *message* 属性が *msg* %
      *args* を使って処理されます。書式化された文字列が "'(asctime)'"
      を含むなら、 "formatTime()" が呼び出され、イベントの発生時刻を書
      式化します。例外情報が存在する場合、 "formatException()" を使っ
      て書式化され、メッセージに追加されます。ここで注意していただきた
      いのは、書式化された例外情報は *exc_text* にキャッシュされるとい
      う点です。これが有用なのは例外情報がピックル化されて回線上を送る
      ことができるからですが、しかし二つ以上の "Formatter" サブクラス
      で例外情報の書式化をカスタマイズしている場合には注意が必要になり
      ます。この場合、フォーマッタが書式化を終えるごとにキャッシュをク
      リアして（ *ext_text* 属性に "None" を設定して）、次のフォーマッ
      タがキャッシュされた値を使わずに新鮮な状態で再計算するようにしな
      ければならないことになります。

      スタック情報が利用可能な場合、(必要ならば "formatStack()" を使っ
      て整形した上で) スタック情報が例外情報の後に追加されます。

   formatTime(record, datefmt=None)

      このメソッドは、フォーマッタが書式化された時間を利用したい際に、
      "format()" から呼び出されます。 このメソッドは特定の要求を提供す
      るためにフォーマッタで上書きすることができますが、基本的な振る舞
      いは以下のようになります: *datefmt* (文字列) が指定された場合、
      レコードが生成された時刻を書式化するために "time.strftime()" で
      使われます。 そうでない場合、 '%Y-%m-%d %H:%M:%S,uuu' というフォ
      ーマットが使われます。 uuu 部分はミリ秒値で、それ以外の文字は
      "time.strftime()" ドキュメントに従います。 このフォーマットの時
      刻の例は "2003-01-23 00:29:50,411" です。 結果の文字列が返されま
      す。

      この関数は、ユーザが設定できる関数を使って、生成時刻をタプルに変
      換します。デフォルトでは、 "time.localtime()" が使われます。特定
      のフォーマッタインスタンスに対してこれを変更するには、
      "converter" 属性を "time.localtime()" や "time.gmtime()" と同じ
      署名をもつ関数に設定してください。すべてのフォーマッタインスタン
      スに対してこれを変更するには、例えば全てのロギング時刻を GMT で
      表示するには、 "Formatter" クラスの "converter" 属性を設定してく
      ださい。

      バージョン 3.3 で変更: 以前は、デフォルトのフォーマットがこの例
      のようにハードコーディングされていました: "2010-09-06
      22:38:15,292" ここで、コンマの前の部分は strptime フォーマット文
      字列 ("'%Y-%m-%d %H:%M:%S'") によって扱われる部分で、コンマの後
      の部分はミリ秒値です。strptime にミリ秒のフォーマットプレースホ
      ルダーがないので、ミリ秒値は別のフォーマット文字列 "'%s,%03d'"
      を使用して追加されます。そして、これらのフォーマット文字列は両方
      ともこのメソッドでハードコーディングされていました。変更後は、こ
      れらの文字列はクラスレベル属性として定義され、必要ならインスタン
      スレベルでオーバーライドすることができます。属性の名前は
      "default_time_format" (strptime 書式文字列用) と
      "default_msec_format" (ミリ秒値の追加用) です。

      バージョン 3.9 で変更: "default_msec_format" 引数が "None" であ
      ることを許容します。

   formatException(exc_info)

      指定された例外情報 ("sys.exc_info()" が返すような標準例外のタプ
      ル) を文字列として書式化します。デフォルトの実装は単に
      "traceback.print_exception()" を使います。結果の文字列が返されま
      す。

   formatStack(stack_info)

      指定されたスタック情報を文字列としてフォーマットします
      ("traceback.print_stack()" によって返される文字列ですが、最後の
      改行が取り除かれています)。このデフォルト実装は、単に入力値をそ
      のまま返します。

class logging.BufferingFormatter(linefmt=None)

   複数のレコードをまとめてフォーマットしたい場合のクラス定義に適した
   基底クラスです。各行 (単一のレコードに相当します) をフォーマットす
   るために使う "Formatter" インスタンスを渡すことができます。特に指定
   がない場合はデフォルトのフォーマッタ (イベントのメッセージだけを出
   力するフォーマッタ) が使われます。

   formatHeader(records)

      *複数のレコード* のリストに対するヘッダを返します。基底クラスの
      実装は単に空の文字列を返すだけです。レコード数やタイトルを表示し
      たり、あるいはセパレータ行したいなど、ヘッダに対して特別な振る舞
      いが必要な場合はこのメソッドをオーバーライドする必要があります。

   formatFooter(records)

      *複数のレコード* のリストに対するフッタを返します。基底クラスの
      実装は単に空の文字列を返すだけです。レコード数やセパレータ行の表
      示など、フッタに対して特別な振る舞いが必要な場合はこのメソッドを
      オーバーライドする必要があります。

   format(records)

      *複数のレコード* のリストに対するフォーマット済みテキストを返し
      ます。基底クラスの実装は、レコードがなければ空の文字列を返し、レ
      コードがある場合はヘッダ、単一のレコードをフォーマットするための
      ラインフォーマッタで各レコードをフォーマットした文字列、そしてフ
      ッタを全て連結したものを返します。


フィルタオブジェクト
====================

"フィルタ (Filter)" は、"ハンドラ" や "ロガー" によって使われ、レベル
によって提供されるのよりも洗練されたフィルタリングを実現します。基底の
フィルタクラスは、ロガー階層構造内の特定地点の配下にあるイベントだけを
許可します。例えば、'A.B' で初期化されたフィルタは、ロガー 'A.B',
'A.B.C', 'A.B.C.D', 'A.B.D' 等によって記録されたイベントは許可しますが
、'A.BB', 'B.A.B' などは許可しません。空の文字列で初期化された場合、す
べてのイベントを通過させます。

class logging.Filter(name='')

   "Filter" クラスのインスタンスを返します。 *name* が指定されていれば
   、 *name* はロガーの名前を表します。指定されたロガーとその子ロガー
   のイベントがフィルタを通過できるようになります。 *name* が指定され
   なければ、すべてのイベントを通過させます。

   filter(record)

      指定されたレコードがログされるべきか？no ならばゼロを、yes なら
      ばゼロでない値を返します。適切と判断されれば、このメソッドによっ
      てレコードはその場で修正されることがあります。

ハンドラに対するフィルタはハンドラがイベントを発行する前に試され、一方
ではロガーに対するフィルタは、イベントが("debug()", "info()" などによ
って)ロギングされる際には、ハンドラにイベントが送信される前にはいつで
も試されることに注意してください。そのフィルタがそれら子孫ロガーにも適
用されていない限り、子孫ロガーによって生成されたイベントはロガーのフィ
ルタ設定によってフィルタされることはありません。

実際には、"Filter" をサブクラス化する必要はありません。同じ意味の
"filter" メソッドを持つ、すべてのインスタンスを通せます。

バージョン 3.2 で変更: 特殊な "Filter" クラスを作ったり、 "filter" メ
ソッドを持つ他のクラスを使う必要はありません: 関数 (あるいは他の
callable) をフィルタとして使用することができます。フィルタロジックは、
フィルタオブジェクトが "filter" 属性を持っているかどうかチェックします
: もし "filter" 属性を持っていたら、それは "Filter" であると仮定され、
その "filter()" メソッドが呼び出されます。そうでなければ、それは
callable であると仮定され、レコードを単一のパラメータとして呼び出され
ます。返される値は "filter()" によって返されるものと一致すべきです。

フィルタは本来、レコードをレベルよりも洗練された基準に基づいてフィルタ
するために使われますが、それが取り付けられたハンドラやロガーによって処
理されるレコードをすべて監視します。これは、特定のロガーやハンドラに処
理されたレコードの数を数えたり、処理されている "LogRecord" の属性を追
加、変更、削除したりするときに便利です。もちろん、LogRecord を変更する
には注意が必要ですが、これにより、ログにコンテキスト情報を注入できます
(Filter を使ったコンテキスト情報の伝達 を参照してください)。


LogRecord オブジェクト
======================

"LogRecord" インスタンスは、何かをログ記録するたびに "Logger" によって
生成されます。また、 "makeLogRecord()" を通して (例えば、ワイヤを通し
て受け取られた pickle 化されたイベントから) 手動で生成することも出来ま
す。

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

   ロギングされているイベントに適切なすべての情報を含みます。

   もっとも重要な情報は *msg* と *args* に渡され、 "msg % args" で結合
   されてレコードの "message" 属性を生成します。

   パラメータ:
      * **name** (*str*) -- この "LogRecord" であらわされるイベントを
        記録したロガーの名前です。 "LogRecord" が持つロガーの名前は、
        たとえ異なる (祖先の) ロガーに接続されたハンドラから出力された
        としても、常に同じ値を持つことに注意してください。

      * **level** (*int*) -- 記録されたイベントの 数値であらわしたロギ
        ングレベル  ("10" が "DEBUG", "20" が "INFO" など) です。この
        パラメータは LogRecord の *2つの* 属性に変換されることに注意し
        てください: 数値は "levelno" に、また対応するログレベルの名前
        は "levelname" に保持されます。

      * **pathname** (*str*) -- ロギングの呼び出しが行われたソースファ
        イルへの完全なパス名をあらわす文字列です。

      * **lineno** (*int*) -- ロギングの呼び出しが発せられたソース行番
        号。

      * **msg** (*typing.Any*) -- The event description message, which
        can be a %-format string with placeholders for variable data,
        or an arbitrary object (see 任意のオブジェクトをメッセージに使
        用する).

      * **args** (*tuple | dict**[**str**, **typing.Any**]*) -- *msg*
        引数と組み合わせてイベント記述を得るための変数データです。

      * **exc_info** (*tuple**[**type**[**BaseException**]**,
        **BaseException**, **types.TracebackType**] **| None*) --
        "sys.exc_info()" によって返される現在の例外情報を含む例外タプ
        ルです。例外情報がない場合は "None" です。

      * **func** (*str | None*) -- ロギングの呼び出しを行った関数また
        はメソッドの名前です。

      * **sinfo** (*str | None*) -- 現在のスレッドのスタックベースから
        ログ呼び出しまでの間のスタック情報を表わすテキスト文字列。

   getMessage()

      ユーザが提供した引数をメッセージに交ぜた後、この "LogRecord" イ
      ンスタンスへのメッセージを返します。ユーザがロギングの呼び出しに
      与えた引数が文字列でなければ、その引数に "str()" が呼ばれ、文字
      列に変換されます。これにより、 "__str__" メソッドが実際のフォー
      マット文字列を返せるようなユーザ定義のクラスをメッセージとして使
      えます。

   バージョン 3.2 で変更: "LogRecord" の生成は、レコードを生成するため
   に使用されるファクトリを提供することにより、さらに設定可能になりま
   した。ファクトリは "getLogRecordFactory()" と
   "setLogRecordFactory()" を使用して設定することができます (ファクト
   リのシグネチャに関しては "setLogRecordFactory()" を参照)。

   この機能を使うと "LogRecord" の生成時に独自の値を注入することができ
   ます。次のパターンが使えます:

      old_factory = logging.getLogRecordFactory()

      def record_factory(*args, **kwargs):
          record = old_factory(*args, **kwargs)
          record.custom_attribute = 0xdecafbad
          return record

      logging.setLogRecordFactory(record_factory)

   このパターンでは複数のファクトリをつなぐこともできます。それらが互
   いの属性を上書きしたりせず、また上にリストされた標準属性を意図せず
   上書きしたりしない限り、驚くようなことは何も起こりません (there
   should be no surprises)。


LogRecord 属性
==============

LogRecord には幾つかの属性があり、そのほとんどはコンストラクタの引数か
ら得られます。(なお、LogRecord コンストラクタの引数と LogRecord 属性が
常に厳密に対応するわけではありません。) これらの属性は、レコードからの
データをフォーマット文字列に統合するのに使えます。以下のテーブルに、属
性名、意味、そして % 形式フォーマット文字列における対応するプレースホ
ルダを (アルファベット順に) 列挙します。

{}-フォーマット ("str.format()") を使用していれば、書式文字列の中でプ
レースホールダーとして "{attrname}" を使うことができます。 $-フォーマ
ット ("string.Template") を使用している場合は、 "${attrname}" 形式にし
てください。もちろん、両方の場合で "attrname" は使用したい実際の属性名
に置き換えてください。

{}-フォーマットの場合には、属性名の後にフォーマットフラグを指定するこ
とができます。属性名とフォーマットフラグの間はコロンで分割します。例:
プレースホールダー "{msecs:03d}" は、ミリセカンド値 "4" を "004" とし
てフォーマットします。利用可能なオプション上の全詳細に関しては
"str.format()" ドキュメンテーションを参照してください。

+------------------+---------------------------+-------------------------------------------------+
| 属性名           | フォーマット              | 説明                                            |
|==================|===========================|=================================================|
| "args"           | このフォーマットを自分で  | "msg" に組み合わせて "message" を生成するための |
|                  | 使う必要はないでしょう。  | 引数のタプル、または、 マージに用いられる辞書(  |
|                  |                           | 引数が一つしかなく、かつそれが辞書の場合)。     |
+------------------+---------------------------+-------------------------------------------------+
| asctime          | "%(asctime)s"             | "LogRecord" が生成された時刻を人間が読める書式  |
|                  |                           | で表したもの。デフォルト では "2003-07-08       |
|                  |                           | 16:49:45,896" 形式 (コンマ以降の数字は時刻のミ  |
|                  |                           | リ秒部 分) です。                               |
+------------------+---------------------------+-------------------------------------------------+
| created          | "%(created)f"             | "LogRecord" が生成された時刻 ("time.time()" に  |
|                  |                           | よって返される形式で)。                         |
+------------------+---------------------------+-------------------------------------------------+
| exc_info         | このフォーマットを自分で  | ("sys.exc_info" 風の) 例外タプルか、例外が起こ  |
|                  | 使う必要はないでしょう。  | っていない場合は "None" 。                      |
+------------------+---------------------------+-------------------------------------------------+
| ファイル名       | "%(filename)s"            | "pathname" のファイル名部分。                   |
+------------------+---------------------------+-------------------------------------------------+
| funcName         | "%(funcName)s"            | ロギングの呼び出しを含む関数の名前。            |
+------------------+---------------------------+-------------------------------------------------+
| levelname        | "%(levelname)s"           | メッセージのための文字のロギングレベル          |
|                  |                           | ("'DEBUG'", "'INFO'", "'WARNING'", "'ERROR'",   |
|                  |                           | "'CRITICAL'")。                                 |
+------------------+---------------------------+-------------------------------------------------+
| levelno          | "%(levelno)s"             | メッセージのための数値のロギングレベル          |
|                  |                           | ("DEBUG", "INFO", "WARNING", "ERROR",           |
|                  |                           | "CRITICAL")。                                   |
+------------------+---------------------------+-------------------------------------------------+
| lineno           | "%(lineno)d"              | ロギングの呼び出しが発せられたソース行番号 (利  |
|                  |                           | 用できる場合のみ)。                             |
+------------------+---------------------------+-------------------------------------------------+
| message          | "%(message)s"             | "msg % args" として求められた、ログメッセージ。 |
|                  |                           | "Formatter.format()" が呼び出されたときに設定さ |
|                  |                           | れます。                                        |
+------------------+---------------------------+-------------------------------------------------+
| module           | "%(module)s"              | モジュール ("filename" の名前部分)。            |
+------------------+---------------------------+-------------------------------------------------+
| msecs            | "%(msecs)d"               | "LogRecord" が生成された時刻のミリ秒部分。      |
+------------------+---------------------------+-------------------------------------------------+
| msg              | このフォーマットを自分で  | 元のロギングの呼び出しで渡されたフォーマット文  |
|                  | 使う必要はないでしょう。  | 字列。 "args" と合わせて 、 "message" 、または  |
|                  |                           | 任意のオブジェクトを生成します (任意のオブジェ  |
|                  |                           | ク トをメッセージに使用する 参照)。             |
+------------------+---------------------------+-------------------------------------------------+
| name             | "%(name)s"                | ロギングに使われたロガーの名前。                |
+------------------+---------------------------+-------------------------------------------------+
| pathname         | "%(pathname)s"            | ロギングの呼び出しが発せられたファイルの完全な  |
|                  |                           | パス名 (利用できる場合の み)。                  |
+------------------+---------------------------+-------------------------------------------------+
| process          | "%(process)d"             | プロセス ID (利用可能な場合のみ)。              |
+------------------+---------------------------+-------------------------------------------------+
| processName      | "%(processName)s"         | プロセス名 (利用可能な場合のみ)。               |
+------------------+---------------------------+-------------------------------------------------+
| relativeCreated  | "%(relativeCreated)d"     | logging モジュールが読み込まれた時刻に対する、  |
|                  |                           | LogRecord が生成された時 刻を、ミリ秒で表したも |
|                  |                           | の。                                            |
+------------------+---------------------------+-------------------------------------------------+
| stack_info       | このフォーマットを自分で  | 現在のスレッドでのスタックの底からこのレコード  |
|                  | 使う必要はないでしょう。  | の生成に帰着したログ呼び 出しまでのスタックフレ |
|                  |                           | ーム情報 (利用可能な場合)。                     |
+------------------+---------------------------+-------------------------------------------------+
| thread           | "%(thread)d"              | スレッド ID (利用可能な場合のみ)。              |
+------------------+---------------------------+-------------------------------------------------+
| threadName       | "%(threadName)s"          | スレッド名 (利用可能な場合のみ)。               |
+------------------+---------------------------+-------------------------------------------------+

バージョン 3.1 で変更: *processName* が追加されました。


LoggerAdapter オブジェクト
==========================

"LoggerAdapter" インスタンスは文脈情報をログ記録呼び出しに渡すのを簡単
にするために使われます。使い方の例は コンテキスト情報をログ記録出力に
付加する を参照してください。

class logging.LoggerAdapter(logger, extra)

   内部で使う "Logger" インスタンスと辞書風 (dict-like) オブジェクトで
   初期化した "LoggerAdapter" のインスタンスを返します。

   process(msg, kwargs)

      文脈情報を挿入するために、ログ記録呼び出しに渡されたメッセージお
      よび/またはキーワード引数に変更を加えます。ここでの実装は
      *extra* としてコンストラクタに渡されたオブジェクトを取り、
      'extra' キーを使って *kwargs* に加えます。返り値は (*msg*,
      *kwargs*) というタプルで、(変更されているはずの) 渡された引数を
      含みます。

"LoggerAdapter" は上記に加え "Logger" のメソッド "debug()", "info()",
"warning()", "error()", "exception()", "critical()", "log()",
"isEnabledFor()", "getEffectiveLevel()", "setLevel()", "hasHandlers()"
をサポートします。これらは "Logger" の対応するメソッドと同じシグニチャ
を持つため、2つのインスタンスは区別せずに利用出来ます。

バージョン 3.2 で変更: "isEnabledFor()", "getEffectiveLevel()",
"setLevel()", "hasHandlers()" が "LoggerAdapter" に追加されました。こ
れらメソッドは元のロガーに処理を委譲します。

バージョン 3.6 で変更: 基底のロガーに移譲し、アダプターをネストできる
ようにするために "manager" 属性と "_log()" メソッドが追加されました。


スレッドセーフ性
================

logging モジュールは、クライアントで特殊な作業を必要としない限りスレッ
ドセーフになっています。このスレッドセーフ性はスレッドロックによって達
成されています; モジュールの共有データへのアクセスを直列化するためのロ
ックが一つ存在し、各ハンドラでも背後にある I/O へのアクセスを直列化す
るためにロックを生成します。

"signal" モジュールを使用して非同期シグナルハンドラを実装している場合
、そのようなハンドラからはログ記録を使用できないかもしれません。これは
、 "threading" モジュールにおけるロック実装が常にリエントラントではな
く、そのようなシグナルハンドラから呼び出すことができないからです。


モジュールレベルの関数
======================

上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します
。

logging.getLogger(name=None)

   指定された名前のロガーを返します。名前が "None" であれば、ロガー階
   層のルート (root) にあるロガーを返します。*name* を指定する場合には
   、通常は *'a'*, *'a.b'*, *'a.b.c.d'* といったドット区切りの階層的な
   名前にします。名前の付け方はログ機能を使う開発者次第です。

   与えられた名前に対して、この関数はどの呼び出しでも同じロガーインス
   タンスを返します。したがって、ロガーインスタンスをアプリケーション
   の各部でやりとりする必要はありません。

logging.getLoggerClass()

   標準の "Logger" クラスか、最後に "setLoggerClass()" に渡したクラス
   を返します。この関数は、新たなクラス定義の中で呼び出して、カスタマ
   イズした "Logger" クラスのインストールが既に他のコードで適用したカ
   スタマイズを取り消さないことを保証するために使われることがあります
   。例えば以下のようにします:

      class MyLogger(logging.getLoggerClass()):
          # ... override behaviour here

logging.getLogRecordFactory()

   "LogRecord" を生成するのに使われる callable を返します。

   バージョン 3.2 で追加: この関数は、ログイベントを表現する
   "LogRecord" の構築方法に関して開発者により多くのコントロールを与え
   るため、 "setLogRecordFactory()" とともに提供されました。

   このファクトリがどのように呼ばれるかに関する詳細は
   "setLogRecordFactory()" を参照してください。

logging.debug(msg, *args, **kwargs)

   レベル "DEBUG" のメッセージをルートロガーで記録します。 *msg* はメ
   ッセージの書式文字列で、 *args* は *msg* に文字列書式化演算子を使っ
   て取り込むための引数です。 (これは、書式文字列の中でキーワードを使
   い、引数として単一の辞書を渡すことができる、ということを意味します
   。)

   キーワード引数 *kwargs* からは 3 つのキーワードが調べられます。一つ
   目は *exc_info* で、この値の評価値が false でない場合、例外情報をロ
   グメッセージに追加します。 ("sys.exc_info()" の返す形式の) 例外情報
   を表すタプルや例外インスタンスが与えられていれば、それをメッセージ
   に使います。それ以外の場合には、 "sys.exc_info()" を呼び出して例外
   情報を取得します。

   2つ目の省略可能なキーワード引数は *stack_info* で、デフォルトは
   "False" です。真の場合、実際のロギング呼び出しを含むスタック情報が
   ロギングメッセージに追加されます。これは *exc_info* 指定によって表
   示されるスタック情報と同じものではないことに注意してください: 前者
   はカレントスレッド内での、一番下からロギング呼び出しまでのスタック
   フレームですが、後者は例外に呼応して、例外ハンドラが見つかるところ
   まで巻き戻されたスタックフレームの情報です。

   *exc_info* とは独立に *stack_info* を指定することもできます (例えば
   、例外が上げられなかった場合でも、コード中のある地点にどのように到
   着したかを単に示すために)。スタックフレームは、次のようなヘッダー行
   に続いて表示されます:

      Stack (most recent call last):

   これは、例外フレームを表示する場合に使用される "Traceback (most
   recent call last):" を模倣します。

   3番目のキーワード引数は *extra* で、当該ログイベント用に作られる
   LogRecoed の __dict__ にユーザー定義属性を加えるのに使われる辞書を
   渡すために用いられます。これらの属性は好きなように使えます。たとえ
   ば、ログメッセージの一部にすることもできます。以下の例を見てくださ
   い:

      FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
      logging.basicConfig(format=FORMAT)
      d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
      logging.warning('Protocol problem: %s', 'connection reset', extra=d)

   これは以下のような出力を行います:

      2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

   *extra* で渡される辞書のキーはロギングシステムで使われているものと
   衝突しないようにしなければなりません。 (どのキーがロギングシステム
   で使われているかについての詳細は "Formatter" のドキュメントを参照し
   てください。)

   これらの属性をログメッセージに使うことにしたなら、少し注意が必要で
   す。上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含ま
   れていることを期待した書式文字列で "Formatter" がセットアップされて
   います。もしこれらが欠けていると、書式化例外が発生してしまうためメ
   ッセージはログに残りません。したがってこの場合、常にこれらのキーを
   含む *extra* 辞書を渡す必要があります。

   このようなことは煩わしいかもしれませんが、この機能は限定された場面
   で使われるように意図しているものなのです。たとえば同じコードがいく
   つものコンテキストで実行されるマルチスレッドのサーバで、興味のある
   条件が現れるのがそのコンテキストに依存している (上の例で言えば、リ
   モートのクライアント IP アドレスや認証されたユーザ名など)、というよ
   うな場合です。そういった場面では、それ用の "Formatter" が特定の
   "Handler" と共に使われるというのはよくあることです。

   ルートロガーにハンドラが接続されていない場合、この関数 (および
   "info()", "warning()", "error()" そして "critical()") は
   "basicConfig()" を呼び出します。

   バージョン 3.2 で変更: *stack_info* パラメータが追加されました。

logging.info(msg, *args, **kwargs)

   レベル "INFO" のメッセージをルートロガーで記録します。引数は
   "debug()" と同じように解釈されます。

logging.warning(msg, *args, **kwargs)

   レベル "WARNING" のメッセージをルートロガーで記録します。引数は
   "debug()" と同じように解釈されます。

   注釈:

     "warning" と機能的に等価な古い関数 "warn" があります。"warn" は廃
     止予定なので使わないでください - 代わりに "warning" を使ってくだ
     さい。

logging.error(msg, *args, **kwargs)

   レベル "ERROR" のメッセージをルートロガーで記録します。引数は
   "debug()" と同じように解釈されます。

logging.critical(msg, *args, **kwargs)

   レベル "CRITICAL" のメッセージをルートロガーで記録します。引数は
   "debug()" と同じように解釈されます。

logging.exception(msg, *args, **kwargs)

   レベル "ERROR" のメッセージをルートロガーで記録します。引数は
   "debug()" と同じように解釈されます。例外情報がログメッセージに追加
   されます。このメソッドは例外ハンドラからのみ呼び出されます。

logging.log(level, msg, *args, **kwargs)

   レベル *level* のメッセージをルートロガーで記録します。その他の引数
   は "debug()" と同じように解釈されます。

logging.disable(level=CRITICAL)

   全てのロガーのレベル *level* を上書きし、これはロガー自身の出力レベ
   ルよりも優先されます。アプリケーション全体を横断するログ出力を一時
   的に調整する必要が生じたら、この関数は便利でしょう。これの効果は重
   大度 *level* 以下の全てのロギング呼び出しを無効にすることですので、
   INFO で呼び出しをすれば、INFO と DEBUG イベントが捨てられる一方で、
   重大度 WARNING 以上のものは、ロガーの有効レベルに基いて処理されます
   。 "logging.disable(logging.NOTSET)" が呼び出されると、この上書きレ
   ベルは削除され、ログ出力は再び個々のロガーの有効レベルに依存するよ
   うになります。

   "CRITICAL" より高い独自のログレベル (これは推奨されません) を定義し
   た場合は、 *level* 引数のデフォルト値を当てにできなくなり、適切な値
   を明示的に与える必要があります。

   バージョン 3.7 で変更: *level* 引数のデフォルトが "CRITICAL" レベル
   になりました。この変更についてのより詳しいことは bpo-28524 を参照し
   てください。

logging.addLevelName(level, levelName)

   内部的な辞書の中でレベル *level* をテキスト *levelName* に関連付け
   ます。これは例えば "Formatter" でメッセージを書式化する際のように、
   数字のレベルをテキスト表現に対応付ける際に用いられます。この関数は
   自作のレベルを定義するために使うこともできます。使われるレベルに対
   する唯一の制限は、レベルは正の整数でなくてはならず、メッセージの深
   刻度が上がるに従ってレベルの数も上がらなくてはならないということで
   す。

   注釈:

     独自のレベルを定義したい場合、 カスタムレベル のセクションを参照
     してください。

logging.getLevelName(level)

   テキストまたは数値表現でログレベル *level* を返してください。

   *level* が定義済みのレベル "CRITICAL", "ERROR", "WARNING", "INFO",
   "DEBUG" のいずれかである場合、対応する文字列が返されます。
   "addLevelName()" を使ってレベルに名前を関連付けていた場合、 *level*
   に関連付けられた名前が返されます。定義済みのレベルに対応する数値を
   指定した場合、レベルに対応した文字列表現を返します。

   *level* パラメータは、 "INFO" のような整数定数の代わりに 'INFO' の
   ようなレベルの文字列表現も受け付けます。この場合、この関数は関連す
   るレベルの数値表現を返します。

   もし渡された数値や文字列がマッチしなければ、 'Level %s' % level が
   返されます。

   注釈:

     レベルは内部的には整数です(これはロギングのロジックが大小比較をす
     る必要があるからです)。この関数は、数値のレベルを、書式記述子
     "%(levelname)s" (LogRecord 属性 参照)によって書式化されるログ出力
     の表示用レベル名に変換するなどの用途に使用されます。

   バージョン 3.4 で変更: Python 3.4以前のバージョンでは、この関数には
   テキストのレベルも渡すことが出来、これは対応する数字レベルに読み替
   えられていました。このドキュメントされていなかった振る舞いは誤りで
   あると判断され、Python 3.4 で一度削除されました。ただし後方互換性の
   ために、これは 3.4.2 で元に戻されました。

logging.makeLogRecord(attrdict)

   属性が *attrdict* で定義された、新しい "LogRecord" インスタンスを生
   成して返します。この関数は、 pickle された "LogRecord" 属性の辞書を
   ソケットを介して送信し、受信端で "LogRecord" インスタンスとして再構
   成する場合に便利です。

logging.basicConfig(**kwargs)

   デフォルトの "Formatter" を持つ "StreamHandler" を生成してルートロ
   ガーに追加し、ロギングシステムの基本的な環境設定を行います。関数
   "debug()", "info()", "warning()", "error()", "critical()" は、ルー
   トロガーにハンドラが定義されていない場合に自動的に "basicConfig()"
   を呼び出します。

   この関数は *force* キーワード引数に "True" が設定されない限り、ルー
   トロガーに設定されたハンドラがあれば何もしません。

   注釈:

     この関数は、他のスレッドが開始される前にメインスレッドから呼び出
     されるべきです。Python の 2.7.1 や 3.2 以前のバージョンでは、この
     関数が複数のスレッドから呼ばれると(珍しい状況下とはいえ)ハンドラ
     がルートロガーに複数回加えられることがあり、ログ内のメッセージが
     重複するという予期しない結果をもたらすことがあります。

   以下のキーワード引数がサポートされます。

   +----------------+-----------------------------------------------+
   | フォーマット   | 説明                                          |
   |================|===============================================|
   | *filename*     | "StreamHandler" ではなく指定された名前で      |
   |                | "FileHandler" が作られま す。                 |
   +----------------+-----------------------------------------------+
   | *filemode*     | *filename* が指定された場合、この モード でフ |
   |                | ァイルが開かれます。 デフォルトは  "'a'" です |
   |                | 。                                            |
   +----------------+-----------------------------------------------+
   | *format*       | ハンドラーで指定されたフォーマット文字列を使  |
   |                | います。デフォルトは "levelname", "name",     |
   |                | "message" 属性をコロン区切りにしたものです。  |
   +----------------+-----------------------------------------------+
   | *datefmt*      | 指定された日時の書式で "time.strftime()" が受 |
   |                | け付けるものを使います 。                     |
   +----------------+-----------------------------------------------+
   | *style*        | *format* が指定された場合、書式文字列にこのス |
   |                | タイルを仕様します。 "'%'", "'{'", "'$'" のう |
   |                | ち1つで、それぞれ printf-style,               |
   |                | "str.format()", "string.Template" に対応しま  |
   |                | す。 デフォルトは "'%'" です。                |
   +----------------+-----------------------------------------------+
   | *level*        | ルートロガーのレベルを指定された レベル に設  |
   |                | 定します。                                    |
   +----------------+-----------------------------------------------+
   | *stream*       | 指定されたストリームを "StreamHandler" の初期 |
   |                | 化に使います。 この引 数は *filename* と同時  |
   |                | には使えないことに注意してください。 両方が指 |
   |                | 定されたときには "ValueError" が送出されます  |
   |                | 。                                            |
   +----------------+-----------------------------------------------+
   | *handlers*     | もし指定されれば、 これは root ロガーに追加さ |
   |                | れる既に作られたハンド ラのイテラブルになりま |
   |                | す。まだフォーマッタがセットされていないすべ  |
   |                | てのハンドラは、この関数で作られたデフォルト  |
   |                | フォーマッタが割り当て られることになります。 |
   |                | この引数は *filename* や *stream* と互換性が  |
   |                | ないことに注意してください。両方が存在する場  |
   |                | 合 "ValueError" が上げ られます。             |
   +----------------+-----------------------------------------------+
   | *force*        | このキーワード引数が真に設定されている場合、  |
   |                | ルートのロガーに取り付 けられたハンドラは全て |
   |                | 取り除かれ、他の引数によって指定された設定が  |
   |                | 有効になる前に閉じられます。                  |
   +----------------+-----------------------------------------------+
   | *encoding*     | もしこのキーワード引数が *filename* とともに  |
   |                | 指定された場合、 "FileHandler" が作成されると |
   |                | きにこの値が利用され、出力ファイルを開 く時に |
   |                | 使用されます。                                |
   +----------------+-----------------------------------------------+
   | *errors*       | もしこのキーワード引数が *filename* とともに  |
   |                | 指定された場合、 "FileHandler" が作成されると |
   |                | きのこの値が使用され、出力ファイルを開 く時に |
   |                | 使われます。もし指定されなかった場合、        |
   |                | 'backslashreplace' が 使用されます。もし      |
   |                | "None" が指定されると "open()" のように渡され |
   |                | 、 'errors' を渡したのと同じように扱われます  |
   |                | 。                                            |
   +----------------+-----------------------------------------------+

   バージョン 3.2 で変更: *style* 引数が追加されました。

   バージョン 3.3 で変更: 互換性のない引数が指定された状況 (例えば
   *handlers* が *stream* や *filename* と一緒に指定されたり、*stream*
   が *filename* と一緒に指定された場合) を捕捉するために、追加のチェ
   ックが加えられました。

   バージョン 3.8 で変更: *force* 引数が追加されました。

   バージョン 3.9 で変更: *encoding* と *errors* 引数が追加されました
   。

logging.shutdown()

   ロギングシステムに対して、バッファのフラッシュを行い、すべてのハン
   ドラを閉じることで順次シャットダウンを行うように告知します。この関
   数はアプリケーションの終了時に呼ばれるべきであり、また呼び出し以降
   はそれ以上ロギングシステムを使ってはなりません。

   loggingモジュールがインポートされると、この関数が終了ハンドラーとし
   て登録されます（ "atexit" 参照）。そのため、通常はこれを手動で行う
   必要はありません。

logging.setLoggerClass(klass)

   ロギングシステムに対して、ロガーをインスタンス化する際にクラス
   *klass* を使うように指示します。 指定するクラスは引数として名前だけ
   をとるようなメソッド "__init__()" を定義していなければならず、
   "__init__()" では "Logger.__init__()" を呼び出さなければなりません
   。 この関数が呼び出されるのはたいてい、独自の振る舞いをするロガーを
   使う必要のあるアプリケーションでロガーがインスタンス化される前です
   。 呼び出された後は、いつでもそのサブクラスを使ってロガーのインスタ
   ンス化をしてはいけません: 引き続き "logging.getLogger()" API を使用
   してロガーを取得してください。

logging.setLogRecordFactory(factory)

   "LogRecord" を生成するのに使われる callable をセットします。

   パラメータ:
      **factory** -- ログレコードを生成するファクトリとして振舞う
      callable。

   バージョン 3.2 で追加: この関数は、ログイベントを表現する
   "LogRecord" の構築方法に関して開発者により多くのコントロールを与え
   るため、 "getLogRecordFactory()" とともに提供されました。

   ファクトリは以下のようなシグネチャを持っています:

   "factory(name, level, fn, lno, msg, args, exc_info, func=None,
   sinfo=None, **kwargs)"

      name:
         ロガーの名前。

      level:
         ログレベル (数値)。

      fn:
         ログ呼び出しが行われたファイルのフルパス名。

      lno:
         ログ呼び出しが行われたファイルの行数。

      msg:
         ログメッセージ。

      "args":
         ログメッセージに対する引数。

      exc_info:
         例外タプルまたは "None"。

      func:
         ログ呼び出しを起動した関数またはメソッドの名前。

      sinfo:
         "traceback.print_stack()" で提供されるような、呼び出し階層を
         示すスタックトレースバック。

      "kwargs":
         追加のキーワード引数。


モジュールレベル属性
====================

logging.lastResort

   「最後の手段のハンドラ」が、この属性で利用可能です。これは
   "StreamHandler" が "sys.stderr" に "WARNING" レベルで書き出している
   のがそうですし、ロギングの設定がなにか不在のロギングイベントを扱う
   場合に使われます。最終的な結果は、メッセージを単に "sys.stderr" に
   出力することです。これはかつて「logger XYZ についてのハンドラが見つ
   かりません」と言っていたエラーメッセージを置き換えています。もしも
   何らかの理由でその昔の振る舞いが必要な場合は、 "lastResort" に
   "None" をセットすれば良いです。

   バージョン 3.2 で追加.


warnings モジュールとの統合
===========================

"captureWarnings()" 関数を使って、 "logging" を "warnings" モジュール
と統合できます。

logging.captureWarnings(capture)

   この関数は、logging による警告の補足を、有効にまたは無効にします。

   *capture* が "True" なら、 "warnings" モジュールに発せられた警告は
   、ロギングシステムにリダイレクトされるようになります。具体的には、
   警告が "warnings.formatwarning()" でフォーマット化され、結果の文字
   列が "'py.warnings'" という名のロガーに、 "WARNING" の重大度でロギ
   ングされるようになります。

   *capture* が "False" なら、警告のロギングシステムに対するリダイレク
   トは止められ、警告は元の (すなわち、"captureWarnings(True)" が呼び
   出される前に有効だった) 送信先にリダイレクトされるようになります。

参考:

  "logging.config" モジュール
     logging モジュールの環境設定 API です。

  "logging.handlers" モジュール
     logging モジュールに含まれる、便利なハンドラです。

  **PEP 282** - ログシステム
     この機能を Python 標準ライブラリに含めることを述べた提案です。

  Python の最初のロギングパッケージ
     これは、 "logging" パッケージのオリジナルのソースです。このサイト
     から利用できるバージョンのパッケージは、 "logging" パッケージを標
     準ライブラリに含まない、 Python 1.5.2, 2.1.x および 2.2.x で使う
     のに適しています。
