tbutils
-回溯跟踪和调用堆栈¶
人们经常提到的一条关于Python的信条是,请求原谅比请求许可更好。也就是说,在许多情况下,处理异常比花费额外的行和执行时间检查条件更具包容性和正确性。这种理念使得良好的异常处理功能变得更加重要。不幸的是, Python 的 traceback
不幸的是,模块已经落后于时代。
这个 tbutils
模块提供两个截然不同但互为补充的功能集:
使用
ExceptionInfo
和TracebackInfo
提取、构造、操作、格式化和序列化异常、回溯和调用堆栈的能力。使用
ParsedException
能够从捕获的输出(如日志和标准输出)中查找和解析回溯。
还有一个是 ContextualTracebackInfo
的变体 TracebackInfo
,它包含来自调用堆栈的每个帧的更多信息,包括局部变量和相邻代码行的值。
- class boltons.tbutils.Callpoint(module_name, module_path, func_name, lineno, lasti, line=None)[源代码]¶
Callpoint是一个轻量级对象,用于表示调用堆栈代码中的单个条目。它存储给定帧的代码相关元数据。可用的属性与下面的参数相同。
- 参数:
- classmethod from_tb(tb)[源代码]¶
从当前异常的回溯创建调用点。与的主要区别
from_frame()
那是不是lineno
和lasti
来自回溯,即TRY块中失败的行,而不是当前正在执行的行(在EXCEPT块中)。
- class boltons.tbutils.ContextualCallpoint(*a, **kw)[源代码]¶
上下文调用点是一个
Callpoint
子类型,具有完全相同的API,并存储两个附加值:repr()
调用点作用域的局部变量的输出调用点代码行前后的若干行
上下文调用点由
ContextualTracebackInfo
。- 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¶
- class boltons.tbutils.ContextualTracebackInfo(frames)[源代码]¶
ContextualTracebackInfo类型是
TracebackInfo
使用的子类型ContextualExceptionInfo
并使用ContextualCallpoint
作为其帧表示基元。- callpoint_type¶
- 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
的别名
- 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。
- class boltons.tbutils.TracebackInfo(frames)[源代码]¶
Traceback Info类提供堆栈跟踪的基本表示形式,无论它来自正在处理的异常还是正常执行的一部分。它基本上是一个包装,围绕着一个列表
Callpoint
表示框架的对象。- 参数:
frames (list) -- 堆栈中的Frame对象列表。
备注
TracebackInfo
可以同时表示异常回溯和非异常回溯(也称为堆栈跟踪)。因此,没有TracebackInfo.from_current()
,因为这将是模棱两可的。相反,调用TracebackInfo.from_frame()
如果没有 frame 参数用于堆栈跟踪,或TracebackInfo.from_traceback()
如果没有 tb 异常回溯的参数。- 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()
。