faulthandler — Dump the Python traceback转储Python回溯

New in version 3.3.版本3.3中新增。

This module contains functions to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal. 该模块包含在故障、超时或用户信号后显式转储Python回溯的函数。Call faulthandler.enable() to install fault handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS, and SIGILL signals. 调用faulthandler.enable()为SIGSEGV、SIGFPE、SIGABRT、SIGBUS和SIGILL信号安装故障处理程序。You can also enable them at startup by setting the PYTHONFAULTHANDLER environment variable or by using the -X faulthandler command line option.您还可以通过设置PYTHONFAULTHANDLER环境变量或使用-X faulthandler命令行选项在启动时启用它们。

The fault handler is compatible with system fault handlers like Apport or the Windows fault handler. 故障处理程序与系统故障处理程序（如Apport或Windows故障处理程序）兼容。The module uses an alternative stack for signal handlers if the sigaltstack() function is available. 如果sigaltstack()函数可用，则该模块使用信号处理程序的替代堆栈。This allows it to dump the traceback even on a stack overflow.这允许它在堆栈溢出时转储回溯。

The fault handler is called on catastrophic cases and therefore can only use signal-safe functions (e.g. it cannot allocate memory on the heap). 故障处理程序在灾难性情况下被调用，因此只能使用信号安全函数（例如，它不能在堆上分配内存）。Because of this limitation traceback dumping is minimal compared to normal Python tracebacks:由于此限制，与普通Python回溯相比，回溯转储是最小的：

  • Only ASCII is supported. 仅支持ASCII。The backslashreplace error handler is used on encoding.backslashreplace错误处理程序用于编码。

  • Each string is limited to 500 characters.每个字符串限制为500个字符。

  • Only the filename, the function name and the line number are displayed. (no source code)仅显示文件名、函数名和行号。（无源代码）

  • It is limited to 100 frames and 100 threads.它限于100帧和100线程。

  • The order is reversed: the most recent call is shown first.顺序相反：首先显示最近的调用。

By default, the Python traceback is written to sys.stderr. 默认情况下，Python回溯被写入sys.stderr。To see tracebacks, applications must be run in the terminal. 要查看回溯，应用程序必须在终端中运行。A log file can alternatively be passed to faulthandler.enable().也可以将日志文件传递给faulthandler.enable()。

The module is implemented in C, so tracebacks can be dumped on a crash or when Python is deadlocked.该模块用C实现，因此可以在崩溃或Python死锁时转储回溯。

The Python Development Mode calls faulthandler.enable() at Python startup.Python开发模式在Python启动时调用faulthandler.enable()。

Dumping the traceback转储回溯

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

Dump the tracebacks of all threads into file. 将所有线程的回溯转储到file中。If all_threads is False, dump only the current thread.如果all_threads为False，则仅转储当前线程。

Changed in version 3.5:版本3.5中更改： Added support for passing file descriptor to this function.添加了向该函数传递文件描述符的支持。

Fault handler state故障处理程序状态

faulthandler.enable(file=sys.stderr, all_threads=True)

Enable the fault handler: install handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback. 启用故障处理程序：为SIGSEGV、SIGFPE、SIGABRT、SIGBUS和SIGILL信号安装处理程序，以转储Python回溯。If all_threads is True, produce tracebacks for every running thread. 如果all_threads为True，则为每个正在运行的线程生成回溯。Otherwise, dump only the current thread.否则，只转储当前线程。

The file must be kept open until the fault handler is disabled: see issue with file descriptors.在禁用故障处理程序之前，file必须保持打开状态：请参阅文件描述符的问题。

Changed in version 3.5:版本3.5中更改： Added support for passing file descriptor to this function.添加了向该函数传递文件描述符的支持。

Changed in version 3.6:版本3.6中更改： On Windows, a handler for Windows exception is also installed.在Windows上，还安装了Windows异常处理程序。

Changed in version 3.10:版本3.10中更改： The dump now mentions if a garbage collector collection is running if all_threads is true.如果all_threads为true，转储现在会提到垃圾收集器集合是否正在运行。

faulthandler.disable()

Disable the fault handler: uninstall the signal handlers installed by enable().禁用故障处理程序：卸载enable()安装的信号处理程序。

faulthandler.is_enabled()

Check if the fault handler is enabled.检查故障处理程序是否已启用。

Dumping the tracebacks after a timeout超时后转储回溯

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

Dump the tracebacks of all threads, after a timeout of timeout seconds, or every timeout seconds if repeat is True. 在timeout秒后转储所有线程的回溯，如果repeat为True，则每timeout秒转储一次。If exit is True, call _exit() with status=1 after dumping the tracebacks. 如果exit为True，则在转储回溯后调用状态为1的_exit()。(Note _exit() exits the process immediately, which means it doesn’t do any cleanup like flushing file buffers.) （注意_exit()会立即退出进程，这意味着它不会进行任何清理，比如刷新文件缓冲区。）If the function is called twice, the new call replaces previous parameters and resets the timeout. 如果函数被调用两次，则新调用将替换先前的参数并重置超时。The timer has a sub-second resolution.计时器的分辨率低于秒。

The file must be kept open until the traceback is dumped or cancel_dump_traceback_later() is called: see issue with file descriptors.在转储回溯或调用cancel_dump_traceback_later()之前，file必须保持打开状态：请参阅文件描述符问题。

This function is implemented using a watchdog thread.此功能使用看门狗线程实现。

Changed in version 3.7:版本3.7中更改： This function is now always available.此功能现在始终可用。

Changed in version 3.5:版本3.5中更改： Added support for passing file descriptor to this function.添加了向该函数传递文件描述符的支持。

faulthandler.cancel_dump_traceback_later()

Cancel the last call to dump_traceback_later().取消上次对dump_traceback_later()的调用。

Dumping the traceback on a user signal转储用户信号的回溯

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

Register a user signal: install a handler for the signum signal to dump the traceback of all threads, or of the current thread if all_threads is False, into file. 注册用户信号：为signum信号安装一个处理程序，以将所有线程的跟踪转储到文件中，如果all_threads为False，则将当前线程的跟踪。Call the previous handler if chain is True.如果链为True，则调用上一个处理程序。

The file must be kept open until the signal is unregistered by unregister(): see issue with file descriptors.file必须保持打开状态，直到通过unregister()注销信号：请参阅文件描述符的问题。

Not available on Windows.Windows上不可用。

Changed in version 3.5:版本3.5中更改： Added support for passing file descriptor to this function.添加了向该函数传递文件描述符的支持。

faulthandler.unregister(signum)

Unregister a user signal: uninstall the handler of the signum signal installed by register(). 注销用户信号：卸载register()安装的signum信号的处理程序。Return True if the signal was registered, False otherwise.如果信号已注册，则返回True，否则返回False。

Not available on Windows.Windows上不可用。

Issue with file descriptors文件描述符问题

enable(), dump_traceback_later() and register() keep the file descriptor of their file argument. enable()、dump_traceback_later()和register()保留其文件参数的文件描述符。If the file is closed and its file descriptor is reused by a new file, or if os.dup2() is used to replace the file descriptor, the traceback will be written into a different file. Call these functions again each time that the file is replaced.如果文件已关闭，并且其文件描述符被新文件重用，或者如果使用os.dup2()替换文件描述符，则回溯将被写入其他文件。每次替换文件时，再次调用这些函数。

Example示例

Example of a segmentation fault on Linux with and without enabling the fault handler:在启用和不启用故障处理程序的情况下，Linux上的分段故障示例：

$ python3 -c "import ctypes; ctypes.string_at(0)"
Segmentation fault
$ python3 -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700 (most recent call first):
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault