PEP 657 – Include Fine Grained Error Locations in Tracebacks | peps.python.org
PEP 657 – Include Fine Grained Error Locations in Tracebacks PEP 657 – Include Fine Grained Error Locations in Tracebacks Author : Pablo Galindo Salgado <pablogsal at python.org>, Batuhan Taskaya <batuhan at python.org>, Ammar Askar <ammar at ammaraskar.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 08-May-2021 Python-Version : 3.11 Post-History : Table of Contents Abstract Motivation Rationale Specification Offset semantics Displaying tracebacks Opt-out mechanism Backwards Compatibility Reference Implementation Rejected Ideas Use a single caret instead of a range Have a configure flag to opt out Lazy loading of column information Implement compression Acknowledgments Copyright Abstract This PEP proposes adding a mapping from each bytecode instruction to the start and end column offsets of the line that generated them as well as the end line number.
This data will be used to improve tracebacks displayed by the CPython interpreter in order to improve the debugging experience. The PEP also proposes adding APIs that allow other tools (such as coverage analysis tools, profilers, tracers, debuggers) to consume this information from code objects. Motivation The primary motivation for this PEP is to improve the feedback presented about the location of errors to aid with debugging.
Python currently keeps a mapping of bytecode to line numbers from compilation. The interpreter uses this mapping to point to the source line associated with an error. While this line-level granularity for instructions is useful, a single line of Python code can compile into dozens of bytecode operations making it hard to track which part of the line caused the error. Consider the following line of Python code: x [ 'a' ][ 'b' ][ 'c' ][ 'd' ] = 1 If any of the values in the dictionaries are None , the error shown is: Traceback ( most recent call last ): File "test.py" , line 2 , in < module > x [ 'a' ][ 'b' ][ 'c' ][ 'd' ] = 1 TypeError : 'NoneType' object is not subscriptable From the traceback, it is impossible to determine which one of the dictionaries had the None element that caused the error.
Users often have to attach a debugger or split up their expression to track down the problem. However, if the interpreter had a mapping of bytecode to column offsets as well as line numbers, it could helpfully display: Traceback ( most recent call last ): File "test.py" , line 2 , in < module > x [ 'a' ][ 'b' ][ 'c' ][ 'd' ] = 1 ~~~~~~~~~~~^^^^^ TypeError : 'NoneType' object is not subscriptable indicating to the user that the object x['a']['b'] must have been None .
This highlighting will occur for every frame in the traceback. For instance, if a similar error is part of a complex function call chain, the traceback would display the code associated to the current instruction in every frame: 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 This problem presents itself in the following situations.
When passing down multiple objects to function calls while accessing the same attribute in them. For instance, this error: 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' With the improvements in this PEP this would show: 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' When dealing with lines with complex mathematical expressions, especially with libraries such as numpy where arithmetic operations can fail based on the arguments.
For example: 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 ) There is no clear indication as to which operation failed, was it the addition on the left, the right or the matrix multiplication in the middle? With this PEP the new error message would look like: 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 ) Giving a much clearer and easier to debug error message.
Debugging aside, this extra information would also be useful for code coverage tools, enabling them to measure expression-level coverage instead of just line-level coverage. For instance, given the following line: x = foo () if bar () else baz () coverage, profile or state analysis tools will highlight the full line in both branches, making it impossible to differentiate what branch was taken. This is a known problem in pycoverage .
Similar efforts to this PEP have taken place in other languages such as Java in the form of JEP358 . NullPointerExceptions in Java were similarly nebulous when it came to lines with complicated expressions. A NullPointerException would provide very little aid in finding the root cause of an error. The implementation for JEP358 is fairly complex, requiring walking back through the bytecode by using a control flow graph analyzer and decompilation techniques to recover the source code that led to the null pointer.
Although the complexity of this solution is high and requires maintenance for the decompiler every time Java bytecode is changed, this improvement was deemed to be worth it for the extra information provided for just one exception type . Rationale In order to identify the range of source code being executed when exceptions are raised, this proposal requires adding new data for every bytecode instruction. This will have an impact on the size of pyc files on disk and the size of code objects in memory.
The authors of this proposal have chosen the data types in a way that tries to minimize this impact. The proposed overhead is storing two uint8_t (one for the start offset and one for the end offset) and the end line information for every bytecode instruction (in the same encoded fashion as the start line is stored currently). As an illustrative example to gauge the impact of this change, we have calculated that including the start and end offsets will increase the size of the standard library’s pyc files by 22% (6MB) from 28.4MB to 34.7MB.
The overhead in memory usage will be the same (assuming the full standard library is loaded into the same program). We believe that this is a very acceptable number since the order of magnitude of the overhead is very small, especially considering the storage size and memory capabilities of modern computers. Additionally, in general the memory size of a Python program is not dominated by code objects. To check this assumption we have executed the test suite of several popular PyPI projects (including NumPy, pytest, Django and Cython) as well as several applications (Black, pylint, mypy executed over either mypy or the standard library) and we found that code objects represent normally 3-6% of the average memory size of the program.
We understand that the extra cost of this information may not be acceptable for some users, so we propose an opt-out mechanism which will cause generated code objects to not have the extra information while also allowing pyc files to not include the extra information. Specification In order to have enough information to correctly resolve the location within a given line where an error was raised, a map linking bytecode instructions to column offsets (start and end offset) and end line numbers is needed.
This is similar in fashion to how line numbers are currently lin
The rest of this page is on the live site.