tracecomparekit 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.
difffinder/tracer.py ADDED
@@ -0,0 +1,192 @@
1
+ """Record how the variables of one function call change, line by line."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import inspect
6
+ import os
7
+ import re
8
+ import sys
9
+ import sysconfig
10
+ from dataclasses import dataclass, field
11
+ from typing import Any, Callable, Dict, List, Optional, Set
12
+
13
+ RETURN = "<return>" # pseudo-variable holding the value a call returned
14
+ RAISE = "<raise>" # pseudo-variable holding the exception a call raised
15
+ MAX_REPR = 1000
16
+ _ADDRESS = re.compile(r"0x[0-9a-fA-F]+")
17
+ _MISSING = object()
18
+
19
+
20
+ class StepLimitExceeded(BaseException):
21
+ """Raised inside a traced call that runs more than ``max_steps`` lines.
22
+
23
+ It derives from BaseException so a student's ``except Exception`` cannot hide it.
24
+ """
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class Event:
29
+ """One variable taking a new value."""
30
+
31
+ step: int # how many lines had run when this happened
32
+ var: str
33
+ value: str # repr() of the new value
34
+ filename: str
35
+ lineno: int # the line that caused the change
36
+ func: str
37
+ depth: int # 0 = the traced function itself, 1 = something it called, ...
38
+
39
+
40
+ @dataclass
41
+ class Trace:
42
+ """Everything recorded from one call."""
43
+
44
+ name: str
45
+ events: List[Event] = field(default_factory=list)
46
+ steps: int = 0
47
+ truncated: bool = False
48
+ arg_names: Dict[str, str] = field(default_factory=dict) # "<arg0>" -> parameter name
49
+
50
+ def history(self, var: str) -> List[Event]:
51
+ """All the values ``var`` took, in order."""
52
+ return [e for e in self.events if e.var == var]
53
+
54
+ @property
55
+ def variables(self) -> Set[str]:
56
+ return {e.var for e in self.events if not e.var.startswith("<")}
57
+
58
+
59
+ def _prefixes():
60
+ paths = {sysconfig.get_path(k) for k in ("stdlib", "platstdlib", "purelib", "platlib")}
61
+ paths.add(os.path.dirname(os.path.abspath(__file__)))
62
+ return tuple(os.path.normcase(os.path.abspath(p)) + os.sep for p in paths if p)
63
+
64
+
65
+ _PREFIXES = _prefixes()
66
+ _CACHE: Dict[str, bool] = {}
67
+
68
+
69
+ def _is_user_code(filename: str) -> bool:
70
+ """True for notebook cells and scripts, False for the stdlib and installed packages."""
71
+ hit = _CACHE.get(filename)
72
+ if hit is None:
73
+ if filename.startswith("<frozen"):
74
+ hit = False
75
+ elif filename.startswith("<"):
76
+ hit = True # <ipython-input-...>, <string>
77
+ else:
78
+ hit = not (os.path.normcase(os.path.abspath(filename)) + os.sep).startswith(_PREFIXES)
79
+ _CACHE[filename] = hit
80
+ return hit
81
+
82
+
83
+ def _safe_repr(value: Any) -> str:
84
+ try:
85
+ text = repr(value)
86
+ except Exception: # a broken __repr__ must not break the trace
87
+ text = "<unrepresentable %s>" % type(value).__name__
88
+ text = _ADDRESS.sub("0x...", text) # object addresses differ between runs
89
+ return text if len(text) <= MAX_REPR else text[:MAX_REPR] + "..."
90
+
91
+
92
+ def record(
93
+ func: Callable[..., Any],
94
+ args: tuple = (),
95
+ kwargs: Optional[dict] = None,
96
+ *,
97
+ max_steps: int = 100_000,
98
+ ) -> Trace:
99
+ """Call ``func(*args, **kwargs)`` and record every change to its variables.
100
+
101
+ Only your own code is traced: the standard library and installed packages are skipped.
102
+ The call's return value (or exception) is stored under :data:`RETURN` / :data:`RAISE`.
103
+ """
104
+ kwargs = dict(kwargs or {})
105
+ trace = Trace(name=getattr(func, "__qualname__", repr(func)))
106
+ events = trace.events
107
+ root = getattr(func, "__code__", None)
108
+ active = [0] # number of traced frames currently running
109
+ counter = [0] # lines executed so far
110
+ last_root_line = [None] # (filename, lineno, funcname) of the last line run at depth 0
111
+
112
+ def flush(frame, seen, depth, lineno):
113
+ code = frame.f_code
114
+ changed = []
115
+ for name, value in frame.f_locals.items():
116
+ if name in code.co_freevars: # a variable of the enclosing function, not this frame's own
117
+ continue
118
+ if name.startswith("__") or inspect.isroutine(value) or inspect.isclass(value) or inspect.ismodule(value):
119
+ continue
120
+ text = _safe_repr(value)
121
+ if seen.get(name, _MISSING) != text:
122
+ seen[name] = text
123
+ changed.append((name, text))
124
+ for name, text in sorted(changed): # sorted: order inside one line must not matter
125
+ events.append(Event(counter[0], name, text, code.co_filename, lineno, code.co_name, depth))
126
+
127
+ def global_trace(frame, event, arg):
128
+ if event != "call":
129
+ return None
130
+ code = frame.f_code
131
+ if code is not root and not _is_user_code(code.co_filename):
132
+ return None
133
+ depth = active[0]
134
+ active[0] += 1
135
+ seen: Dict[str, str] = {}
136
+ current = [code.co_firstlineno]
137
+
138
+ def local_trace(frame, event, arg):
139
+ if event == "line":
140
+ counter[0] += 1
141
+ if counter[0] > max_steps:
142
+ raise StepLimitExceeded()
143
+ # State is "before this line runs", so changes belong to the previous line.
144
+ flush(frame, seen, depth, current[0])
145
+ current[0] = frame.f_lineno
146
+ if depth == 0:
147
+ last_root_line[0] = (code.co_filename, current[0], code.co_name)
148
+ elif event == "return":
149
+ flush(frame, seen, depth, current[0])
150
+ active[0] -= 1
151
+ return local_trace
152
+
153
+ return local_trace
154
+
155
+ def add_end(var: str, text: str) -> None:
156
+ where = last_root_line[0] or (
157
+ getattr(root, "co_filename", "<unknown>"),
158
+ getattr(root, "co_firstlineno", 0),
159
+ trace.name,
160
+ )
161
+ events.append(Event(counter[0], var, text, where[0], where[1], where[2], 0))
162
+
163
+ def add_arg_events() -> None:
164
+ """Record the final state of each argument, so in-place changes are compared too."""
165
+ try:
166
+ bound = inspect.signature(func).bind(*args, **kwargs)
167
+ bound.apply_defaults()
168
+ except (TypeError, ValueError):
169
+ return
170
+ for idx, (name, value) in enumerate(bound.arguments.items()):
171
+ var = "<arg%d>" % idx
172
+ trace.arg_names[var] = name
173
+ add_end(var, _safe_repr(value))
174
+
175
+ previous = sys.gettrace()
176
+ sys.settrace(global_trace)
177
+ try:
178
+ result = func(*args, **kwargs)
179
+ except StepLimitExceeded:
180
+ trace.truncated = True
181
+ except Exception as exc:
182
+ sys.settrace(previous)
183
+ add_arg_events()
184
+ add_end(RAISE, "%s: %s" % (type(exc).__name__, exc))
185
+ else:
186
+ sys.settrace(previous)
187
+ add_arg_events()
188
+ add_end(RETURN, _safe_repr(result))
189
+ finally:
190
+ sys.settrace(previous)
191
+ trace.steps = counter[0]
192
+ return trace
@@ -0,0 +1,189 @@
1
+ Metadata-Version: 2.5
2
+ Name: tracecomparekit
3
+ Version: 0.1.0
4
+ Summary: Check a Python function against a reference solution and see exactly how they differ.
5
+ Project-URL: Homepage, https://github.com/clemonl/DiffFinder
6
+ Project-URL: Repository, https://github.com/clemonl/DiffFinder
7
+ Project-URL: Documentation, https://github.com/clemonl/DiffFinder#readme
8
+ Author: Clement Leung, Iko Yeung, James
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Requires-Python: >=3.9
12
+ Provides-Extra: dev
13
+ Requires-Dist: pytest; extra == 'dev'
14
+ Provides-Extra: hermes
15
+ Requires-Dist: hermes-acp-sdk; extra == 'hermes'
16
+ Requires-Dist: hermes-agent[acp]; extra == 'hermes'
17
+ Description-Content-Type: text/markdown
18
+
19
+ # DiffFinder
20
+
21
+ **Check a Python function against a reference solution and see exactly how they differ.**
22
+
23
+ Give DiffFinder your function and a known-good one. It runs both on the same input and tells you whether they
24
+ behave the same, and if not, what is different: the result, an exception, or a change to the input.
25
+
26
+ ```text
27
+ pip install tracecomparekit
28
+ ```
29
+
30
+ ## Motivation
31
+
32
+ When a program gives the wrong answer, a beginner often cannot tell *what* is wrong, only that something is.
33
+ But frequently a correct solution already exists (the lecturer's, a textbook's, a classmate's). Then the useful
34
+ question is not "what does my code do?" but **"how does my code's behaviour differ from the right one?"**
35
+
36
+ ## What makes it different
37
+
38
+ - **You supply a reference function, not hand-written expected values.** There is nothing to calculate by hand,
39
+ and the reference can be written in any style.
40
+ - **It compares behaviour, not source code.** A loop and a formula that give the same answers are reported as the
41
+ same. A text diff of the two would be useless.
42
+ - **It catches what a printed return value hides:** a function that crashes where the reference does not, or one
43
+ that changes its input list in place when the reference leaves it alone.
44
+ - **No dependencies**, so it installs next to anything, including on a shared notebook server.
45
+
46
+ ## Quick start
47
+
48
+ ```python
49
+ from difffinder import compare
50
+
51
+ def count_to(n): # your version
52
+ total = 0
53
+ for i in range(n):
54
+ total += i
55
+ return total
56
+
57
+ def count_to_ref(n): # the reference
58
+ total = 0
59
+ for i in range(n + 1):
60
+ total += i
61
+ return total
62
+
63
+ compare(count_to, count_to_ref, args=(4,))
64
+ ```
65
+
66
+ ```text
67
+ DIFFERENT: count_to and count_to_ref behave differently on (n=4).
68
+ result: yours returned 6, the reference returned 10.
69
+ ```
70
+
71
+ Different algorithms with the same behaviour are reported as the same:
72
+
73
+ ```python
74
+ def formula(n):
75
+ return n * (n + 1) // 2
76
+
77
+ compare(count_to_ref, formula, args=(4,))
78
+ ```
79
+
80
+ ```text
81
+ SAME: count_to_ref and formula behave the same on (n=4).
82
+ ```
83
+
84
+ Crashes and changes to the input are shown too:
85
+
86
+ ```python
87
+ def sort_in_place(items):
88
+ items.sort()
89
+ return items
90
+
91
+ def sorted_copy(items):
92
+ return sorted(items)
93
+
94
+ compare(sort_in_place, sorted_copy, args=([3, 1, 2],))
95
+ ```
96
+
97
+ ```text
98
+ DIFFERENT: sort_in_place and sorted_copy behave differently on (items=[3, 1, 2]).
99
+ argument 'items' afterwards: yours [1, 2, 3], the reference [3, 1, 2].
100
+ ```
101
+
102
+ ```python
103
+ def first_item(items):
104
+ return items[0]
105
+
106
+ def first_or_none(items):
107
+ return items[0] if items else None
108
+
109
+ compare(first_item, first_or_none, args=([],))
110
+ ```
111
+
112
+ ```text
113
+ DIFFERENT: first_item and first_or_none behave differently on (items=[]).
114
+ result: yours raised IndexError: list index out of range, the reference returned None.
115
+ ```
116
+
117
+ ## Usage
118
+
119
+ ```python
120
+ compare(candidate, reference, args=(), kwargs=None)
121
+ ```
122
+
123
+ | Part | Meaning |
124
+ | --- | --- |
125
+ | `candidate` | your function (the one you want to check) |
126
+ | `reference` | the known-good function |
127
+ | `args` | a tuple of positional arguments, for example `(4,)` or `([3, 1, 2], 5)` (note the comma in a one-item tuple) |
128
+ | `kwargs` | a dict of keyword arguments, for example `{"reverse": True}` |
129
+
130
+ It returns a `Comparison` with `.same` (`True` or `False`), `.differences` (a list), and `.candidate` /
131
+ `.reference`, which hold what each function did. `run(func, args)` runs a single function and records the same
132
+ information.
133
+
134
+ ### When are two functions "the same"?
135
+
136
+ On the input you give, they must have:
137
+
138
+ 1. the same return value (compared with `==`), or both raise the same kind of exception, and
139
+ 2. the same final state of every argument they received.
140
+
141
+ Each function runs on its own deep copy of your arguments, so your data is never changed.
142
+
143
+ ## Limitations
144
+
145
+ - It checks **one input per call**. A function can match on your input and still be wrong on another, so try
146
+ several (such as an empty list, zero, or a negative number).
147
+ - The functions must finish. It cannot yet stop an endless loop.
148
+ - Anything a function does besides returning or changing its arguments (printing, files, network) happens once
149
+ per function.
150
+ - Parameters are matched by position, so the two functions may use different parameter names.
151
+
152
+ ## Trace a difference
153
+
154
+ `compare_traces()` records changes to local variables and shows where the two runs first
155
+ diverge. The report displays as text in the terminal and as a table in Jupyter.
156
+
157
+ ```python
158
+ from difffinder import compare_traces, find_difference
159
+
160
+ report = compare_traces(count_to, count_to_ref, args=(4,), probe=False)
161
+ print(report)
162
+
163
+ first = find_difference(count_to, count_to_ref, [0, 1, 4])
164
+ print(first.args) # (1,)
165
+ ```
166
+
167
+ By default, `compare_traces()` also runs the functions on variations of the positional inputs
168
+ and tries to shrink a failing example. Use `probe=False` to run each function once.
169
+ Pass `watch=["total"]` to compare a particular variable. Offline hints appear in the report.
170
+ For an optional model-generated hint, pass `ai=your_callable`. The callable receives a prompt
171
+ containing the functions' source, input, and comparison report.
172
+
173
+ ## Sorting visualizer
174
+
175
+ With Tkinter installed, run `python -m difffinder.sorting_visualizer`. Choose two sorting
176
+ functions, enter a list, and click **Compare & Record** to step through their changes side by side.
177
+ For a terminal example, run `python -m difffinder.demo --console`.
178
+
179
+ ## Development
180
+
181
+ ```text
182
+ git clone https://github.com/clemonl/DiffFinder
183
+ cd difffinder
184
+ pip install -e ".[dev]"
185
+ pytest
186
+ ```
187
+
188
+ Requirements are listed in [SPEC.md](SPEC.md) and the division of work in [TEAM.md](TEAM.md).
189
+ Released under the MIT license.
@@ -0,0 +1,17 @@
1
+ difffinder/__init__.py,sha256=5cvpnoJiSkFBaVG_L1J8oOPgoYf9UJFhT1jA4CjTO8M,881
2
+ difffinder/__main__.py,sha256=z_lvhuBa3sj5PfMGkw8tNSL_QAXMxLSE5_PaF8zIjPw,76
3
+ difffinder/ai.py,sha256=J_0afrRMm3cV4TDU34oAshGIiloDfiaT6j_O7t63YvY,8980
4
+ difffinder/comparison.py,sha256=suOE9vmnPG-g4sH38CLgZyJoEL65Og0Fb3ewAtFf6c4,3234
5
+ difffinder/demo.py,sha256=ERA6PNuYLlzaJAphGq-Vp_Z3yze_w6951RxIFSVTgtQ,835
6
+ difffinder/diff.py,sha256=O7hSvnyGcPhm460L1fVwkvqcxX0tjOq48VUTcwbZmi4,9082
7
+ difffinder/hints.py,sha256=O8aUHTMRTYReJZDcFqEn4x5i0bUAoIjUBGaxeqebauc,5415
8
+ difffinder/outcome.py,sha256=TgIQ-cSWm3Gb6LgSOxA6T0ci2RR1oWUvTk0s8rnLVdw,2618
9
+ difffinder/probe.py,sha256=Cu1P5vBExcT36cH0yjP8aqY8Cx3GM1YBxXfRPstl68A,12383
10
+ difffinder/render.py,sha256=cOpV409uZgz_VycacSm3H7LfNXaIF3LQbaVdmVYWXkE,6901
11
+ difffinder/selfcheck.py,sha256=MrACPmB7Ra77EfajfwnZPmidqIdfvsvJYG_W4fjGq1E,3769
12
+ difffinder/sorting_visualizer.py,sha256=oarNReD95Wcmcf3BLs4Qzn4Dqesm8ODJYDa1QPjnGAI,34808
13
+ difffinder/tracer.py,sha256=f50jQHCoEyE-gjtWkqXnJ76hzEB5cbRD-lsfFCv_AYU,6696
14
+ tracecomparekit-0.1.0.dist-info/METADATA,sha256=4DCFTiE01YAuHJ819P3mEwxgddZu8O3JWhukPcXc0K0,6320
15
+ tracecomparekit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
16
+ tracecomparekit-0.1.0.dist-info/licenses/LICENSE,sha256=3pLNKmCbMkE41yqUKr3fyt_1oB4EnuwBSk66qOvMvEc,1112
17
+ tracecomparekit-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,23 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Clement
4
+ Copyright (c) 2026 Iko
5
+ Copyright (c) 2026 James
6
+
7
+ Permission is hereby granted, free of charge, to any person obtaining a copy
8
+ of this software and associated documentation files (the "Software"), to deal
9
+ in the Software without restriction, including without limitation the rights
10
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11
+ copies of the Software, and to permit persons to whom the Software is
12
+ furnished to do so, subject to the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.