`logging` --- Python 的日誌記錄工具¶

這個模組定義了函式與類別 (class)，為應用程式和函式庫實作彈性的日誌管理系統。

由標準函式庫模組提供的日誌記錄 API 的主要好處是，所有的 Python 模組都能參與日誌記錄，因此你的應用程式日誌可以包含你自己的訊息，並與來自第三方模組的訊息整合在一起。

Here's a simple example of idiomatic usage:

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

If you run myapp.py, you should see this in myapp.log:

INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished

The key feature of this idiomatic usage is that the majority of code is simply creating a module level logger with getLogger(__name__), and using that logger to do any needed logging. This is concise, while allowing downstream code fine-grained control if needed. Logged messages to the module-level logger get forwarded to handlers of loggers in higher-level modules, all the way up to the highest-level logger known as the root logger; this approach is known as hierarchical logging.

For logging to be useful, it needs to be configured: setting the levels and destinations for each logger, potentially changing how specific modules log, often based on command-line arguments or application configuration. In most cases, like the one above, only the root logger needs to be so configured, since all the lower level loggers at module level eventually forward their messages to its handlers. basicConfig() provides a quick way to configure the root logger that handles many use cases.

這個模組提供了很多的功能性以及彈性。如果你對於 logging 不熟悉，熟悉它最好的方法就是去看教學（請看右上方的連結）。

The basic classes defined by the module, together with their attributes and methods, are listed in the sections below.

Loggers expose the interface that application code directly uses.
Handlers send the log records (created by loggers) to the appropriate destination.
Filters provide a finer grained facility for determining which log records to output.
格式器指定日誌記錄在最終輸出中的佈局。

Logger 物件¶

Loggers have the following attributes and methods. Note that Loggers should NEVER be instantiated directly, but always through the module-level function logging.getLogger(name). Multiple calls to getLogger() with the same name will always return a reference to the same Logger object.

The name is potentially a period-separated hierarchical value, like foo.bar.baz (though it could also be just plain foo, for example). 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 descendants of foo. In addition, all loggers are descendants of the root logger. The logger name hierarchy is analogous to the Python package hierarchy, and identical to it if you organise your loggers on a per-module basis using the recommended construction logging.getLogger(__name__). That's because in a module, __name__ is the module's name in the Python package namespace.

class logging.Logger¶

name¶: This is the logger's name, and is the value that was passed to getLogger() to obtain the logger.

備註

此屬性應被視為唯讀。

level¶: The threshold of this logger, as set by the setLevel() method.

備註

Do not set this attribute directly - always use setLevel(), which has checks for the level passed to it.

parent¶: The parent logger of this logger. It may change based on later instantiation of loggers which are higher up in the namespace hierarchy.

備註

This value should be treated as read-only.

propagate¶

如果此屬性評估為 true，則在此日誌紀錄器被記錄的事件會被傳到更高階（上代）日誌記錄器的處理函式和所有附加在此日誌記錄器的任何處理器。訊息會直接傳到上代 loggers 的處理器 - 在問題中上代日誌記錄器的層級或是篩選器都不會被考慮。

If this evaluates to false, logging messages are not passed to the handlers of ancestor loggers.

Spelling it out with an example: If the propagate attribute of the logger named A.B.C evaluates to true, any event logged to A.B.C via a method call such as logging.getLogger('A.B.C').error(...) will [subject to passing that logger's level and filter settings] be passed in turn to any handlers attached to loggers named A.B, A and the root logger, after first being passed to any handlers attached to A.B.C. If any logger in the chain A.B.C, A.B, A has its propagate attribute set to false, then that is the last logger whose handlers are offered the event to handle, and propagation stops at that point.

此建構函式將該屬性設為 True。

備註

If you attach a handler to a logger and one or more of its ancestors, it may emit the same record multiple times. In general, you should not need to attach a handler to more than one logger - if you just attach it to the appropriate logger which is highest in the logger hierarchy, then it will see all events logged by all descendant loggers, provided that their propagate setting is left set to True. A common scenario is to attach handlers only to the root logger, and to let propagation take care of the rest.

handlers¶: The list of handlers directly attached to this logger instance.

備註

This attribute should be treated as read-only; it is normally changed via the addHandler() and removeHandler() methods, which use locks to ensure thread-safe operation.

disabled¶: This attribute disables handling of any events. It is set to False in the initializer, and only changed by logging configuration code.

備註

此屬性應被視為唯讀。

setLevel(level)¶

Sets the threshold for this logger to level. Logging messages which are less severe than level will be ignored; logging messages which have severity level or higher will be emitted by whichever handler or handlers service this logger, unless a handler's level has been set to a higher severity level than level.

當一個日誌記錄器被建立時，記錄層級會被設定成 NOTSET （當此日誌記錄器是根日誌記錄器，或是代表父日誌記錄器的非根日誌記錄器時，會使所有訊息被處理）。請注意根日誌記錄器會以記錄等級 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.

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.

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.

層級清單請見 Logging Levels。

在 3.2 版的變更: The level parameter now accepts a string representation of the level such as 'INFO' as an alternative to the integer constants such as INFO. Note, however, that levels are internally stored as integers, and methods such as e.g. getEffectiveLevel() and isEnabledFor() will return/expect to be passed integers.

isEnabledFor(level)¶: Indicates if a message of severity

logging --- Python 的日誌記錄工具¶

Logger 物件¶

`logging` --- Python 的日誌記錄工具¶