摘要

本 PEP 提案添加一个映射，将每个字节码指令映射到生成它们的行的起始和结束列偏移量，以及结束行号。此数据将用于改进 CPython 解释器显示的回溯信息，以改善调试体验。PEP 还提议添加 API，允许其他工具（例如代码覆盖率分析工具、分析器、跟踪器、调试器）从代码对象中使用此信息。

动机

本 PEP 的主要动机是改进关于错误位置的反馈，以帮助调试。

Python 目前在编译时保留了一个字节码到行号的映射。解释器使用此映射来指向与错误关联的源代码行。虽然指令的行级粒度很有用，但一行 Python 代码可以编译成数十个字节码操作，这使得难以跟踪导致错误的代码行哪一部分。

考虑以下 Python 代码行

x['a']['b']['c']['d'] = 1

如果字典中的任何值是 None，则显示的错误是

Traceback (most recent call last):
  File "test.py", line 2, in <module>
    x['a']['b']['c']['d'] = 1
TypeError: 'NoneType' object is not subscriptable

从回溯信息中，无法确定哪个字典具有导致错误的 None 元素。用户通常必须附加调试器或拆分表达式以追踪问题。

但是，如果解释器具有字节码到列偏移量以及行号的映射，它可以帮助显示

Traceback (most recent call last):
  File "test.py", line 2, in <module>
    x['a']['b']['c']['d'] = 1
    ~~~~~~~~~~~^^^^^
TypeError: 'NoneType' object is not subscriptable

指示用户对象 x['a']['b'] 必须是 None。此突出显示将出现在回溯信息的每个帧中。例如，如果类似的错误是复杂函数调用链的一部分，则回溯信息将显示与每个帧中当前指令关联的代码

Traceback (most recent call last):
  File "test.py", line 14, in <module>
    lel3(x)
    ^^^^^^^
  File "test.py", line 12, in lel3
    return lel2(x) / 23
           ^^^^^^^
  File "test.py", line 9, in lel2
    return 25 + lel(x) + lel(x)
                ^^^^^^
  File "test.py", line 6, in lel
    return 1 + foo(a,b,c=x['z']['x']['y']['z']['y'], d=e)
                         ~~~~~~~~~~~~~~~~^^^^^
TypeError: 'NoneType' object is not subscriptable

此问题出现在以下情况下。

• 当将多个对象传递给函数调用时，同时访问其中的相同属性。例如，此错误

  Traceback (most recent call last):
    File "test.py", line 19, in <module>
      foo(a.name, b.name, c.name)
  AttributeError: 'NoneType' object has no attribute 'name'
  

  使用本 PEP 中的改进，这将显示

  Traceback (most recent call last):
    File "test.py", line 17, in <module>
      foo(a.name, b.name, c.name)
                  ^^^^^^
  AttributeError: 'NoneType' object has no attribute 'name'
  

• 处理包含复杂数学表达式的行时，尤其是在 numpy 等库中，算术运算可能会根据参数失败。例如

  Traceback (most recent call last):
    File "test.py", line 1, in <module>
      x = (a + b) @ (c + d)
  ValueError: operands could not be broadcast together with shapes (1,2) (2,3)
  

  没有明确的指示说明哪个操作失败了，是左边的加法、右边的加法还是中间的矩阵乘法？使用本 PEP，新的错误消息将如下所示

  Traceback (most recent call last):
    File "test.py", line 1, in <module>
      x = (a + b) @ (c + d)
                     ~~^~~
  ValueError: operands could not be broadcast together with shapes (1,2) (2,3)
  

  提供了一个更清晰、更容易调试的错误消息。

除了调试之外，此额外信息对于代码覆盖率工具也很有用，使它们能够测量表达式级覆盖率，而不仅仅是行级覆盖率。例如，给定以下行

x = foo() if bar() else baz()

覆盖率、分析或状态分析工具将在两个分支中突出显示整行，这使得无法区分采取了哪个分支。这是 pycoverage 中的一个已知问题。

类似于本 PEP 的工作已经在其他语言中进行，例如 Java 中的 JEP358。Java 中的 NullPointerExceptions 在处理包含复杂表达式的行时同样模糊不清。一个 NullPointerException 在查找错误的根本原因方面提供的帮助非常少。JEP358 的实现相当复杂，需要使用控制流图分析器和反编译技术回溯字节码，以恢复导致空指针的源代码。尽管此解决方案的复杂性很高，并且每次更改 Java 字节码时都需要维护反编译器，但此改进被认为值得为仅一种异常类型提供的额外信息。

基本原理

为了识别在引发异常时执行的源代码范围，此提案要求为每个字节码指令添加新的数据。这将影响磁盘上 pyc 文件的大小以及内存中代码对象的大小。本提案的作者以一种试图最大程度地减少这种影响的方式选择了数据类型。建议的开销是为每个字节码指令存储两个 uint8_t（一个用于起始偏移量，一个用于结束偏移量）以及结束行信息（以与当前存储的起始行相同的方式编码）。

作为一个说明性示例来衡量此更改的影响，我们计算出包含起始和结束偏移量将使标准库的 pyc 文件大小增加 22%（6MB），从 28.4MB 增加到 34.7MB。内存使用量的开销将相同（假设完整标准库加载到同一个程序中）。我们认为这是一个非常可以接受的数字，因为开销的数量级非常小，特别是考虑到现代计算机的存储大小和内存能力。此外，通常 Python 程序的内存大小不受代码对象支配。为了检查这个假设，我们执行了几个流行的 PyPI 项目（包括 NumPy、pytest、Django 和 Cython）以及几个应用程序（Black、pylint、mypy 在 mypy 或标准库上执行）的测试套件，我们发现代码对象通常占程序平均内存大小的 3-6%。

我们理解此信息的额外成本对于某些用户来说可能无法接受，因此我们提出了一个退出机制，该机制将导致生成的代码对象不包含额外信息，同时还允许 pyc 文件不包含额外信息。

规范

为了获得足够的信息来正确解析引发错误的给定行中的位置，需要一个将字节码指令链接到列偏移量（起始和结束偏移量）和结束行号的映射。这类似于当前将行号链接到字节码指令的方式。

以下更改将在本 PEP 的实现过程中执行

• 偏移量信息将通过代码对象类中的一个新属性 co_positions 公开给 Python，该属性将返回一个四元素元组序列，其中包含每个指令的完整位置（包括起始行、结束行、起始列偏移量和结束列偏移量），或者如果代码对象是在没有偏移量信息的情况下创建的，则返回 None。
• 一个新的 C-API 函数

  int PyCode_Addr2Location(
      PyCodeObject *co, int addrq,
      int *start_line, int *start_column,
      int *end_line, int *end_column)
  

  将被添加，以便在给定字节码指令的索引的情况下可以获取结束行、起始列偏移量和结束列偏移量。如果信息不可用，此函数将值设置为 0。

信息的内部存储、压缩和编码作为实现细节，可以在任何时候更改，只要公共 API 保持不变。

  File "test.py", line 6, in lel
    return 1 + foo(a,b,c=x['z']['x']['y']['z']['y'], d=e)
                         ~~~~~~~~~~~~~~~~^^^^^
TypeError: 'NoneType' object is not subscriptable

def foo(x):
    1 + 1/0 + 2

def bar(x):
    try:
        1 + foo(x) + foo(x)
    except Exception as e:
        raise ValueError("oh no!") from e

bar(bar(bar(2)))

Traceback (most recent call last):
  File "test.py", line 6, in bar
    1 + foo(x) + foo(x)
        ^^^^^^
  File "test.py", line 2, in foo
    1 + 1/0 + 2
        ~^~
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "test.py", line 10, in <module>
    bar(bar(bar(2)))
            ^^^^^^
  File "test.py", line 8, in bar
    raise ValueError("oh no!") from e
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: oh no

def foo(x):
    1 + 1/0 + 2
def bar(x):
    try:
        1 + foo(x) + foo(x)
    except Exception:
        raise
bar(bar(bar(2)))

Traceback (most recent call last):
  File "test.py", line 10, in <module>
    bar(bar(bar(2)))
            ^^^^^^
  File "test.py", line 6, in bar
    1 + foo(x) + foo(x)
        ^^^^^^
  File "test.py", line 2, in foo
    1 + 1/0 + 2
        ~^~
ZeroDivisionError: division by zero

向后兼容性

更改完全向后兼容。

参考实现

可以在实现分支中找到参考实现。

被拒绝的想法

致谢

感谢 Carl Friedrich Bolz-Tereick 为 Pypy 解释器展示了这个想法的初始原型，并进行了有益的讨论。

版权

本文档置于公共领域或根据 CC0-1.0-Universal 许可证，以两者中许可范围更广者为准。