loop-autopsy 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/LICENSE +22 -22
  2. {loop_autopsy-0.1.0/src/loop_autopsy.egg-info → loop_autopsy-0.2.0}/PKG-INFO +243 -230
  3. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/README.md +218 -205
  4. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/pyproject.toml +44 -44
  5. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/setup.cfg +4 -4
  6. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/__init__.py +57 -57
  7. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/config.py +112 -109
  8. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/detectors.py +279 -279
  9. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/growth.py +204 -204
  10. loop_autopsy-0.2.0/src/loop_autopsy/heatmap.py +367 -0
  11. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/magics.py +69 -65
  12. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/monitor.py +166 -166
  13. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/report.py +207 -207
  14. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy/transformer.py +215 -215
  15. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0/src/loop_autopsy.egg-info}/PKG-INFO +243 -230
  16. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/tests/test_detectors.py +81 -81
  17. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/tests/test_end_to_end.py +98 -74
  18. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/tests/test_growth.py +63 -63
  19. loop_autopsy-0.2.0/tests/test_heatmap.py +147 -0
  20. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/tests/test_report.py +43 -43
  21. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/tests/test_transformer.py +69 -69
  22. loop_autopsy-0.1.0/src/loop_autopsy/heatmap.py +0 -171
  23. loop_autopsy-0.1.0/tests/test_heatmap.py +0 -47
  24. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy.egg-info/SOURCES.txt +0 -0
  25. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy.egg-info/dependency_links.txt +0 -0
  26. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy.egg-info/requires.txt +0 -0
  27. {loop_autopsy-0.1.0 → loop_autopsy-0.2.0}/src/loop_autopsy.egg-info/top_level.txt +0 -0
@@ -1,22 +1,22 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 NATHANAEL George Steindhart, SETIAWAN Matthew Henson,
4
- LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
5
-
6
- Permission is hereby granted, free of charge, to any person obtaining a copy
7
- of this software and associated documentation files (the "Software"), to deal
8
- in the Software without restriction, including without limitation the rights
9
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
- copies of the Software, and to permit persons to whom the Software is
11
- furnished to do so, subject to the following conditions:
12
-
13
- The above copyright notice and this permission notice shall be included in all
14
- copies or substantial portions of the Software.
15
-
16
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NATHANAEL George Steindhart, SETIAWAN Matthew Henson,
4
+ LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
@@ -1,230 +1,243 @@
1
- Metadata-Version: 2.4
2
- Name: loop-autopsy
3
- Version: 0.1.0
4
- Summary: Stops runaway loops in Jupyter and shows the evidence for why they never ended.
5
- Author: NATHANAEL George Steindhart, SETIAWAN Matthew Henson, LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
6
- License: MIT
7
- Project-URL: Homepage, https://github.com/Geoeoeo217/loop-autopsy
8
- Project-URL: Repository, https://github.com/Geoeoeo217/loop-autopsy
9
- Project-URL: Documentation, https://github.com/Geoeoeo217/loop-autopsy#readme
10
- Keywords: jupyter,ipython,education,infinite-loop,debugging,beginners
11
- Classifier: Framework :: IPython
12
- Classifier: Framework :: Jupyter
13
- Classifier: Intended Audience :: Education
14
- Classifier: License :: OSI Approved :: MIT License
15
- Classifier: Programming Language :: Python :: 3
16
- Classifier: Topic :: Education
17
- Classifier: Topic :: Software Development :: Debuggers
18
- Requires-Python: >=3.9
19
- Description-Content-Type: text/markdown
20
- License-File: LICENSE
21
- Requires-Dist: ipython>=7.0
22
- Provides-Extra: test
23
- Requires-Dist: pytest; extra == "test"
24
- Dynamic: license-file
25
-
26
- # loop-autopsy
27
-
28
- **Stops runaway loops in Jupyter and shows the evidence for why they never ended.**
29
-
30
- ```python
31
- %load_ext loop_autopsy
32
-
33
- count = 1
34
- while count <= 5:
35
- print(count)
36
- ```
37
-
38
- Instead of freezing the notebook, the loop is stopped after 3 rounds and you get:
39
-
40
- ![A loop-autopsy report for a stuck loop](https://raw.githubusercontent.com/Geoeoeo217/loop-autopsy/main/docs/report.png)
41
-
42
- ```
43
- Loop autopsy — stuck loop (line 2)
44
- while count <= 5:
45
-
46
- Nothing changed between rounds: `count = 1` stayed exactly the same, so the
47
- condition `count <= 5` is True every time and the loop can never end.
48
-
49
- Last rounds checked:
50
- round count (same)
51
- ----- ------------
52
- 1 1
53
- 2 1
54
- 3 1
55
-
56
- Hint: Add a line inside the loop that changes `count` so that `count <= 5`
57
- eventually becomes False (for example `count += 1`).
58
- ```
59
-
60
- ---
61
-
62
- ## Motivation
63
-
64
- Every beginner writes an infinite loop. In a notebook on a shared JupyterHub this
65
- is worse than it sounds:
66
-
67
- - the cell hangs with no explanation, and the only remedy is the stop button ■;
68
- - a `print` inside the loop floods the browser with output until the tab freezes;
69
- - the loop keeps using CPU and memory on a server shared by the whole class.
70
-
71
- Pressing ■ stops the loop but teaches nothing. The student still does not know
72
- *which* variable failed to change or *why* the condition never became False.
73
-
74
- ## Innovation
75
-
76
- loop-autopsy watches loops **while they run** and stops them only when it can
77
- **prove** they will never end. Then it shows the evidence.
78
-
79
- | | Stops a stuck loop? | Explains *why*? | When? |
80
- |---|---|---|---|
81
- | Stop button ■ | yes (you press it) | no | whenever you notice |
82
- | Timeout decorators (e.g. `wrapt_timeout_decorator`) | yes, after a fixed time | no | after the time limit |
83
- | Error explainers (e.g. `friendly-traceback`) | no | explains *errors*, but an infinite loop raises none | after a crash |
84
- | Memory monitors (e.g. `jupyter-resource-usage`) | no | no | shows totals only |
85
- | **loop-autopsy** | **yes, automatically** | **yes, with a replay table** | **during the loop, often after 3 rounds** |
86
-
87
- How it works, in short:
88
-
89
- 1. An IPython **AST transformer** (it edits the code's syntax tree before it runs)
90
- adds a tiny check to every `while` and `for` loop you type in a cell.
91
- 2. Each check takes a **fingerprint** of the loop's variables. If a deterministic
92
- loop comes back to an *exactly identical* state, it must repeat forever: that
93
- is a proof, not a guess.
94
- 3. Further rules catch a counter moving *away* from its target, a `!=` condition
95
- that jumps over its stop value (`0.1 + 0.1 + ...` never equals `1.0`), a list
96
- that grows while you loop over it, and memory running out.
97
- 4. Anything it cannot prove falls back to an honest time limit. No AI model, no
98
- internet, and the same result every time.
99
-
100
- Every rule and its numbers are listed below, and every number can be changed (see Settings).
101
-
102
- ## What it detects
103
-
104
- | Pattern | Example | Stopped after |
105
- |---|---|---|
106
- | **Stuck**: nothing changes | `while count <= 5: print(count)` | 3 rounds |
107
- | **Cycle**: values go round in a circle | `while a < 5: a = (a + 1) % 3` | about 2 cycles |
108
- | **Wrong direction** | `while i < 10: i -= 1` | 500 checks |
109
- | **Jumped over** the stop value | `while x != 1.0: x += 0.1` | about 100 checks |
110
- | **Growing list** in a `for` loop | `for n in nums: nums.append(n)` | 2,000 rounds |
111
- | **Memory** about to run out | a loop filling a huge list | at 85% of the limit |
112
- | **Too long** (fallback) | anything else | 60 s |
113
-
114
- Plus two extras:
115
-
116
- - **Press ■ yourself** and you still get the replay table, showing which
117
- variables never changed.
118
- - **Cell health bar**: time, memory and loops for a cell, coloured green / yellow /
119
- red. It warns when memory passes 75% of your limit and names the biggest
120
- variables (pandas and NumPy aware). It also mutes output after 1,000 printed
121
- lines so the browser stays responsive.
122
-
123
- ## Example use cases
124
-
125
- - **Students** in an intro course: load it once at the top of every notebook and
126
- never lose a session to a frozen loop again.
127
- - **Instructors** on JupyterHub: load it for everyone (see below) to protect the
128
- shared server and turn every infinite loop into a mini-lesson.
129
- - **Teaching assistants**: the replay table shows at a glance what went wrong in
130
- a student's loop.
131
- - **Data notebooks**: the health bar shows which cell is slow or memory-hungry.
132
-
133
- ## Setup
134
-
135
- ```bash
136
- pip install loop-autopsy
137
- ```
138
-
139
- The only requirement is IPython (already present in Jupyter). Python 3.9+.
140
-
141
- In a notebook:
142
-
143
- ```python
144
- %load_ext loop_autopsy
145
- ```
146
-
147
- **For instructors**: to turn it on for every notebook, add this to the IPython
148
- profile (`~/.ipython/profile_default/ipython_config.py`):
149
-
150
- ```python
151
- c.InteractiveShellApp.extensions = ["loop_autopsy"]
152
- ```
153
-
154
- ## Usage
155
-
156
- | Command | Effect |
157
- |---|---|
158
- | `%autopsy` | status and settings |
159
- | `%autopsy on` / `off` | start / stop watching loops |
160
- | `%autopsy last` | show the last report again |
161
- | `%autopsy heatmap on` / `off` / `auto` | cell health bar (`auto` = only when a cell is slow or memory-heavy) |
162
- | `%autopsy config time_limit=120` | change a setting (see Settings below) |
163
- | `%%autopsy off` | first line of a cell: run that cell without watching |
164
- | `%autopsy help` | help |
165
-
166
- Cells that use `%timeit` / `%%timeit` are never watched, so timings stay accurate.
167
- Loops inside generators (`yield`) are left alone, because infinite generators are
168
- normal.
169
-
170
- Try [examples/demo.ipynb](examples/demo.ipynb) for every feature in one notebook.
171
-
172
- ## Settings
173
-
174
- Change any of these with `%autopsy config key=value` (for example `%autopsy config time_limit=120`).
175
-
176
- | Setting | Default | Meaning |
177
- |---|---|---|
178
- | `time_limit` | 60 | seconds before a loop that cannot be proven stuck is stopped (0 = never) |
179
- | `direction_after` | 500 | checks in a row moving away from the stop value before "wrong direction" |
180
- | `jump_after` | 100 | checks in a row after jumping over a `!=` stop value |
181
- | `growth_after` | 2000 | rounds before a growing list in a `for` loop is reported |
182
- | `memory_stop` | 0.85 | stop a loop when memory reaches this fraction of the limit |
183
- | `memory_warn` | 0.75 | health bar warning at this fraction of the limit |
184
- | `max_output_lines` | 1000 | printed lines per cell before output is muted (0 = off) |
185
- | `replay_rows` | 6 | rows in the replay table |
186
- | `max_watched` | 25 | variables watched per loop |
187
- | `heatmap` | `auto` | `on`, `off` or `auto` |
188
- | `time_yellow` / `time_red` | 1.0 / 10.0 | seconds for a yellow / red health bar |
189
- | `mem_yellow` / `mem_red` | 0.50 / 0.80 | memory fraction for a yellow / red health bar |
190
-
191
- The memory limit is read from JupyterHub's `MEM_LIMIT` setting, then the container's
192
- memory limit, then the computer's total RAM.
193
-
194
- ## Limitations (honest list)
195
-
196
- - No tool can detect *every* infinite loop (the halting problem). loop-autopsy
197
- only reports a stuck, cycling, wrong-direction or jumped-over loop when it can
198
- prove it; everything else gets the time limit.
199
- - Loops that call your own functions or modules such as `random` cannot be proven
200
- stuck (those calls might change hidden state), so they rely on the time limit.
201
- - Only code typed in notebook cells is watched, not code inside imported modules.
202
- - Watching adds a small cost to each loop round (roughly 0.1–0.2 µs per round on
203
- simple loops). Use `%%autopsy off` for heavy number crunching.
204
- - A bare `except:` inside a loop can catch the stop signal, just as it catches ■.
205
-
206
- ## Development
207
-
208
- ```bash
209
- git clone https://github.com/Geoeoeo217/loop-autopsy
210
- cd loop-autopsy
211
- pip install -e ".[test]"
212
- pytest
213
- ```
214
-
215
- ## Team
216
-
217
- Built by a team of five for CS1302 (Introduction to Computer Programming).
218
-
219
- | Member | Part |
220
- |---|---|
221
- | NATHANAEL George Steindhart | project lead: loop rewriting (`transformer.py`), run-time glue (`monitor.py`), magics, packaging |
222
- | SETIAWAN Matthew Henson | detection rules: stuck, cycle, wrong direction, jumped over, time limit (`detectors.py`) |
223
- | LATHIF Muhammad Akmal | memory and growing-list rules (`growth.py`) |
224
- | KWAN Kendrick Matthew | replay table and reports (`report.py`) |
225
- | HANDAYA Clement Steward | cell health bar and output guard (`heatmap.py`) |
226
-
227
-
228
- ## License
229
-
230
- MIT
1
+ Metadata-Version: 2.4
2
+ Name: loop-autopsy
3
+ Version: 0.2.0
4
+ Summary: Stops runaway loops in Jupyter and shows the evidence for why they never ended.
5
+ Author: NATHANAEL George Steindhart, SETIAWAN Matthew Henson, LATHIF Muhammad Akmal, KWAN Kendrick Matthew, HANDAYA Clement Steward
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Geoeoeo217/loop-autopsy
8
+ Project-URL: Repository, https://github.com/Geoeoeo217/loop-autopsy
9
+ Project-URL: Documentation, https://github.com/Geoeoeo217/loop-autopsy#readme
10
+ Keywords: jupyter,ipython,education,infinite-loop,debugging,beginners
11
+ Classifier: Framework :: IPython
12
+ Classifier: Framework :: Jupyter
13
+ Classifier: Intended Audience :: Education
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Education
17
+ Classifier: Topic :: Software Development :: Debuggers
18
+ Requires-Python: >=3.9
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: ipython>=7.0
22
+ Provides-Extra: test
23
+ Requires-Dist: pytest; extra == "test"
24
+ Dynamic: license-file
25
+
26
+ # loop-autopsy
27
+
28
+ **Stops runaway loops in Jupyter and shows the evidence for why they never ended.**
29
+
30
+ ```python
31
+ %load_ext loop_autopsy
32
+
33
+ count = 1
34
+ while count <= 5:
35
+ print(count)
36
+ ```
37
+
38
+ Instead of freezing the notebook, the loop is stopped after 3 rounds and you get:
39
+
40
+ ![A loop-autopsy report for a stuck loop](https://raw.githubusercontent.com/Geoeoeo217/loop-autopsy/main/docs/report.png)
41
+
42
+ ```
43
+ Loop autopsy — stuck loop (line 2)
44
+ while count <= 5:
45
+
46
+ Nothing changed between rounds: `count = 1` stayed exactly the same, so the
47
+ condition `count <= 5` is True every time and the loop can never end.
48
+
49
+ Last rounds checked:
50
+ round count (same)
51
+ ----- ------------
52
+ 1 1
53
+ 2 1
54
+ 3 1
55
+
56
+ Hint: Add a line inside the loop that changes `count` so that `count <= 5`
57
+ eventually becomes False (for example `count += 1`).
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Motivation
63
+
64
+ Every beginner writes an infinite loop. In a notebook on a shared JupyterHub this
65
+ is worse than it sounds:
66
+
67
+ - the cell hangs with no explanation, and the only remedy is the stop button ■;
68
+ - a `print` inside the loop floods the browser with output until the tab freezes;
69
+ - the loop keeps using CPU and memory on a server shared by the whole class.
70
+
71
+ Pressing ■ stops the loop but teaches nothing. The student still does not know
72
+ *which* variable failed to change or *why* the condition never became False.
73
+
74
+ ## Innovation
75
+
76
+ loop-autopsy watches loops **while they run** and stops them only when it can
77
+ **prove** they will never end. Then it shows the evidence.
78
+
79
+ | | Stops a stuck loop? | Explains *why*? | When? |
80
+ |---|---|---|---|
81
+ | Stop button ■ | yes (you press it) | no | whenever you notice |
82
+ | Timeout decorators (e.g. `wrapt_timeout_decorator`) | yes, after a fixed time | no | after the time limit |
83
+ | Error explainers (e.g. `friendly-traceback`) | no | explains *errors*, but an infinite loop raises none | after a crash |
84
+ | Memory monitors (e.g. `jupyter-resource-usage`) | no | no | shows totals only |
85
+ | **loop-autopsy** | **yes, automatically** | **yes, with a replay table** | **during the loop, often after 3 rounds** |
86
+
87
+ How it works, in short:
88
+
89
+ 1. An IPython **AST transformer** (it edits the code's syntax tree before it runs)
90
+ adds a tiny check to every `while` and `for` loop you type in a cell.
91
+ 2. Each check takes a **fingerprint** of the loop's variables. If a deterministic
92
+ loop comes back to an *exactly identical* state, it must repeat forever: that
93
+ is a proof, not a guess.
94
+ 3. Further rules catch a counter moving *away* from its target, a `!=` condition
95
+ that jumps over its stop value (`0.1 + 0.1 + ...` never equals `1.0`), a list
96
+ that grows while you loop over it, and memory running out.
97
+ 4. Anything it cannot prove falls back to an honest time limit. No AI model, no
98
+ internet, and the same result every time.
99
+
100
+ Every rule and its numbers are listed below, and every number can be changed (see Settings).
101
+
102
+ ## What it detects
103
+
104
+ | Pattern | Example | Stopped after |
105
+ |---|---|---|
106
+ | **Stuck**: nothing changes | `while count <= 5: print(count)` | 3 rounds |
107
+ | **Cycle**: values go round in a circle | `while a < 5: a = (a + 1) % 3` | about 2 cycles |
108
+ | **Wrong direction** | `while i < 10: i -= 1` | 500 checks |
109
+ | **Jumped over** the stop value | `while x != 1.0: x += 0.1` | about 100 checks |
110
+ | **Growing list** in a `for` loop | `for n in nums: nums.append(n)` | 2,000 rounds |
111
+ | **Memory** about to run out | a loop filling a huge list | at 85% of the limit |
112
+ | **Too long** (fallback) | anything else | 60 s |
113
+
114
+ Plus three extras:
115
+
116
+ - **Press ■ yourself** and you still get the replay table, showing which
117
+ variables never changed.
118
+ - **Cell health bar**: time, memory and loops for a cell, coloured green / yellow /
119
+ red. It warns when memory passes 75% of your limit and names the biggest
120
+ variables (pandas and NumPy aware). It also mutes output after 1,000 printed
121
+ lines so the browser stays responsive.
122
+ - **Session summary**: `%autopsy summary` shows every cell you have run as a strip
123
+ of coloured squares, then a table of the heaviest cells with their time, memory
124
+ and stopped loops. Here a cell is coloured only by what it did itself (its run
125
+ time and the memory it added), so one big dataframe does not turn every later
126
+ cell red. The health bar is different: it colours by total memory in use, to
127
+ warn you when you are close to the limit.
128
+
129
+ ## Example use cases
130
+
131
+ - **Students** in an intro course: load it once at the top of every notebook and
132
+ never lose a session to a frozen loop again.
133
+ - **Instructors** on JupyterHub: load it for everyone (see below) to protect the
134
+ shared server and turn every infinite loop into a mini-lesson.
135
+ - **Teaching assistants**: the replay table shows at a glance what went wrong in
136
+ a student's loop.
137
+ - **Data notebooks**: the health bar shows which cell is slow or memory-hungry.
138
+
139
+ ## Setup
140
+
141
+ ```bash
142
+ pip install loop-autopsy
143
+ ```
144
+
145
+ The only requirement is IPython (already present in Jupyter). Python 3.9+.
146
+
147
+ In a notebook:
148
+
149
+ ```python
150
+ %load_ext loop_autopsy
151
+ ```
152
+
153
+ **For instructors**: to turn it on for every notebook, add this to the IPython
154
+ profile (`~/.ipython/profile_default/ipython_config.py`):
155
+
156
+ ```python
157
+ c.InteractiveShellApp.extensions = ["loop_autopsy"]
158
+ ```
159
+
160
+ ## Usage
161
+
162
+ | Command | Effect |
163
+ |---|---|
164
+ | `%autopsy` | status and settings |
165
+ | `%autopsy on` / `off` | start / stop watching loops |
166
+ | `%autopsy last` | show the last report again |
167
+ | `%autopsy heatmap on` / `off` / `auto` | cell health bar (`auto` = only when a cell is slow or memory-heavy) |
168
+ | `%autopsy summary` | the 10 heaviest cells of this session, worst first |
169
+ | `%autopsy summary all` / `clear` | every cell in run order / forget the history |
170
+ | `%autopsy config time_limit=120` | change a setting (see Settings below) |
171
+ | `%%autopsy off` | first line of a cell: run that cell without watching |
172
+ | `%autopsy help` | help |
173
+
174
+ Cells that use `%timeit` / `%%timeit` are never watched, so timings stay accurate.
175
+ Loops inside generators (`yield`) are left alone, because infinite generators are
176
+ normal.
177
+
178
+ Try [examples/demo.ipynb](examples/demo.ipynb) for every feature in one notebook.
179
+
180
+ ## Settings
181
+
182
+ Change any of these with `%autopsy config key=value` (for example `%autopsy config time_limit=120`).
183
+
184
+ | Setting | Default | Meaning |
185
+ |---|---|---|
186
+ | `time_limit` | 60 | seconds before a loop that cannot be proven stuck is stopped (0 = never) |
187
+ | `direction_after` | 500 | checks in a row moving away from the stop value before "wrong direction" |
188
+ | `jump_after` | 100 | checks in a row after jumping over a `!=` stop value |
189
+ | `growth_after` | 2000 | rounds before a growing list in a `for` loop is reported |
190
+ | `memory_stop` | 0.85 | stop a loop when memory reaches this fraction of the limit |
191
+ | `memory_warn` | 0.75 | health bar warning at this fraction of the limit |
192
+ | `max_output_lines` | 1000 | printed lines per cell before output is muted (0 = off) |
193
+ | `replay_rows` | 6 | rows in the replay table |
194
+ | `max_watched` | 25 | variables watched per loop |
195
+ | `heatmap` | `auto` | `on`, `off` or `auto` |
196
+ | `time_yellow` / `time_red` | 1.0 / 10.0 | seconds for a yellow / red health bar |
197
+ | `mem_yellow` / `mem_red` | 0.50 / 0.80 | memory fraction for a yellow / red health bar |
198
+ | `history_cells` | 200 | cells remembered for `%autopsy summary` (0 = off) |
199
+ | `grow_yellow` / `grow_red` | 0.05 / 0.20 | summary: memory one cell added, as a fraction of the limit, for a yellow / red square |
200
+
201
+ The summary also uses `time_yellow` / `time_red` for a cell's run time. Its history
202
+ lives in memory only and is gone when the kernel restarts.
203
+
204
+ The memory limit is read from JupyterHub's `MEM_LIMIT` setting, then the container's
205
+ memory limit, then the computer's total RAM.
206
+
207
+ ## Limitations (honest list)
208
+
209
+ - No tool can detect *every* infinite loop (the halting problem). loop-autopsy
210
+ only reports a stuck, cycling, wrong-direction or jumped-over loop when it can
211
+ prove it; everything else gets the time limit.
212
+ - Loops that call your own functions or modules such as `random` cannot be proven
213
+ stuck (those calls might change hidden state), so they rely on the time limit.
214
+ - Only code typed in notebook cells is watched, not code inside imported modules.
215
+ - Watching adds a small cost to each loop round (roughly 0.1–0.2 µs per round on
216
+ simple loops). Use `%%autopsy off` for heavy number crunching.
217
+ - A bare `except:` inside a loop can catch the stop signal, just as it catches ■.
218
+
219
+ ## Development
220
+
221
+ ```bash
222
+ git clone https://github.com/Geoeoeo217/loop-autopsy
223
+ cd loop-autopsy
224
+ pip install -e ".[test]"
225
+ pytest
226
+ ```
227
+
228
+ ## Team
229
+
230
+ Built by a team of five for CS1302 (Introduction to Computer Programming).
231
+
232
+ | Member | Part |
233
+ |---|---|
234
+ | NATHANAEL George Steindhart | project lead: loop rewriting (`transformer.py`), run-time glue (`monitor.py`), magics, packaging |
235
+ | SETIAWAN Matthew Henson | detection rules: stuck, cycle, wrong direction, jumped over, time limit (`detectors.py`) |
236
+ | LATHIF Muhammad Akmal | memory and growing-list rules (`growth.py`) |
237
+ | KWAN Kendrick Matthew | replay table and reports (`report.py`) |
238
+ | HANDAYA Clement Steward | cell health bar and output guard (`heatmap.py`) |
239
+
240
+
241
+ ## License
242
+
243
+ MIT