摘要

本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中的NullPointerException在处理包含复杂表达式的行时同样模糊不清。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 许可证下，以更宽松者为准。