pytho****@googl*****
pytho****@googl*****
2011年 5月 20日 (金) 06:22:43 JST
5 new revisions: Revision: 12a1f571704b Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:33:21 2011 Log: 原文を追加 http://code.google.com/p/python-doc-ja/source/detail?r=12a1f571704b Revision: fa7e351aad9b Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:44:46 2011 Log: 2.6.6 以前の訳文の重複を修正 http://code.google.com/p/python-doc-ja/source/detail?r=fa7e351aad9b Revision: 48dd780ae2ef Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:45:04 2011 Log: 2.6.6: library/logging.rst http://code.google.com/p/python-doc-ja/source/detail?r=48dd780ae2ef Revision: e88a48ee19a2 Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:45:05 2011 Log: 改行位置の調整 http://code.google.com/p/python-doc-ja/source/detail?r=e88a48ee19a2 Revision: 3110f66edd40 Author: Nozomu Kaneko <nozom****@gmail*****> Date: Thu May 19 14:12:34 2011 Log: 訳文の見直し http://code.google.com/p/python-doc-ja/source/detail?r=3110f66edd40 ============================================================================== Revision: 12a1f571704b Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:33:21 2011 Log: 原文を追加 http://code.google.com/p/python-doc-ja/source/detail?r=12a1f571704b Modified: /library/logging.rst ======================================= --- /library/logging.rst Sat Nov 27 10:59:46 2010 +++ /library/logging.rst Wed May 18 09:33:21 2011 @@ -1,4 +1,3 @@ - :mod:`logging` --- Python 用ロギング機能 ======================================== @@ -14,14 +13,36 @@ .. versionadded:: 2.3 + +.. This module defines functions and classes which implement a flexible error +.. logging system for applications. + このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logging) システムを実装するための関数やクラスを定義しています。 + +.. Logging is performed by calling methods on instances of the :class:`Logger` +.. class (hereafter called :dfn:`loggers`). Each instance has a name, and they are +.. conceptually arranged in a namespace hierarchy using dots (periods) as +.. separators. For example, a logger named "scan" is the parent of loggers +.. "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, +.. and indicate the area of an application in which a logged message originates. + ログ記録は :class:`Logger` クラスのインスタンス (以降 :dfn:`ロガー ` :logger) におけるメソッドを呼び出すことで行われます。各インスタンスは名前をもち、ド ット (ピリオド) を区切り文字として表記することで、 概念的には名前空間中の階層構造に配置されることになります。例えば、"scan" と 名づけられたロガーは "scan.text"、"scan.html"、 および "scan.pdf" ロガーの親ロガーとなります。ロガー名には何をつけてもよ く、ログに記録されるメッセージの生成元となるアプリケーション中の特定の 領域を示すことになります。 + +.. Logged messages also have levels of importance associated with them. The default +.. levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, +.. :const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the +.. importance of a logged message by calling an appropriate method of +.. :class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`, +.. :meth:`error` and :meth:`critical`, which mirror the default levels. You are not +.. constrained to use these levels: you can specify your own and use a more general +.. :class:`Logger` method, :meth:`log`, which takes an explicit level argument. + ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連 付けられています。デフォルトのレベルとして提供されているものは :const:`DEBUG` 、 :const:`INFO` 、 :const:`WARNING` 、 :const:`ERROR` およ び :const:`CRITICAL` です。簡便性のために、 :class:`Logger` の適切なメソッド群 を呼ぶことで、ログに記録されたメッセージの @@ -34,25 +55,46 @@ チュートリアル -------------- +.. The key benefit of having the logging API provided by a standard library module +.. is that all Python modules can participate in logging, so your application log +.. can include messages from third-party modules. + 標準ライブラリモジュールが提供するログ記録 API があることの御利益は、 全ての Python モジュールがログ記録に参加できることであり、 これによってあなたが書くアプリケーションのログにサードパーティーのモジュー ルが出力するメッセージを含ませることができます。 + +.. It is, of course, possible to log messages with different verbosity levels or to +.. different destinations. Support for writing log messages to files, HTTP +.. GET/POST locations, email via SMTP, generic sockets, or OS-specific logging +.. mechanisms are all supported by the standard module. You can also create your +.. own log destination class if you have special requirements not met by any of the +.. built-in classes. + もちろん、複数のメッセージをそれぞれ別々の冗舌性レベルで別々の出力先にログ 記録することができます。 ログメッセージをファイルへ、HTTP GET/POST 先へ、SMTP 経由で電子メールへ、汎 用のソケットへ、もしくは OS ごとのログ記録機構へ書き込むことを全て標準モジ ュールでサポートします。 これら組み込まれたクラスが特別な要求仕様に合わないような場合には、 独自のログ記録先クラスを作り出すこともできます。 + 単純な例 ^^^^^^^^ .. sectionauthor:: Doug Hellmann .. (see <http://blog.doughellmann.com/2007/05/pymotw-logging.html>) + +.. Most applications are probably going to want to log to a file, so let's start +.. with that case. Using the :func:`basicConfig` function, we can set up the +.. default handler so that debug messages are written to a file: + ほとんどのアプリケーションではファイルにログ記録することを望むことになるで しょうから、 まずはこのケースから始めましょう。 :func:`basicConfig` 関数を使って、デバッグメッセージがファイルに書き込まれ るように、 -デフォルトのハンドラをセットアップします:: +デフォルトのハンドラをセットアップします。 + + +:: import logging LOG_FILENAME = '/tmp/logging_example.out' @@ -60,17 +102,33 @@ logging.debug('This message should go to the log file') + +.. And now if we open the file and look at what we have, we should find the log +.. message: + ではこのファイルを開いて結果を確認しましょう。 -こんなログメッセージが見つかるでしょう:: +こんなログメッセージが見つかるでしょう: + + +:: DEBUG:root:This message should go to the log file + +.. If you run the script repeatedly, the additional log messages are appended to +.. the file. To create a new file each time, you can pass a filemode argument to +.. :func:`basicConfig` with a value of ``'w'``. Rather than managing the file size +.. yourself, though, it is simpler to use a :class:`RotatingFileHandler`: + スクリプトを繰り返し実行すると、 さらなるログメッセージがファイルに追記されていきます。 毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡すファイルモード 引数を ``'w'`` にします。 ファイルサイズを自分で管理する代わりに、 -もっと簡単に :class:`RotatingFileHandler` を使う手があります:: +もっと簡単に :class:`RotatingFileHandler` を使う手があります。 + + +:: import glob import logging @@ -98,8 +156,15 @@ for filename in logfiles: print filename + +.. The result should be 6 separate files, each with part of the log history for the +.. application: + 結果は分割された 6 ファイルになっているはずで、 -それぞれがアプリケーションのログ記録の一部になっています:: +それぞれがアプリケーションのログ記録の一部になっています。 + + +:: /tmp/logging_rotatingfile_example.out /tmp/logging_rotatingfile_example.out.1 @@ -108,25 +173,52 @@ /tmp/logging_rotatingfile_example.out.4 /tmp/logging_rotatingfile_example.out.5 + +.. The most current file is always :file:`/tmp/logging_rotatingfile_example.out`, +.. and each time it reaches the size limit it is renamed with the suffix +.. ``.1``. Each of the existing backup files is renamed to increment the suffix +.. (``.1`` becomes ``.2``, etc.) and the ``.5`` file is erased. + 最新のファイルはいつでも :file:`/tmp/logging_rotatingfile_example.out` で、 サイズの上限に達するたびに拡張子 ``.1`` を付けた名前に改名されます。 既にあるバックアップファイルはその拡張子がインクリメントされ (``.1`` が ``.2`` になるなど)、 ``.5`` ファイルは消去されます。 + +.. Obviously this example sets the log length much much too small as an extreme +.. example. You would want to set *maxBytes* to an appropriate value. + 見て判るようにここでは例示のためにファイルの大きさをとんでもなく小さな値に 設定しています。 実際に使うときは *maxBytes* を適切な値に設定して下さい。 + +.. Another useful feature of the logging API is the ability to produce different +.. messages at different log levels. This allows you to instrument your code with +.. debug messages, for example, but turning the log level down so that those debug +.. messages are not written for your production system. The default levels are +.. ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG`` and ``NOTSET``. + ログ記録 API のもう一つの有用な仕組みが異なるメッセージを異なるログレベルで 生成する能力です。 これを使えば、たとえばコードの中にデバッグメッセージを埋め込みつつ、 出荷段階でログ記録レベルを落としてこれが記録されないようにするといったこと ができます。 デフォルトで設定されているレベルは ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG``, ``NOTSET`` で す。 + +.. The logger, handler, and log message call each specify a level. The log message +.. is only emitted if the handler and logger are configured to emit messages of +.. that level or lower. For example, if a message is ``CRITICAL``, and the logger +.. is set to ``ERROR``, the message is emitted. If a message is a ``WARNING``, and +.. the logger is set to produce only ``ERROR``\s, the message is not emitted: + ロガー、ハンドラ、メッセージをログ記録する関数呼び出しは、どれもレベルを指 定します。 ログメッセージはハンドラとロガーがそのレベル以下を吐き出す設定の時だけ吐き 出されます。 たとえば、メッセージが ``CRITICAL`` でロガーが ``ERROR`` の設定ならばメッ セージは吐き出されます。 一方、メッセージが ``WARNING`` でロガーが ``ERROR`` だけ生成するならば、 -メッセージは吐き出されません:: +メッセージは吐き出されません。 + + +:: import logging import sys @@ -148,8 +240,15 @@ logging.error('This is an error message') logging.critical('This is a critical error message') + +.. Run the script with an argument like 'debug' or 'warning' to see which messages +.. show up at different levels: + スクリプトを 'debug' とか 'warning' といった引数で実行して、 -レベルの違いによってどのメッセージが現れるようになるか見てみましょう:: +レベルの違いによってどのメッセージが現れるようになるか見てみましょう。 + + +:: $ python logging_level_example.py debug DEBUG:root:This is a debug message @@ -164,6 +263,17 @@ ERROR:root:This is an error message CRITICAL:root:This is a critical error message + +.. You will notice that these log messages all have ``root`` embedded in them. The +.. logging module supports a hierarchy of loggers with different names. An easy +.. way to tell where a specific log message comes from is to use a separate logger +.. object for each of your modules. Each new logger "inherits" the configuration +.. of its parent, and log messages sent to a logger include the name of that +.. logger. Optionally, each logger can be configured differently, so that messages +.. from different modules are handled in different ways. Let's look at a simple +.. example of how to log from different modules so it is easy to trace the source +.. of the message: + 気付いたかもしれませんが、全てのログメッセージに ``root`` が埋め込まれてい ます。 ログ記録モジュールは異なる名前のロガーの階層をサポートしているのです。 ログメッセージがどこから発生しているかを教える簡単な方法は、 @@ -172,7 +282,10 @@ あるロガーに送られたログメッセージはそのロガーの名前を含みます。 場合によっては、ロガーをそれぞれ異なるように設定して、 それぞれのモジュールからのメッセージを異なったやり方で扱うこともできます。 -では、単純な例でメッセージの出所が簡単に追跡できるように別々のモジュールか らログ記録を行う方法を見てみましょう:: +では、単純な例でメッセージの出所が簡単に追跡できるように別々のモジュールか らログ記録を行う方法を見てみましょう。 + + +:: import logging @@ -184,27 +297,55 @@ logger1.warning('This message comes from one module') logger2.warning('And this message comes from another module') -出力はこうなります:: + +.. And the output: + +出力はこうなります: + + +:: $ python logging_modules_example.py WARNING:package1.module1:This message comes from one module WARNING:package2.module2:And this message comes from another module + +.. There are many more options for configuring logging, including different log +.. message formatting options, having messages delivered to multiple destinations, +.. and changing the configuration of a long-running application on the fly using a +.. socket interface. All of these options are covered in depth in the library +.. module documentation. + 他にもオプションはもっといろいろあります。 ログ記録方法の設定、たとえばログメッセージフォーマットを変えるオプション、 メッセージを複数の送り先に配送するようなもの、 ソケットインターフェイスを通して長く走り続けるアプリケーションの設定を途中 で変更するものなどです。 全てのオプションはライブラリモジュールの文書の中でもっと細かく説明してあり ます。 + ロガー ^^^^^^ +.. The logging library takes a modular approach and offers the several categories +.. of components: loggers, handlers, filters, and formatters. Loggers expose the +.. interface that application code directly uses. Handlers send the log records to +.. the appropriate destination. Filters provide a finer grained facility for +.. determining which log records to send on to a handler. Formatters specify the +.. layout of the resultant log record. + logging ライブラリはモジュラー・アプローチを取ってコンポーネントのカテゴ リーをいくつかに分けています: ロガー、ハンドラ、フィルタ、フォーマッタ。 ロガーはアプリケーションのコードが直接使うインターフェイスを外部に公開して います。 ハンドラはログ記録を適切な行き先に送ります。 フィルタはどのログ記録をハンドラにおくるかを決めるさらにきめ細かい機構を提 供します。 フォーマッタは最終的なログ記録のレイアウトを指定します。 + +.. :class:`Logger` objects have a threefold job. First, they expose several +.. methods to application code so that applications can log messages at runtime. +.. Second, logger objects determine which log messages to act upon based upon +.. severity (the default filtering facility) or filter objects. Third, logger +.. objects pass along relevant log messages to all interested log handlers. + :class:`Logger` オブジェクトの仕事は大きく三つに分かれます。 一つめは、アプリケーションが実行中にメッセージを記録できるように、 いくつかのメソッドをアプリケーションから呼べるようにしています。 @@ -212,20 +353,49 @@ 深刻さ(デフォルトのフィルター機構)またはフィルターオブジェクトに基づいて決 定します。 三つめに、ロガーオブジェクトはログハンドラがそれぞれ持っている興味に関連す るログメッセージを回送します。 + +.. The most widely used methods on logger objects fall into two categories: +.. configuration and message sending. + ロガーオブジェクトのとりわけ広く使われるメソッドは二つのカテゴリーに分類で きます: 設定とメッセージ送信です。 + +.. * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger +.. will handle, where debug is the lowest built-in severity level and critical is +.. the highest built-in severity. For example, if the severity level is info, +.. the logger will handle only info, warning, error, and critical messages and +.. will ignore debug messages. + * :meth:`Logger.setLevel` ロガーが扱うログメッセージの最も低い深刻さを指定 します。 ここで組み込まれた深刻さは debug が一番低く、 critical が一番高くなりま す。 たとえば、深刻さが info と設定されたロガーは info, warning, error, critical のメッセージしか扱わず debug メッセージは無視します。 + +.. * :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter +.. objects from the logger object. This tutorial does not address filters. + * :meth:`Logger.addFilter` と :meth:`Logger.removeFilter` はロガーオブジェクトにフィルターを追加したり削除したりします。 このチュートリアルではフィルターは説明しません。 + +.. With the logger object configured, the following methods create log messages: + 設定されたロガーオブジェクトを使えば、以下のメソッドはログメッセージを作り 出します: + +.. * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, +.. :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with +.. a message and a level that corresponds to their respective method names. The +.. message is actually a format string, which may contain the standard string +.. substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The +.. rest of their arguments is a list of objects that correspond with the +.. substitution fields in the message. With regard to :const:`**kwargs`, the +.. logging methods care only about a keyword of :const:`exc_info` and use it to +.. determine whether to log exception information. + * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, :meth:`Logger.error`, :meth:`Logger.critical` は全て、 メッセージとメソッド名に対応したレベルでログ記録を作り出します。 @@ -235,14 +405,37 @@ :const:`**kwargs` については、ログ記録メソッドが気にするキーワードは :const:`exc_info` だけで、例外の情報をログに記録するかを決定するのに使い ます。 + +.. * :meth:`Logger.exception` creates a log message similar to +.. :meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a +.. stack trace along with it. Call this method only from an exception handler. + * :meth:`Logger.exception` は :meth:`Logger.error` と似たログメッセージを作 成します。 違いは :meth:`Logger.exception` がスタックトレースを一緒に吐き出すことで す。 例外ハンドラでだけ使うようにして下さい。 + +.. * :meth:`Logger.log` takes a log level as an explicit argument. This is a +.. little more verbose for logging messages than using the log level convenience +.. methods listed above, but this is how to log at custom log levels. + * :meth:`Logger.log` はログレベルを陽に引き渡される引数として取ります。 これは上に挙げた便宜的なログレベルごとのメソッドを使うより少しコード量が 多くなりますが、 独自のログレベルを使うにはこのようにするものなのです。 + +.. :func:`getLogger` returns a reference to a logger instance with the specified +.. if it it is provided, or ``root`` if not. The names are period-separated +.. hierarchical structures. Multiple calls to :func:`getLogger` with the same name +.. will return a reference to the same logger object. Loggers that are further +.. down in the hierarchical list are children of loggers higher up in the list. +.. For example, given a logger with a name of ``foo``, loggers with names of +.. ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``. +.. Child loggers propagate messages up to their parent loggers. Because of this, +.. it is unnecessary to define and configure all the loggers an application uses. +.. It is sufficient to configure a top-level logger and create child loggers as +.. needed. + :func:`getLogger` は指定されればその特定の、そうでなければ ``root`` のロガーインスタンスへの参照を返します。 ロガーの名前はピリオド区切りの階層構造を表します。 @@ -260,6 +453,15 @@ ハンドラ ^^^^^^^^ +.. :class:`Handler` objects are responsible for dispatching the appropriate log +.. messages (based on the log messages' severity) to the handler's specified +.. destination. Logger objects can add zero or more handler objects to themselves +.. with an :func:`addHandler` method. As an example scenario, an application may +.. want to send all log messages to a log file, all log messages of error or higher +.. to stdout, and all messages of critical to an email address. This scenario +.. requires three individual handlers where each handler is responsible for sending +.. messages of a specific severity to a specific location. + :class:`Handler` オブジェクトは適切なログメッセージを(ログメッセージの深刻 さに基づいて) ハンドラの指定された宛先に振り分けることに責任を持ちます。 ロガーオブジェクトには :func:`addHandler` メソッドで0個以上のハンドラを追加 することができます。 @@ -269,14 +471,32 @@ 送りたいとします。 この場合、三つの個別のハンドラがそれぞれの深刻さと宛先に応じて必要になりま す。 + +.. The standard library includes quite a few handler types; this tutorial uses only +.. :class:`StreamHandler` and :class:`FileHandler` in its examples. + このライブラリには多数のハンドラを用意してありますが、 このチュートリアルでは :class:`StreamHandler` と :class:`FileHandler` だけを例に取り上げます。 + +.. There are very few methods in a handler for application developers to concern +.. themselves with. The only handler methods that seem relevant for application +.. developers who are using the built-in handler objects (that is, not creating +.. custom handlers) are the following configuration methods: + アプリケーション開発者にとってハンドラを扱う上で気にするべきメソッドは極々 限られています。 備え付けのハンドラオブジェクトを使う (つまり自作ハンドラを作らない) 開発者に関係あるハンドラのメソッドは次の設定用のメソッドだけでしょう: + +.. * The :meth:`Handler.setLevel` method, just as in logger objects, specifies the +.. lowest severity that will be dispatched to the appropriate destination. Why +.. are there two :func:`setLevel` methods? The level set in the logger +.. determines which severity of messages it will pass to its handlers. The level +.. set in each handler determines which messages that handler will send on. +.. :func:`setFormatter` selects a Formatter object for this handler to use. + * :meth:`Handler.setLevel` メソッドは、ロガーオブジェクトの場合と同様に、 適切な宛先に振り分けられるべき最も低い深刻さを指定します。 なぜ二つも :func:`setLevel` メソッドがあるのでしょう? @@ -284,8 +504,18 @@ ハンドラでセットされるレベルはハンドラがどのメッセージを送るべきか決めま す。 :func:`setFormatter` でこのハンドラが使用する Formatter オブジェクトを選 択します。 + +.. * :func:`addFilter` and :func:`removeFilter` respectively configure and +.. deconfigure filter objects on handlers. + * :func:`addFilter` および :func:`removeFilter` はそれぞれハンドラへのフィ ルタオブジェクトの設定、設定解除を行います。 + +.. Application code should not directly instantiate and use handlers. Instead, the +.. :class:`Handler` class is a base class that defines the interface that all +.. Handlers should have and establishes some default behavior that child classes +.. can use (or override). + アプリケーションのコード中ではハンドラを直接インスタンス化して使ってはなり ません。 そうではなく、 :class:`Handler` クラスは全てのハンドラが持つべきインターフ ェイスを定義し、 子クラスが使える (もしくはオーバライドできる) いくつかのデフォルトの振る舞 いを確立します。 @@ -294,23 +524,49 @@ フォーマッタ ^^^^^^^^^^^^ +.. Formatter objects configure the final order, structure, and contents of the log +.. message. Unlike the base :class:`logging.Handler` class, application code may +.. instantiate formatter classes, although you could likely subclass the formatter +.. if your application needs special behavior. The constructor takes two optional +.. arguments: a message format string and a date format string. If there is no +.. message format string, the default is to use the raw message. If there is no +.. date format string, the default date format is: + フォーマッタオブジェクトは最終的なログメッセージの順序、構造および内容を設 定します。 基底クラスの :class:`logging.Handler` とは違って、 アプリケーションのコードはフォーマッタクラスをインスタンス化して構いません が、 特別な振る舞いをさせたいアプリケーションではフォーマッタのサブクラスを使う 可能性もあります。 コンストラクタは二つのオプション引数を取ります: メッセージのフォーマット文 字列と日付のフォーマット文字列です。 メッセージのフォーマット文字列がなければ、デフォルトではメッセージをそのま ま使います。 -日付のフォーマット文字列がなければデフォルトは:: +日付のフォーマット文字列がなければデフォルトは + + +:: %Y-%m-%d %H:%M:%S + +.. with the milliseconds tacked on at the end. + で、最後にミリ秒が付きます。 + +.. The message format string uses ``%(<dictionary key>)s`` styled string +.. substitution; the possible keys are documented in :ref:`formatter-objects`. + メッセージのフォーマット文字列は ``%(<dictionary key>)s`` 形式の文字列代入 を用います。 使えるキーについては :ref:`formatter-objects` に書いてあります。 + +.. The following message format string will log the time in a human-readable +.. format, the severity of the message, and the contents of the message, in that +.. order: + 下のメッセージのフォーマット文字列は、人が読みやすい形式の時刻、メッセージ の深刻さ、 -メッセージの内容をその順番に出力します:: +メッセージの内容をその順番に出力します。 + + +:: "%(asctime)s - %(levelname)s - %(message)s" @@ -318,12 +574,21 @@ ログ記録方法の設定 ^^^^^^^^^^^^^^^^^^ +.. Programmers can configure logging either by creating loggers, handlers, and +.. formatters explicitly in a main module with the configuration methods listed +.. above (using Python code), or by creating a logging config file. The following +.. code is an example of configuring a very simple logger, a console handler, and a +.. simple formatter in a Python module: + プログラマはログ記録方法を設定できます。 一つの方法は中心となるモジュールで上で述べたような設定メソッドで (Python コードを使って) ロガー、ハンドラ、フォーマッタを自ら手を下して作成 することです。 もう一つの方法は、ログ記録設定ファイルを作ることです。 以下のコードは、例としてごく単純なロガー、コンソールハンドラ、そして単純な フォーマッタを -Python モジュールの中で設定しています:: +Python モジュールの中で設定しています。 + + +:: import logging @@ -347,7 +612,13 @@ logger.error("error message") logger.critical("critical message") -このモジュールをコマンドラインから実行すると、以下の出力が得られます:: + +.. Running this module from the command line produces the following output: + +このモジュールをコマンドラインから実行すると、以下の出力が得られます。 + + +:: $ python simple_logging_module.py 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message @@ -356,8 +627,16 @@ 2005-03-19 15:10:26,697 - simple_example - ERROR - error message 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message + +.. The following Python module creates a logger, handler, and formatter nearly +.. identical to those in the example listed above, with the only difference being +.. the names of the objects: + 次の Python モジュールもロガー、ハンドラ、フォーマッタを上の例とほぼ同じ形 で生成しますが、 -オブジェクトの名前だけが異なります:: +オブジェクトの名前だけが異なります。 + + +:: import logging import logging.config @@ -374,7 +653,13 @@ logger.error("error message") logger.critical("critical message") -そしてこれが logging.conf ファイルです:: + +.. Here is the logging.conf file: + +そしてこれが logging.conf ファイルです: + + +:: [loggers] keys=root,simpleExample @@ -405,7 +690,13 @@ format=%(asctime)s - %(name)s - %(levelname)s - %(message)s datefmt= -出力は設定ファイルを使わないバージョンとほぼ同じです:: + +.. The output is nearly identical to that of the non-config-file-based example: + +出力は設定ファイルを使わないバージョンとほぼ同じです。 + + +:: $ python simple_logging_config.py 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message @@ -414,14 +705,27 @@ 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message + +.. You can see that the config file approach has a few advantages over the Python +.. code approach, mainly separation of configuration and code and the ability of +.. noncoders to easily modify the logging properties. + 設定ファイル経由の方が Python コード経由に比べていくつかの利点を有している ことが見て取れると思います。 設定とコードの分離が最大の違いで、プログラマ以外にも容易にログ出力の表現を 変更できます。 + .. _library-config: ライブラリのためのログ記録方法の設定 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. When developing a library which uses logging, some consideration needs to be +.. given to its configuration. If the using application does not use logging, and +.. library code makes logging calls, then a one-off message "No handlers could be +.. found for logger X.Y.Z" is printed to the console. This message is intended +.. to catch mistakes in logging configuration, but will confuse an application +.. developer who is not aware of logging by the library. + ログ記録を行うライブラリを開発するときには、いくつかその設定について考えて おくべきことがあります。 ライブラリを使うアプリケーションが logging を使っていないときに、 ライブラリが logging を呼び出すと "No handlers could be found for logger X.Y.Z" @@ -430,6 +734,15 @@ このメッセージは logging の設定ミスを捕らえるためのものですが、 ライブラリが logging を使っているとアプリケーション開発者が知らない場合混乱 につながりかねません。 + +.. In addition to documenting how a library uses logging, a good way to configure +.. library logging so that it does not cause a spurious message is to add a +.. handler which does nothing. This avoids the message being printed, since a +.. handler will be found: it just doesn't produce any output. If the library user +.. configures logging for application use, presumably that configuration will add +.. some handlers, and if levels are suitably configured then logging calls made +.. in library code will send output to those handlers, as normal. + ライブラリが logging をどのように使っているかを文書に書くだけでなく、 意図しないメッセージを出さないために何もしないハンドラを加えるように設定し ておくのが良い方法です。 こうすればメッセージが出力されるのを(ハンドラが見つかるので)防げるので、何 も出力しないようになります。 @@ -437,7 +750,13 @@ おそらくその設定で何かハンドラを追加することでしょう。 その中でレベルが適切に設定されていればライブラリコード中の logging 呼び出し はそのハンドラに(普段通りに)出力を送ります。 -何もしないハンドラは以下のよう簡単に定義できます:: + +.. A do-nothing handler can be simply defined as follows: + +何もしないハンドラは以下のよう簡単に定義できます。 + + +:: import logging @@ -445,15 +764,28 @@ def emit(self, record): pass + +.. An instance of this handler should be added to the top-level logger of the +.. logging namespace used by the library. If all logging by a library *foo* is +.. done using loggers with names matching "foo.x.y", then the code: + このハンドラのインスタンスがライブラリで使われるログ記録の名前空間の最上位 ロガーに追加されなければなりません。 ライブラリ *foo* のログ記録が全て "foo.x.y" にマッチする名前のロガーで行わ れるならば、 -次のコードで望むような効果を得られます:: +次のコードで望むような効果を得られます。 + + +:: import logging h = NullHandler() logging.getLogger("foo").addHandler(h) + +.. should have the desired effect. If an organisation produces a number of +.. libraries, then the logger name specified can be "orgname.foo" rather than +.. just "foo". + 組織がいくつものライブラリを世に出しているならば、指定されるロガーの名前は 単なる "foo" ではなく "orgname.foo" かもしれませんね。 @@ -461,9 +793,32 @@ ログレベル ---------- +.. The numeric values of logging levels are given in the following table. These are +.. primarily of interest if you want to define your own levels, and need them to +.. have specific values relative to the predefined levels. If you define a level +.. with the same numeric value, it overwrites the predefined value; the predefined +.. name is lost. + ログレベルの数値は以下の表のように与えられています。これらは基本的に自分で レベルを定義したい人のためのもので、 定義するレベルを既存のレベルの間に位置づけるために具体的な値が必要になりま す。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われ ます。 + +.. +--------------+---------------+ +.. | Level | Numeric value | +.. +==============+===============+ +.. | ``CRITICAL`` | 50 | +.. +--------------+---------------+ +.. | ``ERROR`` | 40 | +.. +--------------+---------------+ +.. | ``WARNING`` | 30 | +.. +--------------+---------------+ +.. | ``INFO`` | 20 | +.. +--------------+---------------+ +.. | ``DEBUG`` | 10 | +.. +--------------+---------------+ +.. | ``NOTSET`` | 0 | +.. +--------------+---------------+ + +--------------+------+ | レベル | 数値 | +==============+======+ @@ -480,14 +835,40 @@ | ``NOTSET`` | 0 | +--------------+------+ + +.. Levels can also be associated with loggers, being set either by the developer or +.. through loading a saved logging configuration. When a logging method is called +.. on a logger, the logger compares its own level with the level associated with +.. the method call. If the logger's level is higher than the method call's, no +.. logging message is actually generated. This is the basic mechanism controlling +.. the verbosity of logging output. + レベルもロガーに関連付けることができ、デベロッパが設定することも、保存され たログ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らのレベルとメソ ッド呼び出しに関連付けられたレベルを比較します。 ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際のログメッセー ジは生成されません。これはログ出力の冗長性を制御するための基本的なメカニズム です。 + +.. Logging messages are encoded as instances of the :class:`LogRecord` class. When +.. a logger decides to actually log an event, a :class:`LogRecord` instance is +.. created from the logging message. + ログ記録されるメッセージは :class:`LogRecord` クラスのインスタンスとして コード化されます。ロガーがあるイベントを実際にログ出力すると決定した場合、 ログメッセージから :class:`LogRecord` インスタンスが生成されます。 + +.. Logging messages are subjected to a dispatch mechanism through the use of +.. :dfn:`handlers`, which are instances of subclasses of the :class:`Handler` +.. class. Handlers are responsible for ensuring that a logged message (in the form +.. of a :class:`LogRecord`) ends up in a particular location (or set of locations) +.. which is useful for the target audience for that message (such as end users, +.. support desk staff, system administrators, developers). Handlers are passed +.. :class:`LogRecord` instances intended for particular destinations. Each logger +.. can have zero, one or more handlers associated with it (via the +.. :meth:`addHandler` method of :class:`Logger`). In addition to any handlers +.. directly associated with a logger, *all handlers associated with all ancestors +.. of the logger* are called to dispatch the message. + ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通して、処理機構 (dispatch mechanism) にかけられます。ハンドラは :class:`Handler` クラスのサブクラスのインスタン スで、ログ記録された (:class:`LogRecord` 形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サ ポートデスクのスタッフ、システム管理者、開発者) @@ -495,46 +876,115 @@ ゼロ個、単一またはそれ以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 *ロガーの上位にあるロガー全て に関連付けられたハンドラ* がメッセージを処理する際に呼び出されます。 + +.. Just as for loggers, handlers can have levels associated with them. A handler's +.. level acts as a filter in the same way as a logger's level does. If a handler +.. decides to actually dispatch an event, the :meth:`emit` method is used to send +.. the message to its destination. Most user-defined subclasses of :class:`Handler` +.. will need to override this :meth:`emit`. + ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。ハンド ラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 ハンドラがあるイベントを実際に処理すると決定した場合、 :meth:`emit` メソッ ドが使われ、メッセージを発送先に送信します。ほとんどのユーザ定義の :class:`Handler` のサブクラスで、この :meth:`emit` をオーバライドする必要が あるでしょう。 + +.. In addition to the base :class:`Handler` class, many useful subclasses are +.. provided: + 基底クラスとなる :class:`Handler` クラスに加えて、多くの有用なサブクラスが 提供されています: -#. :class:`StreamHandler` のインスタンスはストリーム (ファイル様オブジェク ト) にエラーメッセージを送信します。 - -#. :class:`FileHandler` のインスタンスはディスク上のファイルにエラーメッ セージを送信します。 - -#. :class:`handlers.BaseRotatingHandler` はログファイルをある時点で交替させ る\ + +.. #. :class:`StreamHandler` instances send error messages to streams (file-like +.. objects). + +1. :class:`StreamHandler` のインスタンスはストリーム (ファイル様オブジェク ト) にエラーメッセージを送信します。 + + +.. #. :class:`FileHandler` instances send error messages to disk files. + +2. :class:`FileHandler` のインスタンスはディスク上のファイルにエラーメッ セージを送信します。 + + +.. #. :class:`handlers.BaseRotatingHandler` is the base class for handlers that +.. rotate log files at a certain point. It is not meant to be instantiated +.. directly. Instead, use :class:`RotatingFileHandler` or +.. :class:`TimedRotatingFileHandler`. + +3. :class:`handlers.BaseRotatingHandler` はログファイルをある時点で交替させ る\ ハンドラの基底クラスです。直接インスタンス化するためのクラスではありませ ん。 :class:`RotatingFileHandler` や :class:`TimedRotatingFileHandler` を使うようにしてください。 -#. :class:`handlers.RotatingFileHandler` のインスタンスは最大ログファイルの \ + +.. #. :class:`handlers.RotatingFileHandler` instances send error messages to disk files, +.. with support for maximum log file sizes and log file rotation. + +4. :class:`handlers.RotatingFileHandler` のインスタンスは最大ログファイルの \ サイズ指定とログファイルの交替機能をサポートしながら、ディスク上のファイ ルにエラーメッセージを送信します。 -#. :class:`handlers.TimedRotatingFileHandler` のインスタンスは、ログファイ ルを\ + +.. #. :class:`handlers.TimedRotatingFileHandler` instances send error messages to disk files +.. rotating the log file at certain timed intervals. + +5. :class:`handlers.TimedRotatingFileHandler` のインスタンスは、ログファイ ルを\ 一定時間間隔ごとに交替しながら、ディスク上のファイルにエラーメッセージを 送信します。 -#. :class:`handlers.SocketHandler` のインスタンスは TCP/IP ソケットにエラー メッセージを送信します。 - -#. :class:`handlers.DatagramHandler` のインスタンスは UDP ソケットにエラー メッセージを送信します。 - -#. :class:`handlers.SMTPHandler` のインスタンスは指定された電子メールアドレ スにエラーメッセージを送信します。 - -#. :class:`handlers.SysLogHandler` のインスタンスは遠隔を含むマシン上の syslog デーモンにエラーメッセージを送信します。 - -#. :class:`handlers.NTEventLogHandler` のインスタンスは Windows NT/2000/XP イベントログにエラーメッセージを送信します。 - -#. :class:`handlers.MemoryHandler` のインスタンスはメモリ上のバッファにエ ラーメッセージを送信し、指定された条件でフラッシュされるようにします。 - -#. :class:`handlers.HTTPHandler` のインスタンスは ``GET`` か ``POST`` セマ ンティクスを使って HTTP - サーバにエラーメッセージを送信します。 - -#. :class:`handlers.WatchedFileHandler` のインスタンスはログ記録を行うファ イルを監視します。 - もしファイルが変われば、一旦ファイルを閉じた後ファイル名を使って再度開き ます。 - このハンドラは Unix ライクなシステムでだけ有用です。 - Windows では元にしている機構がサポートされていません。 + +.. #. :class:`handlers.SocketHandler` instances send error messages to TCP/IP sockets. + +6. :class:`handlers.SocketHandler` のインスタンスは TCP/IP ソケットにエラー メッセージを送信します。 + + +.. #. :class:`handlers.DatagramHandler` instances send error messages to UDP sockets. + +7. :class:`handlers.DatagramHandler` のインスタンスは UDP ソケットにエラー メッセージを送信します。 + + +.. #. :class:`handlers.SMTPHandler` instances send error messages to a designated email +.. address. + +8. :class:`handlers.SMTPHandler` のインスタンスは指定された電子メールアドレ スにエラーメッセージを送信します。 + + +.. #. :class:`handlers.SysLogHandler` instances send error messages to a Unix syslog daemon, +.. possibly on a remote machine. + +9. :class:`handlers.SysLogHandler` のインスタンスは遠隔を含むマシン上の syslog デーモンにエラーメッセージを送信します。 + + +.. #. :class:`handlers.NTEventLogHandler` instances send error messages to a Windows +.. NT/2000/XP event log. + +10. :class:`handlers.NTEventLogHandler` のインスタンスは Windows NT/2000/XP イベントログにエラーメッセージを送信します。 + + +.. #. :class:`handlers.MemoryHandler` instances send error messages to a buffer in memory, +.. which is flushed whenever specific criteria are met. + +11. :class:`handlers.MemoryHandler` のインスタンスはメモリ上のバッファにエ ラーメッセージを送信し、指定された条件でフラッシュされるようにします。 + + +.. #. :class:`handlers.HTTPHandler` instances send error messages to an HTTP server using +.. either ``GET`` or ``POST`` semantics. + +12. :class:`handlers.HTTPHandler` のインスタンスは ``GET`` か ``POST`` セマ ンティクスを使って HTTP + サーバにエラーメッセージを送信します。 + +.. #. :class:`handlers.WatchedFileHandler` instances watch the file they are logging to. If +.. the file changes, it is closed and reopened using the file name. This handler +.. is only useful on Unix-like systems; Windows does not support the underlying +.. mechanism used. + +13. :class:`handlers.WatchedFileHandler` のインスタンスはログ記録を行うファ イルを監視します。 + もしファイルが変われば、一旦ファイルを閉じた後ファイル名を使って再度開 きます。 + このハンドラは Unix ライクなシステムでだけ有用です。 + Windows では元にしている機構がサポートされていません。 + + +.. The :class:`StreamHandler` and :class:`FileHandler` +.. classes are defined in the core logging package. The other handlers are +.. defined in a sub- module, :mod:`logging.handlers`. (There is also another +.. sub-module, :mod:`logging.config`, for configuration functionality.) :class:`StreamHandler` および :class:`FileHandler` クラスは、中核となる\ ログ化機構パッケージ内で定義されています。他のハンドラはサブモジュール、 @@ -542,38 +992,84 @@ (サブモジュールにはもうひとつ :mod:`logging.config` があり、 これは環境設定機能のためのものです。) + +.. Logged messages are formatted for presentation through instances of the +.. :class:`Formatter` class. They are initialized with a format string suitable for +.. use with the % operator and a dictionary. + ログ記録されたメッセージは :class:`Formatter` クラスのインスタンスを介し、 表示用に書式化されます。これらのインスタンスは % 演算子と辞書を使うのに適した書式化文字列で初期化されます。 + +.. For formatting multiple messages in a batch, instances of +.. :class:`BufferingFormatter` can be used. In addition to the format string (which +.. is applied to each message in the batch), there is provision for header and +.. trailer format strings. + 複数のメッセージの初期化をバッチ処理するため に、 :class:`BufferingFormatter` のインスタンスを使うことができます。書式化 文字列 (バッチ処理で各メッセージに適用されます) に加えて、ヘッダ (header) およびト レイラ (trailer) 書式化文字列が用意されています。 + +.. When filtering based on logger level and/or handler level is not enough, +.. instances of :class:`Filter` can be added to both :class:`Logger` and +.. :class:`Handler` instances (through their :meth:`addFilter` method). Before +.. deciding to process a message further, both loggers and handlers consult all +.. their filters for permission. If any filter returns a false value, the message +.. is not processed further. + ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリングが十分 でない場合、 :class:`Logger` および :class:`Handler` インスタンスに :class:`Filter` のインスタンスを (:meth:`addFilter` メソッド を介して) 追加することができます。メッセージの処理を進める前に、ロガーとハンドラはと もに、全てのフィルタでメッセージの処理が許可されているか調べます。 いずれかのフィルタが偽となる値を返した場合、メッセージの処理は行われませ ん。 + +.. The basic :class:`Filter` functionality allows filtering by specific logger +.. name. If this feature is used, messages sent to the named logger and its +.. children are allowed through the filter, and all others dropped. + 基本的な :class:`Filter` 機能では、指定されたロガー名でフィルタを行えるよう になっています。この機能が利用された場合、名前付けされた ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過できるよう になり、その他のメッセージは捨てられます。 + +.. In addition to the classes described above, there are a number of module- level +.. functions. + 上で述べたクラスに加えて、いくつかのモジュールレベルの関数が存在します。 .. function:: getLogger([name]) + .. Return a logger with the specified name or, if no name is specified, return a + .. logger which is the root logger of the hierarchy. If specified, the name is + .. typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*. + .. Choice of these names is entirely up to the developer who is using logging. + 指定された名前のロガーを返します。名前が指定されていない場合、ロガー階層 のルート (root) にあるロガーを返します。 *name* を指定する場合には、通常は *"a"*, *"a.b"*, あるいは *"a.b.c.d"* といっ たようなドット区切りの階層的な 名前にします。名前の付け方はログ機能を使う開発者次第です。 + + .. All calls to this function with a given name return the same logger instance. + .. This means that logger instances never need to be passed between different parts + .. of an application. + 与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。従って、ロガーインスタンスをアプリケーションの各部 でやりとりする必要はなくなります。 .. function:: getLoggerClass() + .. Return either the standard :class:`Logger` class, or the last class passed to + .. :func:`setLoggerClass`. This function may be called from within a new class + .. definition, to ensure that installing a customised :class:`Logger` class will + .. not undo customisations already applied by other code. For example: + 標準の :class:`Logger` クラスか、最後に :func:`setLoggerClass` に渡した クラスを返します。この関数は、新たに定義するクラス内で呼び出し、カスタマ イズした :class:`Logger` クラスのインストールを行うときに - 既に他のコードで適用したカスタマイズを取り消そうとしていないか確かめるの に使います。例えば以下のようにします:: + 既に他のコードで適用したカスタマイズを取り消そうとしていないか確かめるの に使います。例えば以下のようにします: + + + :: class MyLogger(logging.getLoggerClass()): # ... override behaviour here @@ -581,83 +1077,166 @@ .. function:: debug(msg[, *args[, **kwargs]]) + .. Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the + .. message format string, and the *args* are the arguments which are merged into + .. *msg* using the string formatting operator. (Note that this means that you can + .. use keywords in the format string, together with a single dictionary argument.) + レベル :const:`DEBUG` のメッセージをルートロガーで記録します。 *msg* は メッセージの書式化文字列で、 *args* は *msg* に 文字列書式化演算子を使って取り込むための引数です。(これは、書式化文字列 でキーワードを使い引数に辞書を渡すことができる、ということを意味します。) + ***The diff for this file has been truncated for email.*** ============================================================================== Revision: fa7e351aad9b Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:44:46 2011 Log: 2.6.6 以前の訳文の重複を修正 http://code.google.com/p/python-doc-ja/source/detail?r=fa7e351aad9b Modified: /library/logging.rst ======================================= --- /library/logging.rst Wed May 18 09:33:21 2011 +++ /library/logging.rst Wed May 18 09:44:46 2011 @@ -1265,13 +1265,9 @@ .. :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting .. it as a :class:`LogRecord` instance at the receiving end. - 属性が *attrdict* で定義された、新たな :class:`LogRecord` インスタンス を生成して返します。この関数は pickle 化された - :class:`LogRecord` 属性の辞書を作成し、ソケットを介して送信し、受信端 で :class:`LogRecord` - インスタンスとして再構成する際に便利です。 - - *attrdict* で属性を定義した、新しい :class:`LogRecord` インスタンスを返 します。この関数は、逆 pickle 化された - :class:`LogRecord` 属性辞書を socket 越しに受け取り、受信端 で :class:`LogRecord` インスタンスに再構築す - る場合に有用です。 + 属性が *attrdict* で定義された、新しい :class:`LogRecord` インスタンスを 生成して返します。 + この関数は、 pickle された :class:`LogRecord` 属性の辞書をソケットを介し て送信し、 + 受信端で :class:`LogRecord` インスタンスとして再構成する場合に便利です。 .. function:: basicConfig([**kwargs]) ============================================================================== Revision: 48dd780ae2ef Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:45:04 2011 Log: 2.6.6: library/logging.rst http://code.google.com/p/python-doc-ja/source/detail?r=48dd780ae2ef Modified: /library/logging.rst ======================================= --- /library/logging.rst Wed May 18 09:44:46 2011 +++ /library/logging.rst Wed May 18 09:45:04 2011 @@ -86,19 +86,23 @@ .. Most applications are probably going to want to log to a file, so let's start .. with that case. Using the :func:`basicConfig` function, we can set up the -.. default handler so that debug messages are written to a file: +.. default handler so that debug messages are written to a file (in the example, +.. we assume that you have the appropriate permissions to create a file called +.. *example.log* in the current directory): ほとんどのアプリケーションではファイルにログ記録することを望むことになるで しょうから、 まずはこのケースから始めましょう。 :func:`basicConfig` 関数を使って、デバッグメッセージがファイルに書き込まれ るように、 デフォルトのハンドラをセットアップします。 +(この例では、カレントディレクトリの中に *example.log* というファイルを作る ための +適切な権限があると仮定しています) :: import logging - LOG_FILENAME = '/tmp/logging_example.out' - logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,) + LOG_FILENAME = 'example.log' + logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG) logging.debug('This message should go to the log file') @@ -116,13 +120,13 @@ .. If you run the script repeatedly, the additional log messages are appended to -.. the file. To create a new file each time, you can pass a filemode argument to +.. the file. To create a new file each time, you can pass a *filemode* argument to .. :func:`basicConfig` with a value of ``'w'``. Rather than managing the file size .. yourself, though, it is simpler to use a :class:`RotatingFileHandler`: スクリプトを繰り返し実行すると、 さらなるログメッセージがファイルに追記されていきます。 -毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡すファイルモード 引数を +毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡す *filemode* 引 数を ``'w'`` にします。 ファイルサイズを自分で管理する代わりに、 もっと簡単に :class:`RotatingFileHandler` を使う手があります。 @@ -134,7 +138,7 @@ import logging import logging.handlers - LOG_FILENAME = '/tmp/logging_rotatingfile_example.out' + LOG_FILENAME = 'logging_rotatingfile_example.out' # Set up a specific logger with our desired output level my_logger = logging.getLogger('MyLogger') @@ -166,23 +170,23 @@ :: - /tmp/logging_rotatingfile_example.out - /tmp/logging_rotatingfile_example.out.1 - /tmp/logging_rotatingfile_example.out.2 - /tmp/logging_rotatingfile_example.out.3 - /tmp/logging_rotatingfile_example.out.4 - /tmp/logging_rotatingfile_example.out.5 + logging_rotatingfile_example.out + logging_rotatingfile_example.out.1 + logging_rotatingfile_example.out.2 + logging_rotatingfile_example.out.3 + logging_rotatingfile_example.out.4 + logging_rotatingfile_example.out.5 -.. The most current file is always :file:`/tmp/logging_rotatingfile_example.out`, +.. The most current file is always :file:`logging_rotatingfile_example.out`, .. and each time it reaches the size limit it is renamed with the suffix .. ``.1``. Each of the existing backup files is renamed to increment the suffix -.. (``.1`` becomes ``.2``, etc.) and the ``.5`` file is erased. - -最新のファイルはいつでも :file:`/tmp/logging_rotatingfile_example.out` で、 +.. (``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased. + +最新のファイルはいつでも :file:`logging_rotatingfile_example.out` で、 サイズの上限に達するたびに拡張子 ``.1`` を付けた名前に改名されます。 既にあるバックアップファイルはその拡張子がインクリメントされ -(``.1`` が ``.2`` になるなど)、 ``.5`` ファイルは消去されます。 +(``.1`` が ``.2`` になるなど)、 ``.6`` ファイルは消去されます。 .. Obviously this example sets the log length much much too small as an extreme @@ -196,13 +200,13 @@ .. messages at different log levels. This allows you to instrument your code with .. debug messages, for example, but turning the log level down so that those debug .. messages are not written for your production system. The default levels are -.. ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG`` and ``NOTSET``. +.. ``NOTSET``, ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and ``CRITICAL``. ログ記録 API のもう一つの有用な仕組みが異なるメッセージを異なるログレベルで 生成する能力です。 これを使えば、たとえばコードの中にデバッグメッセージを埋め込みつつ、 出荷段階でログ記録レベルを落としてこれが記録されないようにするといったこと ができます。 デフォルトで設定されているレベルは -``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG``, ``NOTSET`` で す。 +``NOTSET``, ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL`` で す。 .. The logger, handler, and log message call each specify a level. The log message @@ -425,18 +429,18 @@ .. :func:`getLogger` returns a reference to a logger instance with the specified -.. if it it is provided, or ``root`` if not. The names are period-separated +.. name if it is provided, or ``root`` if not. The names are period-separated .. hierarchical structures. Multiple calls to :func:`getLogger` with the same name .. will return a reference to the same logger object. Loggers that are further .. down in the hierarchical list are children of loggers higher up in the list. .. For example, given a logger with a name of ``foo``, loggers with names of -.. ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``. -.. Child loggers propagate messages up to their parent loggers. Because of this, -.. it is unnecessary to define and configure all the loggers an application uses. -.. It is sufficient to configure a top-level logger and create child loggers as -.. needed. - -:func:`getLogger` は指定されればその特定の、そうでなければ ``root`` +.. ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all descendants of ``foo``. +.. Child loggers propagate messages up to the handlers associated with their +.. ancestor loggers. Because of this, it is unnecessary to define and configure +.. handlers for all the loggers an application uses. It is sufficient to +.. configure handlers for a top-level logger and create child loggers as needed. + +:func:`getLogger` は指定されればその特定の名前の、そうでなければ ``root`` のロガーインスタンスへの参照を返します。 ロガーの名前はピリオド区切りの階層構造を表します。 同じ名前で :func:`getLogger` を複数回呼び出した場合、 @@ -444,10 +448,10 @@ 階層リストを下ったロガーはリスト上位のロガーの子です。 たとえば、名前が ``foo`` であるロガーがあったとして、 ``foo.bar``, ``foo.bar.baz``, ``foo.bam`` といった名前のロガーは全て -``foo`` の子になります。 -子ロガーはメッセージを親ロガーに伝えます。 -このため、アプリケーションが使っている全てのロガーを定義して設定する必要は ありません。 -トップレベルのロガーだけ設定しておいて必要に応じて子ロガーを作成すれば十分 です。 +``foo`` の子孫になります。 +子ロガーはメッセージを親ロガーのハンドラに伝えます。 +このため、アプリケーションが使っている全てのロガーのためのハンドラを定義し て設定する必要はありません。 +トップレベルのロガーのためのハンドラだけ設定しておいて必要に応じて子ロガー を作成すれば十分です。 ハンドラ @@ -495,14 +499,17 @@ .. are there two :func:`setLevel` methods? The level set in the logger .. determines which severity of messages it will pass to its handlers. The level .. set in each handler determines which messages that handler will send on. -.. :func:`setFormatter` selects a Formatter object for this handler to use. * :meth:`Handler.setLevel` メソッドは、ロガーオブジェクトの場合と同様に、 適切な宛先に振り分けられるべき最も低い深刻さを指定します。 なぜ二つも :func:`setLevel` メソッドがあるのでしょう? ロガーでセットされるレベルはメッセージのどの深刻さを付随するハンドラに渡 すか決めます。 ハンドラでセットされるレベルはハンドラがどのメッセージを送るべきか決めま す。 - :func:`setFormatter` でこのハンドラが使用する Formatter オブジェクトを選 択します。 + + +.. * :func:`setFormatter` selects a Formatter object for this handler to use. + +* :func:`setFormatter` でこのハンドラが使用する Formatter オブジェクトを選 択します。 .. * :func:`addFilter` and :func:`removeFilter` respectively configure and @@ -511,12 +518,12 @@ * :func:`addFilter` および :func:`removeFilter` はそれぞれハンドラへのフィ ルタオブジェクトの設定、設定解除を行います。 -.. Application code should not directly instantiate and use handlers. Instead, the -.. :class:`Handler` class is a base class that defines the interface that all -.. Handlers should have and establishes some default behavior that child classes -.. can use (or override). - -アプリケーションのコード中ではハンドラを直接インスタンス化して使ってはなり ません。 +.. Application code should not directly instantiate and use instances of +.. :class:`Handler`. Instead, the :class:`Handler` class is a base class that +.. defines the interface that all handlers should have and establishes some +.. default behavior that child classes can use (or override). + +アプリケーションのコード中では :class:`Handler` のインスタンスを直接インス タンス化して使ってはなりません。 そうではなく、 :class:`Handler` クラスは全てのハンドラが持つべきインターフ ェイスを定義し、 子クラスが使える (もしくはオーバライドできる) いくつかのデフォルトの振る舞 いを確立します。 @@ -552,10 +559,10 @@ .. The message format string uses ``%(<dictionary key>)s`` styled string -.. substitution; the possible keys are documented in :ref:`formatter-objects`. +.. substitution; the possible keys are documented in :ref:`formatter`. メッセージのフォーマット文字列は ``%(<dictionary key>)s`` 形式の文字列代入 を用います。 -使えるキーについては :ref:`formatter-objects` に書いてあります。 +使えるキーについては :ref:`formatter` に書いてあります。 .. The following message format string will log the time in a human-readable @@ -867,7 +874,9 @@ .. can have zero, one or more handlers associated with it (via the .. :meth:`addHandler` method of :class:`Logger`). In addition to any handlers .. directly associated with a logger, *all handlers associated with all ancestors -.. of the logger* are called to dispatch the message. +.. of the logger* are called to dispatch the message (unless the *propagate* flag +.. for a logger is set to a false value, at which point the passing to ancestor +.. handlers stops). ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通して、処理機構 (dispatch mechanism) にかけられます。ハンドラは :class:`Handler` クラスのサブクラスのインスタン スで、ログ記録された (:class:`LogRecord` @@ -875,6 +884,8 @@ に行き着くようにする役割を持ちます。ハンドラには特定の行き先に方向付けられ た :class:`LogRecord` インスタンスが渡されます。各ロガーは ゼロ個、単一またはそれ以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 *ロガーの上位にあるロガー全て に関連付けられたハンドラ* がメッセージを処理する際に呼び出されます。 +(ただしロガーの *propagate* フラグが false 値にセットされている場合を除く。 +その場合は、祖先ハンドラへの通過は止まります。) .. Just as for loggers, handlers can have levels associated with them. A handler's @@ -888,45 +899,48 @@ :class:`Handler` のサブクラスで、この :meth:`emit` をオーバライドする必要が あるでしょう。 +有用なハンドラ集 +---------------- + .. In addition to the base :class:`Handler` class, many useful subclasses are .. provided: 基底クラスとなる :class:`Handler` クラスに加えて、多くの有用なサブクラスが 提供されています: -.. #. :class:`StreamHandler` instances send error messages to streams (file-like +.. #. :ref:`stream-handler` instances send error messages to streams (file-like .. objects). -1. :class:`StreamHandler` のインスタンスはストリーム (ファイル様オブジェク ト) にエラーメッセージを送信します。 +1. :ref:`stream-handler` のインスタンスはストリーム (ファイル様オブジェクト ) にエラーメッセージを送信します。 -.. #. :class:`FileHandler` instances send error messages to disk files. - -2. :class:`FileHandler` のインスタンスはディスク上のファイルにエラーメッ セージを送信します。 +.. #. :ref:`file-handler` instances send error messages to disk files. + +2. :ref:`file-handler` のインスタンスはディスク上のファイルにエラーメッセー ジを送信します。 -.. #. :class:`handlers.BaseRotatingHandler` is the base class for handlers that +.. #. :class:`BaseRotatingHandler` is the base class for handlers that .. rotate log files at a certain point. It is not meant to be instantiated -.. directly. Instead, use :class:`RotatingFileHandler` or -.. :class:`TimedRotatingFileHandler`. - -3. :class:`handlers.BaseRotatingHandler` はログファイルをある時点で交替させ る\ +.. directly. Instead, use :ref:`rotating-file-handler` or +.. :ref:`timed-rotating-file-handler`. + +3. :class:`BaseRotatingHandler` はログファイルをある時点で交替させる\ ハンドラの基底クラスです。直接インスタンス化するためのクラスではありませ ん。 - :class:`RotatingFileHandler` - や :class:`TimedRotatingFileHandler` を使うようにしてください。 + :ref:`rotating-file-handler` + や :ref:`timed-rotating-file-handler` を使うようにしてください。 -.. #. :class:`handlers.RotatingFileHandler` instances send error messages to disk files, -.. with support for maximum log file sizes and log file rotation. - -4. :class:`handlers.RotatingFileHandler` のインスタンスは最大ログファイルの \ +.. #. :ref:`rotating-file-handler` instances send error messages to disk +.. files, with support for maximum log file sizes and log file rotation. + +4. :ref:`rotating-file-handler` のインスタンスは最大ログファイルの\ サイズ指定とログファイルの交替機能をサポートしながら、ディスク上のファイ ルにエラーメッセージを送信します。 -.. #. :class:`handlers.TimedRotatingFileHandler` instances send error messages to disk files -.. rotating the log file at certain timed intervals. - -5. :class:`handlers.TimedRotatingFileHandler` のインスタンスは、ログファイ ルを\ +.. #. :ref:`timed-rotating-file-handler` instances send error messages to +.. disk files, rotating the log file at certain timed intervals. + +5. :ref:`timed-rotating-file-handler` のインスタンスは、ログファイルを\ 一定時間間隔ごとに交替しながら、ディスク上のファイルにエラーメッセージを 送信します。 @@ -935,47 +949,48 @@ 6. :class:`handlers.SocketHandler` のインスタンスは TCP/IP ソケットにエラー メッセージを送信します。 -.. #. :class:`handlers.DatagramHandler` instances send error messages to UDP sockets. - -7. :class:`handlers.DatagramHandler` のインスタンスは UDP ソケットにエラー メッセージを送信します。 +.. #. :ref:`datagram-handler` instances send error messages to UDP +.. sockets. + +7. :ref:`datagram-handler` のインスタンスは UDP ソケットにエラーメッセージ を送信します。 -.. #. :class:`handlers.SMTPHandler` instances send error messages to a designated email -.. address. - -8. :class:`handlers.SMTPHandler` のインスタンスは指定された電子メールアドレ スにエラーメッセージを送信します。 +.. #. :ref:`smtp-handler` instances send error messages to a designated +.. email address. + +8. :ref:`smtp-handler` のインスタンスは指定された電子メールアドレスにエラー メッセージを送信します。 -.. #. :class:`handlers.SysLogHandler` instances send error messages to a Unix syslog daemon, -.. possibly on a remote machine. - -9. :class:`handlers.SysLogHandler` のインスタンスは遠隔を含むマシン上の syslog デーモンにエラーメッセージを送信します。 +.. #. :ref:`syslog-handler` instances send error messages to a Unix +.. syslog daemon, possibly on a remote machine. + +9. :ref:`syslog-handler` のインスタンスは遠隔を含むマシン上の syslog デーモ ンにエラーメッセージを送信します。 -.. #. :class:`handlers.NTEventLogHandler` instances send error messages to a Windows -.. NT/2000/XP event log. - -10. :class:`handlers.NTEventLogHandler` のインスタンスは Windows NT/2000/XP イベントログにエラーメッセージを送信します。 +.. #. :ref:`nt-eventlog-handler` instances send error messages to a +.. Windows NT/2000/XP event log. + +10. :ref:`nt-eventlog-handler` のインスタンスは Windows NT/2000/XP イベント ログにエラーメッセージを送信します。 -.. #. :class:`handlers.MemoryHandler` instances send error messages to a buffer in memory, -.. which is flushed whenever specific criteria are met. - -11. :class:`handlers.MemoryHandler` のインスタンスはメモリ上のバッファにエ ラーメッセージを送信し、指定された条件でフラッシュされるようにします。 +.. #. :ref:`memory-handler` instances send error messages to a buffer +.. in memory, which is flushed whenever specific criteria are met. + +11. :ref:`memory-handler` のインスタンスはメモリ上のバッファにエラーメッ セージを送信し、指定された条件でフラッシュされるようにします。 -.. #. :class:`handlers.HTTPHandler` instances send error messages to an HTTP server using -.. either ``GET`` or ``POST`` semantics. - -12. :class:`handlers.HTTPHandler` のインスタンスは ``GET`` か ``POST`` セマ ンティクスを使って HTTP +.. #. :ref:`http-handler` instances send error messages to an HTTP +.. server using either ``GET`` or ``POST`` semantics. + +12. :ref:`http-handler` のインスタンスは ``GET`` か ``POST`` セマンティクス を使って HTTP サーバにエラーメッセージを送信します。 -.. #. :class:`handlers.WatchedFileHandler` instances watch the file they are logging to. If -.. the file changes, it is closed and reopened using the file name. This handler -.. is only useful on Unix-like systems; Windows does not support the underlying -.. mechanism used. - -13. :class:`handlers.WatchedFileHandler` のインスタンスはログ記録を行うファ イルを監視します。 +.. #. :ref:`watched-file-handler` instances watch the file they are +.. logging to. If the file changes, it is closed and reopened using the file +.. name. This handler is only useful on Unix-like systems; Windows does not +.. support the underlying mechanism used. + +13. :ref:`watched-file-handler` のインスタンスはログ記録を行うファイルを監 視します。 もしファイルが変われば、一旦ファイルを閉じた後ファイル名を使って再度開 きます。 このハンドラは Unix ライクなシステムでだけ有用です。 Windows では元にしている機構がサポートされていません。 @@ -1031,6 +1046,9 @@ ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過できるよう になり、その他のメッセージは捨てられます。 +モジュールレベル関数 +-------------------- + .. In addition to the classes described above, there are a number of module- level .. functions. @@ -1222,10 +1240,18 @@ .. Provides an overriding level *lvl* for all loggers which takes precedence over .. the logger's own level. When the need arises to temporarily throttle logging - .. output down across the whole application, this function can be useful. + .. output down across the whole application, this function can be useful. Its + .. effect is to disable all logging calls of severity *lvl* and below, so that + .. if you call it with a value of INFO, then all INFO and DEBUG events would be + .. discarded, whereas those of severity WARNING and above would be processed + .. according to the logger's effective level. 全てのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。アプリケーション全体にわたって一時的にログ出力の 頻度を押し下げる必要が生じた場合にはこの関数が有効です。 + その効果は、深刻度 *lvl* 以下のすべてのログ呼び出しを無効にすることで す。 + そのためこの関数を値 INFO を伴って呼び出した場合、すべての INFO と DEBUG イベントは捨てられ、 + ロガーの実効レベルに従って優先度 WARNING 以上のものは処理されるでしょ う。 + .. function:: addLevelName(lvl, levelName) @@ -1274,20 +1300,19 @@ .. Does basic configuration for the logging system by creating a .. :class:`StreamHandler` with a default :class:`Formatter` and adding it to the - .. root logger. The function does nothing if any handlers have been defined for - .. the root logger. The functions :func:`debug`, :func:`info`, :func:`warning`, + .. root logger. The functions :func:`debug`, :func:`info`, :func:`warning`, .. :func:`error` and :func:`critical` will call :func:`basicConfig` automatically .. if no handlers are defined for the root logger. デフォルトの :class:`Formatter` を持つ :class:`StreamHandler` を生成してルートロガーに追加し、ログ記録システムの基本的な環境設定を行い ます。 - この関数はルートロガーに対しハンドラが一つも定義されていなければ何もしま せん。 関数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, およ び :func:`critical` は、ルートロガーにハンドラが定義されていない場合に自動的 に :func:`basicConfig` を呼び出します。 - .. This function does nothing if the root logger already has handlers configured. + .. This function does nothing if the root logger already has handlers + .. configured for it. この関数はルートロガーに設定されたハンドラがあれば何もしません。 @@ -1396,6 +1421,8 @@ いPython 1.5.2 と 2.1.x、2.2.xでも使用できます +.. _logger: + Logger オブジェクト ------------------- @@ -1410,11 +1437,11 @@ .. attribute:: Logger.propagate .. If this evaluates to false, logging messages are not passed by this logger or by - .. child loggers to higher level (ancestor) loggers. The constructor sets this - .. attribute to 1. + .. its child loggers to the handlers of higher level (ancestor) loggers. The + .. constructor sets this attribute to 1. この値の評価結果が偽になる場合、ログ記録しようとするメッセージはこのロ ガーに渡されず、 - また子ロガーから上位の (親の) ロガーに渡されません。 + また子ロガーから上位の (親の) ロガーのハンドラに渡されません。 コンストラクタはこの属性を 1 に設定します。 @@ -1680,11 +1707,11 @@ .. Handles a record by passing it to all handlers associated with this logger and .. its ancestors (until a false value of *propagate* is found). This method is used .. for unpickled records received from a socket, as well as those created locally. - .. Logger-level filtering is applied using :meth:`filter`. + .. Logger-level filtering is applied using :meth:`~Logger.filter`. レコードをこのロガーおよびその上位ロガーに (*propagate* の値が偽になるま で) さかのぼった関連付けられている全てのハンドラに渡して 処理します。このメソッドはソケットから受信した逆 pickle 化されたレコード に対してもレコードがローカルで生成された場合と同様に用いられます。 - :meth:`filter` によって、ロガーレベルでのフィルタが適用されます。 + :meth:`~Logger.filter` によって、ロガーレベルでのフィルタが適用されま す。 .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info [, func, extra]) @@ -1765,7 +1792,7 @@ logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(levelname)s %(message)s', - filename='/tmp/myapp.log', + filename='myapp.log', filemode='w') logging.debug('A debug message') logging.info('Some information') @@ -1773,10 +1800,10 @@ .. The :meth:`basicConfig` method is used to change the configuration defaults, -.. which results in output (written to ``/tmp/myapp.log``) which should look +.. which results in output (written to ``myapp.log``) which should look .. something like the following: -ここでは、 :meth:`basicConfig` メソッドを使って、以下のような出力例になる (そして ``/tmp/myapp.log`` に書き込まれる) +ここでは、 :meth:`basicConfig` メソッドを使って、以下のような出力例になる (そして ``myapp.log`` に書き込まれる) ように、デフォルト設定を変更しています。 @@ -2008,6 +2035,51 @@ この例題では、コンソールとファイルのハンドラだけを使っていますが、実際には 任意の数のハンドラや組み合わせを使えます。 +.. _logging-exceptions: + +ログ記録中に発生する例外 +------------------------ + +.. The logging package is designed to swallow exceptions which occur while logging +.. in production. This is so that errors which occur while handling logging events +.. - such as logging misconfiguration, network or other similar errors - do not +.. cause the application using logging to terminate prematurely. + +logging パッケージは、ログを生成している間に起こる例外を飲み込むように +設計されています。これは、ログ記録イベントを扱っている間に発生するエラー +(ログ記録の設定ミス、ネットワークまたは他の同様のエラー) によって +ログ記録を使用するアプリケーションが早期に終了しないようにするためです。 + + +.. :class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never +.. swallowed. Other exceptions which occur during the :meth:`emit` method of a +.. :class:`Handler` subclass are passed to its :meth:`handleError` method. + +:class:`SystemExit` と :class:`KeyboardInterrupt` 例外は決して飲み込まれま せん。 +:class:`Handler` サブクラスの :meth:`emit` メソッドの間に起こる他の例外は、 +:meth:`handleError` メソッドに渡されます。 + + +.. The default implementation of :meth:`handleError` in :class:`Handler` checks +.. to see if a module-level variable, :data:`raiseExceptions`, is set. If set, a +.. traceback is printed to :data:`sys.stderr`. If not set, the exception is swallowed. + +:class:`Handler` の :meth:`handleError` のデフォルト実装は、 +モジュールレベル変数 :data:`raiseExceptions` が設定されているかどうかチェッ クします。 +設定されているなら、トレースバックが :data:`sys.stderr` に出力されます。 +設定されていないなら、例外は飲み込まれます。 + + +.. **Note:** The default value of :data:`raiseExceptions` is ``True``. This is because +.. during development, you typically want to be notified of any exceptions that +.. occur. It's advised that you set :data:`raiseExceptions` to ``False`` for production +.. usage. + +**Note:** :data:`raiseExceptions` のデフォルト値は ``True`` です。 +これは、開発の間に起こるどんな例外についても通常は通知してほしいからです。 +実運用環境では :data:`raiseExceptions` を ``False`` に設定することをお勧め します。 + + .. _context-info: 文脈情報をログ記録出力に付加する @@ -2196,6 +2268,57 @@ :class:`LoggerAdapter` クラスは以前のバージョンにはありません。 +.. _multiple-processes: + +複数のプロセスからの単一ファイルへのログ記録 +-------------------------------------------- + +.. Although logging is thread-safe, and logging to a single file from multiple +.. threads in a single process *is* supported, logging to a single file from +.. *multiple processes* is *not* supported, because there is no standard way to +.. serialize access to a single file across multiple processes in Python. If you +.. need to log to a single file from multiple processes, the best way of doing +.. this is to have all the processes log to a :class:`SocketHandler`, and have a +.. separate process which implements a socket server which reads from the socket +.. and logs to file. (If you prefer, you can dedicate one thread in one of the +.. existing processes to perform this function.) The following section documents +.. this approach in more detail and includes a working socket receiver which can +.. be used as a starting point for you to adapt in your own applications. + +ログ記録はスレッドセーフであり、単一プロセスの複数のスレッドからの +単一ファイルへのログ記録はサポート *されています* が、 +*複数プロセス* からの単一ファイルへのログ記録はサポート *されません* 。 +なぜなら、複数のプロセスをまたいで単一のファイルへのアクセスを直列化する +標準の方法が Python には存在しないからです。 +複数のプロセスから単一ファイルへログ記録しなければならないなら、最も良い方 法は、 +すべてのプロセスが :class:`SocketHandler` に対してログ記録を行い、 +独立したプロセスとしてソケットサーバを動かすことです。 +ソケットサーバはソケットから読み取ってファイルにログを書き出します。 +(この機能を実行するために、既存のプロセスの1つのスレッドを割り当てることも できます) +以下のセクションでは、このアプローチをさらに詳細に文書化しています。 +動作するソケット受信プログラムが含まれているので、 +アプリケーションに組み込むための出発点として使用できるでしょう。 + + +.. If you are using a recent version of Python which includes the +.. :mod:`multiprocessing` module, you can write your own handler which uses the +.. :class:`Lock` class from this module to serialize access to the file from +.. your processes. The existing :class:`FileHandler` and subclasses do not make +.. use of :mod:`multiprocessing` at present, though they may do so in the future. +.. Note that at present, the :mod:`multiprocessing` module does not provide +.. working lock functionality on all platforms (see +.. http://bugs.python.org/issue3770). + +:mod:`multiprocessing` モジュールを含む最近のバージョンの Python を使用して いるなら、 +複数のプロセスからファイルへのアクセスを直列化するのにこのモジュール の :class:`Lock` クラスを使って +独自のハンドラを書くことができます。 +既存の :class:`FileHandler` とそのサブクラスは現在のとこ ろ :mod:`multiprocessing` を利用していませんが、 +将来は利用するようになるかもしれません。 +現在のところ :mod:`multiprocessing` モジュールが提供するロック機能は +すべてのプラットホームで動作するわけではないことに注意してください。 +(http://bugs.python.org/issue3770 参照) + + .. _network-logging: ログイベントをネットワーク越しに送受信する @@ -2346,6 +2469,113 @@ 69 myapp.area2 ERROR The five boxing wizards jump quickly. +.. Note that there are some security issues with pickle in some scenarios. If +.. these affect you, you can use an alternative serialization scheme by overriding +.. the :meth:`makePickle` method and implementing your alternative there, as +.. well as adapting the above script to use your alternative serialization. + +特定のシナリオでは pickle にはいくつかのセキュリティ問題があることに注意し てください。 +これが問題になる場合、 :meth:`makePickle` メソッドをオーバーライドして代替 手段を実装することで +異なるシリアライズ手法を使用できます。 +代替シリアライズ手法を使うように上記のスクリプトを修正することもできます。 + + +任意のオブジェクトをメッセージに使用する +---------------------------------------- + +.. In the preceding sections and examples, it has been assumed that the message +.. passed when logging the event is a string. However, this is not the only +.. possibility. You can pass an arbitrary object as a message, and its +.. :meth:`__str__` method will be called when the logging system needs to convert +.. it to a string representation. In fact, if you want to, you can avoid +.. computing a string representation altogether - for example, the +.. :class:`SocketHandler` emits an event by pickling it and sending it over the +.. wire. + +前のセクションとそこで挙げた例では、イベントを記録するときに渡されたメッ セージが +文字列であると仮定していました。しかし、これは唯一の可能性ではありません。 +メッセージとして任意のオブジェクトを渡すことができます。 +そして、ログ記録システムがそのオブジェクトを文字列表現に変換する必要がある とき、 +:meth:`__str__` メソッドを呼び出します。 +実際、そうしたければ、文字列表現を計算することを完全に避けることができます +-- 例えば、 :class:`SocketHandler` は、イベントを pickle してネットワーク +上で送信することでログ出力します。 + + +最適化 +------ + +.. Formatting of message arguments is deferred until it cannot be avoided. +.. However, computing the arguments passed to the logging method can also be +.. expensive, and you may want to avoid doing it if the logger will just throw +.. away your event. To decide what to do, you can call the :meth:`isEnabledFor` +.. method which takes a level argument and returns true if the event would be +.. created by the Logger for that level of call. You can write code like this: + +message 引数の整形は、それが避けられなくなるまで延期されます。 +しかしながら、 logging メソッドに渡す引数を計算するのもまた高価である場合が あります。 +ロガーが単にイベントを捨てるなら、それを避けたいと考えるかもしれません。 +どうするかを決定するために :meth:`isEnabledFor` メソッドを呼ぶことができま す。 +このメソッドは引数にレベルを取って、そのレベルの呼び出しに対して Logger が イベントを生成するなら true を返します。 +このようにコードを書くことができます: + + +:: + + if logger.isEnabledFor(logging.DEBUG): + logger.debug("Message with %s, %s", expensive_func1(), + expensive_func2()) + + +.. so that if the logger's threshold is set above ``DEBUG``, the calls to +.. :func:`expensive_func1` and :func:`expensive_func2` are never made. + +このようにすると、ロガーの閾値が ``DEBUG`` より上に設定されている場合、 +:func:`expensive_func1` と :func:`expensive_func2` の呼び出しは行われませ ん。 + + +.. There are other optimizations which can be made for specific applications which +.. need more precise control over what logging information is collected. Here's a +.. list of things you can do to avoid processing during logging which you don't +.. need: + +どんなログ情報が集められるかについてより正確なコントロールを必要とする、 +特定のアプリケーションのためにできる他の最適化があります。 +これは、ログ記録の間の不要な処理を避けるためにできることのリストです: + + +.. +-----------------------------------------------+----------------------------------------+ +.. | What you don't want to collect | How to avoid collecting it | +.. +===============================================+========================================+ +.. | Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. | +.. +-----------------------------------------------+----------------------------------------+ +.. | Threading information. | Set ``logging.logThreads`` to ``0``. | +.. +-----------------------------------------------+----------------------------------------+ +.. | Process information. | Set ``logging.logProcesses`` to ``0``. | +.. +-----------------------------------------------+----------------------------------------+ + ++-------------------------------------------+-------------------------------------------+ +| 不要な情報 | それを避ける方 法 | ++===========================================+===========================================+ +| 呼び出しがどこから行われたかに関する情報 | ``logging._srcfile`` を ``None`` にする | ++-------------------------------------------+-------------------------------------------+ +| スレッド情報 | ``logging.logThreads`` を ``0`` にする | ++-------------------------------------------+-------------------------------------------+ +| プロセス情報 | ``logging.logProcesses`` を ``0`` にする | ++-------------------------------------------+-------------------------------------------+ + + +.. Also note that the core logging module only includes the basic handlers. If +.. you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't +.. take up any memory. + +また、コア logging モジュールが基本的なハンドラだけを含んでいることに注意し てください。 +:mod:`logging.handlers` と :mod:`logging.config` をインポートしなければ、 +余分なメモリを消費することはありません。 + + +.. _handler: + Handler オブジェクト -------------------- @@ -2496,11 +2726,11 @@ 実装するためのものなので、 :exc:`NotImplementedError` を送出します。 +.. _stream-handler: + StreamHandler ^^^^^^^^^^^^^ -.. module:: logging.handlers - .. The :class:`StreamHandler` class, located in the core :mod:`logging` package, .. sends logging output to streams such as *sys.stdout*, *sys.stderr* or any .. file-like object (or, more precisely, any object which supports :meth:`write` @@ -2511,6 +2741,8 @@ および :meth:`flush` メソッドをサポートする何らかのオブジェクト) といったス トリームに送信します。 +.. currentmodule:: logging + .. class:: StreamHandler([strm]) .. Returns a new instance of the :class:`StreamHandler` class. If *strm* is @@ -2544,6 +2776,8 @@ :meth:`close` メソッドは :class:`Handler` から継承しているため何も行 わないので、 :meth:`flush` 呼び出しを明示的に行う必要があります。 +.. _file-handler: + FileHandler ^^^^^^^^^^^ @@ -2570,6 +2804,13 @@ デフォルトでは、ファイルは無制限に大きくなりつづけます。 + .. .. versionchanged:: 2.6 + .. *delay* was added. + + .. versionchanged:: 2.6 + *delay* が追加されました。 + + .. method:: close() .. Closes the file. @@ -2584,12 +2825,16 @@ *record* をファイルに出力します。 +.. _null-handler: + .. See :ref:`library-config` for more information on how to use .. :class:`NullHandler`. :class:`NullHandler` の使い方について詳しくは :ref:`library-config` を参照 して下さい。 +.. _watched-file-handler: + WatchedFileHandler ^^^^^^^^^^^^^^^^^^ @@ -2650,6 +2895,13 @@ デフォルトでは、ファイルは無制限に大きくなりつづけます。 + .. .. versionchanged:: 2.6 + .. *delay* was added. + + .. versionchanged:: 2.6 + *delay* が追加されました。 + + .. method:: emit(record) .. Outputs the record to the file, but first checks to see if the file has @@ -2661,6 +2913,8 @@ 既存のストリームはフラッシュして閉じられ、ファイルが再度開かれます。 +.. _rotating-file-handler: + RotatingFileHandler ^^^^^^^^^^^^^^^^^^^ @@ -2712,6 +2966,13 @@ などが存在する場合、それらのファイルはそれぞ れ :file:`app.log.2` 、 :file:`app.log.3` といった具合に名前変更されます。 + .. .. versionchanged:: 2.6 + .. *delay* was added. + + .. versionchanged:: 2.6 + *delay* が追加されました。 + + .. method:: doRollover() .. Does a rollover, as described above. @@ -2727,6 +2988,8 @@ 上述のようなロールオーバを行いながら、レコードをファイルに出力しま す。 +.. _timed-rotating-file-handler: + TimedRotatingFileHandler ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2794,13 +3057,25 @@ .. The extensions are date-and-time based, using the strftime format .. ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the .. rollover interval. - .. If the *utc* argument is true, times in UTC will be used; otherwise - .. local time is used. 古いログファイルを保存する際にロギングシステムは拡張子を付けます。 拡張子は日付と時間に基づいて、 strftime の ``%Y-%m-%d_%H-%M-%S`` 形式かその前の方の一部分を、 ロールオーバ間隔に依存した形で使います。 + + + .. When computing the next rollover time for the first time (when the handler + .. is created), the last modification time of an existing log file, or else + .. the current time, is used to compute when the next rotation will occur. + + 最初に次のロールオーバー時間を計算するとき (ハンドラが生成されるとき)、 + 次のローテーションがいつ起こるかを計算するために、 + 既存のログファイルの最終変更時刻または現在の時間が使用されます。 + + + .. If the *utc* argument is true, times in UTC will be used; otherwise + .. local time is used. + *utc* 引数が真の場合時刻は UTC になり、それ以外では現地時間が使われま す。 @@ -2814,6 +3089,19 @@ interval を変えると古いファイルが残ったままになることもあります。 + .. If *delay* is true, then file opening is deferred until the first call to + .. :meth:`emit`. + + *delay* が true なら、ファイルを開くのは :meth:`emit` の最初の呼び出しま で延期されます。 + + + .. .. versionchanged:: 2.6 + .. *delay* was added. + + .. versionchanged:: 2.6 + *delay* が追加されました。 + + .. method:: doRollover() .. Does a rollover, as described above. @@ -2828,6 +3116,8 @@ :meth:`setRollover` で解説した方法でロールオーバを行いながら、レコー ドをファイルに出力します。 +.. _socket-handler: + SocketHandler ^^^^^^^^^^^^^ @@ -2898,6 +3188,18 @@ レコードの属性辞書を pickle 化して、長さを指定プレフィクス付きのバイ ナリにし、ソケットを介して送信できるようにして返します。 + .. Note that pickles aren't completely secure. If you are concerned about + .. security, you may want to override this method to implement a more secure + .. mechanism. For example, you can sign pickles using HMAC and then verify + .. them on the receiving end, or alternatively you can disable unpickling of + .. global objects on the receiving end. + + pickle が完全に安全というわけではないことに注意してください。 + セキュリティに関して心配なら、より安全なメカニズムを実装するためにこ のメソッドをオーバーライドすると良いでしょう。 + 例えば、 HMAC を使って pickle に署名して、受け取る側ではそれを検証す ることができます。 + あるいはまた、受け取る側でグローバルなオブジェクトの unpickle を無効 にすることができます。 + + .. method:: send(packet) .. Send a pickled string *packet* to the socket. This function allows for @@ -2907,6 +3209,8 @@ この関数はネットワークが処理待ち状態の時に発生しうる部分的送信を行え ます。 +.. _datagram-handler: + DatagramHandler ^^^^^^^^^^^^^^^ @@ -2957,6 +3261,8 @@ pickle 化された文字列をソケットに送信します。 +.. _syslog-handler: + SysLogHandler ^^^^^^^^^^^^^ @@ -3014,6 +3320,104 @@ 文字列が渡された場合、内部の対応付け辞書が使われ、整数に変換されま す。 + .. The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and + .. mirror the values defined in the ``sys/syslog.h`` header file. + + シンボリックな ``LOG_`` 値は :class:`SysLogHandler` で定義されていま す。 + これは ``sys/syslog.h`` ヘッダーファイルで定義された値を反映していま す。 + + + + **Priorities** + + +--------------------------+---------------+ + | Name (string) | Symbolic value| + +==========================+===============+ + | ``alert`` | LOG_ALERT | + +--------------------------+---------------+ + | ``crit`` or ``critical`` | LOG_CRIT | + +--------------------------+---------------+ + | ``debug`` | LOG_DEBUG | + +--------------------------+---------------+ + | ``emerg`` or ``panic`` | LOG_EMERG | + +--------------------------+---------------+ + | ``err`` or ``error`` | LOG_ERR | + +--------------------------+---------------+ + | ``info`` | LOG_INFO | + +--------------------------+---------------+ + | ``notice`` | LOG_NOTICE | + +--------------------------+---------------+ + | ``warn`` or ``warning`` | LOG_WARNING | + +--------------------------+---------------+ + + + **Facilities** + + +---------------+---------------+ + | Name (string) | Symbolic value| + +===============+===============+ + | ``auth`` | LOG_AUTH | + +---------------+---------------+ + | ``authpriv`` | LOG_AUTHPRIV | + +---------------+---------------+ + | ``cron`` | LOG_CRON | + +---------------+---------------+ + | ``daemon`` | LOG_DAEMON | + +---------------+---------------+ + | ``ftp`` | LOG_FTP | + +---------------+---------------+ + | ``kern`` | LOG_KERN | + +---------------+---------------+ + | ``lpr`` | LOG_LPR | + +---------------+---------------+ + | ``mail`` | LOG_MAIL | + +---------------+---------------+ + | ``news`` | LOG_NEWS | + +---------------+---------------+ + | ``syslog`` | LOG_SYSLOG | + +---------------+---------------+ + | ``user`` | LOG_USER | + +---------------+---------------+ + | ``uucp`` | LOG_UUCP | + +---------------+---------------+ + | ``local0`` | LOG_LOCAL0 | + +---------------+---------------+ + | ``local1`` | LOG_LOCAL1 | + +---------------+---------------+ + | ``local2`` | LOG_LOCAL2 | + +---------------+---------------+ + | ``local3`` | LOG_LOCAL3 | + +---------------+---------------+ + | ``local4`` | LOG_LOCAL4 | + +---------------+---------------+ + | ``local5`` | LOG_LOCAL5 | + +---------------+---------------+ + | ``local6`` | LOG_LOCAL6 | + +---------------+---------------+ + | ``local7`` | LOG_LOCAL7 | + +---------------+---------------+ + + + .. method:: mapPriority(levelname) + + .. Maps a logging level name to a syslog priority name. + .. You may need to override this if you are using custom levels, or + .. if the default algorithm is not suitable for your needs. The + .. default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and + .. ``CRITICAL`` to the equivalent syslog names, and all other level + .. names to "warning". + + ログレベル名を syslog 優先度名に写像します。 + カスタムレベルを使用している場合や、 + デフォルトアルゴリズムがニーズに適していない場合には、 ***The diff for this file has been truncated for email.*** ============================================================================== Revision: e88a48ee19a2 Author: Nozomu Kaneko <nozom****@gmail*****> Date: Wed May 18 09:45:05 2011 Log: 改行位置の調整 http://code.google.com/p/python-doc-ja/source/detail?r=e88a48ee19a2 Modified: /library/logging.rst ======================================= --- /library/logging.rst Wed May 18 09:45:04 2011 +++ /library/logging.rst Wed May 18 09:45:05 2011 @@ -27,11 +27,11 @@ .. "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, .. and indicate the area of an application in which a logged message originates. -ログ記録は :class:`Logger` クラスのインスタンス (以降 :dfn:`ロガー ` :logger) -におけるメソッドを呼び出すことで行われます。各インスタンスは名前をもち、ド ット (ピリオド) を区切り文字として表記することで、 -概念的には名前空間中の階層構造に配置されることになります。例えば、"scan" と 名づけられたロガーは "scan.text"、"scan.html"、 -および "scan.pdf" ロガーの親ロガーとなります。ロガー名には何をつけてもよ く、ログに記録されるメッセージの生成元となるアプリケーション中の特定の -領域を示すことになります。 +ログ記録は :class:`Logger` クラスのインスタンス (以降 :dfn:`ロガー ` :logger) におけるメソッドを呼び出すことで行われます。 +各インスタンスは名前をもち、ドット (ピリオド) を区切り文字として表記するこ とで、 +概念的には名前空間中の階層構造に配置されることになります。 +例えば、"scan" と名づけられたロガーは "scan.text"、"scan.html"、およ び "scan.pdf" ロガーの親ロガーとなります。 +ロガー名には何をつけてもよく、ログに記録されるメッセージの生成元となるアプ リケーション中の特定の領域を示すことになります。 .. Logged messages also have levels of importance associated with them. The default @@ -43,13 +43,15 @@ .. constrained to use these levels: you can specify your own and use a more general .. :class:`Logger` method, :meth:`log`, which takes an explicit level argument. -ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連 付けられています。デフォルトのレベルとして提供されているものは -:const:`DEBUG` 、 :const:`INFO` 、 :const:`WARNING` 、 :const:`ERROR` およ び -:const:`CRITICAL` です。簡便性のために、 :class:`Logger` の適切なメソッド群 を呼ぶことで、ログに記録されたメッセージの -重要性を指定することができます。それらのメソッドとは、デフォルトのレベルを 反映する形で、 :meth:`debug` 、 :meth:`info` 、 -:meth:`warning` 、 :meth:`error` および :meth:`critical` となっています。 -これらのレベルを指定するにあたって制限はありません: :class:`Logger` のより 汎用的なメソッドで、明示的なレベル指定のための引数を持つ -:meth:`log` を使って自分自身でレベルを定義したり使用したりできます。 +ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連 付けられています。 +デフォルトのレベルとして提供されているもの は :const:`DEBUG` 、 :const:`INFO` 、 +:const:`WARNING` 、 :const:`ERROR` および :const:`CRITICAL` です。 +簡便性のために、 :class:`Logger` の適切なメソッド群を呼ぶことで、 +ログに記録されたメッセージの重要性を指定することができます。 +それらのメソッドとは、デフォルトのレベルを反映する形で、 +:meth:`debug` 、 :meth:`info` 、 :meth:`warning` 、 :meth:`error` およ び :meth:`critical` となっています。 +これらのレベルを指定するにあたって制限はありません: :class:`Logger` のより 汎用的なメソッドで、 +明示的なレベル指定のための引数を持つ :meth:`log` を使って自分自身でレベルを 定義したり使用したりできます。 チュートリアル @@ -72,7 +74,8 @@ .. built-in classes. もちろん、複数のメッセージをそれぞれ別々の冗舌性レベルで別々の出力先にログ 記録することができます。 -ログメッセージをファイルへ、HTTP GET/POST 先へ、SMTP 経由で電子メールへ、汎 用のソケットへ、もしくは OS ごとのログ記録機構へ書き込むことを全て標準モジ ュールでサポートします。 +ログメッセージをファイルへ、HTTP GET/POST 先へ、SMTP 経由で電子メールへ、汎 用のソケットへ、 +もしくは OS ごとのログ記録機構へ書き込むことを全て標準モジュールでサポート します。 これら組み込まれたクラスが特別な要求仕様に合わないような場合には、 独自のログ記録先クラスを作り出すこともできます。 @@ -124,12 +127,9 @@ .. :func:`basicConfig` with a value of ``'w'``. Rather than managing the file size .. yourself, though, it is simpler to use a :class:`RotatingFileHandler`: -スクリプトを繰り返し実行すると、 -さらなるログメッセージがファイルに追記されていきます。 -毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡す *filemode* 引 数を -``'w'`` にします。 -ファイルサイズを自分で管理する代わりに、 -もっと簡単に :class:`RotatingFileHandler` を使う手があります。 +スクリプトを繰り返し実行すると、さらなるログメッセージがファイルに追記され ていきます。 +毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡す *filemode* 引 数を ``'w'`` にします。 +ファイルサイズを自分で管理する代わりに、もっと簡単 に :class:`RotatingFileHandler` を使う手があります。 :: @@ -185,8 +185,8 @@ 最新のファイルはいつでも :file:`logging_rotatingfile_example.out` で、 サイズの上限に達するたびに拡張子 ``.1`` を付けた名前に改名されます。 -既にあるバックアップファイルはその拡張子がインクリメントされ -(``.1`` が ``.2`` になるなど)、 ``.6`` ファイルは消去されます。 +既にあるバックアップファイルはその拡張子がインクリメントされ (``.1`` が ``.2`` になるなど)、 +``.6`` ファイルは消去されます。 .. Obviously this example sets the log length much much too small as an extreme @@ -218,8 +218,7 @@ ロガー、ハンドラ、メッセージをログ記録する関数呼び出しは、どれもレベルを指 定します。 ログメッセージはハンドラとロガーがそのレベル以下を吐き出す設定の時だけ吐き 出されます。 たとえば、メッセージが ``CRITICAL`` でロガーが ``ERROR`` の設定ならばメッ セージは吐き出されます。 -一方、メッセージが ``WARNING`` でロガーが ``ERROR`` だけ生成するならば、 -メッセージは吐き出されません。 +一方、メッセージが ``WARNING`` でロガーが ``ERROR`` だけ生成するならば、メ ッセージは吐き出されません。 :: @@ -337,7 +336,8 @@ .. determining which log records to send on to a handler. Formatters specify the .. layout of the resultant log record. -logging ライブラリはモジュラー・アプローチを取ってコンポーネントのカテゴ リーをいくつかに分けています: ロガー、ハンドラ、フィルタ、フォーマッタ。 +logging ライブラリはモジュラー・アプローチを取ってコンポーネントのカテゴ リーをいくつかに分けています: +ロガー、ハンドラ、フィルタ、フォーマッタ。 ロガーはアプリケーションのコードが直接使うインターフェイスを外部に公開して います。 ハンドラはログ記録を適切な行き先に送ります。 フィルタはどのログ記録をハンドラにおくるかを決めるさらにきめ細かい機構を提 供します。 @@ -440,15 +440,12 @@ .. handlers for all the loggers an application uses. It is sufficient to .. configure handlers for a top-level logger and create child loggers as needed. -:func:`getLogger` は指定されればその特定の名前の、そうでなければ ``root`` -のロガーインスタンスへの参照を返します。 +:func:`getLogger` は指定されればその特定の名前の、そうでなければ ``root`` のロガーインスタンスへの参照を返します。 ロガーの名前はピリオド区切りの階層構造を表します。 -同じ名前で :func:`getLogger` を複数回呼び出した場合、 -同一のロガーオブジェクトへの参照が返されます。 +同じ名前で :func:`getLogger` を複数回呼び出した場合、同一のロガーオブジェク トへの参照が返されます。 階層リストを下ったロガーはリスト上位のロガーの子です。 たとえば、名前が ``foo`` であるロガーがあったとして、 -``foo.bar``, ``foo.bar.baz``, ``foo.bam`` といった名前のロガーは全て -``foo`` の子孫になります。 +``foo.bar``, ``foo.bar.baz``, ``foo.bam`` といった名前のロガーは全て ``foo`` の子孫になります。 子ロガーはメッセージを親ロガーのハンドラに伝えます。 このため、アプリケーションが使っている全てのロガーのためのハンドラを定義し て設定する必要はありません。 トップレベルのロガーのためのハンドラだけ設定しておいて必要に応じて子ロガー を作成すれば十分です。 @@ -466,8 +463,8 @@ .. requires three individual handlers where each handler is responsible for sending .. messages of a specific severity to a specific location. -:class:`Handler` オブジェクトは適切なログメッセージを(ログメッセージの深刻 さに基づいて) -ハンドラの指定された宛先に振り分けることに責任を持ちます。 +:class:`Handler` オブジェクトは適切なログメッセージを +(ログメッセージの深刻さに基づいて) ハンドラの指定された宛先に振り分けること に責任を持ちます。 ロガーオブジェクトには :func:`addHandler` メソッドで0個以上のハンドラを追加 することができます。 有り得るシナリオとして、あるアプリケーションが全てのログメッセージをログフ ァイルに、 error 以上の全てのログメッセージを標準出力に、 @@ -480,8 +477,7 @@ .. :class:`StreamHandler` and :class:`FileHandler` in its examples. このライブラリには多数のハンドラを用意してありますが、 -このチュートリアルでは -:class:`StreamHandler` と :class:`FileHandler` だけを例に取り上げます。 +このチュートリアルでは :class:`StreamHandler` と :class:`FileHandler` だけ を例に取り上げます。 .. There are very few methods in a handler for application developers to concern @@ -793,8 +789,8 @@ .. libraries, then the logger name specified can be "orgname.foo" rather than .. just "foo". -組織がいくつものライブラリを世に出しているならば、指定されるロガーの名前は 単なる "foo" -ではなく "orgname.foo" かもしれませんね。 +組織がいくつものライブラリを世に出しているならば、 +指定されるロガーの名前は単なる "foo" ではなく "orgname.foo" かもしれません ね。 ログレベル @@ -806,8 +802,10 @@ .. with the same numeric value, it overwrites the predefined value; the predefined .. name is lost. -ログレベルの数値は以下の表のように与えられています。これらは基本的に自分で レベルを定義したい人のためのもので、 -定義するレベルを既存のレベルの間に位置づけるために具体的な値が必要になりま す。もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われ ます。 +ログレベルの数値は以下の表のように与えられています。 +これらは基本的に自分でレベルを定義したい人のためのもので、 +定義するレベルを既存のレベルの間に位置づけるために具体的な値が必要になりま す。 +もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われま す。 .. +--------------+---------------+ @@ -852,16 +850,17 @@ レベルもロガーに関連付けることができ、デベロッパが設定することも、保存され たログ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らのレベルとメソ ッド呼び出しに関連付けられたレベルを比較します。 -ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際のログメッセー ジは生成されません。これはログ出力の冗長性を制御するための基本的なメカニズム です。 +ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際のログメッセー ジは生成されません。 +これはログ出力の冗長性を制御するための基本的なメカニズムです。 .. Logging messages are encoded as instances of the :class:`LogRecord` class. When .. a logger decides to actually log an event, a :class:`LogRecord` instance is .. created from the logging message. -ログ記録されるメッセージは :class:`LogRecord` クラスのインスタンスとして -コード化されます。ロガーがあるイベントを実際にログ出力すると決定した場合、 ログメッセージから :class:`LogRecord` -インスタンスが生成されます。 +ログ記録されるメッセージは :class:`LogRecord` クラスのインスタンスとして コード化されます。 +ロガーがあるイベントを実際にログ出力すると決定した場合、 +ログメッセージから :class:`LogRecord` インスタンスが生成されます。 .. Logging messages are subjected to a dispatch mechanism through the use of @@ -878,11 +877,11 @@ .. for a logger is set to a false value, at which point the passing to ancestor .. handlers stops). -ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通して、処理機構 (dispatch mechanism) -にかけられます。ハンドラは :class:`Handler` クラスのサブクラスのインスタン スで、ログ記録された (:class:`LogRecord` -形式の) メッセージが、そのメッセージの伝達対象となる相手 (エンドユーザ、サ ポートデスクのスタッフ、システム管理者、開発者) -に行き着くようにする役割を持ちます。ハンドラには特定の行き先に方向付けられ た :class:`LogRecord` インスタンスが渡されます。各ロガーは -ゼロ個、単一またはそれ以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソッド) で関連付けることができます。 +ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通して、処理機構 (dispatch mechanism) にかけられます。 +ハンドラは :class:`Handler` クラスのサブクラスのインスタンスで、 +ログ記録された (:class:`LogRecord` 形式の) メッセージが、そのメッセージの伝 達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開 発者) に行き着くようにする役割を持ちます。 +ハンドラには特定の行き先に方向付けられた :class:`LogRecord` インスタンスが 渡されます。 +各ロガーはゼロ個、単一またはそれ以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソッド) で関連付けることができます。 ロガーに直接関連付けられたハンドラに加えて、 *ロガーの上位にあるロガー全て に関連付けられたハンドラ* がメッセージを処理する際に呼び出されます。 (ただしロガーの *propagate* フラグが false 値にセットされている場合を除く。 その場合は、祖先ハンドラへの通過は止まります。) @@ -894,9 +893,12 @@ .. the message to its destination. Most user-defined subclasses of :class:`Handler` .. will need to override this :meth:`emit`. -ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。ハンド ラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 -ハンドラがあるイベントを実際に処理すると決定した場合、 :meth:`emit` メソッ ドが使われ、メッセージを発送先に送信します。ほとんどのユーザ定義の -:class:`Handler` のサブクラスで、この :meth:`emit` をオーバライドする必要が あるでしょう。 +ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。 +ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 +ハンドラがあるイベントを実際に処理すると決定した場合、 +:meth:`emit` メソッドが使われ、メッセージを発送先に送信します。 +ほとんどのユーザ定義の :class:`Handler` のサブクラスで、 +この :meth:`emit` をオーバライドする必要があるでしょう。 有用なハンドラ集 @@ -924,24 +926,23 @@ .. directly. Instead, use :ref:`rotating-file-handler` or .. :ref:`timed-rotating-file-handler`. -3. :class:`BaseRotatingHandler` はログファイルをある時点で交替させる\ - ハンドラの基底クラスです。直接インスタンス化するためのクラスではありませ ん。 - :ref:`rotating-file-handler` - や :ref:`timed-rotating-file-handler` を使うようにしてください。 +3. :class:`BaseRotatingHandler` はログファイルをある時点で交替させるハンド ラの基底クラスです。 + 直接インスタンス化するためのクラスではありません。 + :ref:`rotating-file-handler` や :ref:`timed-rotating-file-handler` を使 うようにしてください。 .. #. :ref:`rotating-file-handler` instances send error messages to disk .. files, with support for maximum log file sizes and log file rotation. -4. :ref:`rotating-file-handler` のインスタンスは最大ログファイルの\ - サイズ指定とログファイルの交替機能をサポートしながら、ディスク上のファイ ルにエラーメッセージを送信します。 +4. :ref:`rotating-file-handler` のインスタンスは最大ログファイルのサイズ指 定とログファイルの交替機能をサポートしながら、 + ディスク上のファイルにエラーメッセージを送信します。 .. #. :ref:`timed-rotating-file-handler` instances send error messages to .. disk files, rotating the log file at certain timed intervals. -5. :ref:`timed-rotating-file-handler` のインスタンスは、ログファイルを\ - 一定時間間隔ごとに交替しながら、ディスク上のファイルにエラーメッセージを 送信します。 +5. :ref:`timed-rotating-file-handler` のインスタンスは、ログファイルを一定 時間間隔ごとに交替しながら、 + ディスク上のファイルにエラーメッセージを送信します。 .. #. :class:`handlers.SocketHandler` instances send error messages to TCP/IP sockets. @@ -976,14 +977,15 @@ .. #. :ref:`memory-handler` instances send error messages to a buffer .. in memory, which is flushed whenever specific criteria are met. -11. :ref:`memory-handler` のインスタンスはメモリ上のバッファにエラーメッ セージを送信し、指定された条件でフラッシュされるようにします。 +11. :ref:`memory-handler` のインスタンスはメモリ上のバッファにエラーメッ セージを送信し、 + 指定された条件でフラッシュされるようにします。 .. #. :ref:`http-handler` instances send error messages to an HTTP .. server using either ``GET`` or ``POST`` semantics. -12. :ref:`http-handler` のインスタンスは ``GET`` か ``POST`` セマンティクス を使って HTTP - サーバにエラーメッセージを送信します。 +12. :ref:`http-handler` のインスタンスは ``GET`` か ``POST`` セマンティクス を使って + HTTP サーバにエラーメッセージを送信します。 .. #. :ref:`watched-file-handler` instances watch the file they are .. logging to. If the file changes, it is closed and reopened using the file @@ -1001,19 +1003,17 @@ .. defined in a sub- module, :mod:`logging.handlers`. (There is also another .. sub-module, :mod:`logging.config`, for configuration functionality.) -:class:`StreamHandler` および :class:`FileHandler` クラスは、中核となる\ -ログ化機構パッケージ内で定義されています。他のハンドラはサブモジュール、 -:mod:`logging.handlers` で定義されています。 -(サブモジュールにはもうひとつ :mod:`logging.config` があり、 -これは環境設定機能のためのものです。) +:class:`StreamHandler` および :class:`FileHandler` クラスは、中核となるログ 化機構パッケージ内で定義されています。 +他のハンドラはサブモジュール、 :mod:`logging.handlers` で定義されています。 +(サブモジュールにはもうひとつ :mod:`logging.config` があり、これは環境設定 機能のためのものです。) .. Logged messages are formatted for presentation through instances of the .. :class:`Formatter` class. They are initialized with a format string suitable for .. use with the % operator and a dictionary. -ログ記録されたメッセージは :class:`Formatter` クラスのインスタンスを介し、 表示用に書式化されます。これらのインスタンスは % -演算子と辞書を使うのに適した書式化文字列で初期化されます。 +ログ記録されたメッセージは :class:`Formatter` クラスのインスタンスを介し、 表示用に書式化されます。 +これらのインスタンスは % 演算子と辞書を使うのに適した書式化文字列で初期化さ れます。 .. For formatting multiple messages in a batch, instances of @@ -1021,8 +1021,10 @@ .. is applied to each message in the batch), there is provision for header and .. trailer format strings. -複数のメッセージの初期化をバッチ処理するため に、 :class:`BufferingFormatter` のインスタンスを使うことができます。書式化 文字列 -(バッチ処理で各メッセージに適用されます) に加えて、ヘッダ (header) およびト レイラ (trailer) 書式化文字列が用意されています。 +複数のメッセージの初期化をバッチ処理するために、 +:class:`BufferingFormatter` のインスタンスを使うことができます。 +書式化文字列 (バッチ処理で各メッセージに適用されます) に加えて、 +ヘッダ (header) およびトレイラ (trailer) 書式化文字列が用意されています。 .. When filtering based on logger level and/or handler level is not enough, @@ -1032,9 +1034,10 @@ .. their filters for permission. If any filter returns a false value, the message .. is not processed further. -ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリングが十分 でない場合、 :class:`Logger` および :class:`Handler` -インスタンスに :class:`Filter` のインスタンスを (:meth:`addFilter` メソッド を介して) -追加することができます。メッセージの処理を進める前に、ロガーとハンドラはと もに、全てのフィルタでメッセージの処理が許可されているか調べます。 +ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリングが十分 でない場合、 +:class:`Logger` および :class:`Handler` インスタンスに :class:`Filter` のイ ンスタンスを +(:meth:`addFilter` メソッドを介して) 追加することができます。 +メッセージの処理を進める前に、ロガーとハンドラはともに、全てのフィルタでメ ッセージの処理が許可されているか調べます。 いずれかのフィルタが偽となる値を返した場合、メッセージの処理は行われませ ん。 @@ -1042,8 +1045,9 @@ .. name. If this feature is used, messages sent to the named logger and its .. children are allowed through the filter, and all others dropped. -基本的な :class:`Filter` 機能では、指定されたロガー名でフィルタを行えるよう になっています。この機能が利用された場合、名前付けされた -ロガーとその下位にあるロガーに送られたメッセージがフィルタを通過できるよう になり、その他のメッセージは捨てられます。 +基本的な :class:`Filter` 機能では、指定されたロガー名でフィルタを行えるよう になっています。 +この機能が利用された場合、名前付けされたロガーとその下位にあるロガーに送ら れたメッセージが +フィルタを通過できるようになり、その他のメッセージは捨てられます。 モジュールレベル関数 @@ -1062,17 +1066,17 @@ .. typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*. .. Choice of these names is entirely up to the developer who is using logging. - 指定された名前のロガーを返します。名前が指定されていない場合、ロガー階層 のルート (root) にあるロガーを返します。 *name* - を指定する場合には、通常は *"a"*, *"a.b"*, あるいは *"a.b.c.d"* といっ たようなドット区切りの階層的な - 名前にします。名前の付け方はログ機能を使う開発者次第です。 + 指定された名前のロガーを返します。名前が指定されていない場合、ロガー階層 のルート (root) にあるロガーを返します。 + *name* を指定する場合には、通常は *"a"*, *"a.b"*, あるいは *"a.b.c.d"* といったようなドット区切りの階層的な名前にします。 + 名前の付け方はログ機能を使う開発者次第です。 .. All calls to this function with a given name return the same logger instance. .. This means that logger instances never need to be passed between different parts .. of an application. - 与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。従って、ロガーインスタンスをアプリケーションの各部 - でやりとりする必要はなくなります。 + 与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。 + 従って、ロガーインスタンスをアプリケーションの各部でやりとりする必要はな くなります。 .. function:: getLoggerClass() @@ -1082,9 +1086,10 @@ .. definition, to ensure that installing a customised :class:`Logger` class will .. not undo customisations already applied by other code. For example: - 標準の :class:`Logger` クラスか、最後に :func:`setLoggerClass` に渡した - クラスを返します。この関数は、新たに定義するクラス内で呼び出し、カスタマ イズした :class:`Logger` クラスのインストールを行うときに - 既に他のコードで適用したカスタマイズを取り消そうとしていないか確かめるの に使います。例えば以下のようにします: + 標準の :class:`Logger` クラスか、最後に :func:`setLoggerClass` に渡した クラスを返します。 + この関数は、新たに定義するクラス内で呼び出し、カスタマイズし た :class:`Logger` クラスのインストールを行うときに + 既に他のコードで適用したカスタマイズを取り消そうとしていないか確かめるの に使います。 + 例えば以下のようにします: :: @@ -1100,8 +1105,9 @@ .. *msg* using the string formatting operator. (Note that this means that you can .. use keywords in the format string, together with a single dictionary argument.) - レベル :const:`DEBUG` のメッセージをルートロガーで記録します。 *msg* は メッセージの書式化文字列で、 *args* は *msg* に - 文字列書式化演算子を使って取り込むための引数です。(これは、書式化文字列 でキーワードを使い引数に辞書を渡すことができる、ということを意味します。) + レベル :const:`DEBUG` のメッセージをルートロガーで記録します。 + *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算 子を使って取り込むための引数です。 + (これは、書式化文字列でキーワードを使い引数に辞書を渡すことができる、と いうことを意味します。) .. There are two keyword arguments in *kwargs* which are inspected: *exc_info* @@ -1110,9 +1116,10 @@ .. :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` .. is called to get the exception information. - キーワード引数 *kwargs* からは二つのキーワードが調べられます。一つめは *exc_info* で、この値の評価値が偽でない場合、 - 例外情報をログメッセージに追加します。(:func:`sys.exc_info` の返す形式 の) 例外情報を表すタプルが与えられていれば、それを - メッセージに使います。それ以外の場合には、 :func:`sys.exc_info` を呼び 出して例外情報を取得します。 + キーワード引数 *kwargs* からは二つのキーワードが調べられます。 + 一つめは *exc_info* で、この値の評価値が偽でない場合、例外情報をログメッ セージに追加します。 + (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれ ば、それをメッセージに使います。 + それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得し ます。 .. The other optional keyword argument is *extra* which can be used to pass a @@ -1121,9 +1128,10 @@ .. be used as you like. For example, they could be incorporated into logged .. messages. For example: - もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた LogRecoed の __dict__ - にユーザー定義属性を増やすのに使われる辞書を渡すのに用いられます。これら の属性は好きなように使えます。たとえば、ログメッセージの一部に - することもできます。以下の例を見てください。 + もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた + LogRecoed の __dict__ にユーザー定義属性を増やすのに使われる辞書を渡すの に用いられます。 + これらの属性は好きなように使えます。たとえば、ログメッセージの一部にする こともできます。 + 以下の例を見てください。 :: @@ -1148,9 +1156,8 @@ .. by the logging system. (See the :class:`Formatter` documentation for more .. information on which keys are used by the logging system.) - *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らない - ようにしなければなりません。(どのキーがロギングシステムで使われているか についての詳細は :class:`Formatter` - のドキュメントを参照してください。) + *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らないようにしなければなりません。 + (どのキーがロギングシステムで使われているかについての詳細 は :class:`Formatter` のドキュメントを参照してください。) .. If you choose to use these attributes in logged messages, you need to exercise @@ -1160,10 +1167,11 @@ .. logged because a string formatting exception will occur. So in this case, you .. always need to pass the *extra* dictionary with these keys. - これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。上 の例では、'clientip' と 'user' が LogRecord - の属性辞書に含まれていることを期待した書式化文字列で :class:`Formatter` はセットアップされてい - ます。これらの属性が欠けていると、書式化例外が発生してしまうためメッセー ジはログに残りません。したがってこの場合、常にこれらのキーがある *extra* - 辞書を渡す必要があります。 + これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。 + 上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれているこ とを期待した書式化文字列で + :class:`Formatter` はセットアップされています。 + これらの属性が欠けていると、書式化例外が発生してしまうためメッセージはロ グに残りません。 + したがってこの場合、常にこれらのキーがある *extra* 辞書を渡す必要があり ます。 .. While this might be annoying, this feature is intended for use in specialized @@ -1173,10 +1181,11 @@ .. above example). In such circumstances, it is likely that specialized .. :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. - このようなことは煩わしいかもしれませんが、この機能は限定された場面で使わ れるように意図しているものなのです。たとえば同じコードがいくつものコ - ンテキストで実行されるマルチスレッドのサーバで、興味のある条件が現れるの がそのコンテキストに依存している(上の例で言えば、リモートのクライアント IP - アドレスや認証されたユーザ名など)、というような場合です。そういった場面 では、それ用の :class:`Formatter` が特定の - :class:`Handler` と共に使われるというのはよくあることです。 + このようなことは煩わしいかもしれませんが、この機能は限定された場面で使わ れるように意図しているものなのです。 + たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドの サーバで、 + 興味のある条件が現れるのがそのコンテキストに依存している + (上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名 など)、というような場合です。 + そういった場面では、それ用の :class:`Formatter` が特定 の :class:`Handler` と共に使われるというのはよくあることです。 .. .. versionchanged:: 2.5 @@ -1191,7 +1200,8 @@ .. Logs a message with level :const:`INFO` on the root logger. The arguments are .. interpreted as for :func:`debug`. - レベル :const:`INFO` のメッセージをルートロガーで記録します。引数 は :func:`debug` と同じように解釈されます。 + レベル :const:`INFO` のメッセージをルートロガーで記録します。 + 引数は :func:`debug` と同じように解釈されます。 .. function:: warning(msg[, *args[, **kwargs]]) @@ -1199,7 +1209,8 @@ .. Logs a message with level :const:`WARNING` on the root logger. The arguments are .. interpreted as for :func:`debug`. - レベル :const:`WARNING` のメッセージをルートロガーで記録します。引数 は :func:`debug` と同じように解釈されます。 + レベル :const:`WARNING` のメッセージをルートロガーで記録します。 + 引数は :func:`debug` と同じように解釈されます。 .. function:: error(msg[, *args[, **kwargs]]) @@ -1207,7 +1218,8 @@ .. Logs a message with level :const:`ERROR` on the root logger. The arguments are .. interpreted as for :func:`debug`. - レベル :const:`ERROR` のメッセージをルートロガーで記録します。引数 は :func:`debug` と同じように解釈されます。 + レベル :const:`ERROR` のメッセージをルートロガーで記録します。 + 引数は :func:`debug` と同じように解釈されます。 .. function:: critical(msg[, *args[, **kwargs]]) @@ -1215,7 +1227,8 @@ .. Logs a message with level :const:`CRITICAL` on the root logger. The arguments .. are interpreted as for :func:`debug`. - レベル :const:`CRITICAL` のメッセージをルートロガーで記録します。引数 は :func:`debug` と同じように解釈されます。 + レベル :const:`CRITICAL` のメッセージをルートロガーで記録します。 + 引数は :func:`debug` と同じように解釈されます。 .. function:: exception(msg[, *args]) @@ -1224,8 +1237,10 @@ .. interpreted as for :func:`debug`. Exception info is added to the logging .. message. This function should only be called from an exception handler. - レベル :const:`ERROR` のメッセージをルートロガーで記録します。引数 は :func:`debug` と同じように解釈されます。 - 例外情報はログメッセージに追加されます。このメソッドは例外ハンドラからの み呼び出されます。 + レベル :const:`ERROR` のメッセージをルートロガーで記録します。 + 引数は :func:`debug` と同じように解釈されます。 + 例外情報はログメッセージに追加されます。 + このメソッドは例外ハンドラからのみ呼び出されます。 .. function:: log(level, msg[, *args[, **kwargs]]) @@ -1233,7 +1248,8 @@ .. Logs a message with level *level* on the root logger. The other arguments are .. interpreted as for :func:`debug`. - レベル :const:`level` のメッセージをルートロガーで記録します。その他の引 数は :func:`debug` と同じように解釈されます。 + レベル :const:`level` のメッセージをルートロガーで記録します。 + その他の引数は :func:`debug` と同じように解釈されます。 .. function:: disable(lvl) @@ -1246,8 +1262,8 @@ .. discarded, whereas those of severity WARNING and above would be processed .. according to the logger's effective level. - 全てのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。アプリケーション全体にわたって一時的にログ出力の - 頻度を押し下げる必要が生じた場合にはこの関数が有効です。 + 全てのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。 + アプリケーション全体にわたって一時的にログ出力の頻度を押し下げる必要が生 じた場合にはこの関数が有効です。 その効果は、深刻度 *lvl* 以下のすべてのログ呼び出しを無効にすることで す。 そのためこの関数を値 INFO を伴って呼び出した場合、すべての INFO と DEBUG イベントは捨てられ、 ロガーの実効レベルに従って優先度 WARNING 以上のものは処理されるでしょ う。 @@ -1263,9 +1279,12 @@ .. registered using this function, levels should be positive integers and they .. should increase in increasing order of severity. - 内部辞書内でレベル *lvl* をテキスト *levelName* に関連付けます。これは例 えば :class:`Formatter` - でメッセージを書式化する際のように、数字のレベルをテキスト表現に対応付け る際に用いられます。この関数は自作のレベルを定義するために使うこともできま す。 - 使われるレベル対する唯一の制限は、レベルは正の整数でなくてはならず、メッ セージの深刻さが上がるに従ってレベルの数も上がらなくてはならないということで す。 + 内部辞書内でレベル *lvl* をテキスト *levelName* に関連付けます。 + これは例えば :class:`Formatter` でメッセージを書式化する際のように、 + 数字のレベルをテキスト表現に対応付ける際に用いられます。 + この関数は自作のレベルを定義するために使うこともできます。 + 使われるレベル対する唯一の制限は、レベルは正の整数でなくてはならず、 + メッセージの深刻さが上がるに従ってレベルの数も上がらなくてはならないとい うことです。 .. function:: getLevelName(lvl) @@ -1281,7 +1300,8 @@ ログ記録レベル *lvl* のテキスト表現を返します。レベルが定義済みのレベ ル :const:`CRITICAL` 、 :const:`ERROR` 、 :const:`WARNING` 、 :const:`INFO` 、あるいは :const:`DEBUG` のいずれかで ある場合、対応する文字列が返されます。 :func:`addLevelName` を使ってレベルに名前を関連づけていた場合、 *lvl* に 関連付けられていた名前が返されます。 - 定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現 を返します。そうでない場合、文字列 "Level %s" % lvl を返します。 + 定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現 を返します。 + そうでない場合、文字列 "Level %s" % lvl を返します。 .. function:: makeLogRecord(attrdict) @@ -1304,11 +1324,10 @@ .. :func:`error` and :func:`critical` will call :func:`basicConfig` automatically .. if no handlers are defined for the root logger. - デフォルトの :class:`Formatter` を持つ :class:`StreamHandler` - を生成してルートロガーに追加し、ログ記録システムの基本的な環境設定を行い ます。 - 関数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, およ び :func:`critical` - は、ルートロガーにハンドラが定義されていない場合に自動的 に :func:`basicConfig` - を呼び出します。 + デフォルトの :class:`Formatter` を持つ :class:`StreamHandler` を生成して ルートロガーに追加し、 + ログ記録システムの基本的な環境設定を行います。 + 関数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, およ び :func:`critical` は、 + ルートロガーにハンドラが定義されていない場合に自動的 に :func:`basicConfig` を呼び出します。 .. This function does nothing if the root logger already has handlers @@ -1381,7 +1400,8 @@ .. closing all handlers. This should be called at application exit and no .. further use of the logging system should be made after this call. - ログ記録システムに対して、バッファのフラッシュを行い、全てのハンドラを閉 じることで順次シャットダウンを行うように告知します。 + ログ記録システムに対して、バッファのフラッシュを行い、 + 全てのハンドラを閉じることで順次シャットダウンを行うように告知します。 この関数はアプリケーションの exit 時に呼ばれるべきであり、 また呼びだし以降はそれ以上ログ記録システムを使ってはなりません。 @@ -1394,10 +1414,11 @@ .. function is typically called before any loggers are instantiated by applications .. which need to use custom logger behavior. - ログ記録システムに対して、ロガーをインスタンス化する際にクラス *klass* を使うように指示します。指定するクラスは引数として名前だけをとるようなメソッ ド - :meth:`__init__` を定義していなければならず、 :meth:`__init__` で は :meth:`Logger.__init__` - を呼び出さなければなりません。典型的な利用法として、この関数は自作のロ ガーを必要とするようなアプリケーションにおいて、他のロガーが - インスタンス化される前にインスタンス化されます。 + ログ記録システムに対して、ロガーをインスタンス化する際にクラス *klass* を使うように指示します。 + 指定するクラスは引数として名前だけをとるようなメソッド :meth:`__init__` を定義していなければならず、 + :meth:`__init__` では :meth:`Logger.__init__` を呼び出さなければなりませ ん。 + 典型的な利用法として、この関数は自作のロガーを必要とするようなアプリケー ションにおいて、 + 他のロガーがインスタンス化される前にインスタンス化されます。 .. seealso:: @@ -1417,8 +1438,8 @@ .. library. `この logging パッケージのオリジナル <http://www.red-dove.com/python_logging.html>`_ - オリジナルの :mod:`logging` パッケージ。このサイトにあるバージョンの パッケージは、標準で :mod:`logging` パッケージを含まな - いPython 1.5.2 と 2.1.x、2.2.xでも使用できます + オリジナルの :mod:`logging` パッケージ。このサイトにあるバージョンの パッケージは、 + 標準で :mod:`logging` パッケージを含まないPython 1.5.2 と 2.1.x、 2.2.xでも使用できます .. _logger: @@ -1430,8 +1451,8 @@ .. instantiated directly, but always through the module-level function .. ``logging.getLogger(name)``. -ロガーは以下の属性とメソッドを持ちます。ロガーを直接インスタンス化すること はできず、常にモジュール関数 -``logging.getLogger(name)`` を介してインスタンス化するので注意してくださ い。 +ロガーは以下の属性とメソッドを持ちます。ロガーを直接インスタンス化すること はできず、 +常にモジュール関数 ``logging.getLogger(name)`` を介してインスタンス化するの で注意してください。 .. attribute:: Logger.propagate @@ -1453,32 +1474,34 @@ .. the root logger, or delegation to the parent when the logger is a non-root .. logger). Note that the root logger is created with level :const:`WARNING`. - このロガーの閾値を *lvl* に設定します。ログ記録しようとするメッセージ で、 *lvl* よりも深刻でないものは無視されます。 - ロガーが生成された際、レベルは :const:`NOTSET` (これにより全てのメッセー ジについて、ロガーがルートロガーであれば処理される、 - そうでなくてロガーが非ルートロガーの場合には親ロガーに代行させる) に設定 されます。ルートロガーは :const:`WARNING` レベル - で生成されることに注意してください。 + このロガーの閾値を *lvl* に設定します。 + ログ記録しようとするメッセージで、 *lvl* よりも深刻でないものは無視され ます。 + ロガーが生成された際、レベルは :const:`NOTSET` (これにより全てのメッセー ジについて、 + ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロ ガーの場合には親ロガーに代行させる) に設定されます。 + ルートロガーは :const:`WARNING` レベルで生成されることに注意してくださ い。 .. The term "delegation to the parent" means that if a logger has a level of .. NOTSET, its chain of ancestor loggers is traversed until either an ancestor with .. a level other than NOTSET is found, or the root is reached. - 「親ロガーに代行させる」という用語の意味は、もしロガーのレベルが NOTEST ならば、祖先ロガーの系列の中を NOTEST 以外のレベルの祖先を見つけるかルー - トに到達するまで辿っていく、ということです。 + 「親ロガーに代行させる」という用語の意味は、もしロガーのレベルが NOTEST ならば、 + 祖先ロガーの系列の中を NOTEST 以外のレベルの祖先を見つけるかルートに到達 するまで辿っていく、ということです。 .. If an ancestor is found with a level other than NOTSET, then that ancestor's .. level is treated as the effective level of the logger where the ancestor search .. began, and is used to determine how a logging event is handled. - もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが祖先の 探索を開始したロガーの実効レベルとして取り扱われ、ログイベントがどの - ように処理されるかを決めるのに使われます。 + もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが祖先の 探索を開始したロガーの実効レベルとして取り扱われ、 + ログイベントがどのように処理されるかを決めるのに使われます。 .. If the root is reached, and it has a level of NOTSET, then all messages will be .. processed. Otherwise, the root's level will be used as the effective level. - ルートに到達した場合、ルートのレベルが NOTEST ならば全てのメッセージは処 理されます。そうでなければルートのレベルが実効レベルとして使われます。 + ルートに到達した場合、ルートのレベルが NOTEST ならば全てのメッセージは処 理されます。 + そうでなければルートのレベルが実効レベルとして使われます。 .. method:: Logger.isEnabledFor(lvl) @@ -1488,9 +1511,9 @@ .. ``logging.disable(lvl)`` and then the logger's effective level as determined .. by :meth:`getEffectiveLevel`. - 深刻さが *lvl* のメッセージが、このロガーで処理されることになっているか どうかを示します。このメソッドはまず、 - ``logging.disable(lvl)`` で設定されるモジュールレベルの深刻さレベルを調 べ、次にロガーの実効レベルを - :meth:`getEffectiveLevel` で調べます。 + 深刻さが *lvl* のメッセージが、このロガーで処理されることになっているか どうかを示します。 + このメソッドはまず、 ``logging.disable(lvl)`` で設定されるモジュールレベ ルの深刻さレベルを調べ、 + 次にロガーの実効レベルを :meth:`getEffectiveLevel` で調べます。 .. method:: Logger.getEffectiveLevel() @@ -1501,7 +1524,8 @@ .. :const:`NOTSET` is found, and that value is returned. このロガーの実効レベルを示します。 :const:`NOTSET` 以外の値 が :meth:`setLevel` で設定されていた場合、その値が返されます。 - そうでない場合、 :const:`NOTSET` 以外の値が見つかるまでロガーの階層を ルートロガーの方向に追跡します。見つかった場合、その値が返されます。 + そうでない場合、 :const:`NOTSET` 以外の値が見つかるまでロガーの階層を ルートロガーの方向に追跡します。 + 見つかった場合、その値が返されます。 .. method:: Logger.debug(msg[, *args[, **kwargs]]) @@ -1511,8 +1535,9 @@ .. *msg* using the string formatting operator. (Note that this means that you can .. use keywords in the format string, together with a single dictionary argument.) - レベル :const:`DEBUG` のメッセージをこのロガーで記録します。 *msg* はメ ッセージの書式化文字列で、 *args* は *msg* に - 文字列書式化演算子を使って取り込むための引数です。(これは、書式化文字列 でキーワードを使い引数に辞書を渡すことができる、ということを意味します。) + レベル :const:`DEBUG` のメッセージをこのロガーで記録します。 + *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算 子を使って取り込むための引数です。 + (これは、書式化文字列でキーワードを使い引数に辞書を渡すことができる、と いうことを意味します。) .. There are two keyword arguments in *kwargs* which are inspected: *exc_info* @@ -1521,9 +1546,10 @@ .. :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` .. is called to get the exception information. - キーワード引数 *kwargs* からは二つのキーワードが調べられます。一つめは *exc_info* で、この値の評価値が偽でない場合、 - 例外情報をログメッセージに追加します。(:func:`sys.exc_info` の返す形式 の) 例外情報を表すタプルが与えられていれば、それを - メッセージに使います。それ以外の場合には、 :func:`sys.exc_info` を呼び 出して例外情報を取得します。 + キーワード引数 *kwargs* からは二つのキーワードが調べられます。 + 一つめは *exc_info* で、この値の評価値が偽でない場合、例外情報をログメッ セージに追加します。 + (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれ ば、それをメッセージに使います。 + それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得し ます。 .. The other optional keyword argument is *extra* which can be used to pass a @@ -1532,16 +1558,17 @@ .. be used as you like. For example, they could be incorporated into logged .. messages. For example: - もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた LogRecoed の __dict__ - にユーザー定義属性を増やすのに使われる辞書を渡すのに用いられます。これら の属性は好きなように使えます。たとえば、ログメッセージの一部に - することもできます。以下の例を見てください。 + もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた + LogRecoed の __dict__ にユーザー定義属性を増やすのに使われる辞書を渡すの に用いられます。 + これらの属性は好きなように使えます。たとえば、ログメッセージの一部にする こともできます。 + 以下の例を見てください。 :: FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) - d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } + d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} logger = logging.getLogger("tcpserver") logger.warning("Protocol problem: %s", "connection reset", extra=d) @@ -1560,9 +1587,8 @@ .. by the logging system. (See the :class:`Formatter` documentation for more .. information on which keys are used by the logging system.) - *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らない - ようにしなければなりません。(どのキーがロギングシステムで使われているか についての詳細は :class:`Formatter` - のドキュメントを参照してください。) + *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らないようにしなければなりません。 + (どのキーがロギングシステムで使われているかについての詳細 は :class:`Formatter` のドキュメントを参照してください。) .. If you choose to use these attributes in logged messages, you need to exercise @@ -1572,10 +1598,11 @@ .. logged because a string formatting exception will occur. So in this case, you .. always need to pass the *extra* dictionary with these keys. - これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。上 の例では、'clientip' と 'user' が LogRecord - の属性辞書に含まれていることを期待した書式化文字列で :class:`Formatter` はセットアップされてい - ます。これらの属性が欠けていると、書式化例外が発生してしまうためメッセー ジはログに残りません。したがってこの場合、常にこれらのキーがある *extra* - 辞書を渡す必要があります。 + これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。 + 上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれているこ とを期待した書式化文字列で + :class:`Formatter` はセットアップされています。 + これらの属性が欠けていると、書式化例外が発生してしまうためメッセージはロ グに残りません。 + したがってこの場合、常にこれらのキーがある *extra* 辞書を渡す必要があり ます。 .. While this might be annoying, this feature is intended for use in specialized @@ -1585,10 +1612,11 @@ .. above example). In such circumstances, it is likely that specialized .. :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. - このようなことは煩わしいかもしれませんが、この機能は限定された場面で使わ れるように意図しているものなのです。たとえば同じコードがいくつものコ - ンテキストで実行されるマルチスレッドのサーバで、興味のある条件が現れるの がそのコンテキストに依存している(上の例で言えば、リモートのクライアント IP - アドレスや認証されたユーザ名など)、というような場合です。そういった場面 では、それ用の :class:`Formatter` が特定の - :class:`Handler` と共に使われるというのはよくあることです。 + このようなことは煩わしいかもしれませんが、この機能は限定された場面で使わ れるように意図しているものなのです。 + たとえば同じコードがいくつものコンテキストで実行されるマルチスレッドの サーバで、 + 興味のある条件が現れるのがそのコンテキストに依存している + (上の例で言えば、リモートのクライアント IP アドレスや認証されたユーザ名 など)、というような場合です。 + そういった場面では、それ用の :class:`Formatter` が特定 の :class:`Handler` と共に使われるというのはよくあることです。 .. .. versionchanged:: 2.5 @@ -1603,7 +1631,8 @@ .. Logs a message with level :const:`INFO` on this logger. The arguments are .. interpreted as for :meth:`debug`. - レベル :const:`INFO` のメッセージをこのロガーで記録します。引数 は :meth:`debug` と同じように解釈されます。 + レベル :const:`INFO` のメッセージをこのロガーで記録します。 + 引数は :meth:`debug` と同じように解釈されます。 .. method:: Logger.warning(msg[, *args[, **kwargs]]) @@ -1611,7 +1640,8 @@ .. Logs a message with level :const:`WARNING` on this logger. The arguments are .. interpreted as for :meth:`debug`. - レベル :const:`WARNING` のメッセージをこのロガーで記録します。引数 は :meth:`debug` と同じように解釈されます。 + レベル :const:`WARNING` のメッセージをこのロガーで記録します。 + 引数は :meth:`debug` と同じように解釈されます。 .. method:: Logger.error(msg[, *args[, **kwargs]]) @@ -1619,7 +1649,8 @@ .. Logs a message with level :const:`ERROR` on this logger. The arguments are .. interpreted as for :meth:`debug`. - レベル :const:`ERROR` のメッセージをこのロガーで記録します。引数 は :meth:`debug` と同じように解釈されます。 + レベル :const:`ERROR` のメッセージをこのロガーで記録します。 + 引数は :meth:`debug` と同じように解釈されます。 .. method:: Logger.critical(msg[, *args[, **kwargs]]) @@ -1627,7 +1658,8 @@ .. Logs a message with level :const:`CRITICAL` on this logger. The arguments are .. interpreted as for :meth:`debug`. - レベル :const:`CRITICAL` のメッセージをこのロガーで記録します。引数 は :meth:`debug` と同じように解釈されます。 + レベル :const:`CRITICAL` のメッセージをこのロガーで記録します。 + 引数は :meth:`debug` と同じように解釈されます。 .. method:: Logger.log(lvl, msg[, *args[, **kwargs]]) @@ -1635,7 +1667,8 @@ .. Logs a message with integer level *lvl* on this logger. The other arguments are .. interpreted as for :meth:`debug`. - 整数で表したレベル *lvl* のメッセージをこのロガーで記録します。その他の 引数は :meth:`debug` と同じように解釈されます。 + 整数で表したレベル *lvl* のメッセージをこのロガーで記録します。 + その他の引数は :meth:`debug` と同じように解釈されます。 .. method:: Logger.exception(msg[, *args]) @@ -1644,8 +1677,10 @@ .. interpreted as for :meth:`debug`. Exception info is added to the logging .. message. This method should only be called from an exception handler. - レベル :const:`ERROR` のメッセージをこのロガーで記録します。引数 は :meth:`debug` と同じように解釈されます。 - 例外情報はログメッセージに追加されます。このメソッドは例外ハンドラからの み呼び出されます。 + レベル :const:`ERROR` のメッセージをこのロガーで記録します。 + 引数は :meth:`debug` と同じように解釈されます。 + 例外情報はログメッセージに追加されます。 + このメソッドは例外ハンドラからのみ呼び出されます。 .. method:: Logger.addFilter(filt) @@ -1667,7 +1702,8 @@ .. Applies this logger's filters to the record and returns a true value if the .. record is to be processed. - このロガーのフィルタをレコード (record) に適用し、レコードがフィルタを透 過して処理されることになる場合には真を返します。 + このロガーのフィルタをレコード (record) に適用し、 + レコードがフィルタを透過して処理されることになる場合には真を返します。 .. method:: Logger.addHandler(hdlr) @@ -1709,8 +1745,10 @@ .. for unpickled records received from a socket, as well as those created locally. .. Logger-level filtering is applied using :meth:`~Logger.filter`. - レコードをこのロガーおよびその上位ロガーに (*propagate* の値が偽になるま で) さかのぼった関連付けられている全てのハンドラに渡して - 処理します。このメソッドはソケットから受信した逆 pickle 化されたレコード に対してもレコードがローカルで生成された場合と同様に用いられます。 + レコードをこのロガーおよびその上位ロガーに (*propagate* の値が偽になるま で) さかのぼった + 関連付けられている全てのハンドラに渡して処理します。 + このメソッドはソケットから受信した逆 pickle 化されたレコードに対しても + レコードがローカルで生成された場合と同様に用いられます。 :meth:`~Logger.filter` によって、ロガーレベルでのフィルタが適用されま す。 @@ -1719,7 +1757,8 @@ .. This is a factory method which can be overridden in subclasses to create .. specialized :class:`LogRecord` instances. - このメソッドは、特殊な :class:`LogRecord` インスタンスを生成するためにサ ブクラスでオーバライドできるファクトリメソッドです。 + このメソッドは、特殊な :class:`LogRecord` インスタンスを生成するために + サブクラスでオーバライドできるファクトリメソッドです。 .. .. versionchanged:: 2.5 @@ -1745,8 +1784,8 @@ .. can appear daunting. This section demonstrates that simple use of the logging .. package is possible. -:mod:`logging` パッケージには高い柔軟性があり、その設定にたじろぐこともある でしょう。そこでこの節では、 :mod:`logging` -パッケージを簡単に使う方法もあることを示します。 +:mod:`logging` パッケージには高い柔軟性があり、その設定にたじろぐこともある でしょう。 +そこでこの節では、 :mod:`logging` パッケージを簡単に使う方法もあることを示 します。 .. The simplest example shows logging to the console: @@ -1780,10 +1819,12 @@ .. the messages - ``sys.stderr``. The severity level, the message format and .. destination can be easily changed, as shown in the example below: -ここではロガーを特定しなかったので、システムはルートロガーを使っています。 デバッグメッセージや情報メッセージは表示されませんが、これはデフォルトの -ルートロガーが WARNING 以上の重要度を持つメッセージしか処理しないように設定 されているからです。 -メッセージの書式もデフォルトの設定に従っています。出力先は ``sys.stderr`` で、これもデフォルトの設定です。 -重要度レベルやメッセージの形式、ログの出力先は、以下の例のように簡単に変更 できます。 +ここではロガーを特定しなかったので、システムはルートロガーを使っています。 +デバッグメッセージや情報メッセージは表示されませんが、 +これはデフォルトのルートロガーが WARNING 以上の重要度を持つメッセージしか処 理しないように設定されているからです。 +メッセージの書式もデフォルトの設定に従っています。 +出力先は ``sys.stderr`` で、これもデフォルトの設定です。 +重要度レベルやメッセージの形式、ログの出力先は、以下の例のように簡単に変更 できます: :: @@ -1803,8 +1844,9 @@ .. which results in output (written to ``myapp.log``) which should look .. something like the following: -ここでは、 :meth:`basicConfig` メソッドを使って、以下のような出力例になる (そして ``myapp.log`` に書き込まれる) -ように、デフォルト設定を変更しています。 +ここでは、 :meth:`basicConfig` メソッドを使って、 +以下のような出力例になる (そして ``myapp.log`` に書き込まれる) ように、 +デフォルト設定を変更しています。 :: @@ -1818,8 +1860,8 @@ .. format of the messages was also changed, and output went to the specified file .. rather than the console. -今度は、重要度が DEBUG か、それ以上のメッセージが処理されました。メッセージ の形式も変更され、出力はコンソールではなく特定のファイル -に書き出されました。 +今度は、重要度が DEBUG か、それ以上のメッセージが処理されました。 +メッセージの形式も変更され、出力はコンソールではなく特定のファイルに書き出 されました。 .. Formatting uses standard Python string formatting - see section @@ -1827,9 +1869,9 @@ .. specifiers. For a complete list of specifiers, consult the :class:`Formatter` .. documentation. -出力の書式化には、通常の Python 文字列に対する初期化を使います - :ref:`string-formatting` -節を参照してください。書式化文字列は、以下の指定子 (specifier) を常にとりま す。指定子の完全なリストについては -:class:`Formatter` のドキュメントを参照してください。 +出力の書式化には、通常の Python 文字列に対する初期化を使います - :ref:`string-formatting` 節を参照してください。 +書式化文字列は、以下の指定子 (specifier) を常にとります。 +指定子の完全なリストについては :class:`Formatter` のドキュメントを参照して ください。 .. +-------------------+-----------------------------------------------+ @@ -1911,16 +1953,17 @@ .. *stream* and *filename* keyword arguments are passed, the *stream* argument is .. ignored. -コンソールやファイルではなく、別個に作成しておいたファイル類似オブジェクト にログを出力したい場合には、 :func:`basicConfig` に -*stream* キーワード引数で渡します。 *stream* と *filename* の両方の引数を 指定した場合、 *stream* -は無視されるので注意してください。 +コンソールやファイルではなく、別個に作成しておいたファイル類似オブジェクト にログを出力したい場合には、 +:func:`basicConfig` に *stream* キーワード引数で渡します。 +*stream* と *filename* の両方の引数を指定した場合、 *stream* は無視される ので注意してください。 .. Of course, you can put variable information in your output. To do this, simply .. have the message be a format string and pass in additional arguments containing .. the variable information, as in the following example: -状況に応じて変化する情報ももちろんログ出力できます。以下のように、単にメッ セージを書式化文字列にして、その後ろに可変情報の引数を渡すだけです。 +状況に応じて変化する情報ももちろんログ出力できます。 +以下のように、単にメッセージを書式化文字列にして、その後ろに可変情報の引数 を渡すだけです。 :: @@ -1956,9 +1999,11 @@ .. Let's also assume that the file should contain timestamps, but the console .. messages should not. Here's how you can achieve this: -コンソールとファイルに、別々のメッセージ書式で、別々の状況に応じたログ出力 を行わせたいとしましょう。例えば DEBUG よりも高いレベルの -メッセージはファイルに記録し、INFO 以上のレベルのメッセージはコンソールに出 力したいという場合です。また、ファイルにはタイムスタンプを -記録し、コンソールには出力しないとします。以下のようにすれば、こうした挙動 を実現できます。 +コンソールとファイルに、別々のメッセージ書式で、別々の状況に応じたログ出力 を行わせたいとしましょう。 +例えば DEBUG よりも高いレベルのメッセージはファイルに記録し、 +INFO 以上のレベルのメッセージはコンソールに出力したいという場合です。 +また、ファイルにはタイムスタンプを記録し、コンソールには出力しないとしま す。 +以下のようにすれば、こうした挙動を実現できます。 :: @@ -2032,7 +2077,8 @@ .. This example uses console and file handlers, but you can use any number and .. combination of handlers you choose. -この例題では、コンソールとファイルのハンドラだけを使っていますが、実際には 任意の数のハンドラや組み合わせを使えます。 +この例題では、コンソールとファイルのハンドラだけを使っていますが、 +実際には任意の数のハンドラや組み合わせを使えます。 .. _logging-exceptions: @@ -2100,8 +2146,7 @@ 時にはログ記録出力にログ関数の呼び出し時に渡されたパラメータに加えて文脈情 報を含めたいこともあるでしょう。 たとえば、ネットワークアプリケーションで、クライアント固有の情報 -(例: リモートクライアントの名前、IP アドレス) -もログ記録に残しておきたいと思ったとしましょう。 +(例: リモートクライアントの名前、IP アドレス) もログ記録に残しておきたいと 思ったとしましょう。 *extra* パラメータをこの目的に使うこともできますが、 いつでもこの方法で情報を渡すのが便利なやり方とも限りません。 また接続ごとに :class:`Logger` インスタンスを生成する誘惑に駆られるかもしれ ませんが、 @@ -2168,8 +2213,7 @@ そこではログ記録呼び出しのメッセージとキーワード引数が渡され、 加工された(はずの)それらの情報を配下のロガーへの呼び出しに渡し直します。 このメソッドのデフォルト実装ではメッセージは元のままですが、 -キーワード引数にはコンストラクタに渡された辞書風オブジェクトを値として -"extra" キーが挿入されます。 +キーワード引数にはコンストラクタに渡された辞書風オブジェクトを値とし て "extra" キーが挿入されます。 ***The diff for this file has been truncated for email.*** ============================================================================== Revision: 3110f66edd40 Author: Nozomu Kaneko <nozom****@gmail*****> Date: Thu May 19 14:12:34 2011 Log: 訳文の見直し http://code.google.com/p/python-doc-ja/source/detail?r=3110f66edd40 Modified: /library/logging.rst ======================================= --- /library/logging.rst Wed May 18 09:45:05 2011 +++ /library/logging.rst Thu May 19 14:12:34 2011 @@ -17,7 +17,7 @@ .. This module defines functions and classes which implement a flexible error .. logging system for applications. -このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logging) システムを実装するための関数やクラスを定義しています。 +このモジュールでは、アプリケーションのための柔軟なエラーログ記録 (logging) システムを実装するための関数やクラスが定義されています。 .. Logging is performed by calling methods on instances of the :class:`Logger` @@ -27,11 +27,11 @@ .. "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, .. and indicate the area of an application in which a logged message originates. -ログ記録は :class:`Logger` クラスのインスタンス (以降 :dfn:`ロガー ` :logger) におけるメソッドを呼び出すことで行われます。 +ログ記録は :class:`Logger` クラスのインスタンス (以降 :dfn:`ロガー ` :logger) のメソッドを呼び出すことで行われます。 各インスタンスは名前をもち、ドット (ピリオド) を区切り文字として表記するこ とで、 概念的には名前空間中の階層構造に配置されることになります。 -例えば、"scan" と名づけられたロガーは "scan.text"、"scan.html"、およ び "scan.pdf" ロガーの親ロガーとなります。 -ロガー名には何をつけてもよく、ログに記録されるメッセージの生成元となるアプ リケーション中の特定の領域を示すことになります。 +例えば、 "scan" と名づけられたロガー は "scan.text", "scan.html", "scan.pdf" ロガーの親ロガーとなります。 +ロガーにはどんな名前を付けてもよく、ロガー名はログに記録されるメッセージの 生成元となるアプリケーション中の特定の領域を示すことになります。 .. Logged messages also have levels of importance associated with them. The default @@ -44,13 +44,13 @@ .. :class:`Logger` method, :meth:`log`, which takes an explicit level argument. ログ記録されたメッセージにはまた、重要度レベル (level of importance) が関連 付けられています。 -デフォルトのレベルとして提供されているもの は :const:`DEBUG` 、 :const:`INFO` 、 -:const:`WARNING` 、 :const:`ERROR` および :const:`CRITICAL` です。 +デフォルトのレベルとして提供されているものは :const:`DEBUG`, :const:`INFO`, +:const:`WARNING`, :const:`ERROR`, :const:`CRITICAL` です。 簡便性のために、 :class:`Logger` の適切なメソッド群を呼ぶことで、 ログに記録されたメッセージの重要性を指定することができます。 -それらのメソッドとは、デフォルトのレベルを反映する形で、 -:meth:`debug` 、 :meth:`info` 、 :meth:`warning` 、 :meth:`error` およ び :meth:`critical` となっています。 -これらのレベルを指定するにあたって制限はありません: :class:`Logger` のより 汎用的なメソッドで、 +そのようなメソッド群としては、デフォルトのレベルを反映して、 +:meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:`critical` が あります。 +また、これらのレベルを使用することに制限されるわけではありませ ん: :class:`Logger` のより汎用的なメソッドで、 明示的なレベル指定のための引数を持つ :meth:`log` を使って自分自身でレベルを 定義したり使用したりできます。 @@ -61,8 +61,8 @@ .. is that all Python modules can participate in logging, so your application log .. can include messages from third-party modules. -標準ライブラリモジュールが提供するログ記録 API があることの御利益は、 -全ての Python モジュールがログ記録に参加できることであり、 +標準ライブラリモジュールとしてログ記録 API が提供される利点は、 +すべての Python モジュールがログ記録に参加できることであり、 これによってあなたが書くアプリケーションのログにサードパーティーのモジュー ルが出力するメッセージを含ませることができます。 @@ -73,11 +73,11 @@ .. own log destination class if you have special requirements not met by any of the .. built-in classes. -もちろん、複数のメッセージをそれぞれ別々の冗舌性レベルで別々の出力先にログ 記録することができます。 -ログメッセージをファイルへ、HTTP GET/POST 先へ、SMTP 経由で電子メールへ、汎 用のソケットへ、 -もしくは OS ごとのログ記録機構へ書き込むことを全て標準モジュールでサポート します。 -これら組み込まれたクラスが特別な要求仕様に合わないような場合には、 -独自のログ記録先クラスを作り出すこともできます。 +もちろん、複数のメッセージをそれぞれ別々の冗長性レベルで別々の出力先にログ 記録することができます。 +ログメッセージをファイルへ、 HTTP GET/POST 先へ、 SMTP 経由で電子メールへ、 汎用のソケットへ、 +もしくは OS 毎のログ記録機構へ書き込むことは、すべて標準モジュールでサポー トしています。 +これら組み込みのクラスが特別な要求仕様に合わないような場合には、 +独自のログ出力先クラスを作り出すこともできます。 単純な例 @@ -128,8 +128,8 @@ .. yourself, though, it is simpler to use a :class:`RotatingFileHandler`: スクリプトを繰り返し実行すると、さらなるログメッセージがファイルに追記され ていきます。 -毎回新しいファイルの方が良ければ、 :func:`basicConfig` に渡す *filemode* 引 数を ``'w'`` にします。 -ファイルサイズを自分で管理する代わりに、もっと簡単 に :class:`RotatingFileHandler` を使う手があります。 +毎回新しいファイルが作られた方が良ければ、 :func:`basicConfig` に渡す *filemode* 引数を ``'w'`` にします。 +ファイルサイズを自分で管理する代わりに、 :class:`RotatingFileHandler` を使 うともっと簡単になります。 :: @@ -164,7 +164,7 @@ .. The result should be 6 separate files, each with part of the log history for the .. application: -結果は分割された 6 ファイルになっているはずで、 +結果は分割された 6 つのファイルになっているはずで、 それぞれがアプリケーションのログ記録の一部になっています。 @@ -192,8 +192,8 @@ .. Obviously this example sets the log length much much too small as an extreme .. example. You would want to set *maxBytes* to an appropriate value. -見て判るようにここでは例示のためにファイルの大きさをとんでもなく小さな値に 設定しています。 -実際に使うときは *maxBytes* を適切な値に設定して下さい。 +明らかに、ここでは例示のためにファイルの大きさをとんでもなく小さな値に設定 しています。 +実際に使うときは *maxBytes* を適切な値に設定してください。 .. Another useful feature of the logging API is the ability to produce different @@ -202,9 +202,9 @@ .. messages are not written for your production system. The default levels are .. ``NOTSET``, ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and ``CRITICAL``. -ログ記録 API のもう一つの有用な仕組みが異なるメッセージを異なるログレベルで 生成する能力です。 +ログ記録 API のもう一つの便利な機能が、異なるメッセージを異なるログレベルで 生成する能力です。 これを使えば、たとえばコードの中にデバッグメッセージを埋め込みつつ、 -出荷段階でログ記録レベルを落としてこれが記録されないようにするといったこと ができます。 +出荷段階でログ記録レベルを落としてデバッグメッセージが記録されないようにす るといったことができます。 デフォルトで設定されているレベルは ``NOTSET``, ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL`` で す。 @@ -215,10 +215,11 @@ .. is set to ``ERROR``, the message is emitted. If a message is a ``WARNING``, and .. the logger is set to produce only ``ERROR``\s, the message is not emitted: -ロガー、ハンドラ、メッセージをログ記録する関数呼び出しは、どれもレベルを指 定します。 -ログメッセージはハンドラとロガーがそのレベル以下を吐き出す設定の時だけ吐き 出されます。 -たとえば、メッセージが ``CRITICAL`` でロガーが ``ERROR`` の設定ならばメッ セージは吐き出されます。 -一方、メッセージが ``WARNING`` でロガーが ``ERROR`` だけ生成するならば、メ ッセージは吐き出されません。 +ロガー、ハンドラ、ログメッセージ呼び出しは、どれもレベルを指定します。 +ログメッセージはハンドラとロガーがそのレベル以下を出力する設定の時だけ出力 されます。 +たとえば、メッセージが ``CRITICAL`` でロガーが ``ERROR`` の設定ならば、メッ セージは出力されます。 +一方、メッセージが ``WARNING`` でロガーが ``ERROR`` だけ生成するように設定 されているならば、 +メッセージは出力されません。 :: @@ -247,8 +248,8 @@ .. Run the script with an argument like 'debug' or 'warning' to see which messages .. show up at different levels: -スクリプトを 'debug' とか 'warning' といった引数で実行して、 -レベルの違いによってどのメッセージが現れるようになるか見てみましょう。 +スクリプトを 'debug' や 'warning' といった引数で実行して、 +レベルの違いによってどのメッセージが現れるか見てみましょう。 :: @@ -277,15 +278,15 @@ .. example of how to log from different modules so it is easy to trace the source .. of the message: -気付いたかもしれませんが、全てのログメッセージに ``root`` が埋め込まれてい ます。 -ログ記録モジュールは異なる名前のロガーの階層をサポートしているのです。 +すべてのログメッセージに ``root`` が埋め込まれていることに気付いたかもしれ ません。 +:mod:`logging` モジュールは異なる名前のロガーの階層をサポートしているので す。 ログメッセージがどこから発生しているかを教える簡単な方法は、 プログラムのモジュールごとに別々のロガーオブジェクトを利用することです。 それぞれの新しいロガーはその親の設定を「継承」していて、 あるロガーに送られたログメッセージはそのロガーの名前を含みます。 場合によっては、ロガーをそれぞれ異なるように設定して、 それぞれのモジュールからのメッセージを異なったやり方で扱うこともできます。 -では、単純な例でメッセージの出所が簡単に追跡できるように別々のモジュールか らログ記録を行う方法を見てみましょう。 +では、単純な例でメッセージの発信源が簡単に追跡できるように別々のモジュール からログ記録を行う方法を見てみましょう。 :: @@ -321,9 +322,9 @@ 他にもオプションはもっといろいろあります。 ログ記録方法の設定、たとえばログメッセージフォーマットを変えるオプション、 -メッセージを複数の送り先に配送するようなもの、 -ソケットインターフェイスを通して長く走り続けるアプリケーションの設定を途中 で変更するものなどです。 -全てのオプションはライブラリモジュールの文書の中でもっと細かく説明してあり ます。 +メッセージを複数の出力先に配送するようなもの、 +ソケットインターフェイスを通して長時間実行されるアプリケーションの設定を途 中で変更するものなどです。 +すべてのオプションはライブラリモジュールの文書の中でもっと細かく説明してあ ります。 ロガー @@ -336,11 +337,11 @@ .. determining which log records to send on to a handler. Formatters specify the .. layout of the resultant log record. -logging ライブラリはモジュラー・アプローチを取ってコンポーネントのカテゴ リーをいくつかに分けています: -ロガー、ハンドラ、フィルタ、フォーマッタ。 +logging ライブラリはモジュラー・アプローチを取っていて、 +コンポーネントのカテゴリーをいくつかに分けています: ロガー、ハンドラ、フィ ルタ、フォーマッタです。 ロガーはアプリケーションのコードが直接使うインターフェイスを外部に公開して います。 -ハンドラはログ記録を適切な行き先に送ります。 -フィルタはどのログ記録をハンドラにおくるかを決めるさらにきめ細かい機構を提 供します。 +ハンドラはログ記録を適切な出力先に送ります。 +フィルタはどのログ記録をハンドラに送るかを決めるさらにきめ細かい機構を提供 します。 フォーマッタは最終的なログ記録のレイアウトを指定します。 @@ -351,17 +352,17 @@ .. objects pass along relevant log messages to all interested log handlers. :class:`Logger` オブジェクトの仕事は大きく三つに分かれます。 -一つめは、アプリケーションが実行中にメッセージを記録できるように、 +一つ目は、アプリケーションが実行中にメッセージを記録できるように、 いくつかのメソッドをアプリケーションから呼べるようにしています。 -二つめに、ロガーオブジェクトはどのメッセージに対して作用するかを、 -深刻さ(デフォルトのフィルター機構)またはフィルターオブジェクトに基づいて決 定します。 -三つめに、ロガーオブジェクトはログハンドラがそれぞれ持っている興味に関連す るログメッセージを回送します。 +二つ目に、ロガーオブジェクトはどのメッセージに対して作用するかを、 +深刻度 (デフォルトのフィルタ機構) またはフィルタオブジェクトに基づいて決定 します。 +三つ目に、ロガーオブジェクトは関心を持っているすべてのログハンドラに関連す るログメッセージを回送します。 .. The most widely used methods on logger objects fall into two categories: .. configuration and message sending. -ロガーオブジェクトのとりわけ広く使われるメソッドは二つのカテゴリーに分類で きます: +とりわけ広く使われるロガーオブジェクトのメソッドは、二つのカテゴリーに分類 できます: 設定とメッセージ送信です。 @@ -371,23 +372,22 @@ .. the logger will handle only info, warning, error, and critical messages and .. will ignore debug messages. -* :meth:`Logger.setLevel` ロガーが扱うログメッセージの最も低い深刻さを指定 します。 - ここで組み込まれた深刻さは debug が一番低く、 critical が一番高くなりま す。 - たとえば、深刻さが info と設定されたロガーは info, warning, error, critical +* :meth:`Logger.setLevel` はロガーが扱うログメッセージの最も低い深刻度を指 定します。 + 組み込みの深刻度の中では debug が一番低く、 critical が一番高くなります。 + たとえば、深刻度が info と設定されたロガーは info, warning, error, critical のメッセージしか扱わず debug メッセージは無視します。 .. * :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter .. objects from the logger object. This tutorial does not address filters. -* :meth:`Logger.addFilter` と :meth:`Logger.removeFilter` - はロガーオブジェクトにフィルターを追加したり削除したりします。 - このチュートリアルではフィルターは説明しません。 +* :meth:`Logger.addFilter` と :meth:`Logger.removeFilter` はロガーオブジェ クトにフィルタを追加または削除します。 + このチュートリアルではフィルタは説明しません。 .. With the logger object configured, the following methods create log messages: -設定されたロガーオブジェクトを使えば、以下のメソッドはログメッセージを作り 出します: +設定されたロガーオブジェクトを使い、以下のメソッドはログメッセージを作り出 します: .. * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, @@ -401,10 +401,10 @@ .. determine whether to log exception information. * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, - :meth:`Logger.error`, :meth:`Logger.critical` は全て、 + :meth:`Logger.error`, :meth:`Logger.critical` はすべて、 メッセージとメソッド名に対応したレベルでログ記録を作り出します。 メッセージは実際にはフォーマット文字列であり、通常の文字列代入に使う - :const:`%s`, :const:`%d`, :const:`%f` などを含み得ます。 + :const:`%s`, :const:`%d`, :const:`%f` などを含むことができます。 残りの引数はメッセージの代入される位置に対応するオブジェクトのリストで す。 :const:`**kwargs` については、ログ記録メソッドが気にするキーワードは :const:`exc_info` だけで、例外の情報をログに記録するかを決定するのに使い ます。 @@ -415,17 +415,17 @@ .. stack trace along with it. Call this method only from an exception handler. * :meth:`Logger.exception` は :meth:`Logger.error` と似たログメッセージを作 成します。 - 違いは :meth:`Logger.exception` がスタックトレースを一緒に吐き出すことで す。 - 例外ハンドラでだけ使うようにして下さい。 + 違いは :meth:`Logger.exception` がスタックトレースを一緒にダンプすること です。 + 例外ハンドラでだけ使うようにしてください。 .. * :meth:`Logger.log` takes a log level as an explicit argument. This is a .. little more verbose for logging messages than using the log level convenience .. methods listed above, but this is how to log at custom log levels. -* :meth:`Logger.log` はログレベルを陽に引き渡される引数として取ります。 - これは上に挙げた便宜的なログレベルごとのメソッドを使うより少しコード量が 多くなりますが、 - 独自のログレベルを使うにはこのようにするものなのです。 +* :meth:`Logger.log` はログレベルを明示的な引数として受け取ります。 + これは上に挙げた便宜的なログレベル毎のメソッドを使うより少しコード量が多 くなりますが、 + 独自のログレベルを使うことができます。 .. :func:`getLogger` returns a reference to a logger instance with the specified @@ -440,14 +440,14 @@ .. handlers for all the loggers an application uses. It is sufficient to .. configure handlers for a top-level logger and create child loggers as needed. -:func:`getLogger` は指定されればその特定の名前の、そうでなければ ``root`` のロガーインスタンスへの参照を返します。 +:func:`getLogger` は、指定されればその特定の名前の、そうでなければ ``root`` のロガーインスタンスへの参照を返します。 ロガーの名前はピリオド区切りの階層構造を表します。 同じ名前で :func:`getLogger` を複数回呼び出した場合、同一のロガーオブジェク トへの参照が返されます。 階層リストを下ったロガーはリスト上位のロガーの子です。 たとえば、名前が ``foo`` であるロガーがあったとして、 -``foo.bar``, ``foo.bar.baz``, ``foo.bam`` といった名前のロガーは全て ``foo`` の子孫になります。 +``foo.bar``, ``foo.bar.baz``, ``foo.bam`` といった名前のロガーはすべて ``foo`` の子孫になります。 子ロガーはメッセージを親ロガーのハンドラに伝えます。 -このため、アプリケーションが使っている全てのロガーのためのハンドラを定義し て設定する必要はありません。 +このため、アプリケーションが使っているすべてのロガーのためのハンドラを定義 して設定する必要はありません。 トップレベルのロガーのためのハンドラだけ設定しておいて必要に応じて子ロガー を作成すれば十分です。 @@ -464,19 +464,19 @@ .. messages of a specific severity to a specific location. :class:`Handler` オブジェクトは適切なログメッセージを -(ログメッセージの深刻さに基づいて) ハンドラの指定された宛先に振り分けること に責任を持ちます。 -ロガーオブジェクトには :func:`addHandler` メソッドで0個以上のハンドラを追加 することができます。 -有り得るシナリオとして、あるアプリケーションが全てのログメッセージをログフ ァイルに、 -error 以上の全てのログメッセージを標準出力に、 -critical のメッセージは全てメールアドレスに、 -送りたいとします。 -この場合、三つの個別のハンドラがそれぞれの深刻さと宛先に応じて必要になりま す。 +(ログメッセージの深刻度に基づいて) ハンドラの指定された出力先に振り分けるこ とに責任を持ちます。 +ロガーオブジェクトには :func:`addHandler` メソッドで 0 個以上のハンドラを追 加することができます。 +例として、あるアプリケーションがすべてのログメッセージをログファイルに、 +error 以上のすべてのログメッセージを標準出力に、 +critical のメッセージはすべてメールアドレスに、 +それぞれ送りたいとします。 +この場合、 3 つの個別のハンドラがそれぞれの深刻度と宛先に応じて必要になりま す。 .. The standard library includes quite a few handler types; this tutorial uses only .. :class:`StreamHandler` and :class:`FileHandler` in its examples. -このライブラリには多数のハンドラを用意してありますが、 +このライブラリには多くのハンドラが用意されていますが、 このチュートリアルでは :class:`StreamHandler` と :class:`FileHandler` だけ を例に取り上げます。 @@ -486,8 +486,8 @@ .. custom handlers) are the following configuration methods: アプリケーション開発者にとってハンドラを扱う上で気にするべきメソッドは極々 限られています。 -備え付けのハンドラオブジェクトを使う (つまり自作ハンドラを作らない) -開発者に関係あるハンドラのメソッドは次の設定用のメソッドだけでしょう: +組み込みのハンドラオブジェクトを使う (つまり自作ハンドラを作らない) +開発者に関係あるハンドラのメソッドは、次の設定用のメソッドだけでしょう: .. * The :meth:`Handler.setLevel` method, just as in logger objects, specifies the @@ -497,10 +497,10 @@ .. set in each handler determines which messages that handler will send on. * :meth:`Handler.setLevel` メソッドは、ロガーオブジェクトの場合と同様に、 - 適切な宛先に振り分けられるべき最も低い深刻さを指定します。 - なぜ二つも :func:`setLevel` メソッドがあるのでしょう? - ロガーでセットされるレベルはメッセージのどの深刻さを付随するハンドラに渡 すか決めます。 - ハンドラでセットされるレベルはハンドラがどのメッセージを送るべきか決めま す。 + 適切な出力先に振り分けられるべき最も低い深刻度を指定します。 + なぜ 2 つも :func:`setLevel` メソッドがあるのでしょうか? + ロガーで設定されるレベルは、付随するハンドラにどんな深刻度のメッセージを 渡すか決めます。 + ハンドラで設定されるレベルは、ハンドラがどのメッセージを送るべきか決めま す。 .. * :func:`setFormatter` selects a Formatter object for this handler to use. @@ -511,7 +511,7 @@ .. * :func:`addFilter` and :func:`removeFilter` respectively configure and .. deconfigure filter objects on handlers. -* :func:`addFilter` および :func:`removeFilter` はそれぞれハンドラへのフィ ルタオブジェクトの設定、設定解除を行います。 +* :func:`addFilter` および :func:`removeFilter` はそれぞれハンドラへのフィ ルタオブジェクトの設定と解除を行います。 .. Application code should not directly instantiate and use instances of @@ -520,8 +520,8 @@ .. default behavior that child classes can use (or override). アプリケーションのコード中では :class:`Handler` のインスタンスを直接インス タンス化して使ってはなりません。 -そうではなく、 :class:`Handler` クラスは全てのハンドラが持つべきインターフ ェイスを定義し、 -子クラスが使える (もしくはオーバライドできる) いくつかのデフォルトの振る舞 いを確立します。 +代わりに、 :class:`Handler` クラスはすべてのハンドラが持つべきインターフェ イスを定義し、 +子クラスが使える (もしくはオーバライドできる) いくつかのデフォルトの振る舞 いを規定します。 フォーマッタ @@ -536,12 +536,12 @@ .. date format string, the default date format is: フォーマッタオブジェクトは最終的なログメッセージの順序、構造および内容を設 定します。 -基底クラスの :class:`logging.Handler` とは違って、 -アプリケーションのコードはフォーマッタクラスをインスタンス化して構いません が、 +基底クラスである :class:`logging.Handler` とは違って、 +アプリケーションのコードはフォーマッタクラスをインスタンス化しても構いませ ん。 特別な振る舞いをさせたいアプリケーションではフォーマッタのサブクラスを使う 可能性もあります。 コンストラクタは二つのオプション引数を取ります: メッセージのフォーマット文 字列と日付のフォーマット文字列です。 メッセージのフォーマット文字列がなければ、デフォルトではメッセージをそのま ま使います。 -日付のフォーマット文字列がなければデフォルトは +日付のフォーマット文字列がなければ、デフォルトは :: @@ -565,8 +565,8 @@ .. format, the severity of the message, and the contents of the message, in that .. order: -下のメッセージのフォーマット文字列は、人が読みやすい形式の時刻、メッセージ の深刻さ、 -メッセージの内容をその順番に出力します。 +次のメッセージフォーマット文字列は、人が読みやすい形式の時刻、メッセージの 深刻度、 +およびメッセージの内容を、順番に出力します。 :: @@ -583,10 +583,9 @@ .. code is an example of configuring a very simple logger, a console handler, and a .. simple formatter in a Python module: -プログラマはログ記録方法を設定できます。 -一つの方法は中心となるモジュールで上で述べたような設定メソッドで -(Python コードを使って) ロガー、ハンドラ、フォーマッタを自ら手を下して作成 することです。 -もう一つの方法は、ログ記録設定ファイルを作ることです。 +ログ記録方法を設定するには、上述のような設定メソッドで (Python コードを使っ て) +main モジュールの中でロガー、ハンドラ、フォーマッタを明示的に作成するか、 +ログ記録設定ファイルを作ります。 以下のコードは、例としてごく単純なロガー、コンソールハンドラ、そして単純な フォーマッタを Python モジュールの中で設定しています。 @@ -730,12 +729,12 @@ .. developer who is not aware of logging by the library. ログ記録を行うライブラリを開発するときには、いくつかその設定について考えて おくべきことがあります。 -ライブラリを使うアプリケーションが logging を使っていないときに、 -ライブラリが logging を呼び出すと "No handlers could be found for logger X.Y.Z" +ライブラリを使うアプリケーションがログ記録を使っていないときに、 +ライブラリがログ記録を呼び出すと "No handlers could be found for logger X.Y.Z" (「ロガー X.Y.Z に対するハンドラが見つかりません」) というメッセージがコンソールに一度だけ流れます。 -このメッセージは logging の設定ミスを捕らえるためのものですが、 -ライブラリが logging を使っているとアプリケーション開発者が知らない場合混乱 につながりかねません。 +このメッセージはログ記録の設定ミスを捕らえるためのものですが、 +ライブラリがログ記録を使っているとアプリケーション開発者が知らない場合混乱 につながりかねません。 .. In addition to documenting how a library uses logging, a good way to configure @@ -746,17 +745,17 @@ .. some handlers, and if levels are suitably configured then logging calls made .. in library code will send output to those handlers, as normal. -ライブラリが logging をどのように使っているかを文書に書くだけでなく、 +ライブラリがログ記録をどのように使っているのかを文書化しておくだけでなく、 意図しないメッセージを出さないために何もしないハンドラを加えるように設定し ておくのが良い方法です。 -こうすればメッセージが出力されるのを(ハンドラが見つかるので)防げるので、何 も出力しないようになります。 -ライブラリを使ってアプリケーションを書くユーザーが logging の設定をするなら ば、 +こうすれば (ハンドラが見つかるので) メッセージが出力されるのを防ぐことがで き、何も出力されないようになります。 +ライブラリを使ってアプリケーションを書くユーザーがログ記録の設定をするなら ば、 おそらくその設定で何かハンドラを追加することでしょう。 -その中でレベルが適切に設定されていればライブラリコード中の logging 呼び出し はそのハンドラに(普段通りに)出力を送ります。 +その中でレベルが適切に設定されていればライブラリコード中のログ記録呼び出し はそのハンドラに (普段通りに) 出力を送ります。 .. A do-nothing handler can be simply defined as follows: -何もしないハンドラは以下のよう簡単に定義できます。 +何もしないハンドラは以下のように簡単に定義できます。 :: @@ -773,7 +772,7 @@ .. done using loggers with names matching "foo.x.y", then the code: このハンドラのインスタンスがライブラリで使われるログ記録の名前空間の最上位 ロガーに追加されなければなりません。 -ライブラリ *foo* のログ記録が全て "foo.x.y" にマッチする名前のロガーで行わ れるならば、 +ライブラリ *foo* のログ記録がすべて "foo.x.y" にマッチする名前のロガーで行 われるならば、 次のコードで望むような効果を得られます。 @@ -790,7 +789,7 @@ .. just "foo". 組織がいくつものライブラリを世に出しているならば、 -指定されるロガーの名前は単なる "foo" ではなく "orgname.foo" かもしれません ね。 +指定されるロガーの名前は単なる "foo" ではなく "orgname.foo" かもしれませ ん。 ログレベル @@ -804,7 +803,7 @@ ログレベルの数値は以下の表のように与えられています。 これらは基本的に自分でレベルを定義したい人のためのもので、 -定義するレベルを既存のレベルの間に位置づけるために具体的な値が必要になりま す。 +定義するレベルを既存のレベルの間に位置づけるためには具体的な値が必要になり ます。 もし数値が他のレベルと同じだったら、既存の値は上書きされその名前は失われま す。 @@ -848,7 +847,7 @@ .. logging message is actually generated. This is the basic mechanism controlling .. the verbosity of logging output. -レベルもロガーに関連付けることができ、デベロッパが設定することも、保存され たログ記録設定を読み込む際に設定することもできます。 +レベルはロガーに関連付けることもでき、開発者が設定することも、保存されたロ グ記録設定を読み込む際に設定することもできます。 ロガーに対してログ記録メソッドが呼び出されると、ロガーは自らのレベルとメソ ッド呼び出しに関連付けられたレベルを比較します。 ロガーのレベルがメソッド呼び出しのレベルよりも高い場合、実際のログメッセー ジは生成されません。 これはログ出力の冗長性を制御するための基本的なメカニズムです。 @@ -858,7 +857,7 @@ .. a logger decides to actually log an event, a :class:`LogRecord` instance is .. created from the logging message. -ログ記録されるメッセージは :class:`LogRecord` クラスのインスタンスとして コード化されます。 +ログ記録されるメッセージは :class:`LogRecord` クラスのインスタンスとしてエ ンコードされます。 ロガーがあるイベントを実際にログ出力すると決定した場合、 ログメッセージから :class:`LogRecord` インスタンスが生成されます。 @@ -877,14 +876,16 @@ .. for a logger is set to a false value, at which point the passing to ancestor .. handlers stops). -ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通して、処理機構 (dispatch mechanism) にかけられます。 +ログ記録されるメッセージは、ハンドラ (:dfn:`handlers`) を通してディスパッチ 機構にかけられます。 ハンドラは :class:`Handler` クラスのサブクラスのインスタンスで、 -ログ記録された (:class:`LogRecord` 形式の) メッセージが、そのメッセージの伝 達対象となる相手 (エンドユーザ、サポートデスクのスタッフ、システム管理者、開 発者) に行き着くようにする役割を持ちます。 -ハンドラには特定の行き先に方向付けられた :class:`LogRecord` インスタンスが 渡されます。 -各ロガーはゼロ個、単一またはそれ以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソッド) で関連付けることができます。 -ロガーに直接関連付けられたハンドラに加えて、 *ロガーの上位にあるロガー全て に関連付けられたハンドラ* がメッセージを処理する際に呼び出されます。 -(ただしロガーの *propagate* フラグが false 値にセットされている場合を除く。 -その場合は、祖先ハンドラへの通過は止まります。) +ログ記録された (:class:`LogRecord` 形式の) メッセージが、 +そのメッセージの伝達対象となる相手 (エンドユーザ、サポートデスクのスタッ フ、 +システム管理者、開発者) に行き着くようにする役割を持ちます。 +ハンドラには特定の出力先を意図された :class:`LogRecord` インスタンスが渡さ れます。 +各ロガーは 0 個以上のハンドラを (:class:`Logger` の :meth:`addHandler` メソ ッド) で関連付けることができます。 +ロガーに直接関連付けられたハンドラに加えて、\ *ロガーの上位にあるロガーすべ てに関連付けられたハンドラ* がメッセージを処理する際に呼び出されます。 +(ただしロガーの *propagate* フラグが false 値にセットされている場合を除きま す。 +その場合は、祖先ハンドラへの伝搬はそこで止まります。) .. Just as for loggers, handlers can have levels associated with them. A handler's @@ -896,7 +897,7 @@ ロガーと同様に、ハンドラは関連付けられたレベルを持つことができます。 ハンドラのレベルはロガーのレベルと同じ方法で、フィルタとして働きます。 ハンドラがあるイベントを実際に処理すると決定した場合、 -:meth:`emit` メソッドが使われ、メッセージを発送先に送信します。 +:meth:`emit` メソッドが使われ、メッセージを出力先に送信します。 ほとんどのユーザ定義の :class:`Handler` のサブクラスで、 この :meth:`emit` をオーバライドする必要があるでしょう。 @@ -913,12 +914,12 @@ .. #. :ref:`stream-handler` instances send error messages to streams (file-like .. objects). -1. :ref:`stream-handler` のインスタンスはストリーム (ファイル様オブジェクト ) にエラーメッセージを送信します。 +1. :ref:`stream-handler` のインスタンスは、ストリーム (file-like オブジェク ト) にエラーメッセージを送信します。 .. #. :ref:`file-handler` instances send error messages to disk files. -2. :ref:`file-handler` のインスタンスはディスク上のファイルにエラーメッセー ジを送信します。 +2. :ref:`file-handler` のインスタンスは、ディスク上のファイルにエラーメッ セージを送信します。 .. #. :class:`BaseRotatingHandler` is the base class for handlers that @@ -926,7 +927,7 @@ .. directly. Instead, use :ref:`rotating-file-handler` or .. :ref:`timed-rotating-file-handler`. -3. :class:`BaseRotatingHandler` はログファイルをある時点で交替させるハンド ラの基底クラスです。 +3. :class:`BaseRotatingHandler` は、ログファイルをある時点でローテーション させるハンドラの基底クラスです。 直接インスタンス化するためのクラスではありません。 :ref:`rotating-file-handler` や :ref:`timed-rotating-file-handler` を使 うようにしてください。 @@ -934,66 +935,67 @@ .. #. :ref:`rotating-file-handler` instances send error messages to disk .. files, with support for maximum log file sizes and log file rotation. -4. :ref:`rotating-file-handler` のインスタンスは最大ログファイルのサイズ指 定とログファイルの交替機能をサポートしながら、 - ディスク上のファイルにエラーメッセージを送信します。 +4. :ref:`rotating-file-handler` のインスタンスは、ディスク上のファイルにエ ラーメッセージを送信します。 + 最大ログファイルのサイズ指定とログファイルのローテーション機能をサポート しています。 .. #. :ref:`timed-rotating-file-handler` instances send error messages to .. disk files, rotating the log file at certain timed intervals. -5. :ref:`timed-rotating-file-handler` のインスタンスは、ログファイルを一定 時間間隔ごとに交替しながら、 - ディスク上のファイルにエラーメッセージを送信します。 +5. :ref:`timed-rotating-file-handler` のインスタンスは、ディスク上のファイ ルにエラーメッセージを送信します。 + ログファイルを一定時間間隔ごとにローテーションします。 .. #. :class:`handlers.SocketHandler` instances send error messages to TCP/IP sockets. -6. :class:`handlers.SocketHandler` のインスタンスは TCP/IP ソケットにエラー メッセージを送信します。 +6. :class:`handlers.SocketHandler` のインスタンスは、 TCP/IP ソケットにエ ラーメッセージを送信します。 .. #. :ref:`datagram-handler` instances send error messages to UDP .. sockets. -7. :ref:`datagram-handler` のインスタンスは UDP ソケットにエラーメッセージ を送信します。 +7. :ref:`datagram-handler` のインスタンスは、 UDP ソケットにエラーメッセー ジを送信します。 .. #. :ref:`smtp-handler` instances send error messages to a designated .. email address. -8. :ref:`smtp-handler` のインスタンスは指定された電子メールアドレスにエラー メッセージを送信します。 +8. :ref:`smtp-handler` のインスタンスは、指定された電子メールアドレスにエ ラーメッセージを送信します。 .. #. :ref:`syslog-handler` instances send error messages to a Unix .. syslog daemon, possibly on a remote machine. -9. :ref:`syslog-handler` のインスタンスは遠隔を含むマシン上の syslog デーモ ンにエラーメッセージを送信します。 +9. :ref:`syslog-handler` のインスタンスは、 Unix syslog デーモンにエラーメ ッセージを送信します。 + 遠隔マシン上の syslog デーモンに送信することもできます。 .. #. :ref:`nt-eventlog-handler` instances send error messages to a .. Windows NT/2000/XP event log. -10. :ref:`nt-eventlog-handler` のインスタンスは Windows NT/2000/XP イベント ログにエラーメッセージを送信します。 +10. :ref:`nt-eventlog-handler` のインスタンスは、 Windows NT/2000/XP イベン トログにエラーメッセージを送信します。 .. #. :ref:`memory-handler` instances send error messages to a buffer .. in memory, which is flushed whenever specific criteria are met. -11. :ref:`memory-handler` のインスタンスはメモリ上のバッファにエラーメッ セージを送信し、 +11. :ref:`memory-handler` のインスタンスは、メモリ上のバッファにエラーメッ セージを送信し、 指定された条件でフラッシュされるようにします。 .. #. :ref:`http-handler` instances send error messages to an HTTP .. server using either ``GET`` or ``POST`` semantics. -12. :ref:`http-handler` のインスタンスは ``GET`` か ``POST`` セマンティクス を使って - HTTP サーバにエラーメッセージを送信します。 +12. :ref:`http-handler` のインスタンスは、 ``GET`` または ``POST`` セマンテ ィクスを使って + HTTP サーバにエラーメッセージを送信します。 .. #. :ref:`watched-file-handler` instances watch the file they are .. logging to. If the file changes, it is closed and reopened using the file .. name. This handler is only useful on Unix-like systems; Windows does not .. support the underlying mechanism used. -13. :ref:`watched-file-handler` のインスタンスはログ記録を行うファイルを監 視します。 - もしファイルが変われば、一旦ファイルを閉じた後ファイル名を使って再度開 きます。 +13. :ref:`watched-file-handler` のインスタンスは、ログ記録を行うファイルを 監視します。 + もしファイルが変更されれば、一旦ファイルを閉じた後ファイル名を使って再 度開きます。 このハンドラは Unix ライクなシステムでだけ有用です。 Windows では元にしている機構がサポートされていません。 @@ -1003,8 +1005,8 @@ .. defined in a sub- module, :mod:`logging.handlers`. (There is also another .. sub-module, :mod:`logging.config`, for configuration functionality.) -:class:`StreamHandler` および :class:`FileHandler` クラスは、中核となるログ 化機構パッケージ内で定義されています。 -他のハンドラはサブモジュール、 :mod:`logging.handlers` で定義されています。 +:class:`StreamHandler` および :class:`FileHandler` クラスは、コア logging パッケージ内で定義されています。 +他のハンドラはサブモジュール :mod:`logging.handlers` で定義されています。 (サブモジュールにはもうひとつ :mod:`logging.config` があり、これは環境設定 機能のためのものです。) @@ -1035,10 +1037,10 @@ .. is not processed further. ロガーレベル、ハンドラレベルの両方または片方に基づいたフィルタリングが十分 でない場合、 -:class:`Logger` および :class:`Handler` インスタンスに :class:`Filter` のイ ンスタンスを -(:meth:`addFilter` メソッドを介して) 追加することができます。 -メッセージの処理を進める前に、ロガーとハンドラはともに、全てのフィルタでメ ッセージの処理が許可されているか調べます。 -いずれかのフィルタが偽となる値を返した場合、メッセージの処理は行われませ ん。 +(:meth:`addFilter` メソッドを介して) :class:`Logger` およ び :class:`Handler` インスタンスに +:class:`Filter` のインスタンスを追加することができます。 +メッセージの処理を進める前に、ロガーとハンドラはともに、すべてのフィルタで メッセージの処理が許可されているか調べます。 +いずれかのフィルタが false 値を返した場合、メッセージの処理は行われません。 .. The basic :class:`Filter` functionality allows filtering by specific logger @@ -1067,7 +1069,7 @@ .. Choice of these names is entirely up to the developer who is using logging. 指定された名前のロガーを返します。名前が指定されていない場合、ロガー階層 のルート (root) にあるロガーを返します。 - *name* を指定する場合には、通常は *"a"*, *"a.b"*, あるいは *"a.b.c.d"* といったようなドット区切りの階層的な名前にします。 + *name* を指定する場合には、通常は *"a"*, *"a.b"*, *"a.b.c.d"* といったド ット区切りの階層的な名前にします。 名前の付け方はログ機能を使う開発者次第です。 @@ -1076,7 +1078,7 @@ .. of an application. 与えられた名前に対して、この関数はどの呼び出しでも同じロガーインスタンス を返します。 - 従って、ロガーインスタンスをアプリケーションの各部でやりとりする必要はな くなります。 + したがって、ロガーインスタンスをアプリケーションの各部でやりとりする必要 はありません。 .. function:: getLoggerClass() @@ -1087,8 +1089,8 @@ .. not undo customisations already applied by other code. For example: 標準の :class:`Logger` クラスか、最後に :func:`setLoggerClass` に渡した クラスを返します。 - この関数は、新たに定義するクラス内で呼び出し、カスタマイズし た :class:`Logger` クラスのインストールを行うときに - 既に他のコードで適用したカスタマイズを取り消そうとしていないか確かめるの に使います。 + この関数は、新たなクラス定義の中で呼び出して、カスタマイズし た :class:`Logger` クラスのインストールが + 既に他のコードで適用したカスタマイズを取り消さないことを保証するために使 われることがあります。 例えば以下のようにします: @@ -1107,7 +1109,7 @@ レベル :const:`DEBUG` のメッセージをルートロガーで記録します。 *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算 子を使って取り込むための引数です。 - (これは、書式化文字列でキーワードを使い引数に辞書を渡すことができる、と いうことを意味します。) + (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡す ことができる、ということを意味します。) .. There are two keyword arguments in *kwargs* which are inspected: *exc_info* @@ -1116,10 +1118,10 @@ .. :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` .. is called to get the exception information. - キーワード引数 *kwargs* からは二つのキーワードが調べられます。 - 一つめは *exc_info* で、この値の評価値が偽でない場合、例外情報をログメッ セージに追加します。 + キーワード引数 *kwargs* からは 2 つのキーワードが調べられます。 + 一つ目は *exc_info* で、この値の評価値が false でない場合、例外情報をロ グメッセージに追加します。 (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれ ば、それをメッセージに使います。 - それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得し ます。 + それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得しま す。 .. The other optional keyword argument is *extra* which can be used to pass a @@ -1128,8 +1130,8 @@ .. be used as you like. For example, they could be incorporated into logged .. messages. For example: - もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた - LogRecoed の __dict__ にユーザー定義属性を増やすのに使われる辞書を渡すの に用いられます。 + もう一つのキーワード引数は *extra* で、当該ログイベント用に作られる + LogRecoed の __dict__ にユーザー定義属性を加えるのに使われる辞書を渡すた めに用いられます。 これらの属性は好きなように使えます。たとえば、ログメッセージの一部にする こともできます。 以下の例を見てください。 @@ -1156,7 +1158,7 @@ .. by the logging system. (See the :class:`Formatter` documentation for more .. information on which keys are used by the logging system.) - *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らないようにしなければなりません。 + *extra* で渡される辞書のキーはロギングシステムで使われているものと衝突し ないようにしなければなりません。 (どのキーがロギングシステムで使われているかについての詳細 は :class:`Formatter` のドキュメントを参照してください。) @@ -1168,10 +1170,10 @@ .. always need to pass the *extra* dictionary with these keys. これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。 - 上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれているこ とを期待した書式化文字列で - :class:`Formatter` はセットアップされています。 - これらの属性が欠けていると、書式化例外が発生してしまうためメッセージはロ グに残りません。 - したがってこの場合、常にこれらのキーがある *extra* 辞書を渡す必要があり ます。 + 上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含まれている ことを期待した書式化文字列で + :class:`Formatter` がセットアップされています。 + もしこれらが欠けていると、書式化例外が発生してしまうためメッセージはログ に残りません。 + したがってこの場合、常にこれらのキーを含む *extra* 辞書を渡す必要があり ます。 .. While this might be annoying, this feature is intended for use in specialized @@ -1192,7 +1194,7 @@ .. *extra* was added. .. versionchanged:: 2.5 - *extra* が追加されました. + *extra* が追加されました。 .. function:: info(msg[, *args[, **kwargs]]) @@ -1239,7 +1241,7 @@ レベル :const:`ERROR` のメッセージをルートロガーで記録します。 引数は :func:`debug` と同じように解釈されます。 - 例外情報はログメッセージに追加されます。 + 例外情報がログメッセージに追加されます。 このメソッドは例外ハンドラからのみ呼び出されます。 @@ -1262,8 +1264,8 @@ .. discarded, whereas those of severity WARNING and above would be processed .. according to the logger's effective level. - 全てのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。 - アプリケーション全体にわたって一時的にログ出力の頻度を押し下げる必要が生 じた場合にはこの関数が有効です。 + すべてのロガーに対して、ロガー自体のレベルに優先するような上書きレベル *lvl* を与えます。 + アプリケーション全体にわたって一時的にログ出力を抑制する必要が生じた場合 にはこの関数が有効です。 その効果は、深刻度 *lvl* 以下のすべてのログ呼び出しを無効にすることで す。 そのためこの関数を値 INFO を伴って呼び出した場合、すべての INFO と DEBUG イベントは捨てられ、 ロガーの実効レベルに従って優先度 WARNING 以上のものは処理されるでしょ う。 @@ -1279,12 +1281,12 @@ .. registered using this function, levels should be positive integers and they .. should increase in increasing order of severity. - 内部辞書内でレベル *lvl* をテキスト *levelName* に関連付けます。 + 内部的な辞書の中でレベル *lvl* をテキスト *levelName* に関連付けます。 これは例えば :class:`Formatter` でメッセージを書式化する際のように、 数字のレベルをテキスト表現に対応付ける際に用いられます。 この関数は自作のレベルを定義するために使うこともできます。 - 使われるレベル対する唯一の制限は、レベルは正の整数でなくてはならず、 - メッセージの深刻さが上がるに従ってレベルの数も上がらなくてはならないとい うことです。 + 使われるレベルに対する唯一の制限は、レベルは正の整数でなくてはならず、 + メッセージの深刻度が上がるに従ってレベルの数も上がらなくてはならないとい うことです。 .. function:: getLevelName(lvl) @@ -1297,9 +1299,9 @@ .. of the defined levels is passed in, the corresponding string representation is .. returned. Otherwise, the string "Level %s" % lvl is returned. - ログ記録レベル *lvl* のテキスト表現を返します。レベルが定義済みのレベ ル :const:`CRITICAL` 、 :const:`ERROR` 、 - :const:`WARNING` 、 :const:`INFO` 、あるいは :const:`DEBUG` のいずれかで ある場合、対応する文字列が返されます。 - :func:`addLevelName` を使ってレベルに名前を関連づけていた場合、 *lvl* に 関連付けられていた名前が返されます。 + ログ記録レベル *lvl* のテキスト表現を返します。レベルが定義済みのレベ ル :const:`CRITICAL`, :const:`ERROR`, + :const:`WARNING`, :const:`INFO`, :const:`DEBUG` のいずれかである場合、対 応する文字列が返されます。 + :func:`addLevelName` を使ってレベルに名前を関連付けていた場合、 *lvl* に 関連付けられた名前が返されます。 定義済みのレベルに対応する数値を指定した場合、レベルに対応した文字列表現 を返します。 そうでない場合、文字列 "Level %s" % lvl を返します。 @@ -1325,8 +1327,8 @@ .. if no handlers are defined for the root logger. デフォルトの :class:`Formatter` を持つ :class:`StreamHandler` を生成して ルートロガーに追加し、 - ログ記録システムの基本的な環境設定を行います。 - 関数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, およ び :func:`critical` は、 + ロギングシステムの基本的な環境設定を行います。 + 関 数 :func:`debug`, :func:`info`, :func:`warning`, :func:`error`, :func:`critical` は、 ルートロガーにハンドラが定義されていない場合に自動的 に :func:`basicConfig` を呼び出します。 @@ -1340,7 +1342,7 @@ .. Formerly, :func:`basicConfig` did not take any keyword arguments. .. versionchanged:: 2.4 - 以前は :func:`basicConfig` はキーワード引数をとりませんでした. + 以前は :func:`basicConfig` はキーワード引数を取りませんでした。 .. The following keyword arguments are supported. @@ -1400,10 +1402,10 @@ .. closing all handlers. This should be called at application exit and no .. further use of the logging system should be made after this call. - ログ記録システムに対して、バッファのフラッシュを行い、 - 全てのハンドラを閉じることで順次シャットダウンを行うように告知します。 - この関数はアプリケーションの exit 時に呼ばれるべきであり、 - また呼びだし以降はそれ以上ログ記録システムを使ってはなりません。 + ロギングシステムに対して、バッファのフラッシュを行い、 + すべてのハンドラを閉じることで順次シャットダウンを行うように告知します。 + この関数はアプリケーションの終了時に呼ばれるべきであり、 + また呼び出し以降はそれ以上ロギングシステムを使ってはなりません。 .. function:: setLoggerClass(klass) @@ -1414,7 +1416,7 @@ .. function is typically called before any loggers are instantiated by applications .. which need to use custom logger behavior. - ログ記録システムに対して、ロガーをインスタンス化する際にクラス *klass* を使うように指示します。 + ロギングシステムに対して、ロガーをインスタンス化する際にクラス *klass* を使うように指示します。 指定するクラスは引数として名前だけをとるようなメソッド :meth:`__init__` を定義していなければならず、 :meth:`__init__` では :meth:`Logger.__init__` を呼び出さなければなりませ ん。 典型的な利用法として、この関数は自作のロガーを必要とするようなアプリケー ションにおいて、 @@ -1439,7 +1441,7 @@ `この logging パッケージのオリジナル <http://www.red-dove.com/python_logging.html>`_ オリジナルの :mod:`logging` パッケージ。このサイトにあるバージョンの パッケージは、 - 標準で :mod:`logging` パッケージを含まないPython 1.5.2 と 2.1.x、 2.2.xでも使用できます + 標準で :mod:`logging` パッケージを含まない Python 1.5.2, 2.1.x, 2.2.x でも使用できます。 .. _logger: @@ -1451,8 +1453,8 @@ .. instantiated directly, but always through the module-level function .. ``logging.getLogger(name)``. -ロガーは以下の属性とメソッドを持ちます。ロガーを直接インスタンス化すること はできず、 -常にモジュール関数 ``logging.getLogger(name)`` を介してインスタンス化するの で注意してください。 +ロガーには以下のような属性とメソッドがあります。ロガーを直接インスタンス化 することはできず、 +常にモジュール関数 ``logging.getLogger(name)`` を介してインスタンス化するこ とに注意してください。 .. attribute:: Logger.propagate @@ -1461,7 +1463,7 @@ .. its child loggers to the handlers of higher level (ancestor) loggers. The .. constructor sets this attribute to 1. - この値の評価結果が偽になる場合、ログ記録しようとするメッセージはこのロ ガーに渡されず、 + この値の評価結果が false になる場合、ログ記録しようとするメッセージはこ のロガーに渡されず、 また子ロガーから上位の (親の) ロガーのハンドラに渡されません。 コンストラクタはこの属性を 1 に設定します。 @@ -1476,8 +1478,8 @@ このロガーの閾値を *lvl* に設定します。 ログ記録しようとするメッセージで、 *lvl* よりも深刻でないものは無視され ます。 - ロガーが生成された際、レベルは :const:`NOTSET` (これにより全てのメッセー ジについて、 - ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロ ガーの場合には親ロガーに代行させる) に設定されます。 + ロガーが生成された際、レベルは :const:`NOTSET` (これによりすべてのメッ セージについて、 + ロガーがルートロガーであれば処理される、そうでなくてロガーが非ルートロ ガーの場合には親ロガーに委譲させる) に設定されます。 ルートロガーは :const:`WARNING` レベルで生成されることに注意してくださ い。 @@ -1485,7 +1487,7 @@ .. NOTSET, its chain of ancestor loggers is traversed until either an ancestor with .. a level other than NOTSET is found, or the root is reached. - 「親ロガーに代行させる」という用語の意味は、もしロガーのレベルが NOTEST ならば、 + 「親ロガーに委譲」という用語の意味は、もしロガーのレベルが NOTEST なら ば、 祖先ロガーの系列の中を NOTEST 以外のレベルの祖先を見つけるかルートに到達 するまで辿っていく、ということです。 @@ -1493,14 +1495,14 @@ .. level is treated as the effective level of the logger where the ancestor search .. began, and is used to determine how a logging event is handled. - もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが祖先の 探索を開始したロガーの実効レベルとして取り扱われ、 + もし NOTEST 以外のレベルの祖先が見つかったなら、その祖先のレベルが探索を 開始したロガーの実効レベルとして扱われ、 ログイベントがどのように処理されるかを決めるのに使われます。 .. If the root is reached, and it has a level of NOTSET, then all messages will be .. processed. Otherwise, the root's level will be used as the effective level. - ルートに到達した場合、ルートのレベルが NOTEST ならば全てのメッセージは処 理されます。 + ルートに到達した場合、ルートのレベルが NOTEST ならばすべてのメッセージは 処理されます。 そうでなければルートのレベルが実効レベルとして使われます。 @@ -1511,8 +1513,8 @@ .. ``logging.disable(lvl)`` and then the logger's effective level as determined .. by :meth:`getEffectiveLevel`. - 深刻さが *lvl* のメッセージが、このロガーで処理されることになっているか どうかを示します。 - このメソッドはまず、 ``logging.disable(lvl)`` で設定されるモジュールレベ ルの深刻さレベルを調べ、 + 深刻度が *lvl* のメッセージが、このロガーで処理されることになっているか どうかを示します。 + このメソッドはまず、 ``logging.disable(lvl)`` で設定されるモジュールレベ ルの深刻度レベルを調べ、 次にロガーの実効レベルを :meth:`getEffectiveLevel` で調べます。 @@ -1537,7 +1539,7 @@ レベル :const:`DEBUG` のメッセージをこのロガーで記録します。 *msg* はメッセージの書式化文字列で、 *args* は *msg* に文字列書式化演算 子を使って取り込むための引数です。 - (これは、書式化文字列でキーワードを使い引数に辞書を渡すことができる、と いうことを意味します。) + (これは、書式化文字列の中でキーワードを使い、引数として単一の辞書を渡す ことができる、ということを意味します。) .. There are two keyword arguments in *kwargs* which are inspected: *exc_info* @@ -1546,10 +1548,10 @@ .. :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` .. is called to get the exception information. - キーワード引数 *kwargs* からは二つのキーワードが調べられます。 - 一つめは *exc_info* で、この値の評価値が偽でない場合、例外情報をログメッ セージに追加します。 + キーワード引数 *kwargs* からは 2 つのキーワードが調べられます。 + 一つ目は *exc_info* で、この値の評価値が false でない場合、例外情報をロ グメッセージに追加します。 (:func:`sys.exc_info` の返す形式の) 例外情報を表すタプルが与えられていれ ば、それをメッセージに使います。 - それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得し ます。 + それ以外の場合には、 :func:`sys.exc_info` を呼び出して例外情報を取得しま す。 .. The other optional keyword argument is *extra* which can be used to pass a @@ -1558,8 +1560,8 @@ .. be used as you like. For example, they could be incorporated into logged .. messages. For example: - もう一つのキーワード引数は *extra* で、当該ログイベント用に作られた - LogRecoed の __dict__ にユーザー定義属性を増やすのに使われる辞書を渡すの に用いられます。 + もう一つのキーワード引数は *extra* で、当該ログイベント用に作られる + LogRecoed の __dict__ にユーザー定義属性を加えるのに使われる辞書を渡すた めに用いられます。 これらの属性は好きなように使えます。たとえば、ログメッセージの一部にする こともできます。 以下の例を見てください。 @@ -1587,7 +1589,7 @@ .. by the logging system. (See the :class:`Formatter` documentation for more .. information on which keys are used by the logging system.) - *extra* で渡される辞書のキーはロギングシステムで使われているものとぶつか らないようにしなければなりません。 + *extra* で渡される辞書のキーはロギングシステムで使われているものと衝突し ないようにしなければなりません。 (どのキーがロギングシステムで使われているかについての詳細 は :class:`Formatter` のドキュメントを参照してください。) @@ -1599,10 +1601,10 @@ .. always need to pass the *extra* dictionary with these keys. これらの属性をログメッセージに使うことにしたなら、少し注意が必要です。 - 上の例では、'clientip' と 'user' が LogRecord の属性辞書に含まれているこ とを期待した書式化文字列で - :class:`Formatter` はセットアップされています。 - これらの属性が欠けていると、書式化例外が発生してしまうためメッセージはロ グに残りません。 - したがってこの場合、常にこれらのキーがある *extra* 辞書を渡す必要があり ます。 + 上の例では、 'clientip' と 'user' が LogRecord の属性辞書に含まれている ことを期待した書式化文字列で + :class:`Formatter` がセットアップされています。 + もしこれらが欠けていると、書式化例外が発生してしまうためメッセージはログ に残りません。 + したがってこの場合、常にこれらのキーを含む *extra* 辞書を渡す必要があり ます。 .. While this might be annoying, this feature is intended for use in specialized @@ -1623,7 +1625,7 @@ .. *extra* was added. .. versionchanged:: 2.5 - *extra* が追加されました. + *extra* が追加されました。 .. method:: Logger.info(msg[, *args[, **kwargs]]) @@ -1679,7 +1681,7 @@ レベル :const:`ERROR` のメッセージをこのロガーで記録します。 引数は :meth:`debug` と同じように解釈されます。 - 例外情報はログメッセージに追加されます。 ***The diff for this file has been truncated for email.***
