tbutils -回溯跟踪和调用堆栈

人们经常提到的一条关于Python的信条是，请求原谅比请求许可更好。也就是说，在许多情况下，处理异常比花费额外的行和执行时间检查条件更具包容性和正确性。这种理念使得良好的异常处理功能变得更加重要。不幸的是， Python 的 traceback 不幸的是，模块已经落后于时代。

这个 tbutils 模块提供两个截然不同但互为补充的功能集：

1. 使用 ExceptionInfo 和 TracebackInfo 提取、构造、操作、格式化和序列化异常、回溯和调用堆栈的能力。

2. 使用 ParsedException 能够从捕获的输出(如日志和标准输出)中查找和解析回溯。

还有一个是 ContextualTracebackInfo 的变体 TracebackInfo ，它包含来自调用堆栈的每个帧的更多信息，包括局部变量和相邻代码行的值。

class boltons.tbutils.Callpoint(module_name, module_path, func_name, lineno, lasti, line=None)

Callpoint是一个轻量级对象，用于表示调用堆栈代码中的单个条目。它存储给定帧的代码相关元数据。可用的属性与下面的参数相同。

参数:

• func_name (str) -- 函数名称

• lineno (int) -- 行号

• module_name (str) -- 模块名称

• module_path (str) -- 模块的文件系统路径

• lasti (int) -- 字节码执行的索引

• line (str) -- 单行代码内容(如果可用)

classmethod from_current(level=1)

从调用函数的位置创建调用点。

classmethod from_frame(frame)

使用从给定帧提取的数据创建Callpoint对象。

classmethod from_tb(tb)

从当前异常的回溯创建调用点。与的主要区别 from_frame() 那是不是 lineno 和 lasti 来自回溯，即TRY块中失败的行，而不是当前正在执行的行(在EXCEPT块中)。

tb_frame_str()

按照在标准打印的Python回溯中显示的方式呈现调用点。返回一个字符串，其中包含文件名、行号、函数名和错误的实际代码行，最多两行。

to_dict()

vt.得到一个. dict 呼叫点的副本。对序列化很有用。

class boltons.tbutils.ContextualCallpoint(*a, **kw)

上下文调用点是一个 Callpoint 子类型，具有完全相同的API，并存储两个附加值：

1. repr() 调用点作用域的局部变量的输出

2. 调用点代码行前后的若干行

上下文调用点由 ContextualTracebackInfo 。

classmethod from_frame(frame)

等同于 Callpoint.from_frame()

classmethod from_tb(tb)

等同于 Callpoint.from_tb()

to_dict()

与以下原则相同 Callpoint.to_dict() ，但具有添加的上下文值。使用 ContextualCallpoint.to_dict() ，每个帧现在将表示为：：

{'func_name': 'print_example',
 'lineno': 0,
 'module_name': 'example_module',
 'module_path': '/home/example/example_module.pyc',
 'lasti': 0,
 'line': 'print "example"',
 'locals': {'variable': '"value"'},
 'pre_lines': ['variable = "value"'],
 'post_lines': []}

本地变量词典和行列表是副本，可以自由更改。

class boltons.tbutils.ContextualExceptionInfo(exc_type, exc_msg, tb_info)

ContextualTracebackInfo类型是 TracebackInfo 子类型，它使用 ContextualCallpoint 作为其帧表示基元。

它包含了重新创建可广泛识别的“500”页面以调试Django应用程序所需的大部分异常信息。

tb_info_type

ContextualTracebackInfo 的别名

class boltons.tbutils.ContextualTracebackInfo(frames)

ContextualTracebackInfo类型是 TracebackInfo 使用的子类型 ContextualExceptionInfo 并使用 ContextualCallpoint 作为其帧表示基元。

callpoint_type

ContextualCallpoint 的别名

class boltons.tbutils.ExceptionInfo(exc_type, exc_msg, tb_info)

ExceptionInfo对象将适合表示异常实例的三个主要字段绑定在一起：异常类型名称、异常本身的字符串表示(异常消息)和有关回溯的信息(存储为 TracebackInfo 对象)。

这些字段与 sys.exc_info() ，但与该函数返回的值不同，ExceptionInfo不包含对实际异常或回溯的任何引用。此属性使其适合序列化或长期保留，而无需担心格式缺陷、循环引用或内存泄漏。

参数:

• exc_type (str) -- 例外类型名称。

• exc_msg (str) -- 异常值的字符串表示形式。

• tb_info (TracebackInfo) -- 有关异常的堆栈跟踪的信息。

就像 TracebackInfo ，ExceptionInfo最常从其类方法之一实例化： from_exc_info() 或 from_current() 。

classmethod from_current()

创建一个 ExceptionInfo 对象从当前正在处理的异常中返回，方法是 sys.exc_info() 。如果当前未处理任何异常，则将引发异常。

classmethod from_exc_info(exc_type, exc_value, traceback)

创建一个 ExceptionInfo 对象来自异常的类型、值和回溯，由 sys.exc_info() 。另请参阅 from_current() 。

get_formatted()

返回未捕获异常时可观察到的、以传统Python内置样式格式化的字符串。换句话说，模仿 traceback.format_exception() 。

tb_info_type

在继承的类型中重写它以控制使用的TracebackInfo类型

TracebackInfo 的别名

to_dict()

vt.得到一个. dict ExceptionInfo的表示形式，适用于JSON序列化。

class boltons.tbutils.ParsedException(exc_type_name, exc_msg, frames=None)

存储分析后的回溯和异常，通常由 sys.excepthook() 或 traceback.print_exception() 。

classmethod from_string(tb_str)

从文本中解析回溯和异常 tb_str 。此文本预计已被解码，否则将被解释为UTF-8。

此方法不会搜索较大的文本正文以进行回溯。如果传递的文本的第一行与已知模式之一不匹配，则会引发 ValueError 将会被唤醒。此方法将忽略第一次回溯结束后的尾随文本。

参数:

tb_str (str) -- 回溯文本 (unicode 或UTF-8字节)

property source_file

包含引发异常的函数的模块的文件路径，如果不可用，则为None。

to_dict()

以JSON可序列化形式获取副本 dict 。

to_string()

将异常及其跟踪设置为跟踪模块返回的标准格式。

ParsedException.from_string(text).to_string() 应该让位 text 。

class boltons.tbutils.TracebackInfo(frames)

Traceback Info类提供堆栈跟踪的基本表示形式，无论它来自正在处理的异常还是正常执行的一部分。它基本上是一个包装，围绕着一个列表 Callpoint 表示框架的对象。

参数:

frames (list) -- 堆栈中的Frame对象列表。

备注

TracebackInfo 可以同时表示异常回溯和非异常回溯(也称为堆栈跟踪)。因此，没有 TracebackInfo.from_current() ，因为这将是模棱两可的。相反，调用 TracebackInfo.from_frame() 如果没有 frame 参数用于堆栈跟踪，或 TracebackInfo.from_traceback() 如果没有 tb 异常回溯的参数。

callpoint_type

Callpoint 的别名

classmethod from_dict(d)

互补性 TracebackInfo.to_dict() 。

classmethod from_frame(frame=None, level=1, limit=None)

创建新的TracebackInfo frame 通过在堆栈中递归最多 limit 泰晤士报。如果 frame 未设置，则从中获取帧 sys._getframe() 使用 level 。

参数:

• frame (types.FrameType) -- 将对象框起自 sys._getframe() 或者在其他地方。默认结果为 sys.get_frame() 。

• level (int) -- 如果 frame 未设置，则所需的帧是从调用此方法开始在堆栈上向上的多个级别。默认 1 (即，此方法的调用方)。

• limit (int) -- 要提取的最大父帧数量(默认为 sys.tracebacklimit )

classmethod from_traceback(tb=None, limit=None)

从回溯创建新的TracebackInfo tb 通过在堆栈中递归最多 limit 泰晤士报。如果 tb 未设置，则从当前处理的异常中获取跟踪。如果未处理任何异常，则引发 ValueError 。

参数:

• frame (types.TracebackType) -- 回溯对象来自 sys.exc_info() 或者在其他地方。如果不存在或设置为 None ，默认为 sys.exc_info()[2] ，并引发一个 ValueError 如果当前未处理任何异常，则。

• limit (int) -- 要提取的最大父帧数量(默认为 sys.tracebacklimit )

get_formatted()

返回在未捕获异常时可观察到的传统Python内置样式中的格式化字符串。换句话说，模仿 traceback.format_tb() 和 traceback.format_stack() 。

to_dict()

返回带有以下列表的词典 Callpoint 转换为DICT的帧。

boltons.tbutils.print_exception(etype, value, tb, limit=None, file=None)

将异常从‘TB’打印到‘FILE’，直到‘Limit’堆栈跟踪条目。

这与print_tb()在以下方面不同：(1)如果Traceback不是NONE，则它打印标题“TraceBack(Last Recent Call Last)：”；(2)它在堆栈跟踪之后打印异常类型和值；(3)如果type为SynaxError，并且Value具有适当的格式，则它打印发生语法错误的行，并在下一行上使用插入符号指示错误的大致位置。