Skip to content

Commit d0bfff4

Browse files
authored
gh-119786: [doc] more consistent syntax in InternalDocs (#125815)
1 parent 4848b0b commit d0bfff4

File tree

6 files changed

+380
-429
lines changed

6 files changed

+380
-429
lines changed

InternalDocs/adaptive.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,7 @@ although these are not fundamental and may change:
3131

3232
## Example family
3333

34-
The `LOAD_GLOBAL` instruction (in
35-
[Python/bytecodes.c](https://github.com/python/cpython/blob/main/Python/bytecodes.c))
34+
The `LOAD_GLOBAL` instruction (in [Python/bytecodes.c](../Python/bytecodes.c))
3635
already has an adaptive family that serves as a relatively simple example.
3736

3837
The `LOAD_GLOBAL` instruction performs adaptive specialization,

InternalDocs/compiler.md

+194-224
Large diffs are not rendered by default.

InternalDocs/exception_handling.md

+12-16
Original file line numberDiff line numberDiff line change
@@ -68,18 +68,16 @@ Handling Exceptions
6868
-------------------
6969

7070
At runtime, when an exception occurs, the interpreter calls
71-
``get_exception_handler()`` in
72-
[Python/ceval.c](https://github.com/python/cpython/blob/main/Python/ceval.c)
71+
`get_exception_handler()` in [Python/ceval.c](../Python/ceval.c)
7372
to look up the offset of the current instruction in the exception
7473
table. If it finds a handler, control flow transfers to it. Otherwise, the
7574
exception bubbles up to the caller, and the caller's frame is
7675
checked for a handler covering the `CALL` instruction. This
7776
repeats until a handler is found or the topmost frame is reached.
7877
If no handler is found, then the interpreter function
79-
(``_PyEval_EvalFrameDefault()``) returns NULL. During unwinding,
78+
(`_PyEval_EvalFrameDefault()`) returns NULL. During unwinding,
8079
the traceback is constructed as each frame is added to it by
81-
``PyTraceBack_Here()``, which is in
82-
[Python/traceback.c](https://github.com/python/cpython/blob/main/Python/traceback.c).
80+
`PyTraceBack_Here()`, which is in [Python/traceback.c](../Python/traceback.c).
8381

8482
Along with the location of an exception handler, each entry of the
8583
exception table also contains the stack depth of the `try` instruction
@@ -174,22 +172,20 @@ which is then encoded as:
174172

175173
for a total of five bytes.
176174

177-
The code to construct the exception table is in ``assemble_exception_table()``
178-
in [Python/assemble.c](https://github.com/python/cpython/blob/main/Python/assemble.c).
175+
The code to construct the exception table is in `assemble_exception_table()`
176+
in [Python/assemble.c](../Python/assemble.c).
179177

180178
The interpreter's function to lookup the table by instruction offset is
181-
``get_exception_handler()`` in
182-
[Python/ceval.c](https://github.com/python/cpython/blob/main/Python/ceval.c).
183-
The Python function ``_parse_exception_table()`` in
184-
[Lib/dis.py](https://github.com/python/cpython/blob/main/Lib/dis.py)
179+
`get_exception_handler()` in [Python/ceval.c](../Python/ceval.c).
180+
The Python function `_parse_exception_table()` in [Lib/dis.py](../Lib/dis.py)
185181
returns the exception table content as a list of namedtuple instances.
186182

187183
Exception Chaining Implementation
188184
---------------------------------
189185

190186
[Exception chaining](https://docs.python.org/dev/tutorial/errors.html#exception-chaining)
191-
refers to setting the ``__context__`` and ``__cause__`` fields of an exception as it is
192-
being raised. The ``__context__`` field is set by ``_PyErr_SetObject()`` in
193-
[Python/errors.c](https://github.com/python/cpython/blob/main/Python/errors.c)
194-
(which is ultimately called by all ``PyErr_Set*()`` functions).
195-
The ``__cause__`` field (explicit chaining) is set by the ``RAISE_VARARGS`` bytecode.
187+
refers to setting the `__context__` and `__cause__` fields of an exception as it is
188+
being raised. The `__context__` field is set by `_PyErr_SetObject()` in
189+
[Python/errors.c](../Python/errors.c) (which is ultimately called by all
190+
`PyErr_Set*()` functions). The `__cause__` field (explicit chaining) is set by
191+
the `RAISE_VARARGS` bytecode.

InternalDocs/frames.md

+8-10
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,19 @@ of three conceptual sections:
1010
globals dict, code object, instruction pointer, stack depth, the
1111
previous frame, etc.
1212

13-
The definition of the ``_PyInterpreterFrame`` struct is in
14-
[Include/internal/pycore_frame.h](https://github.com/python/cpython/blob/main/Include/internal/pycore_frame.h).
13+
The definition of the `_PyInterpreterFrame` struct is in
14+
[Include/internal/pycore_frame.h](../Include/internal/pycore_frame.h).
1515

1616
# Allocation
1717

1818
Python semantics allows frames to outlive the activation, so they need to
1919
be allocated outside the C call stack. To reduce overhead and improve locality
2020
of reference, most frames are allocated contiguously in a per-thread stack
21-
(see ``_PyThreadState_PushFrame`` in
22-
[Python/pystate.c](https://github.com/python/cpython/blob/main/Python/pystate.c)).
21+
(see `_PyThreadState_PushFrame` in [Python/pystate.c](../Python/pystate.c)).
2322

2423
Frames of generators and coroutines are embedded in the generator and coroutine
25-
objects, so are not allocated in the per-thread stack. See ``PyGenObject`` in
26-
[Include/internal/pycore_genobject.h](https://github.com/python/cpython/blob/main/Include/internal/pycore_genobject.h).
24+
objects, so are not allocated in the per-thread stack. See `PyGenObject` in
25+
[Include/internal/pycore_genobject.h](../Include/internal/pycore_genobject.h).
2726

2827
## Layout
2928

@@ -82,16 +81,15 @@ frames for each activation, but with low runtime overhead.
8281

8382
### Generators and Coroutines
8483

85-
Generators (objects of type ``PyGen_Type``, ``PyCoro_Type`` or
86-
``PyAsyncGen_Type``) have a `_PyInterpreterFrame` embedded in them, so
84+
Generators (objects of type `PyGen_Type`, `PyCoro_Type` or
85+
`PyAsyncGen_Type`) have a `_PyInterpreterFrame` embedded in them, so
8786
that they can be created with a single memory allocation.
8887
When such an embedded frame is iterated or awaited, it can be linked with
8988
frames on the per-thread stack via the linkage fields.
9089

9190
If a frame object associated with a generator outlives the generator, then
9291
the embedded `_PyInterpreterFrame` is copied into the frame object (see
93-
``take_ownership()`` in
94-
[Python/frame.c](https://github.com/python/cpython/blob/main/Python/frame.c)).
92+
`take_ownership()` in [Python/frame.c](../Python/frame.c)).
9593

9694
### Field names
9795

0 commit comments

Comments
 (0)