Skip to content

gh-139588: Docs: Convert the execution model "textual" diagram to a visual diagram #140721

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

gh-139588: Docs: Convert the execution model "textual" diagram to a visual diagram #140721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c042754
Doc: Add sphinx.ext.graphviz extension dependency
adorilson Oct 28, 2025
c0dd3c4
Doc: Convert the execution model "textual" diagram to a visual diagra…
adorilson Oct 28, 2025
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
5 changes: 5 additions & 0 deletions Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
'sphinx.ext.coverage',
'sphinx.ext.doctest',
'sphinx.ext.extlinks',
'sphinx.ext.graphviz',
]

# Skip if downstream redistributors haven't installed them
Expand Down Expand Up @@ -560,6 +561,10 @@
}
extlinks_detect_hardcoded_links = True

# Options for sphinx.ext.graphviz
# -------------------------------
graphviz_output_format = 'svg'

# Options for c_annotations extension
# -----------------------------------

Expand Down
87 changes: 78 additions & 9 deletions Doc/reference/executionmodel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,9 +412,35 @@ its operating system (OS), if there is one. When a program runs,
the conceptual layers of how it runs on the host look something
like this:

| **host machine**
| **process** (global resources)
| **thread** (runs machine code)
.. graphviz::

digraph general_comput_model {
graph [
bgcolor=white,
splines=false,
overlap=false,
rankdir=TB,
];

subgraph cluster_host {
label="host machine";
style=filled;
color=lightgrey;
penwidth=2;
shape=ellipse;

subgraph cluster_process {
label="process\n(global resources)";
style=filled;
color=white;
penwidth=2;

thread [label="thread\n(runs machine code)",
style=filled, fillcolor=lightgreen];

}
}
}

Each process represents a program running on the host. Think of each
process itself as the data part of its program. Think of the process'
Expand Down Expand Up @@ -471,12 +497,55 @@ Python Runtime Model
The same conceptual layers apply to each Python program, with some
extra data layers specific to Python:

| **host machine**
| **process** (global resources)
| Python global runtime (*state*)
| Python interpreter (*state*)
| **thread** (runs Python bytecode and "C-API")
| Python thread *state*
.. graphviz::

digraph python_exec_model {
graph [
bgcolor=white,
splines=false,
overlap=false,
rankdir=TB,
];

subgraph cluster_host {
label="host machine";
style=filled;
color=lightgrey;
penwidth=2;
shape=ellipse;

subgraph cluster_process {
label="process\n(global resources)";
style=filled;
color=white;
penwidth=2;

subgraph cluster_runtime {
label="Python global runtime\n(state)";
style=filled;
color=lightyellow;
penwidth=2;

subgraph cluster_interpreter {
label="Python interpreter\n(state)";
style=filled;
color=lightblue;
penwidth=2;

subgraph cluster_thread {
label="thread\n(runs Python bytecode and C-API)";
style=filled;
color=lightgreen;
penwidth=2;

thread_state [label="Python thread state",
style=filled, fillcolor=white];
}
}
}
}
}
}

At the conceptual level: when a Python program starts, it looks exactly
like that diagram, with one of each. The runtime may grow to include
Expand Down
Loading