Python 3长异常消息可读性差，包开发中该如何规范处理？

针对你开发Python包时遇到的长异常消息可读性差、重抛后重复显示的问题，这里有几个实用的解决方案，兼顾用户体验和调试便利性：

1. 自定义异常类，结构化消息（最简单的原生方案） #

不需要额外捕获逻辑，直接让你的SanityCheckException携带格式化后的多行消息，Python的回溯会自动保留换行，大幅提升可读性。

修改你的自定义异常和抛出逻辑：

class SanityCheckException(Exception):
    pass

# 在抛出异常的位置，用多行字符串格式化消息
if list(par_names)[0] != "scan":  # 注意：用!=而非is not来比较字符串！
    raise SanityCheckException(
        "Error in signature of user-supplied log-likelihood function!\n"
        "The first argument must be named 'scan' and will be passed:\n"
        "- A reference to a global ScannerBit object\n"
        "- You can use this object to print extra information to the scan output file, for example."
    )

这样触发异常时，回溯里的消息会自动分段换行，用户能清晰看到提示内容，不需要额外处理。

注意：比较字符串时建议用!=而不是is not，is not是比较对象身份，可能在某些情况下出现意外行为。

2. 全局异常钩子，美化输出且避免重复 #

如果想让提示更醒目（比如加分隔线、强调符号），同时避免局部捕获重抛导致的消息重复，可以用Python的sys.excepthook全局处理异常显示。

示例代码：

import sys
import traceback

class SanityCheckException(Exception):
    def __init__(self):
        # 存储详细提示，用简短消息作为异常的默认描述
        super().__init__("Invalid log-likelihood function signature")
        self.detailed_hint = (
            "⚠️  ScannerBit Sanity Check Failed\n"
            "----------------------------------------\n"
            "Your log-likelihood function's first argument must be named 'scan'.\n"
            "This argument receives a global ScannerBit object, which you can use to:\n"
            "  • Print extra information to the scan output file\n"
            "  • Access other ScannerBit utility features\n"
            "----------------------------------------"
        )

def custom_exception_handler(exctype, value, tb):
    if exctype is SanityCheckException:
        # 先打印美化的详细提示
        print("\n" + value.detailed_hint + "\n")
        # 再打印回溯信息（可选，保留调试上下文）
        traceback.print_tb(tb)
        # 最后打印简短的异常标识
        print(f"\n{exctype.__name__}: {value}")
    else:
        # 其他异常用默认处理逻辑
        sys.__excepthook__(exctype, value, tb)

# 注册全局钩子
sys.excepthook = custom_exception_handler

这样当触发SanityCheckException时，用户会先看到清晰的美化提示，再看到回溯信息，不会出现重复的长消息，同时保留了调试所需的上下文。

3. 局部捕获+标记避免重复（针对特定场景） #

如果只需要在特定代码块处理异常，可以给自定义异常加一个标记，确保美化消息只打印一次：

class SanityCheckException(Exception):
    def __init__(self, detailed_msg):
        self.detailed_msg = detailed_msg
        self._has_been_shown = False
        super().__init__("Invalid log-likelihood signature")

# 在你的Scan类初始化中：
try:
    if list(par_names)[0] != "scan":
        raise SanityCheckException(
            "Error in signature of user-supplied log-likelihood function!\n"
            "The first argument must be named 'scan' and will be passed a reference to a global ScannerBit object that can be used to e.g. print extra information to the scan output file."
        )
except SanityCheckException as e:
    if not e._has_been_shown:
        print("\n" + "="*60)
        print(e.detailed_msg)
        print("="*60 + "\n")
        e._has_been_shown = True
    raise  # 重新抛出，保留完整回溯

这种方式适合你只想在特定位置美化输出，同时保留回溯的场景，标记确保不会重复打印详细消息。

总结最佳实践 #

• 优先选择方案1：结构化消息是最轻量的方式，不需要额外逻辑，原生回溯就足够清晰。
• 如果需要更醒目的提示，用方案2的全局钩子，统一处理所有自定义异常的显示，代码更整洁。
• 避免无标记的局部捕获重抛，容易导致消息重复；如果必须局部处理，用方案3的标记机制。

内容的提问来源于stack exchange，提问作者Ben Farmer