Skip to content

gh-119786: add code object doc, inline locations.md into it #126832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iritkatriel merged 5 commits into from
Nov 22, 2024
Merged

gh-119786: add code object doc, inline locations.md into it #126832

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9817511
gh-119786: add code object doc, inline locations.md into it
iritkatriel Nov 14, 2024
cd4142d
Update Objects/lnotab_notes.txt
iritkatriel Nov 14, 2024
b4d819d
Delete InternalDocs/_code_objects.md
iritkatriel Nov 14, 2024
93cc192
Apply suggestions from code review
iritkatriel Nov 19, 2024
dfc672b
mark's comments
iritkatriel Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
mark's comments
  • Loading branch information
@iritkatriel
iritkatriel committed Nov 22, 2024
commit dfc672bffd5ec6d5c3938abc7fb28de452fcfb9d
11 changes: 4 additions & 7 deletions InternalDocs/code_objects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,6 @@ Code objects are typically produced by the bytecode [compiler](compiler.md),
although they are often written to disk by one process and read back in by another.
The disk version of a code object is serialized using the
[marshal](https://docs.python.org/dev/library/marshal.html) protocol.
Some code objects are pre-loaded into the interpreter using
[`Tools/build/deepfreeze.py`](../Tools/build/deepfreeze.py),
which writes
[`Python/deepfreeze/deepfreeze.c`](../Python/deepfreeze/deepfreeze.c).

Code objects are nominally immutable.
Some fields (including `co_code_adaptive` and fields for runtime
Expand Down Expand Up @@ -58,8 +54,8 @@ compact, but doesn't return end line numbers or column offsets.
From C code, you need to call
[`PyCode_Addr2Location`](https://docs.python.org/dev/c-api/code.html#c.PyCode_Addr2Location).

As the locations table is only consulted by exception handling (to set ``tb_lineno``)
and by tracing (to pass the line number to the tracing function), lookup is not
As the locations table is only consulted when displaying a traceback and when
tracing (to pass the line number to the tracing function), lookup is not
performance critical.
In order to reduce the overhead during tracing, the mapping from instruction offset to
line number is cached in the ``_co_linearray`` field.
Expand All @@ -72,9 +68,10 @@ returned by the `co_positions()` iterator.

> [!NOTE]
> `co_linetable` is not to be confused with `co_lnotab`.
> For backwards compatibility, `co_lnotab` stores the format
> For backwards compatibility, `co_lnotab` exposes the format
> as it existed in Python 3.10 and lower: this older format
> stores only the start line for each instruction.
> It is lazily created from `co_linetable` when accessed.
> See [`Objects/lnotab_notes.txt`](../Objects/lnotab_notes.txt) for more details.

`co_linetable` consists of a sequence of location entries.
Expand Down