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() со значением status=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. Вызвать предыдущий обработчик, если chain равно 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.13/library/faulthandler.html