better-exceptions

在 Python 中自动提供更美观、更实用的异常信息。

使用方法

通过 pip 安装 better_exceptions：

pip install better_exceptions

并将 BETTER_EXCEPTIONS 环境变量设置为任意值：

export BETTER_EXCEPTIONS=1  # Linux / OSX
setx BETTER_EXCEPTIONS 1    # Windows

就是这样！

Python REPL（交互式 shell）

要在 Python REPL 中使用 better_exceptions，请先安装该软件包（按照上述说明操作），然后运行：

$ python -m better_exceptions
Type "help", "copyright", "credits" or "license" for more information.
(BetterExceptionsConsole)
>>>

以便进入启用了 better_exceptions 的 Python 交互式 shell。

高级用法

如果您希望输出完整的值，而不是将其截断到特定的字符数量：

import better_exceptions
better_exceptions.MAX_LENGTH = None

在生产环境中使用 better_exceptions 时，不要忘记取消设置 BETTER_EXCEPTIONS 变量，以避免在日志中泄露敏感数据。

与 unittest 配合使用

如果希望使用 better_exceptions 来格式化 unittest 的异常输出，可以使用以下猴子补丁：

import sys
import unittest
import better_exceptions

def patch(self, err, test):
    lines = better_exceptions.format_exception(*err)
    if sys.version_info[0] == 2:
        return u"".join(lines).encode("utf-8")
    return "".join(lines)

unittest.result.TestResult._exc_info_to_string = patch

请注意，这使用了一个未公开的方法覆盖，因此不能保证在所有平台或 Python 版本上都能正常工作。

Django 用法

在 settings.py 中，将新类添加到 MIDDLEWARE 设置中，并更新日志配置：

# ...

MIDDLEWARE = [
    # ...
    "better_exceptions.integrations.django.BetterExceptionsMiddleware",
]

# ...

from better_exceptions.integrations.django import skip_errors_filter

# if you don't want to override LOGGING because you want to change the default,
# you can vendor Django's default logging configuration and update it for
# better-exceptions. the default for Django 3.1.4 can be found here:
# https://github.com/django/django/blob/3.1.4/django/utils/log.py#L13-L63
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'filters': {
        'skip_errors': {
            '()': 'django.utils.log.CallbackFilter',
            'callback': skip_errors_filter,
        }
    },
    'handlers': {
        'console': {
            'level': 'INFO',
            # without the 'filters' key, Django will log errors twice:
            # one time from better-exceptions and one time from Django.
            # with the 'skip_errors' filter, we remove the repeat log
            # from Django, which is unformatted.
            'filters': ['skip_errors'],
            'class': 'logging.StreamHandler',
        }
    },
    'loggers': {
        'django': {
            'handlers': [
                'console',
            ],
        }
    }
}

示例输出：

故障排除

如果您没有看到美观的异常信息，首先请确保环境变量已存在。您可以尝试 echo $BETTER_EXCEPTIONS（Linux / OSX）或 echo %BETTER_EXCEPTIONS%（Windows）。在 Linux 和 OSX 系统上，export 命令不会永久添加变量，您可能需要编辑 ~/.profile 文件以使其持久生效。在 Windows 系统上，执行 setx 命令后需要打开一个新的终端。

检查是否与其他库存在冲突，以及 sys.excepthook 函数是否已被正确替换为 better_exceptions 的函数。有时其他组件可能会设置自己的异常处理器，例如 Ubuntu 系统中的 python3-apport 包，您可能需要卸载它。

确保您没有不小心删除 better_exceptions_hook.pth 文件，该文件应与您所有 Python 包安装位置中的 better_exceptions 文件夹位于同一位置。否则，请尝试重新安装 better_exceptions。

您也可以尝试通过在脚本开头添加 import better_exceptions; better_exceptions.hook() 来手动激活钩子。

最后，如果您仍然无法使此模块正常工作，请新建一个 issue，准确描述您的问题并详细说明您的配置（Python 和 better_exceptions 版本、操作系统、代码片段、解释器等），以便我们能够重现您遇到的错误。

许可证

版权所有 © 2017，Josh Junon。根据 MIT 许可证 授权。