schwarzlog

为Python的logging模块添加一些缺失功能的库。

$ pip install schwarzlog

注意：目前大多数功能尚未文档化。尽管如此，我将继续编写一些文档。

动机/背景

logging常有助于在已部署的代码中找到问题。

然而，Python的logging基础设施有时会让人感到有些恼火。例如，如果一个库开始记录数据，但应用程序/单元测试没有配置logging基础设施，Python将发出警告。如果库支持条件logging（例如，通过传递一个标志来决定是否使用logging以避免上述“未安装logging处理器”的问题），这可能会使库代码复杂化（因为需要进行“是否启用logging”的检查）。

我还发现测试库中的Python logging有些繁琐，因为必须安装全局处理器（并在测试完成后清理！）。

此库应使用辅助函数解决所有这些问题

• 它可以直接返回一个指定名称的新logger。
• 如果应该完全禁用logging，则它将返回一个伪logger，该logger将丢弃所有消息。应用程序不需要知道这一点，并且不会改变全局状态。
• 调用者还可以传递一个预先配置的logger（例如，以便轻松测试发出的日志消息或使用自定义的logging机制）。

自其推出以来，此库已扩展了一些有用的辅助函数和专门的logging类。

CallbackLogger

一个类似于Logger的类，可以在通过logging基础设施传递日志消息的同时触发额外的回调。我正在使用此功能来确保由底层库记录的严重问题会在UI中显示出来。如果设置merge_arguments = True，回调只会获得最终消息（作为str），否则它将获得logging.LogRecord。

用法

import logging
from schwarz.log_utils import CallbackLogger

_l = logging.getLogger('foo')
logged_msgs = []
cb = logged_msgs.append
log = CallbackLogger(log=_l, callback=cb, callback_minlevel=logging.ERROR, merge_arguments=True)
log.info('info message')
log.error('error message')
logged_msgs == ['error message']

ForwardingLogger

此记录器将高于一定级别的消息（默认为所有消息）转发到配置的父记录器。可选地，它可以将配置的 forward_prefix 预先附加到所有 转发的 日志消息上。forward_suffix 与 forward_prefix 类似，但会附加一些字符串。

这在你需要记录上下文信息时很有帮助。例如，你可以记录与特定文件（例如“imgfile.log”）相关的详细消息，但你希望将更重要的消息（例如警告、错误）记录到应用程序使用的另一个日志文件中。在这种情况下，你可以快速在你的主日志文件中找到问题，同时详细数据可以在单独的日志文件中可用。

Python 的默认日志模块无法处理此问题，因为

• Logger 的日志级别仅应用于直接在该记录器上发出的消息（不适用于传播日志消息），请参阅 Marius Gedminas 的这篇博客文章：日志级别。
• 仅对某些记录器添加日志前缀，只能通过复制处理程序配置来完成。Python 的处理程序相当基础，因此如果复制的处理程序访问共享资源（例如日志文件），Python 将打开它两次（如果使用 mode='w'，则会导致数据丢失）。

用法

import logging
from schwarz.log_utils import get_logger, ForwardingLogger

parent_logger = logging.getLogger('foo')
log = ForwardingLogger(
    forward_to=parent_logger,
    forward_prefix='[ABC] ',
    forward_minlevel=logging.INFO
)
log.info('foo')
# parent_logger sees a log message like "[ABC] foo"

测试支持

该库还包含一些辅助工具，可以简化与日志相关的测试编写。

import logging
from schwarz.log_utils.testutils import *

# "lc" works a bit similar to a LogCapture instance
log, lc = build_collecting_logger()
log.info('foo')
log.debug('bar')

assert_did_log_message(lc, 'foo')
# this raises an AssertionError as "foo" was logged with INFO
assert_did_log_message(lc, 'foo', level=logging.DEBUG)

lr = assert_did_log_message(lc, 'foo', level=logging.INFO)
# you can also inspect the actual "LogRecord" instance "lr" if you need to

assert_no_log_messages(lc, min_level=logging.WARN)

更改

0.7.0 (2024-08-06)

• 停止支持 Python 2

0.6.2 (2022-05-25)

• assert_did_log_message(…) 现在返回 LogRecord 实例，调用者可以使用它进行更详细的检查。
• ForwardingLogger 现在也正确地转发了 .exc_info，以便主记录器也可以记录异常。