codejourney 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,796 @@
1
+ """CodeJourney's structured Python execution tracing API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import linecache
6
+ import sys
7
+ import types
8
+ import uuid
9
+ from dataclasses import dataclass
10
+ from typing import Any, Dict, Optional, Tuple
11
+
12
+ from .analysis import (
13
+ ConditionInfo,
14
+ EducationalWarning,
15
+ LoopInfo,
16
+ ProgramAnalysis,
17
+ analyze_source,
18
+ )
19
+
20
+ __all__ = [
21
+ "AliasInfo",
22
+ "CollectionSnapshot",
23
+ "ConditionInfo",
24
+ "ConditionPreview",
25
+ "EducationalWarning",
26
+ "ExecutionError",
27
+ "LoopBoundary",
28
+ "LoopInfo",
29
+ "LoopIteration",
30
+ "ObjectSnapshot",
31
+ "ProgramAnalysis",
32
+ "TraceEvent",
33
+ "TraceResult",
34
+ "VariableDiff",
35
+ "VisualizationResult",
36
+ "run_viz",
37
+ ]
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class ObjectSnapshot:
42
+ """Safe type-only description of a value not inspected by CodeJourney."""
43
+
44
+ type_name: str
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class CollectionSnapshot:
49
+ """Immutable snapshot of a dictionary, set, or frozenset."""
50
+
51
+ type_name: str
52
+ items: Tuple[Any, ...]
53
+
54
+
55
+ @dataclass(frozen=True)
56
+ class ExecutionError:
57
+ """A syntax or runtime error raised while analyzing the source."""
58
+
59
+ type_name: str
60
+ message: str
61
+ line_number: Optional[int] = None
62
+
63
+
64
+ @dataclass(frozen=True)
65
+ class VariableDiff:
66
+ """A variable change and the affected collection entries, when known."""
67
+
68
+ name: str
69
+ change: str
70
+ before: Any = None
71
+ after: Any = None
72
+ list_indices: Tuple[int, ...] = ()
73
+ dictionary_keys: Tuple[Any, ...] = ()
74
+
75
+
76
+ @dataclass(frozen=True)
77
+ class AliasInfo:
78
+ name: str
79
+ linked_to: str
80
+
81
+ @property
82
+ def label(self) -> str:
83
+ return f"Linked to {self.linked_to}"
84
+
85
+
86
+ @dataclass(frozen=True)
87
+ class LoopIteration:
88
+ loop_id: str
89
+ kind: str
90
+ iteration_index: int
91
+ total_iterations: Optional[int]
92
+ line_number: int
93
+ group_id: str = ""
94
+
95
+ @property
96
+ def label(self) -> str:
97
+ total = self.total_iterations if self.total_iterations is not None else "?"
98
+ return f"Iteration {self.iteration_index + 1} of {total}"
99
+
100
+
101
+ @dataclass(frozen=True)
102
+ class LoopBoundary:
103
+ kind: str
104
+ loop_id: str
105
+ iteration_index: int
106
+ total_iterations: Optional[int]
107
+ group_id: str = ""
108
+
109
+
110
+ @dataclass(frozen=True)
111
+ class ConditionPreview:
112
+ condition_id: str
113
+ expression: str
114
+ preview: str
115
+ result: Optional[bool]
116
+
117
+
118
+ @dataclass(frozen=True)
119
+ class TraceEvent:
120
+ """One observed event from the submitted program.
121
+
122
+ For line events, ``after`` is the snapshot at line entry and ``before`` is
123
+ the previous snapshot from the same frame.
124
+ """
125
+
126
+ event: str
127
+ line_number: Optional[int]
128
+ source_line: Optional[str]
129
+ before: Dict[str, Any]
130
+ after: Dict[str, Any]
131
+ changed_variables: Tuple[str, ...]
132
+ exception_type: Optional[str] = None
133
+ variable_diffs: Tuple[VariableDiff, ...] = ()
134
+ aliases: Tuple[AliasInfo, ...] = ()
135
+ loop_iterations: Tuple[LoopIteration, ...] = ()
136
+ loop_boundaries: Tuple[LoopBoundary, ...] = ()
137
+ condition_preview: Optional[ConditionPreview] = None
138
+ warning_codes: Tuple[str, ...] = ()
139
+ frame_id: int = 0
140
+
141
+ @property
142
+ def variables(self) -> Dict[str, Any]:
143
+ """Return the snapshot associated with this event."""
144
+ return self.after
145
+
146
+
147
+ @dataclass(frozen=True)
148
+ class TraceResult:
149
+ """Structured trace data returned by :func:`run_viz`."""
150
+
151
+ source: str
152
+ events: Tuple[TraceEvent, ...]
153
+ max_steps: int
154
+ truncated: bool = False
155
+ error: Optional[ExecutionError] = None
156
+ loops: Tuple[LoopInfo, ...] = ()
157
+ conditions: Tuple[ConditionInfo, ...] = ()
158
+ warnings: Tuple[EducationalWarning, ...] = ()
159
+
160
+ def _repr_html_(self) -> str:
161
+ from .visualization import render_html
162
+
163
+ return render_html(self)
164
+
165
+ VisualizationResult = TraceResult
166
+
167
+
168
+ class _StepLimitReached(BaseException):
169
+ pass
170
+
171
+
172
+ def _type_name(value: Any) -> str:
173
+ return type.__getattribute__(type(value), "__name__")
174
+
175
+
176
+ def _snapshot_value(
177
+ value: Any,
178
+ active_ids: Optional[set[int]] = None,
179
+ depth: int = 0,
180
+ ) -> Any:
181
+ if type(value) in (type(None), bool, int, float, str, bytes):
182
+ return value
183
+
184
+ if active_ids is None:
185
+ active_ids = set()
186
+ value_id = id(value)
187
+ value_type = type(value)
188
+
189
+ if value_id in active_ids:
190
+ return ObjectSnapshot("recursive " + _type_name(value))
191
+ if depth >= 8:
192
+ return ObjectSnapshot("nested " + _type_name(value))
193
+
194
+ if value_type in (list, tuple, dict, set, frozenset):
195
+ active_ids.add(value_id)
196
+ try:
197
+ if value_type is list:
198
+ return [
199
+ _snapshot_value(item, active_ids, depth + 1)
200
+ for item in value
201
+ ]
202
+ if value_type is tuple:
203
+ return tuple(
204
+ _snapshot_value(item, active_ids, depth + 1)
205
+ for item in value
206
+ )
207
+ if value_type is dict:
208
+ return CollectionSnapshot(
209
+ "dict",
210
+ tuple(
211
+ (
212
+ _snapshot_value(key, active_ids, depth + 1),
213
+ _snapshot_value(item, active_ids, depth + 1),
214
+ )
215
+ for key, item in value.items()
216
+ ),
217
+ )
218
+ return CollectionSnapshot(
219
+ _type_name(value),
220
+ tuple(_snapshot_value(item, active_ids, depth + 1) for item in value),
221
+ )
222
+ finally:
223
+ active_ids.remove(value_id)
224
+
225
+ return ObjectSnapshot(_type_name(value))
226
+
227
+
228
+ def _snapshot_locals(local_values: Dict[str, Any]) -> Dict[str, Any]:
229
+ return {
230
+ name: _snapshot_value(value)
231
+ for name, value in local_values.items()
232
+ if isinstance(name, str) and not name.startswith("__")
233
+ }
234
+
235
+
236
+ def _changed_variables(
237
+ before: Dict[str, Any],
238
+ after: Dict[str, Any],
239
+ ) -> Tuple[str, ...]:
240
+ names = before.keys() | after.keys()
241
+ return tuple(
242
+ sorted(
243
+ name
244
+ for name in names
245
+ if name not in before or name not in after or before[name] != after[name]
246
+ )
247
+ )
248
+
249
+
250
+ def _same_snapshot(left: Any, right: Any) -> bool:
251
+ if type(left) is not type(right):
252
+ return False
253
+ if type(left) in (type(None), bool, int, float, str, bytes):
254
+ return left == right
255
+ if isinstance(left, ObjectSnapshot):
256
+ return left.type_name == right.type_name
257
+ if isinstance(left, CollectionSnapshot):
258
+ return left.type_name == right.type_name and _same_snapshot(left.items, right.items)
259
+ if type(left) in (list, tuple):
260
+ return len(left) == len(right) and all(
261
+ _same_snapshot(left_item, right_item)
262
+ for left_item, right_item in zip(left, right)
263
+ )
264
+ return False
265
+
266
+
267
+ def _mapping_items(snapshot: Any) -> Optional[Tuple[Tuple[Any, Any], ...]]:
268
+ if isinstance(snapshot, CollectionSnapshot) and snapshot.type_name == "dict":
269
+ return snapshot.items
270
+ return None
271
+
272
+
273
+ def _collection_changes(before: Any, after: Any) -> Tuple[Tuple[int, ...], Tuple[Any, ...]]:
274
+ changed_indices = ()
275
+ if type(before) is list and type(after) is list:
276
+ changed_indices = tuple(
277
+ index
278
+ for index in range(max(len(before), len(after)))
279
+ if index >= len(before)
280
+ or index >= len(after)
281
+ or not _same_snapshot(before[index], after[index])
282
+ )
283
+
284
+ before_items = _mapping_items(before)
285
+ after_items = _mapping_items(after)
286
+ changed_keys = ()
287
+ if before_items is not None and after_items is not None:
288
+ unmatched = list(before_items)
289
+ found_keys = []
290
+ changed = []
291
+ for key, value in after_items:
292
+ match = next(
293
+ (
294
+ index
295
+ for index, (old_key, _) in enumerate(unmatched)
296
+ if _same_snapshot(old_key, key)
297
+ ),
298
+ None,
299
+ )
300
+ if match is None:
301
+ changed.append(key)
302
+ else:
303
+ old_key, old_value = unmatched.pop(match)
304
+ found_keys.append(old_key)
305
+ if not _same_snapshot(old_value, value):
306
+ changed.append(key)
307
+ changed.extend(key for key, _ in unmatched)
308
+ changed_keys = tuple(changed)
309
+ return changed_indices, changed_keys
310
+
311
+
312
+ def _variable_diffs(
313
+ before: Dict[str, Any],
314
+ after: Dict[str, Any],
315
+ ) -> Tuple[VariableDiff, ...]:
316
+ diffs = []
317
+ for name in _changed_variables(before, after):
318
+ if name not in before:
319
+ change = "added"
320
+ elif name not in after:
321
+ change = "removed"
322
+ else:
323
+ change = "modified"
324
+ old_value = before.get(name)
325
+ new_value = after.get(name)
326
+ indices, keys = _collection_changes(old_value, new_value)
327
+ diffs.append(
328
+ VariableDiff(
329
+ name=name,
330
+ change=change,
331
+ before=old_value,
332
+ after=new_value,
333
+ list_indices=indices,
334
+ dictionary_keys=keys,
335
+ )
336
+ )
337
+ return tuple(diffs)
338
+
339
+
340
+ def _aliases(local_values: Dict[str, Any]) -> Tuple[AliasInfo, ...]:
341
+ references: Dict[int, list[str]] = {}
342
+ seen_containers = set()
343
+ scalar_types = (type(None), bool, int, float, complex, str, bytes)
344
+
345
+ def visit(path: str, value: Any) -> None:
346
+ value_type = type(value)
347
+ mutable = value_type in (list, dict, set, bytearray) or value_type not in (
348
+ *scalar_types,
349
+ tuple,
350
+ frozenset,
351
+ )
352
+ if mutable:
353
+ references.setdefault(id(value), []).append(path)
354
+ if value_type in (list, tuple):
355
+ if id(value) in seen_containers:
356
+ return
357
+ seen_containers.add(id(value))
358
+ for index, item in enumerate(value):
359
+ visit(f"{path}[{index}]", item)
360
+ elif value_type is dict:
361
+ if id(value) in seen_containers:
362
+ return
363
+ seen_containers.add(id(value))
364
+ for index, item in enumerate(value.values()):
365
+ visit(f"{path}.value[{index}]", item)
366
+
367
+ for name, value in local_values.items():
368
+ if isinstance(name, str) and not name.startswith("__"):
369
+ visit(name, value)
370
+ return tuple(
371
+ AliasInfo(name=path, linked_to=paths[0])
372
+ for paths in references.values()
373
+ if len(paths) > 1
374
+ for path in paths[1:]
375
+ )
376
+
377
+
378
+ def _condition_preview(
379
+ condition: ConditionInfo,
380
+ values: Dict[str, Any],
381
+ result: Optional[bool],
382
+ ) -> ConditionPreview:
383
+ import ast
384
+
385
+ class _SubstituteNames(ast.NodeTransformer):
386
+ complete = True
387
+
388
+ def visit_Name(self, node: ast.Name) -> Any:
389
+ if not isinstance(node.ctx, ast.Load):
390
+ return node
391
+ value = values.get(node.id, _MISSING)
392
+ if type(value) not in (type(None), bool, int, float, str):
393
+ self.complete = False
394
+ return node
395
+ return ast.copy_location(ast.Constant(value=value), node)
396
+
397
+ try:
398
+ expression_tree = ast.parse(condition.expression, mode="eval")
399
+ substitute = _SubstituteNames()
400
+ substituted_tree = substitute.visit(expression_tree)
401
+ ast.fix_missing_locations(substituted_tree)
402
+ substituted = ast.unparse(substituted_tree.body)
403
+ except (SyntaxError, ValueError):
404
+ substitute = None
405
+ substituted = condition.expression
406
+
407
+ if substitute is not None and substitute.complete and result is not None:
408
+ preview = f"{condition.expression} -> {substituted} -> {result}"
409
+ else:
410
+ preview = f"{condition.expression} (value unavailable)"
411
+ return ConditionPreview(condition.condition_id, condition.expression, preview, result)
412
+
413
+
414
+ def _sanitize_loop_iterations(
415
+ events: list[TraceEvent],
416
+ loops: Tuple[LoopInfo, ...],
417
+ ) -> list[TraceEvent]:
418
+ import dataclasses
419
+
420
+ loops_by_id = {loop.loop_id: loop for loop in loops}
421
+ sanitized = []
422
+ for index, event in enumerate(events):
423
+ iterations = []
424
+ for iteration in event.loop_iterations:
425
+ loop = loops_by_id[iteration.loop_id]
426
+ if event.event == "line" and event.line_number == loop.line_number:
427
+ next_line = None
428
+ for later in events[index + 1 :]:
429
+ if later.frame_id == event.frame_id and later.event in {"line", "return"}:
430
+ next_line = later.line_number
431
+ break
432
+ if (
433
+ next_line is None
434
+ or not loop.contains(next_line)
435
+ or (
436
+ loop.total_iterations is not None
437
+ and iteration.iteration_index >= loop.total_iterations
438
+ )
439
+ ):
440
+ continue
441
+ elif event.event == "return" and not any(
442
+ boundary.loop_id == iteration.loop_id and boundary.kind == "end"
443
+ for boundary in event.loop_boundaries
444
+ ):
445
+ continue
446
+ iterations.append(iteration)
447
+ sanitized.append(
448
+ dataclasses.replace(event, loop_iterations=tuple(iterations))
449
+ )
450
+ return sanitized
451
+
452
+
453
+ _MISSING = object()
454
+
455
+
456
+ def _attach_condition_previews(
457
+ events: list[TraceEvent],
458
+ conditions: Tuple[ConditionInfo, ...],
459
+ ) -> list[TraceEvent]:
460
+ import dataclasses
461
+
462
+ by_line = {condition.line_number: condition for condition in conditions}
463
+ enriched = list(events)
464
+ for index, event in enumerate(events):
465
+ condition = by_line.get(event.line_number)
466
+ if event.event != "line" or condition is None:
467
+ continue
468
+
469
+ next_line = None
470
+ condition_raised = False
471
+ for later in events[index + 1 :]:
472
+ if later.frame_id != event.frame_id:
473
+ continue
474
+ if later.event == "exception":
475
+ condition_raised = True
476
+ break
477
+ if later.event in {"line", "return"}:
478
+ next_line = later.line_number
479
+ break
480
+
481
+ result = (
482
+ condition.body_contains(next_line)
483
+ if next_line is not None and not condition_raised
484
+ else None
485
+ )
486
+ values = {
487
+ name: value
488
+ for name, value in event.after.items()
489
+ if type(value) in (type(None), bool, int, float, str)
490
+ }
491
+ enriched[index] = dataclasses.replace(
492
+ event,
493
+ condition_preview=_condition_preview(condition, values, result),
494
+ )
495
+ return enriched
496
+
497
+
498
+ def _error_line(error: BaseException, filename: str) -> Optional[int]:
499
+ line_number = error.lineno if type(error) is SyntaxError else None
500
+ if line_number is not None:
501
+ return line_number
502
+ traceback = error.__traceback__
503
+ while traceback is not None:
504
+ if traceback.tb_frame.f_code.co_filename == filename:
505
+ line_number = traceback.tb_lineno
506
+ traceback = traceback.tb_next
507
+ return line_number
508
+
509
+
510
+ def _safe_error_message(error: BaseException) -> str:
511
+ arguments = BaseException.__getattribute__(error, "args")
512
+ if type(arguments) is tuple and arguments:
513
+ message = arguments[0]
514
+ if type(message) is str:
515
+ return message
516
+ if type(message) in (type(None), bool, int, float):
517
+ return str(message)
518
+ return "Execution raised an exception."
519
+
520
+
521
+ def run_viz(code_str: str, *, max_steps: int = 500) -> TraceResult:
522
+ """Execute source and return a bounded, structured Python trace.
523
+
524
+ This function is not a security sandbox. Submitted code runs with this
525
+ process's normal permissions; ``max_steps`` limits traced Python lines only.
526
+ """
527
+ if not isinstance(code_str, str):
528
+ raise TypeError("code_str must be a string")
529
+ if isinstance(max_steps, bool) or not isinstance(max_steps, int):
530
+ raise TypeError("max_steps must be an integer")
531
+ if max_steps <= 0:
532
+ raise ValueError("max_steps must be a positive integer")
533
+
534
+ filename = f"<codejourney-{uuid.uuid4().hex}>"
535
+ source_lines = code_str.splitlines()
536
+ events = []
537
+ warnings = []
538
+ line_steps = 0
539
+ previous_snapshots: Dict[int, Dict[str, Any]] = {}
540
+ loop_states: Dict[int, Dict[str, Dict[str, Any]]] = {}
541
+ loop_invocations: Dict[Tuple[int, str], int] = {}
542
+ namespace: Dict[str, Any] = {"__name__": "__main__"}
543
+ error: Optional[ExecutionError] = None
544
+ truncated = False
545
+
546
+ try:
547
+ analysis = analyze_source(code_str)
548
+ compiled = compile(code_str, filename, "exec")
549
+ except (SyntaxError, ValueError, TypeError) as exc:
550
+ error = ExecutionError(
551
+ type_name=_type_name(exc),
552
+ message=_safe_error_message(exc),
553
+ line_number=_error_line(exc, filename),
554
+ )
555
+ return TraceResult(code_str, (), max_steps, error=error)
556
+
557
+ linecache.cache[filename] = (
558
+ len(code_str),
559
+ None,
560
+ source_lines,
561
+ filename,
562
+ )
563
+
564
+ def trace(frame: types.FrameType, event: str, arg: Any) -> Any:
565
+ nonlocal line_steps
566
+ if frame.f_code.co_filename != filename:
567
+ return None
568
+
569
+ if event == "line":
570
+ if line_steps >= max_steps:
571
+ raise _StepLimitReached()
572
+ line_steps += 1
573
+
574
+ if event not in {"line", "return", "exception"}:
575
+ return trace
576
+ if (
577
+ event == "exception"
578
+ and isinstance(arg, tuple)
579
+ and arg
580
+ and arg[0] is _StepLimitReached
581
+ ):
582
+ return trace
583
+
584
+ frame_id = id(frame)
585
+ line_number = frame.f_lineno
586
+ boundaries = []
587
+ state = loop_states.setdefault(frame_id, {})
588
+
589
+ if event == "line":
590
+ for loop_id in tuple(state):
591
+ loop = next(item for item in analysis.loops if item.loop_id == loop_id)
592
+ if line_number != loop.line_number and not loop.contains(line_number):
593
+ current = state.pop(loop_id)
594
+ if current["started"]:
595
+ boundaries.append(
596
+ LoopBoundary(
597
+ "end",
598
+ loop_id,
599
+ current["index"],
600
+ loop.total_iterations,
601
+ current["group_id"],
602
+ )
603
+ )
604
+
605
+ for loop in analysis.loops:
606
+ if line_number != loop.line_number:
607
+ continue
608
+ current = state.get(loop.loop_id)
609
+ if current is None:
610
+ invocation_key = (frame_id, loop.loop_id)
611
+ invocation = loop_invocations.get(invocation_key, 0) + 1
612
+ loop_invocations[invocation_key] = invocation
613
+ current = {
614
+ "index": 0,
615
+ "started": False,
616
+ "group_id": f"{loop.loop_id}-run-{invocation}",
617
+ }
618
+ else:
619
+ if current["started"]:
620
+ boundaries.append(
621
+ LoopBoundary(
622
+ "end",
623
+ loop.loop_id,
624
+ current["index"],
625
+ loop.total_iterations,
626
+ current["group_id"],
627
+ )
628
+ )
629
+ current = {
630
+ "index": current["index"] + 1,
631
+ "started": False,
632
+ "group_id": current["group_id"],
633
+ }
634
+ state[loop.loop_id] = current
635
+
636
+ for loop in analysis.loops:
637
+ current = state.get(loop.loop_id)
638
+ if current is not None and loop.contains(line_number) and not current["started"]:
639
+ current["started"] = True
640
+ boundaries.append(
641
+ LoopBoundary(
642
+ "start",
643
+ loop.loop_id,
644
+ current["index"],
645
+ loop.total_iterations,
646
+ current["group_id"],
647
+ )
648
+ )
649
+
650
+ active_iterations = []
651
+ for loop in analysis.loops:
652
+ current = state.get(loop.loop_id)
653
+ if current is not None and (
654
+ line_number == loop.line_number or loop.contains(line_number)
655
+ ):
656
+ active_iterations.append(
657
+ LoopIteration(
658
+ loop_id=loop.loop_id,
659
+ kind=loop.kind,
660
+ iteration_index=current["index"],
661
+ total_iterations=loop.total_iterations,
662
+ line_number=loop.line_number,
663
+ group_id=current["group_id"],
664
+ )
665
+ )
666
+ active_iterations.sort(
667
+ key=lambda item: next(
668
+ loop.line_number
669
+ for loop in analysis.loops
670
+ if loop.loop_id == item.loop_id
671
+ )
672
+ )
673
+
674
+ if event == "return":
675
+ for loop_id, current in tuple(state.items()):
676
+ loop = next(item for item in analysis.loops if item.loop_id == loop_id)
677
+ if current["started"]:
678
+ boundaries.append(
679
+ LoopBoundary(
680
+ "end",
681
+ loop_id,
682
+ current["index"],
683
+ loop.total_iterations,
684
+ current["group_id"],
685
+ )
686
+ )
687
+ loop_states.pop(frame_id, None)
688
+
689
+ after = _snapshot_locals(frame.f_locals)
690
+ before = previous_snapshots.get(frame_id, {})
691
+ changed = _changed_variables(before, after)
692
+ diffs = _variable_diffs(before, after)
693
+ source_line = (
694
+ source_lines[line_number - 1]
695
+ if 1 <= line_number <= len(source_lines)
696
+ else None
697
+ )
698
+ exception_type = None
699
+ if event == "exception" and isinstance(arg, tuple) and arg:
700
+ exception_type = type.__getattribute__(arg[0], "__name__")
701
+
702
+ warning_codes = []
703
+ for warning in analysis.warnings:
704
+ if warning.line_number == line_number:
705
+ if warning.code in {"break-first-iteration", "return-first-iteration"}:
706
+ if any(item.iteration_index == 0 for item in active_iterations):
707
+ warning_codes.append(warning.code)
708
+ warnings.append(warning)
709
+ else:
710
+ warning_codes.append(warning.code)
711
+ warnings.append(warning)
712
+
713
+ events.append(
714
+ TraceEvent(
715
+ event=event,
716
+ line_number=line_number,
717
+ source_line=source_line,
718
+ before=before,
719
+ after=after,
720
+ changed_variables=changed,
721
+ exception_type=exception_type,
722
+ variable_diffs=diffs,
723
+ aliases=_aliases(frame.f_locals),
724
+ loop_iterations=tuple(active_iterations),
725
+ loop_boundaries=tuple(boundaries),
726
+ warning_codes=tuple(dict.fromkeys(warning_codes)),
727
+ frame_id=frame_id,
728
+ )
729
+ )
730
+ if event == "return":
731
+ previous_snapshots.pop(frame_id, None)
732
+ else:
733
+ previous_snapshots[frame_id] = after
734
+ return trace
735
+
736
+ previous_trace = sys.gettrace()
737
+ try:
738
+ sys.settrace(trace)
739
+ exec(compiled, namespace, namespace)
740
+ except _StepLimitReached:
741
+ truncated = True
742
+ except Exception as exc:
743
+ error = ExecutionError(
744
+ type_name=_type_name(exc),
745
+ message=_safe_error_message(exc),
746
+ line_number=_error_line(exc, filename),
747
+ )
748
+ finally:
749
+ sys.settrace(previous_trace)
750
+ linecache.cache.pop(filename, None)
751
+
752
+ events = _attach_condition_previews(events, analysis.conditions)
753
+ events = _sanitize_loop_iterations(events, analysis.loops)
754
+ warning_by_key = {
755
+ (warning.code, warning.line_number): warning
756
+ for warning in analysis.warnings
757
+ if warning.code not in {"break-first-iteration", "return-first-iteration"}
758
+ }
759
+ warning_by_key.update(
760
+ {
761
+ (warning.code, warning.line_number): warning
762
+ for warning in warnings
763
+ }
764
+ )
765
+ unique_warnings = tuple(warning_by_key.values())
766
+
767
+ return TraceResult(
768
+ source=code_str,
769
+ events=tuple(events),
770
+ max_steps=max_steps,
771
+ truncated=truncated,
772
+ error=error,
773
+ loops=analysis.loops,
774
+ conditions=analysis.conditions,
775
+ warnings=unique_warnings,
776
+ )
777
+
778
+
779
+ def _register_pyviz_magic() -> None:
780
+ try:
781
+ from IPython import get_ipython
782
+ except ImportError:
783
+ return
784
+
785
+ shell = get_ipython()
786
+ if shell is not None:
787
+ shell.register_magic_function(pyviz, magic_kind="cell", magic_name="pyviz")
788
+
789
+
790
+ def pyviz(line: str, cell: str) -> TraceResult:
791
+ """IPython cell magic implementation for ``%%pyviz``."""
792
+ del line
793
+ return run_viz(cell)
794
+
795
+
796
+ _register_pyviz_magic()