loop-autopsy 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,171 @@
1
+ """Cell health bar and output guard.
2
+
3
+ After each cell a thin coloured bar shows time, memory and loops watched.
4
+ In ``auto`` mode it only appears when something is worth seeing.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import sys
10
+ import time
11
+ from typing import Any, Callable, Dict, List, Optional, Tuple
12
+
13
+ from .config import Settings
14
+ from .growth import current_rss, format_bytes, largest_variables, memory_limit
15
+
16
+ COLORS = ("#2b8a3e", "#e67700", "#c92a2a") # green, yellow, red
17
+ LABELS = ("healthy", "watch out", "heavy")
18
+ BIG_GROWTH = 100 * 1024 * 1024 # 100 MB
19
+
20
+
21
+ # --------------------------------------------------------------------------- output guard
22
+ class OutputGuard:
23
+ """Wraps sys.stdout and mutes it after ``max_lines`` printed lines."""
24
+
25
+ NOTICE = ("\n[loop-autopsy] Output muted after {n:,} lines to keep your browser responsive. "
26
+ "The cell is still running; a stuck loop will still be stopped.\n")
27
+
28
+ def __init__(self, stream, max_lines: int):
29
+ self._stream = stream
30
+ self.raw_stream = stream # reports write here so they are never muted
31
+ self.max_lines = max_lines
32
+ self.lines = 0
33
+ self.muted = False
34
+
35
+ def write(self, text: str) -> int:
36
+ if self.muted:
37
+ return len(text)
38
+ newlines = text.count("\n")
39
+ if self.max_lines and self.lines + newlines >= self.max_lines:
40
+ keep = self.max_lines - self.lines
41
+ cut = 0
42
+ for _ in range(keep):
43
+ cut = text.index("\n", cut) + 1
44
+ self._stream.write(text[:cut])
45
+ self._stream.write(self.NOTICE.format(n=self.max_lines))
46
+ self.lines = self.max_lines
47
+ self.muted = True
48
+ return len(text)
49
+ self.lines += newlines
50
+ return self._stream.write(text)
51
+
52
+ def __getattr__(self, name: str) -> Any:
53
+ return getattr(self._stream, name)
54
+
55
+
56
+ # --------------------------------------------------------------------------- bar
57
+ def level_of(value: float, yellow: float, red: float) -> int:
58
+ return 2 if value >= red else 1 if value >= yellow else 0
59
+
60
+
61
+ def build_bar(elapsed: float, rss: Optional[int], limit: Optional[int], delta: Optional[int],
62
+ loops: int, stopped: int, settings: Settings,
63
+ biggest: Optional[List[Tuple[str, int]]] = None) -> Tuple[int, str, str]:
64
+ """Return (level, html, text) for one cell. Pure function: easy to test."""
65
+ frac = (rss / limit) if rss and limit else None
66
+ level = level_of(elapsed, settings.time_yellow, settings.time_red)
67
+ if frac is not None:
68
+ level = max(level, level_of(frac, settings.mem_yellow, settings.mem_red))
69
+ color = COLORS[level]
70
+
71
+ bits = [f"time {elapsed:.2f} s"]
72
+ if frac is not None:
73
+ bits.append(f"memory {format_bytes(rss)} / {format_bytes(limit)} ({frac:.0%})")
74
+ if delta is not None:
75
+ sign = "+" if delta >= 0 else "-"
76
+ bits.append(f"{sign}{format_bytes(abs(delta))} this cell")
77
+ if loops:
78
+ bits.append(f"{loops} loop{'s' if loops != 1 else ''} watched")
79
+ if stopped:
80
+ bits.append(f"{stopped} stopped")
81
+ text = f"[{LABELS[level]}] " + " | ".join(bits)
82
+
83
+ warn_text, warn_html = "", ""
84
+ if frac is not None and frac >= settings.memory_warn:
85
+ names = ", ".join(f"{n} ({format_bytes(b)})" for n, b in (biggest or []))
86
+ warn_text = f"\nWarning: memory is at {frac:.0%} of your limit." + (f" Biggest variables: {names}." if names else "")
87
+ listed = ", ".join(f"<code>{n}</code> ({format_bytes(b)})" for n, b in (biggest or []))
88
+ warn_html = (f"<div style='color:{COLORS[2]};margin-top:3px'><b>Warning:</b> memory is at {frac:.0%} of "
89
+ f"your limit.{' Biggest variables: ' + listed + '.' if listed else ''} "
90
+ f"Delete what you no longer need with <code>del name</code>.</div>")
91
+
92
+ fill = min(100, int((frac or 0) * 100))
93
+ html_text = (
94
+ f"<div style='font-size:80%;opacity:.9;margin:2px 0;line-height:1.3'>"
95
+ f"<div style='height:4px;border-radius:2px;background:rgba(128,128,128,.25);margin-bottom:2px'>"
96
+ f"<div style='height:4px;width:{max(fill, 2)}%;border-radius:2px;background:{color}'></div></div>"
97
+ f"<span style='color:{color};font-weight:bold'>{LABELS[level]}</span> &middot; "
98
+ + " &middot; ".join(bits) + f"{warn_html}</div>"
99
+ )
100
+ return level, html_text, text + warn_text
101
+
102
+
103
+ def should_show(mode: str, level: int, delta: Optional[int]) -> bool:
104
+ """``auto`` shows the bar only when the cell was slow, memory is high or grew a lot.
105
+ (A stopped loop already shows its own report, so it does not trigger the bar.)"""
106
+ if mode == "on":
107
+ return True
108
+ if mode == "off":
109
+ return False
110
+ return level > 0 or (delta is not None and delta >= BIG_GROWTH)
111
+
112
+
113
+ # --------------------------------------------------------------------------- IPython hooks
114
+ class CellHealth:
115
+ """Registers pre/post cell hooks. ``stats`` is shared with the monitor."""
116
+
117
+ def __init__(self, shell, settings: Settings, stats: Dict[str, int],
118
+ show: Optional[Callable[[str, str], None]] = None):
119
+ self.shell, self.settings, self.stats = shell, settings, stats
120
+ self.show = show
121
+ self.depth = 0
122
+ self._t0 = 0.0
123
+ self._rss0: Optional[int] = None
124
+ self._guard: Optional[OutputGuard] = None
125
+ self._saved_stdout = None
126
+
127
+ def register(self) -> None:
128
+ self.shell.events.register("pre_run_cell", self.pre_run_cell)
129
+ self.shell.events.register("post_run_cell", self.post_run_cell)
130
+
131
+ def unregister(self) -> None:
132
+ for name, cb in (("pre_run_cell", self.pre_run_cell), ("post_run_cell", self.post_run_cell)):
133
+ try:
134
+ self.shell.events.unregister(name, cb)
135
+ except ValueError:
136
+ pass
137
+ self._restore_stdout()
138
+
139
+ def pre_run_cell(self, info=None) -> None:
140
+ self.depth += 1
141
+ if self.depth > 1:
142
+ return # nested run_cell (e.g. %%autopsy off): the outer cell is measured
143
+ self.stats.update(loops=0, stopped=0)
144
+ self._t0 = time.perf_counter()
145
+ self._rss0 = current_rss()
146
+ if self.settings.max_output_lines:
147
+ self._saved_stdout = sys.stdout
148
+ self._guard = OutputGuard(sys.stdout, self.settings.max_output_lines)
149
+ sys.stdout = self._guard
150
+
151
+ def post_run_cell(self, result=None) -> None:
152
+ if self.depth == 0:
153
+ return # hooks were registered during this cell: nothing was measured
154
+ self.depth -= 1
155
+ if self.depth:
156
+ return
157
+ self._restore_stdout()
158
+ elapsed = time.perf_counter() - self._t0
159
+ rss, limit = current_rss(), memory_limit()
160
+ delta = (rss - self._rss0) if (rss is not None and self._rss0 is not None) else None
161
+ frac = (rss / limit) if rss and limit else 0
162
+ biggest = largest_variables(self.shell.user_ns) if frac >= self.settings.memory_warn else None
163
+ level, html_text, text = build_bar(elapsed, rss, limit, delta, self.stats.get("loops", 0),
164
+ self.stats.get("stopped", 0), self.settings, biggest)
165
+ if should_show(self.settings.heatmap, level, delta) and self.show:
166
+ self.show(text, html_text)
167
+
168
+ def _restore_stdout(self) -> None:
169
+ if self._guard is not None and sys.stdout is self._guard:
170
+ sys.stdout = self._saved_stdout
171
+ self._guard = None
loop_autopsy/magics.py ADDED
@@ -0,0 +1,65 @@
1
+ """``%autopsy`` line magic and ``%%autopsy off`` cell magic. Owner: George."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from IPython.core.magic import Magics, line_cell_magic, magics_class
6
+
7
+ HELP = """loop-autopsy commands
8
+ %autopsy show status and settings
9
+ %autopsy on | off start / stop watching loops
10
+ %autopsy last show the last report again
11
+ %autopsy heatmap on|off|auto cell health bar (auto = only when worth seeing)
12
+ %autopsy config key=value ... change a setting, e.g. %autopsy config time_limit=120
13
+ %%autopsy off (first line of a cell) run that cell without watching
14
+ """
15
+
16
+
17
+ @magics_class
18
+ class AutopsyMagics(Magics):
19
+ def __init__(self, shell, monitor):
20
+ super().__init__(shell)
21
+ self.monitor = monitor
22
+
23
+ @line_cell_magic
24
+ def autopsy(self, line: str, cell: str = None):
25
+ args = line.split()
26
+ if cell is not None:
27
+ if args[:1] == ["off"]:
28
+ with self.monitor.paused():
29
+ self.shell.run_cell(cell, store_history=False)
30
+ return None
31
+ print("Use %%autopsy off on the first line of a cell to run it without loop watching.")
32
+ return None
33
+
34
+ command = args[0].lower() if args else "status"
35
+ settings = self.monitor.settings
36
+ if command == "status":
37
+ state = "ON" if self.monitor.enabled else "OFF"
38
+ print(f"loop-autopsy is {state}. Settings:")
39
+ for key, value in settings.as_dict().items():
40
+ print(f" {key:<17}{value}")
41
+ elif command in ("on", "off"):
42
+ self.monitor.enabled = command == "on"
43
+ print(f"loop-autopsy is now {command.upper()}.")
44
+ elif command == "last":
45
+ if not self.monitor.show_last():
46
+ print("No loop has been stopped yet.")
47
+ elif command == "heatmap":
48
+ mode = args[1].lower() if len(args) > 1 else ""
49
+ try:
50
+ settings.update("heatmap", mode)
51
+ print(f"Cell health bar: {mode}")
52
+ except ValueError as err:
53
+ print(err)
54
+ elif command == "config":
55
+ if len(args) == 1:
56
+ print("Usage: %autopsy config key=value [key=value ...]")
57
+ for pair in args[1:]:
58
+ key, _, raw = pair.partition("=")
59
+ try:
60
+ print(f"{key} = {settings.update(key, raw)}")
61
+ except (KeyError, ValueError) as err:
62
+ print(f"Could not set {key!r}: {err}")
63
+ else:
64
+ print(HELP)
65
+ return None
@@ -0,0 +1,166 @@
1
+ """Run-time glue: receives begin/due/check calls from instrumented loops,
2
+ runs the detectors and shows reports.
3
+ Owner: NATHANAEL George Steindhart.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import re
10
+ import time
11
+ import types
12
+ from contextlib import contextmanager
13
+ from typing import Any, Dict, List, Optional, Tuple
14
+
15
+ from . import detectors, growth, report
16
+ from .config import Finding, LoopInfo, LoopState, LoopStopped, Settings
17
+
18
+ _TIMEIT = re.compile(r"^\s*%%?timeit\b", re.MULTILINE)
19
+ SLOW_GAP = 0.25 # seconds between checks before the stride is reduced
20
+ INTERRUPT_WINDOW = 2.0 # seconds: a loop checked this recently is "the running loop"
21
+
22
+
23
+ _PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
24
+
25
+
26
+ def _without_our_frames(tb):
27
+ """Cut the traceback where it enters loop-autopsy, so students only see their code."""
28
+ first = tb
29
+ while tb is not None and tb.tb_next is not None:
30
+ nxt = tb.tb_next
31
+ if os.path.dirname(os.path.abspath(nxt.tb_frame.f_code.co_filename)) == _PACKAGE_DIR:
32
+ tb.tb_next = None
33
+ break
34
+ tb = nxt
35
+ return first
36
+
37
+
38
+ def _skip(value: Any) -> bool:
39
+ return callable(value) or isinstance(value, types.ModuleType)
40
+
41
+
42
+ class Monitor:
43
+ """One per IPython shell. Instrumented code calls it as ``__loop_autopsy__``."""
44
+
45
+ def __init__(self, shell, settings: Settings):
46
+ self.shell = shell
47
+ self.settings = settings
48
+ self.infos: List[LoopInfo] = []
49
+ self.states: List[Optional[LoopState]] = []
50
+ self.enabled = True
51
+ self.paused_cell = False
52
+ self._pause_depth = 0
53
+ self.stats: Dict[str, int] = {"loops": 0, "stopped": 0}
54
+ self.last: Optional[Tuple[Finding, LoopState, float]] = None
55
+ self.active: Optional[LoopState] = None
56
+ self.active_time = 0.0
57
+ self._old_exc = None
58
+
59
+ # ------------------------------------------------------------------ transformer side
60
+ def register(self, info: LoopInfo) -> int:
61
+ info.loop_id = len(self.infos)
62
+ self.infos.append(info)
63
+ self.states.append(None)
64
+ return info.loop_id
65
+
66
+ def is_paused(self) -> bool:
67
+ return not self.enabled or self.paused_cell or self._pause_depth > 0
68
+
69
+ @contextmanager
70
+ def paused(self):
71
+ self._pause_depth += 1
72
+ try:
73
+ yield
74
+ finally:
75
+ self._pause_depth -= 1
76
+
77
+ def pre_run_cell(self, info=None) -> None:
78
+ raw = getattr(info, "raw_cell", "") or ""
79
+ self.paused_cell = bool(_TIMEIT.search(raw))
80
+ self.active = None
81
+
82
+ # ------------------------------------------------------------------ loop side (hot path)
83
+ def begin(self, loop_id: int) -> None:
84
+ self.states[loop_id] = LoopState(self.infos[loop_id], started=time.perf_counter(),
85
+ replay_rows=self.settings.replay_rows)
86
+ self.stats["loops"] += 1
87
+
88
+ def due(self, loop_id: int) -> bool:
89
+ state = self.states[loop_id]
90
+ if state is None or not self.enabled:
91
+ return False
92
+ state.rounds += 1
93
+ return state.rounds >= state.next_check
94
+
95
+ def check(self, loop_id: int, namespace: Dict[str, Any]) -> None:
96
+ state = self.states[loop_id]
97
+ info = state.info
98
+ now = time.perf_counter()
99
+ state.checks += 1
100
+ values = {}
101
+ for name in info.watched:
102
+ if name in namespace:
103
+ value = namespace[name]
104
+ if not _skip(value):
105
+ values[name] = value
106
+ if state.checks == 1:
107
+ growth.remember_start(state, values)
108
+ report.record(state, values)
109
+ self.active, self.active_time = state, now
110
+
111
+ gap, state.last_check = now - state.last_check, now
112
+ if not state.scratch.get("rep_refine"):
113
+ base = 256 if state.rounds >= 100_000 else 16 if state.rounds >= 1_000 else 1
114
+ state.stride = base if gap <= SLOW_GAP else max(1, min(base, state.stride) // 4)
115
+
116
+ finding = (detectors.check_repeat(info, state, values)
117
+ or detectors.check_direction(info, state, values, self.settings)
118
+ or growth.check_growing_iterable(info, state, values, self.settings))
119
+ if finding is None and state.checks % 16 == 0:
120
+ finding = growth.check_memory(info, state, values, self.settings)
121
+ if finding is None:
122
+ finding = detectors.check_time(info, state, self.settings, now)
123
+ state.next_check = state.rounds + state.stride
124
+ if finding is not None:
125
+ state.stopped = finding
126
+ self.stats["stopped"] += 1
127
+ self.last = (finding, state, now - state.started)
128
+ raise LoopStopped(finding)
129
+
130
+ # ------------------------------------------------------------------ reports
131
+ def show_last(self) -> bool:
132
+ if not self.last:
133
+ return False
134
+ finding, state, elapsed = self.last
135
+ report.display_report(report.render_text(finding, state, elapsed),
136
+ report.render_html(finding, state, elapsed))
137
+ return True
138
+
139
+ def install_exception_handler(self) -> None:
140
+ self._old_exc = (self.shell.custom_exceptions, getattr(self.shell, "CustomTB", None))
141
+ self.shell.set_custom_exc((LoopStopped, KeyboardInterrupt), self._handle)
142
+
143
+ def remove_exception_handler(self) -> None:
144
+ if self._old_exc is None:
145
+ return
146
+ old_tuple, old_tb = self._old_exc
147
+ self.shell.custom_exceptions = old_tuple
148
+ if old_tb is not None:
149
+ self.shell.CustomTB = old_tb
150
+ self._old_exc = None
151
+
152
+ def _handle(self, shell, etype, value, tb, tb_offset=None):
153
+ if issubclass(etype, LoopStopped):
154
+ self.show_last()
155
+ return []
156
+ # KeyboardInterrupt: keep IPython's normal message, then add the replay.
157
+ shell.showtraceback((etype, value, _without_our_frames(tb)), tb_offset=tb_offset)
158
+ state = self.active
159
+ if (state is not None and state.stopped is None and state.history
160
+ and time.perf_counter() - self.active_time < INTERRUPT_WINDOW):
161
+ finding = report.interrupt_finding(state)
162
+ elapsed = time.perf_counter() - state.started
163
+ self.last = (finding, state, elapsed)
164
+ report.display_report(report.render_text(finding, state, elapsed),
165
+ report.render_html(finding, state, elapsed))
166
+ return []
loop_autopsy/report.py ADDED
@@ -0,0 +1,207 @@
1
+ """Turn a Finding and a loop's history into a readable report.
2
+
3
+ ``record`` is called on every check, so it must stay fast: it stores values,
4
+ not text, and converts containers to a small size marker.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import html
10
+ from decimal import Decimal
11
+ from fractions import Fraction
12
+ from typing import Any, Dict, List, Optional, Tuple
13
+
14
+ from .config import Finding, LoopState
15
+
16
+ _IMMUTABLE = (type(None), bool, int, float, complex, str, bytes, Fraction, Decimal, range)
17
+ ACCENT = {"stuck": "#d9480f", "cycle": "#d9480f", "wrong_direction": "#d9480f", "jumped_over": "#d9480f",
18
+ "growing_iterable": "#c2255c", "memory": "#c2255c", "time_limit": "#e67700", "interrupt": "#1971c2"}
19
+ _MISSING = object()
20
+
21
+
22
+ class Text(str):
23
+ """repr of a small container, frozen at the time of the check."""
24
+
25
+ def __repr__(self):
26
+ return str(self)
27
+
28
+
29
+ class Size:
30
+ """Marker stored in the history instead of a (mutable) container."""
31
+
32
+ __slots__ = ("kind", "length")
33
+
34
+ def __init__(self, kind: str, length: int):
35
+ self.kind, self.length = kind, length
36
+
37
+ def __eq__(self, other):
38
+ return isinstance(other, Size) and (self.kind, self.length) == (other.kind, other.length)
39
+
40
+ def __hash__(self):
41
+ return hash((self.kind, self.length))
42
+
43
+ def __repr__(self):
44
+ return f"{self.kind}(len={self.length})" if self.length >= 0 else f"<{self.kind}>"
45
+
46
+
47
+ def replay_value(value: Any) -> Any:
48
+ """Cheap snapshot of one value for the replay table."""
49
+ if isinstance(value, _IMMUTABLE):
50
+ return value
51
+ if isinstance(value, tuple) and len(value) <= 10 and all(isinstance(x, _IMMUTABLE) for x in value):
52
+ return value
53
+ try:
54
+ if isinstance(value, (list, dict, set, tuple)) and len(value) <= 8:
55
+ text = repr(value)
56
+ if len(text) <= 40:
57
+ return Text(text)
58
+ return Size(type(value).__name__, len(value))
59
+ except Exception:
60
+ return Size(type(value).__name__, -1)
61
+
62
+
63
+ def record(state: LoopState, values: Dict[str, Any]) -> None:
64
+ """Append this check to the loop's replay history."""
65
+ state.history.append((state.rounds, {n: replay_value(v) for n, v in values.items()}))
66
+
67
+
68
+ def short_repr(value: Any, width: int = 40) -> str:
69
+ text = repr(value)
70
+ return text if len(text) <= width else text[: width - 3] + "..."
71
+
72
+
73
+ # --------------------------------------------------------------------------- table
74
+ def _same(a: Any, b: Any) -> bool:
75
+ try:
76
+ return type(a) is type(b) and bool(a == b)
77
+ except Exception:
78
+ return False
79
+
80
+
81
+ def replay_table(state: LoopState) -> Tuple[List[str], List[List[str]], List[str]]:
82
+ """Return (columns, rows, unchanged_columns). Rows start with the round number."""
83
+ order = list(state.info.watched)
84
+ present: List[str] = []
85
+ for _, snap in state.history:
86
+ for name in snap:
87
+ if name not in present:
88
+ present.append(name)
89
+ columns = [n for n in order if n in present] + [n for n in present if n not in order]
90
+ rows = [[f"{rnd:,}"] + [short_repr(snap[c]) if c in snap else "-" for c in columns]
91
+ for rnd, snap in state.history]
92
+ unchanged = []
93
+ if len(state.history) >= 2:
94
+ for c in columns:
95
+ seen = [snap.get(c, _MISSING) for _, snap in state.history]
96
+ if seen[0] is not _MISSING and all(_same(seen[0], v) for v in seen[1:]):
97
+ unchanged.append(c)
98
+ return columns, rows, unchanged
99
+
100
+
101
+ def _footer(state: LoopState, elapsed: Optional[float]) -> str:
102
+ t = f" in {elapsed:.2f} s" if elapsed is not None else ""
103
+ return f"Stopped after {state.rounds:,} rounds{t} · %autopsy last = show again · %%autopsy off = skip a cell"
104
+
105
+
106
+ # --------------------------------------------------------------------------- text
107
+ def _text_table(columns: List[str], rows: List[List[str]], unchanged: List[str]) -> str:
108
+ head = ["round"] + [c + (" (same)" if c in unchanged else "") for c in columns]
109
+ widths = [max([len(head[i])] + [len(r[i]) for r in rows]) for i in range(len(head))]
110
+ line = lambda cells: " ".join(c.ljust(w) for c, w in zip(cells, widths)).rstrip() # noqa: E731
111
+ return "\n".join([line(head), line(["-" * w for w in widths])] + [line(r) for r in rows])
112
+
113
+
114
+ def render_text(finding: Finding, state: LoopState, elapsed: Optional[float] = None) -> str:
115
+ columns, rows, unchanged = replay_table(state)
116
+ return "\n".join([
117
+ f"Loop autopsy — {finding.title} (line {state.info.lineno})",
118
+ f" {state.info.header}",
119
+ "",
120
+ finding.explanation,
121
+ "",
122
+ "Last rounds checked:",
123
+ _text_table(columns, rows, unchanged) if columns else "(no variables to show)",
124
+ "",
125
+ "Hint: " + finding.hint,
126
+ _footer(state, elapsed),
127
+ ])
128
+
129
+
130
+ # --------------------------------------------------------------------------- html
131
+ def _md_code(text: str) -> str:
132
+ """Escape, then turn `backticks` into <code>."""
133
+ out, inside = [], False
134
+ for piece in html.escape(text).split("`"):
135
+ out.append(f"<code>{piece}</code>" if inside else piece)
136
+ inside = not inside
137
+ return "".join(out)
138
+
139
+
140
+ def _html_table(columns, rows, unchanged, culprits) -> str:
141
+ if not columns:
142
+ return "<p><i>(no variables to show)</i></p>"
143
+ th = "padding:2px 10px;text-align:left;border-bottom:1px solid rgba(128,128,128,.4)"
144
+ head = f"<th style='{th}'>round</th>"
145
+ for c in columns:
146
+ mark = " <span style='font-weight:normal;opacity:.7'>(same)</span>" if c in unchanged else ""
147
+ style = th + (";color:#d9480f" if c in culprits else "")
148
+ head += f"<th style='{style}'><code>{html.escape(c)}</code>{mark}</th>"
149
+ body = "".join(
150
+ "<tr>" + "".join(f"<td style='padding:2px 10px;font-family:monospace'>{html.escape(x)}</td>" for x in r) + "</tr>"
151
+ for r in rows
152
+ )
153
+ return f"<table style='border-collapse:collapse;margin:6px 0'><tr>{head}</tr>{body}</table>"
154
+
155
+
156
+ def render_html(finding: Finding, state: LoopState, elapsed: Optional[float] = None) -> str:
157
+ columns, rows, unchanged = replay_table(state)
158
+ color = ACCENT.get(finding.kind, "#d9480f")
159
+ return (
160
+ f"<div style='border-left:4px solid {color};padding:8px 12px;margin:6px 0;"
161
+ f"background:rgba(128,128,128,.07);border-radius:4px;line-height:1.45'>"
162
+ f"<div style='font-weight:bold;color:{color}'>Loop autopsy — {html.escape(finding.title)} "
163
+ f"(line {state.info.lineno})</div>"
164
+ f"<div style='margin:4px 0'><code>{html.escape(state.info.header)}</code></div>"
165
+ f"<p style='margin:6px 0'>{_md_code(finding.explanation)}</p>"
166
+ f"<div style='opacity:.8;font-size:90%'>Last rounds checked:</div>"
167
+ f"{_html_table(columns, rows, unchanged, set(finding.culprits))}"
168
+ f"<p style='margin:6px 0'><b>Hint:</b> {_md_code(finding.hint)}</p>"
169
+ f"<div style='opacity:.65;font-size:85%'>{html.escape(_footer(state, elapsed))}</div></div>"
170
+ )
171
+
172
+
173
+ # --------------------------------------------------------------------------- interrupt (stop button)
174
+ def interrupt_finding(state: LoopState) -> Finding:
175
+ """What we can say when the student pressed stop themselves."""
176
+ _, _, unchanged = replay_table(state)
177
+ cond = [n for n in state.info.cond_names if n in unchanged]
178
+ hint = "Compare the replay table with the loop's stop condition: are the values moving towards it?"
179
+ if cond:
180
+ names = ", ".join(f"`{n}`" for n in cond)
181
+ text = (f"You stopped this loop. In the last rounds checked, {names} never changed, "
182
+ f"so `{state.info.test_src or 'the condition'}` could not become False.")
183
+ hint = f"Find the line inside the loop that should change {names}."
184
+ elif unchanged:
185
+ names = ", ".join(f"`{n}`" for n in unchanged)
186
+ text = f"You stopped this loop. In the last rounds checked, {names} did not change."
187
+ else:
188
+ text = "You stopped this loop. Here is what its variables were doing just before."
189
+ return Finding("interrupt", "you stopped this loop", text, hint, tuple(cond))
190
+
191
+
192
+ def display_report(text: str, html_text: str) -> None:
193
+ """HTML inside Jupyter, plain text in terminal IPython or plain Python."""
194
+ try:
195
+ from IPython import get_ipython
196
+ from IPython.display import HTML, display
197
+
198
+ shell = get_ipython()
199
+ if shell is not None and shell.__class__.__name__ == "ZMQInteractiveShell":
200
+ display(HTML(html_text))
201
+ return
202
+ except Exception:
203
+ pass
204
+ import sys
205
+
206
+ stream = getattr(sys.stdout, "raw_stream", sys.stdout) # skip the output guard
207
+ print(text, file=stream)