logging-tree 1.10

传播

关于日志工作原理的快速提醒：默认情况下，一个节点不仅会将消息提交给自己（如果有的话）的处理程序，还会将每个消息“传播”到其父节点。例如，附加到根记录器的Stream处理程序不仅会接收直接发送到根的消息，还会接收从子节点如a.b传播上来的消息。

>>> logging.getLogger().warning('message sent to the root')
message sent to the root
>>> logging.getLogger('a.b').warning('message sent to a.b')
message sent to a.b

但是，消息在传播过程中不会受到过滤。因此，一个调试级别的消息，由于根节点的级别设置为WARNING，将被根节点丢弃，但会被a.b节点接受，并允许它传播到根处理程序。

>>> logging.getLogger().debug('this message is ignored')
>>> logging.getLogger('a.b').debug('but this message prints!')
but this message prints!

如果根节点和a.b都附加了处理程序，那么由a.b接受的消息将被打印两次，一次由其自身节点打印，然后当消息传播到根时再打印第二次。

>>> logging.getLogger('a.b').addHandler(h)
>>> logging.getLogger('a.b').warning('this message prints twice')
this message prints twice
this message prints twice

但是，您可以通过将节点的propagate属性设置为False来阻止节点将其消息传播到父节点。

>>> logging.getLogger('a.b').propagate = False
>>> logging.getLogger('a.b').warning('does not propagate')
does not propagate

日志树将通过不再绘制从节点指向其父节点的箭头<--来指示已关闭传播。

>>> printout()
<--""
   Level WARNING
   Handler Stream <sys.stdout>
   |
   o<--"a"
   |   Level NOTSET so inherits level WARNING
   |   |
   |   o   "a.b"
   |       Level DEBUG
   |       Propagate OFF
   |       Handler Stream <sys.stdout>
   |
   o<--[x]
       |
       o<--"x.c"
           Level NOTSET so inherits level WARNING

您可以通过设置属性True来再次打开传播。

API

尽管大多数用户只需调用顶级printout()例程，但此包还提供了一些较低级别的调用。以下是完整列表

logging_tree.printout(node=None)

打印当前日志树，或基于给定node的树，到标准输出。

logging_tree.format.build_description(node=None)

构建并返回当前记录器树或多行描述，或基于给定node的树，作为单个字符串，其中包含换行符并在末尾包含换行符。

logging_tree.format.describe(node)

一个生成器，它产生一系列描述基于给定node的树的行。请注意，返回的行不带换行终止符。

logging_tree.tree()

从logging模块获取当前日志器树。返回一个节点，它只是一个包含三个字段的元组

[0] 记录器名称（根记录器的名称为""）。

[1] logging.Logger对象本身。

[2] 零个或多个子节点列表。

您可以在GitHub上找到此包的issue tracker https://github.com/brandon-rhodes/logging_tree。您可以使用以下命令运行此包的测试套件

$ python -m unittest discover logging_tree

在较旧版本的Python中，您将不得不安装unittest2并使用其unit2命令行工具来运行测试。

变更日志

版本 1.10 - 2024年5月3日

宣布与Python 3.12兼容，并扩展文档以描述日志消息传播的基础知识。

版本 1.9 - 2021年4月10日

宣布与Python 3.9兼容。改进了旧Python版本中日志模块使用的旧式类中显示内置Formatter类的方式。

版本 1.8.1 - 2020年1月26日

调整一个测试以使其在Python 3.8下通过，并更新分发分类器以宣布与Python版本3.8兼容。

版本 1.8 - 2018年8月5日

提高输出效果，以更好地解释如果将“父”属性设置为None时会发生什么。

版本 1.7 - 2016年1月23日

检测每个记录器是否具有正确的“父”属性，如果没有，则打印其日志消息发送的位置。

版本 1.6 - 2015年1月8日

修复了如果自定义日志格式化程序缺少格式字符串属性会导致崩溃的问题。

版本 1.5 - 2014年12月24日

处理器现在可以显示其日志级别，如果已设置，以及其自定义日志格式化程序，如果已安装。

版本 1.4 - 2014年1月8日

感谢Dave Brondsema的贡献，已禁用的记录器现在实际上被标记为“禁用”，以减少它们未能记录任何内容的意外性。

版本 1.3 - 2013年10月29日

明确显示记录器级别NOTSET以及从记录器的祖先继承的有效级别；即使它可能包含忽略它们的自定义代码，也显示自定义记录处理程序的.filters列表。

版本 1.2 - 2013年1月19日

由于@ralphbean，现在与Python 3.3兼容。

版本 1.1 - 2012年2月17日

现在与2.3 <= Python <= 3.2兼容。

版本 1.0 - 2012年2月13日

可以在内存处理器内部显示处理器；整个公共接口已文档化；100%测试覆盖率。

版本 0.6 - 2012年2月10日

为每个logging.handlers类添加了显示格式。

版本 0.5 - 2012年2月8日

初始版本。