pytho****@googl*****
pytho****@googl*****
2011年 11月 20日 (日) 23:48:12 JST
Revision: 742560d703bb Author: Arihiro TAKASE <hinac****@gmail*****> Date: Sun Nov 20 06:46:59 2011 Log: Update 2.7.2: library/logging.handlers, logging.config http://code.google.com/p/python-doc-ja/source/detail?r=742560d703bb Modified: /library/logging.config.rst /library/logging.handlers.rst ======================================= --- /library/logging.config.rst Fri Oct 28 23:01:19 2011 +++ /library/logging.config.rst Sun Nov 20 06:46:59 2011 @@ -1,8 +1,8 @@ -:mod:`logging.config` --- Logging configuration -=============================================== +:mod:`logging.config` --- ロギングの環境設定 +============================================ .. module:: logging.config - :synopsis: Configuration of the logging module. + :synopsis: logging モジュールの環境設定 .. moduleauthor:: Vinay Sajip <vinay_sajip****@red-d*****> @@ -10,185 +10,177 @@ .. sidebar:: Important - This page contains only reference information. For tutorials, - please see - - * :ref:`Basic Tutorial <logging-basic-tutorial>` - * :ref:`Advanced Tutorial <logging-advanced-tutorial>` - * :ref:`Logging Cookbook <logging-cookbook>` - -This section describes the API for configuring the logging module. + このページには、リファレンス情報だけが含まれています。 + チュートリアルは、以下のページを参照してください + + * :ref:`基本チュートリアル <logging-basic-tutorial>` + * :ref:`上級チュートリアル <logging-advanced-tutorial>` + * :ref:`ロギングクックブック <logging-cookbook>` + +この節は、 logging モジュールを設定するための API を解説します。 .. _logging-config-api: -Configuration functions -^^^^^^^^^^^^^^^^^^^^^^^ - -The following functions configure the logging module. They are located in the -:mod:`logging.config` module. Their use is optional --- you can configure the -logging module using these functions or by making calls to the main API (defined -in :mod:`logging` itself) and defining handlers which are declared either in -:mod:`logging` or :mod:`logging.handlers`. +環境設定のための関数 +^^^^^^^^^^^^^^^^^^^^ + +以下の関数は logging モジュールの環境設定をします。 +これらの関数は、 :mod:`logging.config` にあります。 +これらの関数の使用はオプションです --- +:mod:`logging` モジュールはこれらの関数を使うか、 (:mod:`logging` 自体で +定義されている) 主要な API を呼び出し、:mod:`logging` か +:mod:`logging.handlers` で宣言されているハンドラを定義することで設定できま す。 .. function:: dictConfig(config) - Takes the logging configuration from a dictionary. The contents of - this dictionary are described in :ref:`logging-config-dictschema` - below. - - If an error is encountered during configuration, this function will - raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError` - or :exc:`ImportError` with a suitably descriptive message. The - following is a (possibly incomplete) list of conditions which will - raise an error: - - * A ``level`` which is not a string or which is a string not - corresponding to an actual logging level. - * A ``propagate`` value which is not a boolean. - * An id which does not have a corresponding destination. - * A non-existent handler id found during an incremental call. - * An invalid logger name. - * Inability to resolve to an internal or external object. - - Parsing is performed by the :class:`DictConfigurator` class, whose - constructor is passed the dictionary used for configuration, and - has a :meth:`configure` method. The :mod:`logging.config` module - has a callable attribute :attr:`dictConfigClass` - which is initially set to :class:`DictConfigurator`. - You can replace the value of :attr:`dictConfigClass` with a - suitable implementation of your own. - - :func:`dictConfig` calls :attr:`dictConfigClass` passing - the specified dictionary, and then calls the :meth:`configure` method on - the returned object to put the configuration into effect:: + 辞書からロギング環境設定を取得します。この辞書の内容は、以下の + :ref:`logging-config-dictschema` で記述されています。 + + 環境設定中にエラーに遭遇すると、この関数は適宜メッセージを記述しつつ + :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError` または + :exc:`ImportError` を送出します。例外を送出する条件を (不完全かも + しれませんが) 以下に列挙します: + + * 文字列でなかったり、実際のロギングレベルと関係ない文字列であったりす る + ``level`` + * ブール値でない ``propagate`` の値 + * 対応する行き先を持たない id + * インクリメンタルな呼び出しの中で見つかった存在しないハンドラ id + * 無効なロガー名 + * 内部や外部のオブジェクトに関わる不可能性 + + 解析は :class:`DictConfigurator` クラスによって行われます。このクラスの + コンストラクタは環境設定に使われる辞書に渡され、このクラスは + :meth:`configure` メソッドを持ちます。 :mod:`logging.config` モジュール は、 + 呼び出し可能属性 :attr:`dictConfigClass` を持ち、これはまず + :class:`DictConfigurator` に設定されます。 :attr:`dictConfigClass` の値 は + 適切な独自の実装で置き換えられます。 + + :func:`dictConfig` は :attr:`dictConfigClass` を、指定された辞書を渡し て + 呼び出し、それから返されたオブジェクトの :meth:`configure` メソッドを + 呼び出して、環境設定を作用させます:: def dictConfig(config): dictConfigClass(config).configure() - For example, a subclass of :class:`DictConfigurator` could call - ``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then - set up custom prefixes which would be usable in the subsequent - :meth:`configure` call. :attr:`dictConfigClass` would be bound to - this new subclass, and then :func:`dictConfig` could be called exactly as - in the default, uncustomized state. + 例えば、 :class:`DictConfigurator` のサブクラスは、自身の + :meth:`__init__()` で ``DictConfigurator.__init__()`` を呼び出し、それ から + 続く :meth:`configure` の呼び出しに使えるカスタムの接頭辞を設定できま す。 + :attr:`dictConfigClass` は、この新しいサブクラスに束縛され、そして + :func:`dictConfig` はちょうどデフォルトの、カスタマイズされていない状態 の + ように呼び出せます。 .. versionadded:: 2.7 .. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True) - Reads the logging configuration from a :mod:`configparser`\-format file - named *fname*. This function can be called several times from an - application, allowing an end user to select from various pre-canned - configurations (if the developer provides a mechanism to present the choices - and load the chosen configuration). - - :param defaults: Defaults to be passed to the ConfigParser can be specified - in this argument. - - :param disable_existing_loggers: If specified as ``False``, loggers which - exist when this call is made are left - alone. The default is ``True`` because this - enables old behaviour in a backward- - compatible way. This behaviour is to - disable any existing loggers unless they or - their ancestors are explicitly named in the - logging configuration. + ログ記録の環境設定をファイル名 *fname* の :mod:`configparser` 形式ファイ ルから読み出します。 + この関数はアプリケーションから何度も呼び出すことができ、これによって、 + (設定を選択し、選択された設定を読み出す機構をデベロッパが提供していれば) + 複数の準備済みの設定からエンドユーザが選択するようにできます。 + + :param defaults: ConfigParser に渡すためのデフォルト値はこの引数で指定で きます。 + + :param disable_existing_loggers: ``False`` に指定されると、この呼び出し が + なされたときに存在するロガーはそのまま に + しておかれます。後方互換性を保って + 古い動作を行えるように、 + デフォルトは ``True`` です。 + この動作は、すべての既存のロガーを、 + ロギング環境設定でそれ自身かその祖先を + 明示的に指名されない限り、無効にしま す。 .. versionchanged:: 2.6 - The ``disable_existing_loggers`` keyword argument was added. Previously, - existing loggers were *always* disabled. + ``disable_existing_loggers`` キーワード引数が追加されました。 + 以前は、既存のロガーは *必ず* 無効にされていました。 .. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT) - Starts up a socket server on the specified port, and listens for new - configurations. If no port is specified, the module's default - :const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be - sent as a file suitable for processing by :func:`fileConfig`. Returns a - :class:`Thread` instance on which you can call :meth:`start` to start the - server, and which you can :meth:`join` when appropriate. To stop the server, - call :func:`stopListening`. - - To send a configuration to the socket, read in the configuration file and - send it to the socket as a string of bytes preceded by a four-byte length - string packed in binary using ``struct.pack('>L', n)``. + 指定されたポートでソケットサーバを開始し、新たな設定を待ち受けます。 + ポートが指定されなければ、モジュールのデフォルトの + :const:`DEFAULT_LOGGING_CONFIG_PORT` が使われます。 + ログ記録の環境設定は :func:`fileConfig` で処理できるようなファイルとして 送信されます。 + :class:`Thread` インスタンスを返し、サーバを開始するため に :meth:`start` を呼び、 + 適切な状況で :meth:`join` を呼び出すことができます。 + サーバを停止するには :func:`stopListening` を呼んでください。 + + ソケットに設定を送るには、まず設定ファイルを読み、それを + ``struct.pack('>L', n)`` を使って長さ 4 バイトのバイナリにパックしたもの を + 前に付けたバイト列としてソケットに送ります。 .. function:: stopListening() - Stops the listening server which was created with a call to :func:`listen`. - This is typically called before calling :meth:`join` on the return value from - :func:`listen`. + :func:`listen` を呼び出して作成された、待ち受け中のサーバを停止します。 + 通常 :func:`listen` の戻り値に対して :meth:`join` が呼ばれる前に呼び出し ます。 .. _logging-config-dictschema: -Configuration dictionary schema -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Describing a logging configuration requires listing the various -objects to create and the connections between them; for example, you -may create a handler named 'console' and then say that the logger -named 'startup' will send its messages to the 'console' handler. -These objects aren't limited to those provided by the :mod:`logging` -module because you might write your own formatter or handler class. -The parameters to these classes may also need to include external -objects such as ``sys.stderr``. The syntax for describing these -objects and connections is defined in :ref:`logging-config-dict-connections` -below. - -Dictionary Schema Details -""""""""""""""""""""""""" - -The dictionary passed to :func:`dictConfig` must contain the following -keys: - -* *version* - to be set to an integer value representing the schema - version. The only valid value at present is 1, but having this key - allows the schema to evolve while still preserving backwards - compatibility. - -All other keys are optional, but if present they will be interpreted -as described below. In all cases below where a 'configuring dict' is -mentioned, it will be checked for the special ``'()'`` key to see if a -custom instantiation is required. If so, the mechanism described in -:ref:`logging-config-dict-userdef` below is used to create an instance; -otherwise, the context is used to determine what to instantiate. - -* *formatters* - the corresponding value will be a dict in which each - key is a formatter id and each value is a dict describing how to - configure the corresponding Formatter instance. - - The configuring dict is searched for keys ``format`` and ``datefmt`` - (with defaults of ``None``) and these are used to construct a - :class:`logging.Formatter` instance. - -* *filters* - the corresponding value will be a dict in which each key - is a filter id and each value is a dict describing how to configure - the corresponding Filter instance. - - The configuring dict is searched for the key ``name`` (defaulting to the - empty string) and this is used to construct a :class:`logging.Filter` - instance. - -* *handlers* - the corresponding value will be a dict in which each - key is a handler id and each value is a dict describing how to - configure the corresponding Handler instance. - - The configuring dict is searched for the following keys: - - * ``class`` (mandatory). This is the fully qualified name of the - handler class. - - * ``level`` (optional). The level of the handler. - - * ``formatter`` (optional). The id of the formatter for this - handler. - - * ``filters`` (optional). A list of ids of the filters for this - handler. - - All *other* keys are passed through as keyword arguments to the - handler's constructor. For example, given the snippet:: +環境設定辞書スキーマ +^^^^^^^^^^^^^^^^^^^^ + +ロギング設定を記述するには、生成するさまざまなオブジェクトと、それらの +つながりを列挙しなければなりません。例えば、 'console' という名前の +ハンドラを生成し、'startup' という名前のロガーがメッセージを +'console' ハンドラに送るというようなことを記述します。 +これらのオブジェクトは、 :mod:`logging` モジュールによって提供されるものに +限らず、独自のフォーマッタやハンドラクラスを書くことも出来ます。 +このクラスへのパラメタは、 ``sys.stderr`` のような外部オブジェクトを +必要とすることもあります。これらのオブジェクトとつながりを記述する構文は、 +以下の :ref:`logging-config-dict-connections` で定義されています。 + +辞書スキーマの詳細 +"""""""""""""""""" + +:func:`dictConfig` に渡される辞書は、以下のキーを含んでいなければなりませ ん: + +* *version* - スキーマのバージョンを表す整数値に設定されます。 + 現在有効な値は 1 だけですが、このキーがあることで、 + このスキーマは後方互換性を保ちながら発展できます。 + +その他すべてのキーは省略可能ですが、与えられたなら以下に記述するように +解釈されます。以下のすべての場合において、 +'環境設定辞書' と記載されている所では、 +その辞書に特殊な ``'()'`` キーがあるかを調べることで、 +カスタムのインスタント化が必要であるか判断されます。 +その場合は、以下の :ref:`logging-config-dict-userdef` で記述されている +機構がインスタンス生成に使われます。そうでなければ、インスタンス化する +べきものを決定するのにコンテキストが使われます。 + + +* *formatters* - 対応する値は辞書で、そのそれぞれのキーが + フォーマッタ id になり、それぞれの値が対応する Formatter インスタンスを + どのように環境設定するかを記述する辞書になります。 + + 環境設定辞書は、(デフォルトが ``None`` の) キー ``format`` と ``datefmt`` を + 検索され、それらが :class:`logging.Formatter` インスタンスを構成するのに + 使われます。 + +* *filters* - 対応する値は辞書で、そのそれぞれのキーが + フィルタ id になり、それぞれの値が対応する Filter インスタンスを + どのように環境設定するかを記述する辞書になります。 + + 環境設定辞書は、(デフォルトが空文字列の) キー ``name`` を + 検索され、それらが :class:`logging.Formatter` インスタンスを構成するのに + 使われます。 + +* *handlers* - 対応する値は辞書で、そのそれぞれのキーが + ハンドラ id になり、それぞれの値が対応する Handler インスタンスを + どのように環境設定するかを記述する辞書になります。 + + 環境設定辞書は、以下のキーを検索されます。 + + * ``class`` (必須)。これはハンドラクラスの完全に修飾された名前です。 + + * ``level`` (任意)。ハンドラのレベルです。 + + * ``formatter`` (任意)。このハンドラへのフォーマッタの id です。 + + * ``filters`` (任意)。このハンドラへのフィルタの id のリストです。 + + その他の *すべての* キーは、ハンドラのコンストラクタにキーワード引数とし て + 渡されます。例えば、以下のコード片が与えられたら:: handlers: console: @@ -204,100 +196,91 @@ maxBytes: 1024 backupCount: 3 - the handler with id ``console`` is instantiated as a - :class:`logging.StreamHandler`, using ``sys.stdout`` as the underlying - stream. The handler with id ``file`` is instantiated as a - :class:`logging.handlers.RotatingFileHandler` with the keyword arguments - ``filename='logconfig.log', maxBytes=1024, backupCount=3``. - -* *loggers* - the corresponding value will be a dict in which each key - is a logger name and each value is a dict describing how to - configure the corresponding Logger instance. - - The configuring dict is searched for the following keys: - - * ``level`` (optional). The level of the logger. - - * ``propagate`` (optional). The propagation setting of the logger. - - * ``filters`` (optional). A list of ids of the filters for this - logger. - - * ``handlers`` (optional). A list of ids of the handlers for this - logger. - - The specified loggers will be configured according to the level, - propagation, filters and handlers specified. - -* *root* - this will be the configuration for the root logger. - Processing of the configuration will be as for any logger, except - that the ``propagate`` setting will not be applicable. - -* *incremental* - whether the configuration is to be interpreted as - incremental to the existing configuration. This value defaults to - ``False``, which means that the specified configuration replaces the - existing configuration with the same semantics as used by the - existing :func:`fileConfig` API. - - If the specified value is ``True``, the configuration is processed - as described in the section on :ref:`logging-config-dict-incremental`. - -* *disable_existing_loggers* - whether any existing loggers are to be - disabled. This setting mirrors the parameter of the same name in - :func:`fileConfig`. If absent, this parameter defaults to ``True``. - This value is ignored if *incremental* is ``True``. + id が ``console`` であるハンドラが、 ``sys.stdout`` を根底の + ストリームにして、 :class:`logging.StreamHandler` としてインスタンス化 + されます。id が ``file`` であるハンドラが、 + ``filename='logconfig.log', maxBytes=1024, backupCount=3`` + をキーワード引数にして、 :class:`logging.handlers.RotatingFileHandler` + としてインスタンス化されます。 + +* *loggers* - 対応する値は辞書で、そのそれぞれのキーが + ロガー名になり、それぞれの値が対応する Logger インスタンスを + どのように環境設定するかを記述する辞書になります。 + + 環境設定辞書は、以下のキーを検索されます。 + + * ``level`` (任意)。ロガーのレベルです。 + + * ``propagate`` (任意)。ロガーの伝播の設定です。 + + * ``filters`` (任意)。このロガーへのフィルタの id のリストです。 + + * ``filters`` (任意)。このロガーへのハンドラの id のリストです。 + + 指定されたロガーは、指定されたレベル、伝播、ハンドラに従って環境設定され ます。 + +* *root* - これは、ルートロガーへの設定になります。 + この環境設定の進行は、 ``propagate`` 設定が適用されないことを除き、 + 他のロガーと同じです。 + +* *incremental* - この環境設定が既存の環境設定に対する増分として + 解釈されるかどうかです。この値のデフォルトは ``False`` で、 + 指定された環境設定は、既存の :func:`fileConfig` API + によって使われているのと同じ意味上で、既存の環境設定を置き換えます。 + + 指定された値が ``True`` なら、環境設定は + :ref:`logging-config-dict-incremental` の節で記述されているように進行しま す。 + + *disable_existing_loggers* - 既存のロガーをすべて無効にするべきかどうかで す。 + この設定は、 :func:`fileConfig` における同じ名前のパラメタと同じです。 + 設定されていなければ、このパラメタのデフォルトは ``True`` です。 + この値は、 *incremental* が ``True`` なら無視されます。 .. _logging-config-dict-incremental: -Incremental Configuration -""""""""""""""""""""""""" - -It is difficult to provide complete flexibility for incremental -configuration. For example, because objects such as filters -and formatters are anonymous, once a configuration is set up, it is -not possible to refer to such anonymous objects when augmenting a -configuration. - -Furthermore, there is not a compelling case for arbitrarily altering -the object graph of loggers, handlers, filters, formatters at -run-time, once a configuration is set up; the verbosity of loggers and -handlers can be controlled just by setting levels (and, in the case of -loggers, propagation flags). Changing the object graph arbitrarily in -a safe way is problematic in a multi-threaded environment; while not -impossible, the benefits are not worth the complexity it adds to the -implementation. - -Thus, when the ``incremental`` key of a configuration dict is present -and is ``True``, the system will completely ignore any ``formatters`` and -``filters`` entries, and process only the ``level`` -settings in the ``handlers`` entries, and the ``level`` and -``propagate`` settings in the ``loggers`` and ``root`` entries. - -Using a value in the configuration dict lets configurations to be sent -over the wire as pickled dicts to a socket listener. Thus, the logging -verbosity of a long-running application can be altered over time with -no need to stop and restart the application. +増分設定 +"""""""" + +増分設定に完全な柔軟性を提供するのは難しいです。例えば、フィルタや +フォーマッタのようなオブジェクトは匿名なので、一旦環境設定がなされると、 +設定を拡張するときにそのような匿名オブジェクトを参照することができません。 + +さらに、一旦環境設定がなされた後、実行時にロガー、ハンドラ、フィルタ、 +フォーマッタのオブジェクトグラフを任意に変えなければならない例もありませ ん。 +ロガーとハンドラの冗長性は、レベル (または、ロガーの場合には、伝播フラグ) を +設定することによってのみ制御できます。安全な方法でオブジェクトグラフを +任意に変えることは、マルチスレッド環境で問題となります。 +不可能ではないですが、その効用は実装に加えられる複雑さに見合いません。 + +従って、環境設定辞書の ``incremental`` キーが与えられ、これが ``True`` +であるとき、システムは ``formatters`` と ``filters`` の項目を完全に無視し、 +``handlers`` の項目の ``level`` 設定と、 ``loggers`` と ``root`` の項目の +``level`` と ``propagate`` 設定のみを処理します。 + +環境設定辞書の値を使うことで、設定は pickle 化された辞書としてソケットリス ナ +にワイヤを通して送ることができます。従って、時間のかかるアプリケーションの +ロギングの冗長性は、アプリケーションを止めて再起動する必要がない時間に +変えることができます。 .. _logging-config-dict-connections: -Object connections +オブジェクトの接続 """""""""""""""""" -The schema describes a set of logging objects - loggers, -handlers, formatters, filters - which are connected to each other in -an object graph. Thus, the schema needs to represent connections -between the objects. For example, say that, once configured, a -particular logger has attached to it a particular handler. For the -purposes of this discussion, we can say that the logger represents the -source, and the handler the destination, of a connection between the -two. Of course in the configured objects this is represented by the -logger holding a reference to the handler. In the configuration dict, -this is done by giving each destination object an id which identifies -it unambiguously, and then using the id in the source object's -configuration to indicate that a connection exists between the source -and the destination object with that id. - -So, for example, consider the following YAML snippet:: +このスキーマは、ロギングオブジェクトの一揃い - ロガー、ハンドラ、フォーマッ タ、 +フィルタ - について記述します。 +これらは、オブジェクトグラフ上でお互い接続されます。 +従って、このスキーマは、オブジェクト間の接続を表現しなければなりません。 +例えば、環境設定で、特定のロガーが特定のハンドラに +取り付けられたとします。この議論では、ロガーとハンドラが、これら 2 つの接続 の +それぞれ送信元と送信先であるといえます。 +もちろん、この設定オブジェクト中では、これはハンドラへの参照を保持している +ロガーで表されます。設定辞書中で、これは次のようになされます。 +まず、送信先オブジェクトを曖昧さなく指定する id を与えます。そして、 +その id を送信元オブジェクトの環境設定で使い、送信元とその id をもつ +送信先が接続されていることを示します。 + +ですから、例えば、以下の YAML のコード片を例にとると:: formatters: brief: @@ -316,45 +299,42 @@ # other configuration for logger 'foo.bar.baz' handlers: [h1, h2] -(Note: YAML used here because it's a little more readable than the -equivalent Python source form for the dictionary.) - -The ids for loggers are the logger names which would be used -programmatically to obtain a reference to those loggers, e.g. -``foo.bar.baz``. The ids for Formatters and Filters can be any string -value (such as ``brief``, ``precise`` above) and they are transient, -in that they are only meaningful for processing the configuration -dictionary and used to determine connections between objects, and are -not persisted anywhere when the configuration call is complete. - -The above snippet indicates that logger named ``foo.bar.baz`` should -have two handlers attached to it, which are described by the handler -ids ``h1`` and ``h2``. The formatter for ``h1`` is that described by id -``brief``, and the formatter for ``h2`` is that described by id -``precise``. +(注釈: YAML がここで使われているのは、辞書の等価な Python 形式よりも +こちらのほうが少し読みやすいからです。) + +ロガーの id は、プログラム上でロガーへの参照を得るために使われるロガー名 で、 +たとえば ``foo.bar.baz`` です。フォーマッタとフィルタの id は、 +(上の ``brief``, ``precise`` のような) 任意の文字列値にできます。 +これらは一時的なもので、環境設定辞書の処理にのみ意味があり、 +オブジェクト間の接続を決定するのに使われます。 +また、これらは設定の呼び出しが完了したとき、どこにも残りません。 + +上記のコード片は、 ``foo.bar.baz`` というの名ロガーに、ハンドラ id ``h1`` と +``h2`` で表される 2 つのハンドラを接続することを示します。 +``h1`` のフォーマッタは id ``brief`` で記述されるもので、 +``h2`` のフォーマッタは id ``precise`` で記述されるものです。 .. _logging-config-dict-userdef: -User-defined objects -"""""""""""""""""""" - -The schema supports user-defined objects for handlers, filters and -formatters. (Loggers do not need to have different types for -different instances, so there is no support in this configuration -schema for user-defined logger classes.) - -Objects to be configured are described by dictionaries -which detail their configuration. In some places, the logging system -will be able to infer from the context how an object is to be -instantiated, but when a user-defined object is to be instantiated, -the system will not know how to do this. In order to provide complete -flexibility for user-defined object instantiation, the user needs -to provide a 'factory' - a callable which is called with a -configuration dictionary and which returns the instantiated object. -This is signalled by an absolute import path to the factory being -made available under the special key ``'()'``. Here's a concrete -example:: +ユーザ定義オブジェクト +"""""""""""""""""""""" + +このスキーマは、ハンドラ、フィルタ、フォーマッタのための、 +ユーザ定義オブジェクトをサポートします。 +(ロガーは、異なるインスタンスに対して異なる型を持つ必要はないので、 +この環境設定スキーマは、ユーザ定義ロガークラスをサポートしていません。) + +設定されるオブジェクトは、それらの設定を詳述する辞書によって記述されます。 +場所によっては、あるオブジェクトがどのようにインスタンス化されるかという +コンテキストを、ロギングシステムが推測できます。しかし、ユーザ定義オブジェ クトが +インスタンス化されるとき、システムはどのようにこれを行うかを知りません。 +ユーザ定義オブジェクトのインスタンス化を完全に柔軟なものにするため、 +ユーザは 'ファクトリ' - 設定辞書を引数として呼ばれ、インスタンス化された +オブジェクトを返す呼び出し可能オブジェクト - を提供する必要があります。 +これは特殊キー ``'()'`` で利用できる、 +ファクトリへの絶対インポートパスによって合図されます。 +ここに具体的な例を挙げます:: formatters: brief: @@ -368,30 +348,29 @@ spam: 99.9 answer: 42 -The above YAML snippet defines three formatters. The first, with id -``brief``, is a standard :class:`logging.Formatter` instance with the -specified format string. The second, with id ``default``, has a -longer format and also defines the time format explicitly, and will -result in a :class:`logging.Formatter` initialized with those two format -strings. Shown in Python source form, the ``brief`` and ``default`` -formatters have configuration sub-dictionaries:: +上記の YAML コード片は 3 つのフォーマッタを定義します。 +1 つ目は、id が ``brief`` で、指定されたフォーマット文字列をもつ、 +標準 :class:`logging.Formatter` インスタンスです。 +2 つ目は、id が ``default`` で、長いフォーマットを持ち、時間フォーマットも +定義していて、結果はその 2 つのフォーマット文字列で初期化された +:class:`logging.Formatter` になります。Python ソース形式で見ると、 +``brief`` と ``default`` フォーマッタは、それぞれ設定の部分辞書:: { 'format' : '%(message)s' } -and:: +と:: { 'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s', 'datefmt' : '%Y-%m-%d %H:%M:%S' } -respectively, and as these dictionaries do not contain the special key -``'()'``, the instantiation is inferred from the context: as a result, -standard :class:`logging.Formatter` instances are created. The -configuration sub-dictionary for the third formatter, with id -``custom``, is:: +を持ち、これらの辞書が特殊キー ``'()'`` を持たないので、インスタンス化は +コンテキストから推測され、結果として標準の :class:`logging.Formatter` +インスタンスが生成されます。id が ``custom`` である、3 つ目の +フォーマッタの設定をする部分辞書は:: { '()' : 'my.package.customFormatterFactory', @@ -400,75 +379,69 @@ 'answer' : 42 } -and this contains the special key ``'()'``, which means that -user-defined instantiation is wanted. In this case, the specified -factory callable will be used. If it is an actual callable it will be -used directly - otherwise, if you specify a string (as in the example) -the actual callable will be located using normal import mechanisms. -The callable will be called with the **remaining** items in the -configuration sub-dictionary as keyword arguments. In the above -example, the formatter with id ``custom`` will be assumed to be -returned by the call:: +で、ユーザ定義のインスタンス化が望まれることを示す特殊キー ``'()'`` を +含みます。この場合、指定された呼び出し可能ファクトリオブジェクトが使われま す。 +これが実際の呼び出し可能オブジェクトであれば、それが直接使われます - +そうではなく、(この例でのように) 文字列を指定したなら、実際の +呼び出し可能オブジェクトは、通常のインポート機構を使って検索されます。 +その呼び出し可能オブジェクトは、環境設定の部分辞書の、 **残りの** 要素を +キーワード引数として呼ばれます。上記の例では、id が ``custom`` のフォーマッ タ +は、以下の呼び出しによって返されるものとみなされます:: my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42) -The key ``'()'`` has been used as the special key because it is not a -valid keyword parameter name, and so will not clash with the names of -the keyword arguments used in the call. The ``'()'`` also serves as a -mnemonic that the corresponding value is a callable. +キー ``'()'`` が特殊キーとして使われるのは、キーワードパラメタ名として不正 で、 +呼び出しに使われるキーワード引数と衝突し得ないからです。 +``'()'`` はまた、対応する値が呼び出し可能オブジェクトであると覚えやすくしま す。 .. _logging-config-dict-externalobj: -Access to external objects -"""""""""""""""""""""""""" - -There are times where a configuration needs to refer to objects -external to the configuration, for example ``sys.stderr``. If the -configuration dict is constructed using Python code, this is -straightforward, but a problem arises when the configuration is -provided via a text file (e.g. JSON, YAML). In a text file, there is -no standard way to distinguish ``sys.stderr`` from the literal string -``'sys.stderr'``. To facilitate this distinction, the configuration -system looks for certain special prefixes in string values and -treat them specially. For example, if the literal string -``'ext://sys.stderr'`` is provided as a value in the configuration, -then the ``ext://`` will be stripped off and the remainder of the -value processed using normal import mechanisms. - -The handling of such prefixes is done in a way analogous to protocol -handling: there is a generic mechanism to look for prefixes which -match the regular expression ``^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`` -whereby, if the ``prefix`` is recognised, the ``suffix`` is processed -in a prefix-dependent manner and the result of the processing replaces -the string value. If the prefix is not recognised, then the string -value will be left as-is. +外部オブジェクトへのアクセス +"""""""""""""""""""""""""""" + +環境設定が、例えば ``sys.stderr`` のような、設定の外部のオブジェクトへの +参照を必要とすることがあります。 +設定辞書が Python コードで構成されていれば話は簡単ですが、 +これがテキストファイル (JSON, YAML 等) を通して提供されていると問題となりま す。 +テキストファイルでは、 ``sys.stderr`` をリテラル文字列 ``'sys.stderr'`` と +区別する標準の方法がありません。この区別を容易にするため、環境設定システム は、 +文字列中の特定の特殊接頭辞を見つけ、それらを特殊に扱います。 +例えば、リテラル文字列 ``'ext://sys.stderr'`` が設定中の値として与えられた ら、 +この ``ext://`` は剥ぎ取られ、この値の残りが普通のインポート機構で処理され ます。 + +このような接頭辞の処理は、プロトコルの処理と同じようになされます。 +どちらの機構も、正規表現 ``^(?P<prefix>[a-z]+)://(?P<suffix>.*)$`` に +マッチする接頭辞を検索し、それによって ``prefix`` が認識されたなら、 +接頭辞に応じたやり方で ``suffix`` が処理され、その処理の結果によって +文字列値が置き換えられます。接頭辞が認識されなければ、その文字列値は +そのまま残されます。 .. _logging-config-dict-internalobj: -Access to internal objects -"""""""""""""""""""""""""" - -As well as external objects, there is sometimes also a need to refer -to objects in the configuration. This will be done implicitly by the -configuration system for things that it knows about. For example, the -string value ``'DEBUG'`` for a ``level`` in a logger or handler will -automatically be converted to the value ``logging.DEBUG``, and the -``handlers``, ``filters`` and ``formatter`` entries will take an -object id and resolve to the appropriate destination object. - -However, a more generic mechanism is needed for user-defined -objects which are not known to the :mod:`logging` module. For -example, consider :class:`logging.handlers.MemoryHandler`, which takes -a ``target`` argument which is another handler to delegate to. Since -the system already knows about this class, then in the configuration, -the given ``target`` just needs to be the object id of the relevant -target handler, and the system will resolve to the handler from the -id. If, however, a user defines a ``my.package.MyHandler`` which has -an ``alternate`` handler, the configuration system would not know that -the ``alternate`` referred to a handler. To cater for this, a generic -resolution system allows the user to specify:: +内部オブジェクトへのアクセス +"""""""""""""""""""""""""""" + +外部オブジェクトと同様、環境設定内部のオブジェクトへのアクセスを +必要とすることもあります。これは、その各オブジェクトを司る環境設定システム に +よって暗黙に行われます。 +例えば、ロガーやハンドラの ``level`` に対する文字列値 ``'DEBUG'`` は、 +自動的に値 ``logging.DEBUG`` に変換されますし、 +``handlers``, ``filters`` および ``formatter`` の項目は、 +オブジェクト id を取って、適切な送信先オブジェクトを決定します。 + +しかし、ユーザ定義モジュールには、 :mod:`logging` モジュールには +分からないような、より一般的な機構が必要です。 +例えば、 :class:`logging.handlers.MemoryHandler` があって、 +委譲する先の別のハンドラである ``target`` 引数を取るとします。 +システムはこのクラスをすでに知っていますから、設定中で、 +与えられた ``target`` は関連するターゲットハンドラのオブジェクト id でさえ +あればよく、システムはその id からハンドラを決定します。 +しかし、ユーザが ``my.package.MyHandler`` を定義して、それが ``alternate`` +ハンドラを持つなら、設定システムは ``alternate`` がハンドラを参照しているこ とを +知りません。これを知らせるのに、一般的な解析システムで、ユーザはこのように +指定できます:: handlers: file: @@ -478,11 +451,12 @@ (): my.package.MyHandler alternate: cfg://handlers.file -The literal string ``'cfg://handlers.file'`` will be resolved in an -analogous way to strings with the ``ext://`` prefix, but looking -in the configuration itself rather than the import namespace. The -mechanism allows access by dot or by index, in a similar way to -that provided by ``str.format``. Thus, given the following snippet:: +リテラル文字列 ``'cfg://handlers.file'`` は、 ``ext://`` 接頭辞が +付いた文字列と同じように分析されますが、インポート名前空間ではなく、 +環境設定自体が検索されます。この機構は ``str.format`` でできるのと同じよう に +ドットやインデクスのアクセスができます。従って、環境設定において +以下のコード片が与えられれば:: + handlers: email: @@ -494,47 +468,42 @@ - dev_team****@domai***** subject: Houston, we have a problem. -in the configuration, the string ``'cfg://handlers'`` would resolve to -the dict with key ``handlers``, the string ``'cfg://handlers.email`` -would resolve to the dict with key ``email`` in the ``handlers`` dict, -and so on. The string ``'cfg://handlers.email.toaddrs[1]`` would -resolve to ``'dev_team.domain.tld'`` and the string -``'cfg://handlers.email.toaddrs[0]'`` would resolve to the value -``'support_team****@domai*****'``. The ``subject`` value could be accessed -using either ``'cfg://handlers.email.subject'`` or, equivalently, -``'cfg://handlers.email[subject]'``. The latter form only needs to be -used if the key contains spaces or non-alphanumeric characters. If an -index value consists only of decimal digits, access will be attempted -using the corresponding integer value, falling back to the string -value if needed. - -Given a string ``cfg://handlers.myhandler.mykey.123``, this will -resolve to ``config_dict['handlers']['myhandler']['mykey']['123']``. -If the string is specified as ``cfg://handlers.myhandler.mykey[123]``, -the system will attempt to retrieve the value from -``config_dict['handlers']['myhandler']['mykey'][123]``, and fall back -to ``config_dict['handlers']['myhandler']['mykey']['123']`` if that -fails. +文字列 ``'cfg://handlers'`` は、キー ``handlers`` をもつ辞書であると +分析され、文字列 ``'cfg://handlers.email'`` は、 ``handlers`` 辞書内の、 +``email`` キーをもつ辞書であると分析されます。文字列 +``'cfg://handlers.email.toaddrs[1]`` は、 ``'dev_team****@domai*****'`` と +分析され、 ``'cfg://handlers.email.toaddrs[0]'`` は値 +``'support_team****@domai*****'`` と分析されます。 ``subject`` の値には、 +``'cfg://handlers.email.subject'`` または等価な +``'cfg://handlers.email[subject]'`` でアクセスできます。 +後者が必要なのは、キーがスペースや非アルファベット文字を含むときのみです。 +インデクス値が十進数時のみで成り立っているなら、まず対応する整数値を使って +アクセスが試みられ、必要なら文字列値で代替します。 + +文字列 ``cfg://handlers.myhandler.mykey.123`` が与えられると、これは +``config_dict['handlers']['myhandler']['mykey']['123']`` と分析されます。 +文字列が ``cfg://handlers.myhandler.mykey[123]`` と指定されたら、 +システムは ``config_dict['handlers']['myhandler']['mykey'][123]`` から +値を引き出そうとし、失敗したら +``config_dict['handlers']['myhandler']['mykey']['123']`` で代替します。 .. _logging-config-fileformat: -Configuration file format -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The configuration file format understood by :func:`fileConfig` is based on -:mod:`configparser` functionality. The file must contain sections called -``[loggers]``, ``[handlers]`` and ``[formatters]`` which identify by name the -entities of each type which are defined in the file. For each such entity, there -is a separate section which identifies how that entity is configured. Thus, for -a logger named ``log01`` in the ``[loggers]`` section, the relevant -configuration details are held in a section ``[logger_log01]``. Similarly, a -handler called ``hand01`` in the ``[handlers]`` section will have its -configuration held in a section called ``[handler_hand01]``, while a formatter -called ``form01`` in the ``[formatters]`` section will have its configuration -specified in a section called ``[formatter_form01]``. The root logger -configuration must be specified in a section called ``[logger_root]``. - -Examples of these sections in the file are given below. :: +環境設定ファイルの書式 +^^^^^^^^^^^^^^^^^^^^^^ + +:func:`fileConfig` が解釈できる環境設定ファイルの形式 は、 :mod:`ConfigParser` の機能に基づいています。 +ファイルには、 ``[loggers]``, ``[handlers]``, ``[formatters]`` といったセク ションが入っていなければならず、 +各セクションではファイル中で定義されている各タイプのエンティティを名前で指 定しています。こうしたエンティティの各々について、 +そのエンティティをどう設定するかを示した個別のセクションがあります。 +すなわち、 ``log01`` という名前の ``[loggers]`` セクションにあるロガーに対 しては、 +対応する詳細設定がセクション ``[logger_log01]`` に収められています。 +同様に、 ``hand01`` という名前の ``[handlers]`` セクションにあるハンドラは +``[handler_hand01]`` と呼ばれるセクションに設定をもつことになり、 +``[formatters]`` セクションにある ``form01`` は ``[formatter_form01]`` と いうセクションで設定が指定されています。 +ルートロガーの設定は ``[logger_root]`` と呼ばれるセクションで指定されていな ければなりません。 + +ファイルにおけるこれらのセクションの例を以下に示します:: [loggers] keys=root,log02,log03,log04,log05,log06,log07 @@ -545,25 +514,22 @@ [formatters] keys=form01,form02,form03,form04,form05,form06,form07,form08,form09 -The root logger must specify a level and a list of handlers. An example of a -root logger section is given below. :: +ルートロガーでは、レベルとハンドラのリストを指定しなければなりません。 +ルートロガーのセクションの例を以下に示します:: [logger_root] level=NOTSET handlers=hand01 -The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or -``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be -logged. Level values are :func:`eval`\ uated in the context of the ``logging`` -package's namespace. - -The ``handlers`` entry is a comma-separated list of handler names, which must -appear in the ``[handlers]`` section. These names must appear in the -``[handlers]`` section and have corresponding sections in the configuration -file. - -For loggers other than the root logger, some additional information is required. -This is illustrated by the following example. :: +``level`` エントリは ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` のうちの一つ か、 ``NOTSET`` になります。 +ルートロガーの場合にのみ、 ``NOTSET`` はすべてのメッセージがログ記録される ことを意味します。 +レベル値は ``logging`` パッケージの名前空間のコンテキストにおい て :func:`eval` されます。 + +``handlers`` エントリはコンマで区切られたハンドラ名からなるリストで、 ``[handlers]`` セクションになくてはなりません。 +また、これらの各ハンドラの名前に対応するセクションが設定ファイルに存在しな ければなりません。 + +ルートロガー以外のロガーでは、いくつか追加の情報が必要になります。 +これは以下の例のように表されます:: [logger_parser] level=DEBUG @@ -571,17 +537,15 @@ propagate=1 qualname=compiler.parser -The ``level`` and ``handlers`` entries are interpreted as for the root logger, -except that if a non-root logger's level is specified as ``NOTSET``, the system -consults loggers higher up the hierarchy to determine the effective level of the -logger. The ``propagate`` entry is set to 1 to indicate that messages must -propagate to handlers higher up the logger hierarchy from this logger, or 0 to -indicate that messages are **not** propagated to handlers up the hierarchy. The -``qualname`` entry is the hierarchical channel name of the logger, that is to -say the name used by the application to get the logger. - -Sections which specify handler configuration are exemplified by the following. -:: +``level`` および ``handlers`` エントリはルートロガーのエントリと同様に解釈 されますが、 +非ルートロガーのレベルが ``NOTSET`` に指定された場合、 +ロギングシステムはロガー階層のより上位のロガーにロガーの実効レベルを問い合 わせるところが違います。 +``propagate`` エントリは、メッセージをロガー階層におけるこのロガーの上位の ハンドラに伝播させることを示す 1 に設定されるか、 +メッセージを階層の上位に伝播 **しない** ことを示す 0 に設定されます。 +``qualname`` エントリはロガーのチャネル名を階層的に表したもの、 +すなわちアプリケーションがこのロガーを取得する際に使う名前になります。 + +ハンドラの環境設定を指定しているセクションは以下の例のようになります:: [handler_hand01] class=StreamHandler @@ -589,23 +553,21 @@ formatter=form01 args=(sys.stdout,) -The ``class`` entry indicates the handler's class (as determined by :func:`eval` -in the ``logging`` package's namespace). The ``level`` is interpreted as for -loggers, and ``NOTSET`` is taken to mean 'log everything'. +``class`` エントリはハンドラのクラス (``logging`` パッケージの名前空間にお いて :func:`eval` で決定されます) を示します。 +``level`` はロガーの場合と同じように解釈され、 ``NOTSET`` は "すべてを記録 する (log everything)" と解釈されます。 .. versionchanged:: 2.6 - Added support for resolving the handler’s class as a dotted module and - class name. - -The ``formatter`` entry indicates the key name of the formatter for this -handler. If blank, a default formatter (``logging._defaultFormatter``) is used. -If a name is specified, it must appear in the ``[formatters]`` section and have -a corresponding section in the configuration file. - -The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging`` -package's namespace, is the list of arguments to the constructor for the handler -class. Refer to the constructors for the relevant handlers, or to the examples -below, to see how typical entries are constructed. :: + ハンドラクラスのドット区切りモジュールおよびクラス名としての解決のサポー トが追加された。 + +``formatter`` エントリはこのハンドラのフォーマッタに対するキー名を表しま す。 +空文字列の場合、デフォルトのフォーマッタ (``logging._defaultFormatter``) が 使われます。 +名前が指定されている場合、その名前は ``[formatters]`` セクションになくては ならず、 +対応するセクションが設定ファイル中になければなりません。 + +``args`` エントリは、 ``logging`` パッケージの名前空間のコンテキスト で :func:`eval` される際、 +ハンドラクラスのコンストラクタに対する引数からなるリストになります。 +典型的なエントリがどうやって作成されるかについては、 +対応するハンドラのコンストラクタか、以下の例を参照してください:: [handler_hand02] class=FileHandler @@ -656,32 +618,30 @@ formatter=form09 args=('localhost:9022', '/log', 'GET') -Sections which specify formatter configuration are typified by the following. :: +フォーマッタの環境設定を指定しているセクションは以下のような形式です:: [formatter_form01] format=F1 %(asctime)s %(levelname)s %(message)s datefmt= class=logging.Formatter -The ``format`` entry is the overall format string, and the ``datefmt`` entry is -the :func:`strftime`\ -compatible date/time format string. If empty, the -package substitutes ISO8601 format date/times, which is almost equivalent to -specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. The ISO8601 format -also specifies milliseconds, which are appended to the result of using the above -format string, with a comma separator. An example time in ISO8601 format is -``2003-01-23 00:29:50,411``. - -The ``class`` entry is optional. It indicates the name of the formatter's class -(as a dotted module and class name.) This option is useful for instantiating a -:class:`Formatter` subclass. Subclasses of :class:`Formatter` can present -exception tracebacks in an expanded or condensed format. +``format`` エントリは全体を書式化する文字列で、 ``datefmt`` エントリ は :func:`strftime` 互換の日付/時刻書式化文字列です。 +空文字列の場合、パッケージによって ISO8601 形式の日付/時刻に置き換えられ、 +日付書式化文字列 ``"%Y-%m-%d %H:%M:%S"`` を指定した場合とほとんど同じになり ます。 +ISO8601 形式ではミリ秒も指定しており、上の書式化文字列の結果にカンマで区切 って追加されます。 +ISO8601 形式の時刻の例は ``2003-01-23 00:29:50,411`` です。 + +``class`` エントリはオプションです。 ***The diff for this file has been truncated for email.*** ======================================= --- /library/logging.handlers.rst Fri Oct 28 23:01:19 2011 +++ /library/logging.handlers.rst Sun Nov 20 06:46:59 2011 @@ -1,8 +1,8 @@ -:mod:`logging.handlers` --- Logging handlers +:mod:`logging.handlers` --- ロギングハンドラ ============================================ .. module:: logging.handlers - :synopsis: Handlers for the logging module. + :synopsis: logging モジュールのためのハンドラ .. moduleauthor:: Vinay Sajip <vinay_sajip****@red-d*****> @@ -10,81 +10,82 @@ .. sidebar:: Important - This page contains only reference information. For tutorials, - please see - - * :ref:`Basic Tutorial <logging-basic-tutorial>` - * :ref:`Advanced Tutorial <logging-advanced-tutorial>` - * :ref:`Logging Cookbook <logging-cookbook>` + このページには、リファレンス情報だけが含まれています。 + チュートリアルは、以下のページを参照してください + + * :ref:`基本チュートリアル <logging-basic-tutorial>` + * :ref:`上級チュートリアル <logging-advanced-tutorial>` + * :ref:`ロギングクックブック <logging-cookbook>` .. currentmodule:: logging -The following useful handlers are provided in the package. Note that three of -the handlers (:class:`StreamHandler`, :class:`FileHandler` and -:class:`NullHandler`) are actually defined in the :mod:`logging` module itself, -but have been documented here along with the other handlers. +このパッケージでは、以下の便利なハンドラが提供されています。なお、これらの +ハンドラのうち、3 つ (:class:`StreamHandler`, :class:`FileHandler` および +:class:`NullHandler`) は、実際には :mod:`logging` モジュール自身で +定義されていますが、他のハンドラと一緒にここでドキュメント化します。 .. _stream-handler: StreamHandler ^^^^^^^^^^^^^ -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` -and :meth:`flush` methods). +:mod:`logging` コアパッケージに含まれる :class:`StreamHandler` クラスは、 +ログ出力を *sys.stdout*, *sys.stderr* あるいは何らかのファイル風 (file-like) オブジェクト +(あるいは、より正確に言えば :meth:`write` および :meth:`flush` メソッドをサ ポートする何らかのオブジェクト) +といったストリームに送信します。 .. class:: StreamHandler(stream=None) - Returns a new instance of the :class:`StreamHandler` class. If *stream* is - specified, the instance will use it for logging output; otherwise, *sys.stderr* - will be used. + :class:`StreamHandler` クラスの新たなインスタンスを返します。 + *stream* が指定された場合、インスタンスはログ出力先として指定されたスト リームを使います; + そうでない場合、 *sys.stderr* が使われます。 .. method:: emit(record) - If a formatter is specified, it is used to format the record. The record - is then written to the stream with a newline terminator. If exception - information is present, it is formatted using - :func:`traceback.print_exception` and appended to the stream. + フォーマッタが指定されていれば、フォーマッタを使ってレコードを書式化 します。 + 次に、レコードがストリームに書き込まれ、末端に改行がつけられます。 + 例外情報が存在する場合、 :func:`traceback.print_exception` を使って書 式化され、 + ストリームの末尾につけられます。 .. method:: flush() - Flushes the stream by calling its :meth:`flush` method. Note that the - :meth:`close` method is inherited from :class:`Handler` and so does - no output, so an explicit :meth:`flush` call may be needed at times. + ストリームの :meth:`flush` メソッドを呼び出してバッファをフラッシュし ます。 + :meth:`close` メソッドは :class:`Handler` から継承しているため何も出 力を行わないので、 + :meth:`flush` 呼び出しを明示的に行う必要があるかもしれません。 .. _file-handler: FileHandler ^^^^^^^^^^^ -The :class:`FileHandler` class, located in the core :mod:`logging` package, -sends logging output to a disk file. It inherits the output functionality from -:class:`StreamHandler`. +:mod:`logging` コアパッケージに含まれる :class:`FileHandler` クラスは、 +ログ出力をディスク上のファイルに送信します。 +このクラスは出力機能を :class:`StreamHandler` から継承しています。 .. class:: FileHandler(filename, mode='a', encoding=None, delay=False) - Returns a new instance of the :class:`FileHandler` class. The specified file is - opened and used as the stream for logging. If *mode* is not specified, - :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file - with that encoding. If *delay* is true, then file opening is deferred until the - first call to :meth:`emit`. By default, the file grows indefinitely. + :class:`FileHandler` クラスの新たなインスタンスを返します。 + 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 + *mode* が指定されなかった場合、 :const:`'a'` が使われます。 + *encoding* が *None* でない場合、その値はファイルを開くときのエンコーデ ィングとして使われます。 + *delay* が true ならば、ファイルを開くのは最初の :meth:`emit` 呼び出しま で遅らせられます。 + デフォルトでは、ファイルは無制限に大きくなりつづけます。 .. versionchanged:: 2.6 - *delay* was added. + *delay* が追加されました。 .. method:: close() - Closes the file. + ファイルを閉じます。 .. method:: emit(record) - Outputs the record to the file. + *record* をファイルに出力します。 .. _null-handler: @@ -94,30 +95,30 @@ .. versionadded:: 2.7 -The :class:`NullHandler` class, located in the core :mod:`logging` package, -does not do any formatting or output. It is essentially a 'no-op' handler -for use by library developers. +:mod:`logging` コアパッケージに含まれる :class:`NullHandler` クラスは、 +いかなるフォーマット化も出力も行いません。これは本質的には、ライブラリ開発 者に +使われる 'no-op' ハンドラです。 .. class:: NullHandler() - Returns a new instance of the :class:`NullHandler` class. + :class:`NullHandler` クラスの新しいインスタンスを返します。 .. method:: emit(record) - This method does nothing. + このメソッドは何もしません。 .. method:: handle(record) - This method does nothing. + このメソッドは何もしません。 .. method:: createLock() - This method returns ``None`` for the lock, since there is no - underlying I/O to which access needs to be serialized. + アクセスが特殊化される必要がある I/O が下にないので、 + このメソッドはロックに対して ``None`` を返します。 -See :ref:`library-config` for more information on how to use -:class:`NullHandler`. +:class:`NullHandler` の使い方の詳しい情報は、 :ref:`library-config` を +参照してください。 .. _watched-file-handler: @@ -128,154 +129,152 @@ .. versionadded:: 2.6 -The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers` -module, is a :class:`FileHandler` which watches the file it is logging to. If -the file changes, it is closed and reopened using the file name. - -A file change can happen because of usage of programs such as *newsyslog* and -*logrotate* which perform log file rotation. This handler, intended for use -under Unix/Linux, watches the file to see if it has changed since the last emit. -(A file is deemed to have changed if its device or inode have changed.) If the -file has changed, the old file stream is closed, and the file opened to get a -new stream. - -This handler is not appropriate for use under Windows, because under Windows -open log files cannot be moved or renamed - logging opens the files with -exclusive locks - and so there is no need for such a handler. Furthermore, -*ST_INO* is not supported under Windows; :func:`stat` always returns zero for -this value. +:mod:`logging.handlers` モジュールに含まれる :class:`WatchedFileHandler` ク ラスは、 +ログ記録先のファイルを監視する :class:`FileHandler` の一種です。 +ファイルが変更された場合、ファイルを閉じてからファイル名を使って開き直しま す。 + +ファイルはログファイルをローテーションさせる *newsyslog* や +*logrotate* のようなプログラムを使うことで変更されることがあります。 +このハンドラは、 Unix/Linux で使われることを意図していますが、 +ファイルが最後にログを出力してから変わったかどうかを監視します。 +(ファイルはデバイスや inode が変わることで変わったと判断します。) +ファイルが変わったら古いファイルのストリームは閉じて、 +現在のファイルを新しいストリームを取得するために開きます。 + +このハンドラを Windows で使うことは適切ではありません。 +というのも Windows では開いているログファイルを移動したり削除したりできない からです - +logging はファイルを排他的ロックを掛けて開きます - そのためこうしたハンドラ は必要ないのです。 +さらに、 Windows では *ST_INO* がサポートされていません +(:func:`stat` はこの値として常に 0 を返します)。 .. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]]) - Returns a new instance of the :class:`WatchedFileHandler` class. The specified - file is opened and used as the stream for logging. If *mode* is not specified, - :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file - with that encoding. If *delay* is true, then file opening is deferred until the - first call to :meth:`emit`. By default, the file grows indefinitely. + :class:`WatchedFileHandler` クラスの新たなインスタンスを返します。 + 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 + *mode* が指定されなかった場合、 :const:`'a'` が使われます。 + *encoding* が *None* でない場合、その値はファイルを開くときのエンコーデ ィングとして使われます。 + *delay* が true ならば、ファイルを開くのは最初の :meth:`emit` 呼び出しま で遅らせられます。 + デフォルトでは、ファイルは無制限に大きくなりつづけます。 .. method:: emit(record) - Outputs the record to the file, but first checks to see if the file has - changed. If it has, the existing stream is flushed and closed and the - file opened again, before outputting the record to the file. + レコードをファイルに出力しますが、その前にファイルが変更されていない かチェックします。 + もし変更されていれば、レコードをファイルに出力する前に、 + 既存のストリームはフラッシュして閉じられ、ファイルが再度開かれます。 .. _rotating-file-handler: RotatingFileHandler ^^^^^^^^^^^^^^^^^^^ -The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers` -module, supports rotation of disk log files. +:mod:`logging.handlers` モジュールに含まれる :class:`RotatingFileHandler` クラスは、 +ディスク上のログファイルに対するローテーション処理をサポートします。 .. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0) - Returns a new instance of the :class:`RotatingFileHandler` class. The specified - file is opened and used as the stream for logging. If *mode* is not specified, - ``'a'`` is used. If *encoding* is not *None*, it is used to open the file - with that encoding. If *delay* is true, then file opening is deferred until the - first call to :meth:`emit`. By default, the file grows indefinitely. - - You can use the *maxBytes* and *backupCount* values to allow the file to - :dfn:`rollover` at a predetermined size. When the size is about to be exceeded, - the file is closed and a new file is silently opened for output. Rollover occurs - whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is - zero, rollover never occurs. If *backupCount* is non-zero, the system will save - old log files by appending the extensions '.1', '.2' etc., to the filename. For - example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you - would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to - :file:`app.log.5`. The file being written to is always :file:`app.log`. When - this file is filled, it is closed and renamed to :file:`app.log.1`, and if files - :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to - :file:`app.log.2`, :file:`app.log.3` etc. respectively. + :class:`RotatingFileHandler` クラスの新たなインスタンスを返します。 + 指定されたファイルが開かれ、ログ記録のためのストリームとして使われます。 + *mode* が指定されなかった場合、 :const:`'a'` が使われます。 + *encoding* が *None* でない場合、その値はファイルを開くときのエンコーデ ィングとして使われます。 + *delay* が true ならば、ファイルを開くのは最初の :meth:`emit` 呼び出しま で遅らせられます。 + デフォルトでは、ファイルは無制限に大きくなりつづけます。 + + *maxBytes* および *backupCount* 値を指定することで、 + あらかじめ決められたサイズでファイルをロールオーバ (:dfn:`rollover`) さ せることができます。 + 指定サイズを超えそうになると、ファイルは閉じられ、暗黙のうちに新たなファ イルが開かれます。 + ロールオーバは現在のログファイルの長さが *maxBytes* に近くなると常に起き ます。 + *backupCount* が非ゼロの場合、システムは古いログファイルをファイル名 に ".1", ".2" といった拡張子を追加して保存します。 + 例えば、 *backupCount* が 5 で、基本のファイル名が :file:`app.log` な ら、 :file:`app.log`, + :file:`app.log.1`, :file:`app.log.2` ... と続き、 :file:`app.log.5` まで を得ることになります。 + ログの書き込み対象になるファイルは常に :file:`app.log` です。 + このファイルが満杯になると、ファイルは閉じられ、 :file:`app.log.1` に名 前が変更されます。 + :file:`app.log.1`, :file:`app.log.2` などが存在する場合、 + それらのファイルはそれぞれ :file:`app.log.2`, :file:`app.log.3` といった 具合に名前が変更されます。 .. versionchanged:: 2.6 - *delay* was added. + *delay* が追加されました。 .. method:: doRollover() - Does a rollover, as described above. + 上述のような方法でロールオーバを行います。 .. method:: emit(record) - Outputs the record to the file, catering for rollover as described - previously. + 上述のようなロールオーバを行いながら、レコードをファイルに出力しま す。 .. _timed-rotating-file-handler: TimedRotatingFileHandler ^^^^^^^^^^^^^^^^^^^^^^^^ -The :class:`TimedRotatingFileHandler` class, located in the -:mod:`logging.handlers` module, supports rotation of disk log files at certain -timed intervals. +:mod:`logging.handlers` モジュールに含まれ る :class:`TimedRotatingFileHandler` クラスは、 +特定の時間間隔でのログローテーションをサポートしています。 .. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False) - Returns a new instance of the :class:`TimedRotatingFileHandler` class. The - specified file is opened and used as the stream for logging. On rotating it also - sets the filename suffix. Rotating happens based on the product of *when* and - *interval*. - - You can use the *when* to specify the type of *interval*. The list of possible - values is below. Note that they are not case sensitive. - - +----------------+-----------------------+ - | Value | Type of interval | - +================+=======================+ - | ``'S'`` | Seconds | - +----------------+-----------------------+ - | ``'M'`` | Minutes | - +----------------+-----------------------+ - | ``'H'`` | Hours | - +----------------+-----------------------+ - | ``'D'`` | Days | - +----------------+-----------------------+ - | ``'W'`` | Week day (0=Monday) | - +----------------+-----------------------+ - | ``'midnight'`` | Roll over at midnight | - +----------------+-----------------------+ - - The system will save old log files by appending extensions to the filename. - 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. - - 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. - - If *backupCount* is nonzero, at most *backupCount* files - will be kept, and if more would be created when rollover occurs, the oldest - one is deleted. The deletion logic uses the interval to determine which - files to delete, so changing the interval may leave old files lying around. - - If *delay* is true, then file opening is deferred until the first call to - :meth:`emit`. + :class:`TimedRotatingFileHandler` クラスの新たなインスタンスを返します。 + *filename* に指定したファイルを開き、ログ出力先のストリームとして使いま す。 + ログファイルのローテーション時には、ファイル名に拡張子 (suffix) をつけま す。 + ログファイルのローテーションは *when* および *interval* の積に基づいて行 います。 + + *when* は *interval* の単位を指定するために使います。 + 使える値は下表の通りです。大小文字の区別は行いません: + + +----------------+-------------------+ + | 値 | *interval* の単位 | + +================+===================+ + | ``'S'`` | 秒 | + +----------------+-------------------+ + | ``'M'`` | 分 | + +----------------+-------------------+ + | ``'H'`` | 時間 | + +----------------+-------------------+ + | ``'D'`` | 日 | + +----------------+-------------------+ + | ``'W'`` | 曜日 (0=Monday) | + +----------------+-------------------+ + | ``'midnight'`` | 深夜 | + +----------------+-------------------+ + + 古いログファイルを保存する際にロギングシステムは拡張子を付けます。 + 拡張子は日付と時間に基づいて、 strftime の ``%Y-%m-%d_%H-%M-%S`` 形式か その前方の一部を、 + ロールオーバ間隔に依存した形で使います。 + + 最初に次のロールオーバー時間を計算するとき (ハンドラが生成されるとき)、 + 次のローテーションがいつ起こるかを計算するために、 + 既存のログファイルの最終変更時刻または現在の時間が使用されます。 + + *utc* 引数が true の場合時刻は UTC になり、それ以外では現地時間が使われ ます。 + + *backupCount* がゼロでない場合、保存されるファイル数は高々 *backupCount* 個で、 + それ以上のファイルがロールオーバされる時に作られるならば、一番古いものが 削除されます。 + 削除のロジックは interval で決まるファイルを削除するので、 + interval を変えると古いファイルが残ったままになることもあります。 + + *delay* が true なら、ファイルを開くのは :meth:`emit` の最初の呼び出しま で延期されます。 .. versionchanged:: 2.6 - *delay* was added. + *delay* が追加されました。 .. versionchanged:: 2.7 - *utc* was added. + *utc* が追加されました。 .. method:: doRollover() - Does a rollover, as described above. + 上述の方法でロールオーバを行います。 .. method:: emit(record) Outputs the record to the file, catering for rollover as described above. + 上で説明した方法でロールオーバを行いながら、レコードをファイルに出力 します。 .. _socket-handler: @@ -283,82 +282,80 @@ SocketHandler ^^^^^^^^^^^^^ -The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module, -sends logging output to a network socket. The base class uses a TCP socket. +:mod:`logging.handlers` モジュールに含まれる :class:`SocketHandler` クラス は、 +ログ出力をネットワークソケットに送信します。基底クラスでは TCP ソケットを用 います。 .. class:: SocketHandler(host, port) - Returns a new instance of the :class:`SocketHandler` class intended to - communicate with a remote machine whose address is given by *host* and *port*. + アドレスが *host* および *port* で与えられた遠隔のマシンと通信するように した + :class:`SocketHandler` クラスのインスタンスを生成して返します。 .. method:: close() - Closes the socket. + ソケットを閉じます。 .. method:: emit() - Pickles the record's attribute dictionary and writes it to the socket in - binary format. If there is an error with the socket, silently drops the - packet. If the connection was previously lost, re-establishes the - connection. To unpickle the record at the receiving end into a - :class:`LogRecord`, use the :func:`makeLogRecord` function. + レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みま す。 + ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられま す。 + 事前に接続が失われていた場合、接続を再度確立します。 + 受信端でレコードを unpickle して :class:`LogRecord` にするには、 + :func:`makeLogRecord` 関数を使ってください。 .. method:: handleError() - Handles an error which has occurred during :meth:`emit`. The most likely - cause is a lost connection. Closes the socket so that we can retry on the - next event. + :meth:`emit` の処理中に発生したエラーを処理します。 + よくある原因は接続の消失です。 + 次のイベント発生時に再試行できるようにソケットを閉じます。 .. method:: makeSocket() - This is a factory method which allows subclasses to define the precise - type of socket they want. The default implementation creates a TCP socket - (:const:`socket.SOCK_STREAM`). + サブクラスで必要なソケット形式を詳細に定義できるようにするためのファ クトリメソッドです。 + デフォルトの実装では、 TCP ソケット (:const:`socket.SOCK_STREAM`) を 生成します。 .. method:: makePickle(record) - Pickles the record's attribute dictionary in binary format with a length - prefix, and returns it ready for transmission across the socket. - - 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 してから先頭に長さ情報を付けてバイナリ形 式にして、 + ソケットを介して送信できるようにして返します。 + + pickle が完全に安全というわけではないことに注意してください。 + セキュリティに関して心配なら、より安全なメカニズムを実装するためにこ のメソッドをオーバーライドすると良いでしょう。 + 例えば、 HMAC を使って pickle に署名して、受け取る側ではそれを検証す ることができます。 + あるいはまた、受け取る側でグローバルなオブジェクトの unpickle を無効 にすることができます。 .. method:: send(packet) - Send a pickled string *packet* to the socket. This function allows for - partial sends which can happen when the network is busy. + pickle された文字列 *packet* をソケットに送信します。 + この関数はネットワークがビジーの時に発生する部分的送信に対応していま す。 .. method:: createSocket() - Tries to create a socket; on failure, uses an exponential back-off - algorithm. On intial failure, the handler will drop the message it was - trying to send. When subsequent messages are handled by the same - instance, it will not try connecting until some time has passed. The - default parameters are such that the initial delay is one second, and if - after that delay the connection still can't be made, the handler will - double the delay each time up to a maximum of 30 seconds. - - This behaviour is controlled by the following handler attributes: - - * ``retryStart`` (initial delay, defaulting to 1.0 seconds). - * ``retryFactor`` (multiplier, defaulting to 2.0). - * ``retryMax`` (maximum delay, defaulting to 30.0 seconds). - - This means that if the remote listener starts up *after* the handler has - been used, you could lose messages (since the handler won't even attempt - a connection until the delay has elapsed, but just silently drop messages - during the delay period). + ソケットの生成を試みます。失敗時には、指数的な減速アルゴリズムを + 使います。最初の失敗時には、ハンドラは送ろうとしていたメッセージを + 落とします。続くメッセージが同じインスタンスで扱われたとき、 + 幾らかの時間が経過するまで接続を試みません。 + デフォルトのパラメタは、最初の遅延時間が 1 秒で、その遅延時間の後で + それでも接続が確保できないなら、遅延時間は 2 倍づつになり、 + 最大で 30 秒になります。 + + この働きは、以下のハンドラ属性で制御されます: + + * ``retryStart`` (最初の遅延時間、デフォルトは 1.0 秒)。 + * ``retryFactor`` (乗数、デフォルトは 2.0)。 + * ``retryMax`` (最大遅延時間、デフォルトは 30.0 秒)。 + + これは、リモートリスナがハンドラが使われた *後に* 起動すると、 + (ハンドラは遅延が経過するまで接続を試みようとさえせず、遅延時間中に黙 って + メッセージを落とすだけなので) + メッセージが失われてしまうこともあるということです。 .. _datagram-handler: @@ -366,34 +363,34 @@ DatagramHandler ^^^^^^^^^^^^^^^ -The :class:`DatagramHandler` class, located in the :mod:`logging.handlers` -module, inherits from :class:`SocketHandler` to support sending logging messages -over UDP sockets. +:mod:`logging.handlers` モジュールに含まれる :class:`DatagramHandler` クラ スは、 +:class:`SocketHandler` を継承しており、 UDP ソケットを介したログ記録メッ セージの送信をサポートしています。 .. class:: DatagramHandler(host, port) - Returns a new instance of the :class:`DatagramHandler` class intended to - communicate with a remote machine whose address is given by *host* and *port*. + アドレスが *host* および *port* で与えられた遠隔のマシンと通信するように した + :class:`DatagramHandler` クラスのインスタンスを生成して返します。 .. method:: emit() - Pickles the record's attribute dictionary and writes it to the socket in - binary format. If there is an error with the socket, silently drops the - packet. To unpickle the record at the receiving end into a - :class:`LogRecord`, use the :func:`makeLogRecord` function. + レコードの属性辞書を pickle して、バイナリ形式でソケットに書き込みま す。 + ソケット操作でエラーが生じた場合、暗黙のうちにパケットは捨てられま す。 + 事前に接続が失われていた場合、接続を再度確立します。 + 受信端でレコードを unpickle して :class:`LogRecord` にするには、 + :func:`makeLogRecord` 関数を使ってください。 .. method:: makeSocket() - The factory method of :class:`SocketHandler` is here overridden to create - a UDP socket (:const:`socket.SOCK_DGRAM`). + ここで :class:`SocketHandler` のファクトリメソッドをオーバライドし て、 + UDP ソケット (:const:`socket.SOCK_DGRAM`) を生成しています。 .. method:: send(s) - Send a pickled string to a socket. + pickle された文字列をソケットに送信します。 .. _syslog-handler: @@ -401,61 +398,62 @@ SysLogHandler ^^^^^^^^^^^^^ -The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module, -supports sending logging messages to a remote or local Unix syslog. +:mod:`logging.handlers` モジュールに含まれる :class:`SysLogHandler` クラス は、 +ログ記録メッセージを遠隔またはローカルの Unix syslog に送信する機能をサポー トしています。 .. class:: SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM) - Returns a new instance of the :class:`SysLogHandler` class intended to - communicate with a remote Unix machine whose address is given by *address* in - the form of a ``(host, port)`` tuple. If *address* is not specified, - ``('localhost', 514)`` is used. The address is used to open a socket. An - alternative to providing a ``(host, port)`` tuple is providing an address as a - string, for example '/dev/log'. In this case, a Unix domain socket is used to - send the message to the syslog. If *facility* is not specified, - :const:`LOG_USER` is used. The type of socket opened depends on the - *socktype* argument, which defaults to :const:`socket.SOCK_DGRAM` and thus - opens a UDP socket. To open a TCP socket (for use with the newer syslog - daemons such as rsyslog), specify a value of :const:`socket.SOCK_STREAM`. - - Note that if your server is not listening on UDP port 514, - :class:`SysLogHandler` may appear not to work. In that case, check what - address you should be using for a domain socket - it's system dependent. - For example, on Linux it's usually '/dev/log' but on OS/X it's - '/var/run/syslog'. You'll need to check your platform and use the - appropriate address (you may need to do this check at runtime if your - application needs to run on several platforms). On Windows, you pretty - much have to use the UDP option. + 遠隔の Unix マシンと通信するための、 :class:`SysLogHandler` クラスの新た なインスタンスを返します。 + マシンのアドレスは ``(host, port)`` のタプル形式をとる *address* で与え られます。 + *address* が指定されない場合、 ``('localhost', 514)`` が使われます。 + アドレスは UDP ソケットを使って開かれます。 + ``(host, port)`` のタプル形式の代わりに文字列で "/dev/log" のように与え ることもできます。 + この場合、 Unix ドメインソケットが syslog にメッセージを送るのに使われま す。 + *facility* が指定されない場合、 :const:`LOG_USER` が使われます。 + 開かれるソケットの型は、 *socktype* 引数に依り、デフォルトは + :const:`socket.SOCK_DGRAM` で、UDP ソケットを開きます。 + (rsyslog のような新しい syslog デーモンと使うために) TCP ソケットを開く + には、 :const:`socket.SOCK_STREAM` の値を指定してください。 + + なお、あなたのサーバが UDP ポート 514 を聴取していないなら、 + :class:`SysLogHandler` が働かないことがあります。その場合は、 + あなたがドメインソケットに使うべきアドレスが何か調べてください - + これはシステム依存です。例えば、Linux システムでは通常 '/dev/log' です が、 + OS/X では '/var/run/syslog' です。あなたのプラットフォームを調べ、 + 適切なアドレスを使うことが必要になります (あなたのアプリケーションが + いくつかのプラットフォームで動く必要があるなら、これを実行時に + 確かめなければならないかもしれません)。 + Windows では、UDP オプションを使う必要性がかなり高いです。 .. versionchanged:: 2.7 - *socktype* was added. + *socktype* が追加されました。 .. method:: close() - Closes the socket to the remote host. + 遠隔ホストへのソケットを閉じます。 .. method:: emit(record) - The record is formatted, and then sent to the syslog server. If exception - information is present, it is *not* sent to the server. + レコードは書式化された後、 syslog サーバに送信されます。 + 例外情報が存在しても、サーバには *送信されません* 。 .. method:: encodePriority(facility, priority) - Encodes the facility and priority into an integer. You can pass in strings - or integers - if strings are passed, internal mapping dictionaries are - used to convert them to integers. - - The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and - mirror the values defined in the ``sys/syslog.h`` header file. - - **Priorities** + ファシリティおよび優先度を整数に符号化します。 + 値は文字列でも整数でも渡すことができます。 + 文字列が渡された場合、内部の対応付け辞書が使われ、整数に変換されま す。 + + シンボリックな ``LOG_`` 値は :class:`SysLogHandler` で定義されていま す。 + これは ``sys/syslog.h`` ヘッダーファイルで定義された値を反映していま す。 + + **優先度** +--------------------------+---------------+ - | Name (string) | Symbolic value| + | 名前 (文字列) | シンボル値 | +==========================+===============+ | ``alert`` | LOG_ALERT | +--------------------------+---------------+ @@ -474,10 +472,10 @@ | ``warn`` or ``warning`` | LOG_WARNING | +--------------------------+---------------+ - **Facilities** + **ファシリティ** +---------------+---------------+ - | Name (string) | Symbolic value| + | 名前 (文字列) | シンボル値 | +===============+===============+ | ``auth`` | LOG_AUTH | +---------------+---------------+ @@ -522,189 +520,181 @@ .. 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 優先度名に対応付けます。 + カスタムレベルを使用している場合や、 + デフォルトアルゴリズムがニーズに適していない場合には、 + このメソッドをオーバーライドする必要があるかもしれません。 + デフォルトアルゴリズムは、 ``DEBUG``, ``INFO``, ``WARNING``, + ``ERROR``, ``CRITICAL`` を等価な syslog 名に、 + 他のすべてのレベル名を "warning" に対応付けます。 .. _nt-eventlog-handler: NTEventLogHandler ^^^^^^^^^^^^^^^^^ -The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers` -module, supports sending logging messages to a local Windows NT, Windows 2000 or -Windows XP event log. Before you can use it, you need Mark Hammond's Win32 -extensions for Python installed. +:mod:`logging.handlers` モジュールに含まれる :class:`NTEventLogHandler` ク ラスは、 +ログ記録メッセージをローカルな Windows NT, Windows 2000, または Windows XP のイベントログに送信する機能をサポートします。 +この機能を使えるようにするには、 Mark Hammond による Python 用 Win32 拡張パ ッケージをインストールする必要があります。 .. class:: NTEventLogHandler(appname, dllname=None, logtype='Application') - Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is - used to define the application name as it appears in the event log. An - appropriate registry entry is created using this name. The *dllname* should give - the fully qualified pathname of a .dll or .exe which contains message - definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used - - this is installed with the Win32 extensions and contains some basic - placeholder message definitions. Note that use of these placeholders will make - your event logs big, as the entire message source is held in the log. If you - want slimmer logs, you have to pass in the name of your own .dll or .exe which - contains the message definitions you want to use in the event log). The - *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and - defaults to ``'Application'``. + :class:`NTEventLogHandler` クラスの新たなインスタンスを返します。 + *appname* はイベントログに表示する際のアプリケーション名を定義するために 使われます。 + この名前を使って適切なレジストリエントリが生成されます。 + *dllname* はログに保存するメッセージ定義の入った .dll または .exe ファ イルへの完全修飾パス名を与えなければなりません + (指定されない場合、 ``win32service.pyd`` が使われます - + このライブラリは Win32 拡張とともにインストールされ、いくつかのプレース ホルダとなるメッセージ定義を含んでいます)。 + これらのプレースホルダを利用すると、メッセージの発信源全体がログに記録さ れるため、 + イベントログは巨大になるので注意してください。 + *logtype* は ``Application``, ``System``, ``Security`` のいずれかで、 + デフォルトは ``Application`` です。 .. method:: close() - At this point, you can remove the application name from the registry as a - source of event log entries. However, if you do this, you will not be able - to see the events as you intended in the Event Log Viewer - it needs to be - able to access the registry to get the .dll name. The current version does - not do this. + 現時点では、イベントログエントリの発信源としてのアプリケーション名を レジストリから除去することはできます。 + しかしこれを行うと、イベントログビューアで意図した通りにログが見えな くなるでしょう - + これはイベントログが .dll 名を取得するためにレジストリにアクセスでき なければならないからです。 + 現在のバージョンではこの操作を行いません。 .. method:: emit(record) - Determines the message ID, event category and event type, and then logs - the message in the NT event log. + メッセージ ID\ 、イベントカテゴリ、イベント型を決定し、メッセージを NT イベントログに記録します。 .. method:: getEventCategory(record) - Returns the event category for the record. Override this if you want to - specify your own categories. This version returns 0. + レコードに対するイベントカテゴリを返します。 + 自作のカテゴリを指定したい場合、このメソッドをオーバライドしてくださ い。 + このクラスのバージョンのメソッドは 0 を返します。 .. method:: getEventType(record) - Returns the event type for the record. Override this if you want to - specify your own types. This version does a mapping using the handler's - typemap attribute, which is set up in :meth:`__init__` to a dictionary - which contains mappings for :const:`DEBUG`, :const:`INFO`, - :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using - your own levels, you will either need to override this method or place a - suitable dictionary in the handler's *typemap* attribute. + レコードのイベント型を返します。 + 自作の型を指定したい場合、このメソッドをオーバライドしてください。 + このクラスのバージョンのメソッドは、ハンドラの *typemap* 属性を使って 対応付けを行います。 + この属性は :meth:`__init__` で初期化さ れ、 :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, + :const:`ERROR`, :const:`CRITICAL` が入っています。 + 自作のレベルを使っているのなら、このメソッドをオーバライドするか、 + ハンドラの *typemap* 属性に適切な辞書を配置する必要があるでしょう。 .. method:: getMessageID(record) - Returns the message ID for the record. If you are using your own messages, - you could do this by having the *msg* passed to the logger being an ID - rather than a format string. Then, in here, you could use a dictionary - lookup to get the message ID. This version returns 1, which is the base - message ID in :file:`win32service.pyd`. + レコードのメッセージ ID を返します。 + 自作のメッセージを使っているのなら、ロガーに渡される *msg* を書式化文 字列ではなく ID にします。 + その上で、辞書参照を行ってメッセージ ID を得ます。 + このクラスのバージョンでは 1 を返します。 + この値は :file:`win32service.pyd` における基本メッセージ ID です。 .. _smtp-handler: SMTPHandler ^^^^^^^^^^^ -The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module, -supports sending logging messages to an email address via SMTP. +:mod:`logging.handlers` モジュールに含まれる :class:`SMTPHandler` クラス は、 +SMTP を介したログ記録メッセージの送信機能をサポートします。 .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None) - Returns a new instance of the :class:`SMTPHandler` class. The instance is - initialized with the from and to addresses and subject line of the email. - The *toaddrs* should be a list of strings. To specify a non-standard SMTP - port, use the (host, port) tuple format for the *mailhost* argument. If you - use a string, the standard SMTP port is used. If your SMTP server requires - authentication, you can specify a (username, password) tuple for the - *credentials* argument. If *secure* is True, then the handler will attempt - to use TLS for the email transmission. + 新たな :class:`SMTPHandler` クラスのインスタンスを返します。 + インスタンスは email の from および to アドレス行、および subject 行とと もに初期化されます。 + *toaddrs* は文字列からなるリストでなければなりません。 + 非標準の SMTP ポートを指定するには、 *mailhost* 引数に (host, port) の タプル形式を指定します。 + 文字列を使った場合、標準の SMTP ポートが使われます。 + もし SMTP サーバが認証を必要とするならば、 (username, password) のタプル 形式を + *credentials* 引数に指定することができます。 + *secure* が真であれば、ハンドラは email の伝達に TLS を使おうと試みま す。 .. versionchanged:: 2.6 - *credentials* was added. + *credentials* が追加されました。 .. versionchanged:: 2.7 - *secure* was added. + *secure* が追加されました。 .. method:: emit(record) - Formats the record and sends it to the specified addressees. + レコードを書式化し、指定されたアドレスに送信します。 .. method:: getSubject(record) - If you want to specify a subject line which is record-dependent, override - this method. + レコードに応じたサブジェクト行を指定したいなら、このメソッドをオーバ ライドしてください。 .. _memory-handler: MemoryHandler ^^^^^^^^^^^^^ -The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module, -supports buffering of logging records in memory, periodically flushing them to a -:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an -event of a certain severity or greater is seen. - -:class:`MemoryHandler` is a subclass of the more general -:class:`BufferingHandler`, which is an abstract class. This buffers logging -records in memory. Whenever each record is added to the buffer, a check is made -by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it -should, then :meth:`flush` is expected to do the needful. +:mod:`logging.handlers` モジュールに含まれる :class:`MemoryHandler` は、 +ログ記録するレコードをメモリ上にバッファリングし、 +定期的にその内容をターゲット (:dfn:`target`) となるハンドラにフラッシュする 機能をサポートしています。 +フラッシュ処理はバッファが一杯になるか、 +ある深刻度かそれ以上のレベルを持つイベントが観測された際に行われます。 + +:class:`MemoryHandler` はより一般的な抽象クラ ス、 :class:`BufferingHandler` のサブクラスです。 +この抽象クラスでは、ログ記録するレコードをメモリ上にバッファリングします。 +各レコードがバッファに追加される毎に、 :meth:`shouldFlush` を呼び出してバッ ファをフラッシュすべきかどうか調べます。 +フラッシュする必要がある場合、 :meth:`flush` が必要にして十分な処理を行うも のと想定しています。 .. class:: BufferingHandler(capacity) - Initializes the handler with a buffer of the specified capacity. + 指定した許容量のバッファでハンドラを初期化します。 .. method:: emit(record) - Appends the record to the buffer. If :meth:`shouldFlush` returns true, - calls :meth:`flush` to process the buffer. + レコードをバッファに追加します。 + :meth:`shouldFlush` が true を返す場合、バッファを処理するため に :meth:`flush` を呼び出します。 .. method:: flush() - You can override this to implement custom flushing behavior. This version - just zaps the buffer to empty. + このメソッドをオーバライドして、自作のフラッシュ動作を実装することが できます。 + このクラスのバージョンのメソッドでは、単にバッファの内容を削除して空 にします。 .. method:: shouldFlush(record) - Returns true if the buffer is up to capacity. This method can be - overridden to implement custom flushing strategies. + バッファが許容量に達している場合に true を返します。 + このメソッドは自作のフラッシュ処理方針を実装するためにオーバライドす ることができます。 .. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None) - Returns a new instance of the :class:`MemoryHandler` class. The instance is - initialized with a buffer size of *capacity*. If *flushLevel* is not specified, - :const:`ERROR` is used. If no *target* is specified, the target will need to be - set using :meth:`setTarget` before this handler does anything useful. + :class:`MemoryHandler` クラスの新たなインスタンスを返します。 + インスタンスはサイズ *capacity* のバッファとともに初期化されます。 + *flushLevel* が指定されていない場合、 :const:`ERROR` が使われます。 + *target* が指定されていない場合、ハンドラが何らかの意味のある処理を行う 前に + :meth:`setTarget` でターゲットを指定する必要があります。 .. method:: close() - Calls :meth:`flush`, sets the target to :const:`None` and clears the - buffer. + :meth:`flush` を呼び出し、ターゲットを :const:`None` に設定してバッフ ァを消去します。 .. method:: flush() - For a :class:`MemoryHandler`, flushing means just sending the buffered - records to the target, if there is one. The buffer is also cleared when - this happens. Override if you want different behavior. + :class:`MemoryHandler` の場合、フラッシュ処理は単に、バッファされたレ コードをターゲットがあれば送信することを意味します。 + これと異なる動作を行いたい場合、オーバライドしてください。 .. method:: setTarget(target) - .. versionchanged:: 2.6 - *credentials* was added. - - - Sets the target handler for this handler. + + ターゲットハンドラをこのハンドラに設定します。 .. method:: shouldFlush(record) - Checks for buffer full or a record at the *flushLevel* or higher. + バッファが一杯になっているか、 *flushLevel* またはそれ以上のレコード でないかを調べます。 .. _http-handler: @@ -712,29 +702,28 @@ HTTPHandler ^^^^^^^^^^^ -The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module, -supports sending logging messages to a Web server, using either ``GET`` or -``POST`` semantics. +:mod:`logging.handlers` モジュールに含まれる :class:`HTTPHandler` クラス は、 +ログ記録メッセージを ``GET`` または ``POST`` セマンティクスを使って Web サーバに送信する機能をサポートしています。 .. class:: HTTPHandler(host, url, method='GET') - Returns a new instance of the :class:`HTTPHandler` class. The *host* can be - of the form ``host:port``, should you need to use a specific port number. - If no *method* is specified, ``GET`` is used. + :class:`HTTPHandler` クラスの新たなインスタンスを返します。 + *host* は特別なポートを使うことが必要な場合には、 ``host:port`` の形式で 使うこともできます。 + *method* が指定されなかった場合 ``GET`` が使われます。 .. method:: emit(record) - Sends the record to the Web server as a percent-encoded dictionary. ***The diff for this file has been truncated for email.***
