Обработка ошибок — Вывод отладочной информации о 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() со значением status=1 после вывода отладочной информации о стеке. (Обратите внимание, что _exit() завершает процесс немедленно, что означает, что он не выполняет очистку, такую как сброс буферов файлов). Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет разрешение в доли секунды.

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

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

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

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

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

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

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

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

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

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

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

faulthandler.unregister(signum)

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

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

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

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

Пример

Пример сегментации памяти на 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

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