faulthandler — Вывод отладочной информации о Python

Добавлен в версии 3.3.

Этот модуль содержит функции для явного вывода отладочной информации о Python, при ошибке, по истечении времени ожидания или при подаче пользовательского сигнала. Вызовите faulthandler.enable(), чтобы установить обработчики ошибок для сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL. Также можно включить их при запуске, установив переменную окружения PYTHONFAULTHANDLER или используя командную строку -X faulthandler.

Обработчик ошибок совместим с системными обработчиками ошибок, такими как Apport или обработчик ошибок Windows. Модуль использует альтернативную стек для обработчиков сигналов, если функция sigaltstack() доступна. Это позволяет выводить отладочную информацию даже при переполнении стека.

Обработчик ошибок вызывается в критических ситуациях и поэтому может использовать только безопасные для сигналов функции (например, он не может выделять память в куче). Из-за этого ограничения вывод отладочной информации минимален по сравнению с обычными отладочными данными Python:

Поддерживается только ASCII. Обработчик ошибок backslashreplace используется для кодирования.
Длина каждой строки ограничена 500 символами.
Отображаются только имя файла, имя функции и номер строки. (без исходного кода)
Ограничение до 100 фреймов и 100 потоков.
Порядок обратный: первый отображается самый последний вызов.

По умолчанию, отладочная информация Python записывается в sys.stderr. Для просмотра отладочной информации приложения необходимо запускать в терминале. Вместо этого, можно передать файл журнала в faulthandler.enable().

Модуль реализован на C, поэтому отладочная информация может быть выведена при сбое или блокировке Python.

Режим разработки Python Режим разработки Python вызывает faulthandler.enable() при запуске Python.

См. также

Module pdb: Интерактивный отладчик исходного кода для программ Python.
Module traceback: Стандартный интерфейс для извлечения, форматирования и вывода стековых следов программ Python.

Вывод отладочной информации

faulthandler.dump_traceback(file=sys.stderr, all_threads=True): Вывод отладочной информации всех потоков в file. Если all_threads равно False, выводить только текущий поток.

См. также

traceback.print_tb(), который можно использовать для вывода объекта отладочной информации.

Изменено в версии 3.5: Добавлена поддержка передачи дескриптора файла в эту функцию.

Состояние обработчика ошибок

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

Включить обработчик ошибок: установить обработчики для сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для вывода отладочной информации Python. Если all_threads равно True, генерировать отладочную информацию для каждого запущенного потока. В противном случае, выводить отладочную информацию только для текущего потока.

file должен оставаться открытым до момента отключения обработчика ошибок: см. проблемы с дескрипторами файлов.

Изменено в версии 3.5: Добавлена поддержка передачи дескриптора файла в эту функцию.

Изменено в версии 3.6: В Windows также установлен обработчик для исключений Windows.

Изменено в версии 3.10: Вывод теперь указывает, если выполняется сборка мусора, если all_threads равно true.

faulthandler.disable(): Отключить обработчик ошибок: отменить установку обработчиков сигналов, установленных функцией enable().

faulthandler.is_enabled(): Проверить, включен ли обработчик ошибок.

Вывод отладочной информации после истечения времени ожидания

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

Вывод отладочной информации всех потоков через timeout секунд или через каждые timeout секунд, если repeat равно True. Если exit равно True, вызвать _exit() со статусом 1 после вывода отладочной информации. (Примечание: _exit() сразу завершает процесс, что означает, что он не выполняет очистку, например, не сбрасывает буферы файлов.) Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет разрешение менее одной секунды.

file должен оставаться открытым до тех пор, пока отладочная информация не будет выведена или не будет вызвано cancel_dump_traceback_later(): см. проблемы с дескрипторами файлов.

Эта функция реализована с помощью потока-сторожа.

Изменено в версии 3.5: Добавлена поддержка передачи дескриптора файла в эту функцию.

Изменено в версии 3.7: Эта функция теперь всегда доступна.

faulthandler.cancel_dump_traceback_later(): Отменить последний вызов dump_traceback_later().

Вывод отладочной информации при пользовательском сигнале

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

Зарегистрировать пользовательский сигнал: установить обработчик для сигнала signum, чтобы вывести отладочную информацию всех потоков, или текущего потока, если all_threads равно False, в file. Вызвать предыдущий обработчик, если цепочка равна True.

file должен оставаться открытым до момента отмены регистрации сигнала с помощью unregister(): см. проблемы с дескрипторами файлов.

Не доступно в Windows.

Изменено в версии 3.5: Добавлена поддержка передачи дескриптора файла в эту функцию.

faulthandler.unregister(signum)

Отменить регистрацию пользовательского сигнала: отменить установку обработчика сигнала signum, установленного функцией register(). Вернуть True если сигнал был зарегистрирован, False в противном случае.

Не доступно в Windows.

Проблемы с дескрипторами файлов

enable(), dump_traceback_later() и register() сохраняют дескриптор файла своего аргумента file. Если файл закрыт и его дескриптор повторно используется новым файлом, или если os.dup2() используется для замены дескриптора файла, отладочная информация будет записана в другой файл. Вызывайте эти функции снова каждый раз, когда файл заменяется.

Пример

Пример сегментации памяти на Linux с включением и выключением обработчика ошибок:

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -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

© 2001–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.12/library/faulthandler.html