xpt 0.1.1__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.
xpt/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ from xpt.expect import expect
2
+
3
+ __all__ = ["expect"]
xpt/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from xpt.cli import main
2
+
3
+ raise SystemExit(main())
xpt/accept.py ADDED
@@ -0,0 +1,129 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ import secrets
5
+ import shutil
6
+ from collections import defaultdict
7
+ from collections.abc import Generator, Iterable, Sequence
8
+ from contextlib import contextmanager
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+
12
+ from xpt.group import Group
13
+ from xpt.record import state_directory
14
+ from xpt.rewrite import Outcome, rewrite
15
+ from xpt.site import Unlocatable
16
+
17
+
18
+ @dataclass(frozen=True, slots=True)
19
+ class AcceptResult:
20
+ """One outcome per group, in the order given, and the project paths that were rewritten."""
21
+
22
+ outcomes: tuple[Outcome, ...]
23
+ changed: tuple[str, ...]
24
+
25
+
26
+ class AcceptError(Exception):
27
+ pass
28
+
29
+
30
+ def accept(root: Path, groups: Iterable[Group], *, dry_run: bool = False) -> AcceptResult:
31
+ """Write each acceptable group's actual value into its source file as the expected value.
32
+
33
+ A group is written only when its expected argument's text still matches the run. Each
34
+ file is rewritten in one pass to a temporary file and moved into place, under an
35
+ exclusive `.xpt/accept.lock`. A dry run reports the same result and writes nothing.
36
+ """
37
+ given = tuple(groups)
38
+ outcomes: dict[int, Outcome] = {}
39
+ by_path: dict[str, list[int]] = defaultdict(list)
40
+ for i, g in enumerate(given):
41
+ site = g.site
42
+ if not g.acceptable or isinstance(site, Unlocatable):
43
+ outcomes[i] = Outcome(g, "skipped", g.detail)
44
+ else:
45
+ by_path[site.path].append(i)
46
+ changed = []
47
+ with lock(state_directory(root) / "accept.lock"):
48
+ for path, indexes in sorted(by_path.items()):
49
+ done = _accept_file(root, path, [given[i] for i in indexes], dry_run)
50
+ outcomes.update(zip(indexes, done.outcomes, strict=True))
51
+ if done.changed:
52
+ changed.append(path)
53
+ return AcceptResult(tuple(outcomes[i] for i in range(len(given))), tuple(changed))
54
+
55
+
56
+ def create(root: Path, groups: Sequence[Group]) -> AcceptResult:
57
+ """Accept missing groups the way `pytest --expect-create` does after the session.
58
+
59
+ A held lock skips every group with the lock's message instead of raising, so the session
60
+ still ends with its report.
61
+ """
62
+ if not groups:
63
+ return AcceptResult((), ())
64
+ try:
65
+ return accept(root, groups)
66
+ except AcceptError as error:
67
+ return AcceptResult(tuple(Outcome(g, "skipped", str(error)) for g in groups), ())
68
+
69
+
70
+ @dataclass(frozen=True, slots=True)
71
+ class _FileResult:
72
+ outcomes: tuple[Outcome, ...]
73
+ changed: bool
74
+
75
+
76
+ def _accept_file(root: Path, path: str, groups: list[Group], dry_run: bool) -> _FileResult:
77
+ def skipped(reason: str) -> _FileResult:
78
+ return _FileResult(tuple(Outcome(g, "skipped", reason) for g in groups), False)
79
+
80
+ file = (root / path).resolve()
81
+ if not file.is_relative_to(root.resolve()) or not file.is_file():
82
+ return skipped(
83
+ f"{path} is not a file under {root.as_posix()}. Run accept from the project root."
84
+ )
85
+ try:
86
+ data = file.read_bytes()
87
+ except OSError as error:
88
+ return skipped(f"{path} could not be read: {error.strerror}.")
89
+ planned = rewrite(path, data, groups)
90
+ if planned.data == data:
91
+ return _FileResult(planned.outcomes, False)
92
+ if dry_run:
93
+ return _FileResult(planned.outcomes, True)
94
+ try:
95
+ _replace(file, planned.data)
96
+ except OSError as error:
97
+ return skipped(f"{path} could not be written: {error.strerror}. It was left unchanged.")
98
+ return _FileResult(planned.outcomes, True)
99
+
100
+
101
+ def _replace(file: Path, data: bytes) -> None:
102
+ temp = file.with_name(f".{file.name}.{secrets.token_hex(4)}.tmp")
103
+ try:
104
+ temp.write_bytes(data)
105
+ shutil.copymode(file, temp)
106
+ os.replace(temp, file)
107
+ finally:
108
+ temp.unlink(missing_ok=True)
109
+ # A same-size edit in the same second passes CPython's and pytest's mtime-and-size pyc check.
110
+ for cached in (file.parent / "__pycache__").glob(f"{file.stem}.*.pyc"):
111
+ cached.unlink(missing_ok=True)
112
+
113
+
114
+ @contextmanager
115
+ def lock(lock: Path) -> Generator[None]:
116
+ try:
117
+ fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
118
+ except FileExistsError:
119
+ shown = lock.as_posix()
120
+ raise AcceptError(
121
+ f"{shown} exists, so another xpt command is writing to .xpt/. "
122
+ f"If none is, delete {shown} and run the command again."
123
+ ) from None
124
+ try:
125
+ os.write(fd, str(os.getpid()).encode("ascii"))
126
+ os.close(fd)
127
+ yield
128
+ finally:
129
+ lock.unlink(missing_ok=True)
xpt/api.py ADDED
@@ -0,0 +1,43 @@
1
+ """The programmatic surface of xpt for tools: read a run, group it, accept or reject groups."""
2
+
3
+ from xpt.accept import AcceptError, AcceptResult, accept
4
+ from xpt.decisions import Rejection, RejectOutcome, RejectStatus, load_rejections, mark, reject
5
+ from xpt.diff import Change, Diff, diff
6
+ from xpt.group import Group, GroupStatus, group
7
+ from xpt.path import format_path
8
+ from xpt.record import Observation, RecordError, Status, latest_run, load_run, run_ids
9
+ from xpt.rewrite import Outcome, OutcomeStatus
10
+ from xpt.site import CallSite, Unlocatable
11
+ from xpt.value import Value, from_json, to_json
12
+
13
+ __all__ = [
14
+ "AcceptError",
15
+ "AcceptResult",
16
+ "CallSite",
17
+ "Change",
18
+ "Diff",
19
+ "Group",
20
+ "GroupStatus",
21
+ "Observation",
22
+ "Outcome",
23
+ "OutcomeStatus",
24
+ "RecordError",
25
+ "RejectOutcome",
26
+ "RejectStatus",
27
+ "Rejection",
28
+ "Status",
29
+ "Unlocatable",
30
+ "Value",
31
+ "accept",
32
+ "diff",
33
+ "format_path",
34
+ "from_json",
35
+ "group",
36
+ "latest_run",
37
+ "load_rejections",
38
+ "load_run",
39
+ "mark",
40
+ "reject",
41
+ "run_ids",
42
+ "to_json",
43
+ ]
xpt/cli.py ADDED
@@ -0,0 +1,198 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import io
5
+ import json
6
+ import shutil
7
+ import sys
8
+ from collections.abc import Callable, Sequence
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import NoReturn
12
+
13
+ from xpt import decisions, render
14
+ from xpt.accept import AcceptError, AcceptResult, accept, lock
15
+ from xpt.group import Group, group, missing
16
+ from xpt.record import (
17
+ DIRECTORY,
18
+ SCHEMA_VERSION,
19
+ RecordError,
20
+ latest_run,
21
+ load_run,
22
+ run_ids,
23
+ )
24
+ from xpt.value import Json
25
+
26
+
27
+ class UsageError(Exception):
28
+ pass
29
+
30
+
31
+ @dataclass(frozen=True, slots=True)
32
+ class Output:
33
+ """A command's result in both forms, and its exit code."""
34
+
35
+ code: int
36
+ lines: list[str]
37
+ data: dict[str, Json]
38
+
39
+
40
+ Command = Callable[[argparse.Namespace, Path], Output]
41
+
42
+
43
+ @dataclass(frozen=True, slots=True)
44
+ class _Run:
45
+ id: str
46
+ groups: tuple[Group, ...]
47
+ run_option: str
48
+
49
+
50
+ def _load(root: Path, run: str | None) -> _Run:
51
+ groups = decisions.mark(group(load_run(root, run)), decisions.load_rejections(root))
52
+ return _Run(run or latest_run(root), groups, f" --run {run}" if run else "")
53
+
54
+
55
+ def _pick(run: _Run, ids: Sequence[str]) -> list[Group]:
56
+ by_id = {g.id: g for g in run.groups if g.id is not None}
57
+ unknown = [i for i in ids if i not in by_id]
58
+ if unknown:
59
+ raise UsageError(
60
+ f"no group {', '.join(unknown)} in run {run.id}. Run xpt failures to list the ids."
61
+ )
62
+ return [by_id[i] for i in dict.fromkeys(ids)]
63
+
64
+
65
+ def failures(args: argparse.Namespace, root: Path) -> Output:
66
+ run = _load(root, args.run)
67
+ return Output(
68
+ 1 if run.groups else 0,
69
+ render.failures_lines(run.id, run.groups, run.run_option),
70
+ {"run": run.id, "groups": [render.group_json(g) for g in run.groups]},
71
+ )
72
+
73
+
74
+ def show(args: argparse.Namespace, root: Path) -> Output:
75
+ run = _load(root, args.run)
76
+ [g] = _pick(run, [args.id])
77
+ return Output(
78
+ 0,
79
+ render.show_lines(g, args.full, run.run_option),
80
+ {"run": run.id, "group": render.group_json(g)},
81
+ )
82
+
83
+
84
+ def accept_command(args: argparse.Namespace, root: Path) -> Output:
85
+ chosen = [bool(args.ids), args.all, args.missing].count(True)
86
+ if chosen == 0:
87
+ raise UsageError(
88
+ "xpt accept needs ids, --missing, or --all. Nothing was accepted. "
89
+ "Run xpt failures to list the ids."
90
+ )
91
+ if chosen > 1:
92
+ raise UsageError("give ids, --missing, or --all, not more than one.")
93
+ run = _load(root, args.run)
94
+ if args.all:
95
+ groups, target = [g for g in run.groups if not g.rejected], "--all"
96
+ elif args.missing:
97
+ groups, target = missing(run.groups), "--missing"
98
+ else:
99
+ groups, target = _pick(run, args.ids), " ".join(args.ids)
100
+ data: dict[str, Json] = {"run": run.id, "dry_run": args.dry_run}
101
+ if not groups:
102
+ empty = render.accept_json(AcceptResult((), ()))
103
+ return Output(0, [f"Nothing to accept in run {run.id}."], data | empty)
104
+ result = accept(root, groups, dry_run=args.dry_run)
105
+ written = all(o.status in ("accepted", "already_accepted") for o in result.outcomes)
106
+ retry = f"xpt accept{run.run_option} {target}"
107
+ return Output(
108
+ 0 if written else 1,
109
+ render.accept_lines(result, args.dry_run, retry),
110
+ data | render.accept_json(result),
111
+ )
112
+
113
+
114
+ def reject(args: argparse.Namespace, root: Path) -> Output:
115
+ run = _load(root, args.run)
116
+ outcomes = decisions.reject(root, run.id, _pick(run, args.ids))
117
+ return Output(
118
+ 1 if any(o.status == "skipped" for o in outcomes) else 0,
119
+ render.reject_lines(outcomes),
120
+ {"run": run.id, "outcomes": [render.outcome_json(o) for o in outcomes]},
121
+ )
122
+
123
+
124
+ def runs(args: argparse.Namespace, root: Path) -> Output:
125
+ recorded = run_ids(root)
126
+ latest = latest_run(root) if (root / DIRECTORY / "latest").is_file() else None
127
+ every = sorted({*recorded, *([latest] if latest else [])}, reverse=True)
128
+ rows = [(r, r == latest, len(group(load_run(root, r))) if r in recorded else 0) for r in every]
129
+ return Output(
130
+ 0,
131
+ render.runs_lines(rows),
132
+ {"runs": [{"id": r, "latest": latest, "failures": n} for r, latest, n in rows]},
133
+ )
134
+
135
+
136
+ def clean(args: argparse.Namespace, root: Path) -> Output:
137
+ directory = root / DIRECTORY
138
+ if not directory.is_dir():
139
+ return Output(0, ["Nothing to clean, .xpt/ does not exist."], {"removed": False})
140
+ with lock(directory / "accept.lock"):
141
+ shutil.rmtree(directory)
142
+ return Output(0, ["Removed .xpt/."], {"removed": True})
143
+
144
+
145
+ class _Parser(argparse.ArgumentParser):
146
+ def error(self, message: str) -> NoReturn:
147
+ raise UsageError(f"{message}. Run {self.prog} --help for usage.")
148
+
149
+
150
+ def _parser() -> argparse.ArgumentParser:
151
+ common = _Parser(add_help=False)
152
+ common.add_argument("--json", action="store_true", help="print one JSON object")
153
+ common.add_argument("--root", type=Path, default=Path(), help="the project root (default: .)")
154
+ picked = _Parser(add_help=False)
155
+ picked.add_argument("--run", help="a run id from xpt runs (default: the latest run)")
156
+
157
+ parser = _Parser(
158
+ prog="xpt", description="Review, accept, and reject recorded expect() failures."
159
+ )
160
+ commands = parser.add_subparsers(dest="command", required=True)
161
+
162
+ def add(name: str, handler: Command, help: str, *parents: _Parser) -> argparse.ArgumentParser:
163
+ sub = commands.add_parser(name, help=help, parents=[common, *parents])
164
+ sub.set_defaults(handler=handler)
165
+ return sub
166
+
167
+ add("failures", failures, "list the failed call sites of a run, with their diffs", picked)
168
+ sub = add("show", show, "show one call site", picked)
169
+ sub.add_argument("id")
170
+ sub.add_argument("--full", action="store_true", help="lift the change and length limits")
171
+ sub = add("accept", accept_command, "write actual values into the test source", picked)
172
+ sub.add_argument("ids", nargs="*", metavar="id")
173
+ sub.add_argument("--all", action="store_true", help="every acceptable call site")
174
+ sub.add_argument("--missing", action="store_true", help="only empty expectations")
175
+ sub.add_argument("--dry-run", action="store_true", help="report and write nothing")
176
+ sub = add("reject", reject, "record actual values as bugs, never to be offered", picked)
177
+ sub.add_argument("ids", nargs="+", metavar="id")
178
+ add("runs", runs, "list recorded runs")
179
+ add("clean", clean, "delete .xpt/ and every recorded value")
180
+ return parser
181
+
182
+
183
+ def main(argv: Sequence[str] | None = None) -> int:
184
+ for stream in (sys.stdout, sys.stderr):
185
+ if isinstance(stream, io.TextIOWrapper):
186
+ stream.reconfigure(encoding="utf-8")
187
+ try:
188
+ args = _parser().parse_args(argv)
189
+ output: Output = args.handler(args, args.root)
190
+ except (UsageError, RecordError, AcceptError) as error:
191
+ print(f"xpt: error: {error}", file=sys.stderr)
192
+ return 2
193
+ if args.json:
194
+ payload = {"schema_version": SCHEMA_VERSION, "command": args.command, **output.data}
195
+ print(json.dumps(payload, ensure_ascii=False, allow_nan=False))
196
+ else:
197
+ print("\n".join(output.lines))
198
+ return output.code
xpt/decisions.py ADDED
@@ -0,0 +1,128 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import json
5
+ import os
6
+ from collections.abc import Iterable
7
+ from dataclasses import dataclass, replace
8
+ from pathlib import Path
9
+ from typing import Literal
10
+
11
+ from xpt.accept import lock
12
+ from xpt.group import Group
13
+ from xpt.record import (
14
+ DIRECTORY,
15
+ SCHEMA_VERSION,
16
+ json_int,
17
+ json_object,
18
+ json_str,
19
+ read_jsonl,
20
+ state_directory,
21
+ versioned,
22
+ )
23
+ from xpt.site import CallSite, SiteKey
24
+ from xpt.value import canonical
25
+
26
+ FILE = "decisions.jsonl"
27
+
28
+ RejectStatus = Literal["rejected", "already_rejected", "skipped"]
29
+
30
+
31
+ @dataclass(frozen=True, slots=True)
32
+ class Rejection:
33
+ """A call site's actual value that was rejected as a bug.
34
+
35
+ `actual_sha` is the sha256 of the value's canonical JSON. A run that records another
36
+ value at the site does not match, so the group is offered for acceptance again.
37
+ """
38
+
39
+ site: SiteKey
40
+ actual_sha: str
41
+
42
+
43
+ @dataclass(frozen=True, slots=True)
44
+ class RejectOutcome:
45
+ group: Group
46
+ status: RejectStatus
47
+ reason: str
48
+
49
+
50
+ def rejection(g: Group) -> Rejection | None:
51
+ """The rejection that matches `g`, or None when it has no one actual value to reject."""
52
+ if not g.acceptable or not isinstance(g.site, CallSite) or len(g.actuals) != 1:
53
+ return None
54
+ digest = hashlib.sha256(canonical(g.actuals[0]).encode("utf-8")).hexdigest()
55
+ return Rejection(g.site.key, digest)
56
+
57
+
58
+ def load_rejections(root: Path) -> frozenset[Rejection]:
59
+ path = root / DIRECTORY / FILE
60
+ if not path.is_file():
61
+ return frozenset()
62
+ return frozenset(read_jsonl(root, path, _decode))
63
+
64
+
65
+ def mark(groups: Iterable[Group], rejections: frozenset[Rejection]) -> tuple[Group, ...]:
66
+ return tuple(replace(g, rejected=rejection(g) in rejections) for g in groups)
67
+
68
+
69
+ def reject(root: Path, run: str, groups: Iterable[Group]) -> tuple[RejectOutcome, ...]:
70
+ """Record a rejection of each group's actual value, once, in `.xpt/decisions.jsonl`.
71
+
72
+ The file is rewritten whole and moved into place under `.xpt/accept.lock`, so a reader
73
+ never sees a partial line and two writers cannot lose each other's records.
74
+ """
75
+ directory = state_directory(root)
76
+ with lock(directory / "accept.lock"):
77
+ known = set(load_rejections(root))
78
+ outcomes, added = [], []
79
+ for g in groups:
80
+ r = rejection(g)
81
+ if r is None:
82
+ outcomes.append(RejectOutcome(g, "skipped", g.detail))
83
+ elif r in known:
84
+ outcomes.append(RejectOutcome(g, "already_rejected", ""))
85
+ else:
86
+ known.add(r)
87
+ added.append(r)
88
+ outcomes.append(RejectOutcome(g, "rejected", ""))
89
+ if added:
90
+ _append(directory / FILE, [_encode(r, run) for r in added])
91
+ return tuple(outcomes)
92
+
93
+
94
+ def _append(path: Path, lines: list[str]) -> None:
95
+ before = path.read_text(encoding="utf-8") if path.is_file() else ""
96
+ temp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
97
+ try:
98
+ temp.write_text(before + "".join(f"{line}\n" for line in lines), encoding="utf-8")
99
+ os.replace(temp, path)
100
+ finally:
101
+ temp.unlink(missing_ok=True)
102
+
103
+
104
+ def _encode(r: Rejection, run: str) -> str:
105
+ path, qualname, callee, ordinal = r.site
106
+ record = {
107
+ "schema_version": SCHEMA_VERSION,
108
+ "decision": "reject",
109
+ "run": run,
110
+ "site": {"path": path, "qualname": qualname, "callee": callee, "ordinal": ordinal},
111
+ "actual_sha": r.actual_sha,
112
+ }
113
+ return json.dumps(record, ensure_ascii=False)
114
+
115
+
116
+ def _decode(data: object) -> Rejection:
117
+ record = versioned(data)
118
+ decision = record.get("decision")
119
+ if decision != "reject":
120
+ raise ValueError(f'decision must be "reject", got {decision!r}.')
121
+ site = json_object(record.get("site"), "site")
122
+ key = (
123
+ json_str(site, "path"),
124
+ json_str(site, "qualname"),
125
+ json_str(site, "callee"),
126
+ json_int(site, "ordinal"),
127
+ )
128
+ return Rejection(key, json_str(record, "actual_sha"))
xpt/diff.py ADDED
@@ -0,0 +1,101 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Hashable
4
+ from dataclasses import dataclass, field
5
+ from typing import Literal
6
+
7
+ from xpt.path import Attr, Index, Key, Path
8
+ from xpt.value import Bool, Dataclass, Dict, Float, Int, Null, Seq, Set, Str, Value
9
+
10
+
11
+ @dataclass(frozen=True, slots=True)
12
+ class Change:
13
+ path: Path
14
+ op: Literal["replace", "add", "remove"]
15
+ expected: Value | None
16
+ actual: Value | None
17
+
18
+
19
+ @dataclass(frozen=True, slots=True)
20
+ class Diff:
21
+ changes: tuple[Change, ...]
22
+ unchanged: int
23
+
24
+
25
+ def diff(expected: Value, actual: Value) -> Diff:
26
+ walk = _Walk()
27
+ walk.compare(expected, actual, ())
28
+ return Diff(tuple(walk.changes), walk.unchanged)
29
+
30
+
31
+ def norm(value: Value) -> Hashable:
32
+ """A hashable stand-in that is equal exactly when Python's == says the values are."""
33
+ match value:
34
+ case Str(v) | Int(v) | Bool(v):
35
+ return v
36
+ case Float():
37
+ return value.v
38
+ case Null():
39
+ return None
40
+ case Seq(kind, items):
41
+ return (kind, tuple(norm(i) for i in items))
42
+ case Set(_, items):
43
+ return ("set", frozenset(norm(i) for i in items))
44
+ case Dict(items):
45
+ return ("dict", frozenset((norm(k), norm(v)) for k, v in items))
46
+ case Dataclass(type_id, fields):
47
+ return ("dataclass", type_id, tuple((f, norm(v)) for f, v in fields))
48
+
49
+
50
+ def leaves(value: Value) -> int:
51
+ match value:
52
+ case Seq(_, items) | Set(_, items):
53
+ return sum(leaves(i) for i in items)
54
+ case Dict(items):
55
+ return sum(leaves(v) for _, v in items)
56
+ case Dataclass(_, fields):
57
+ return sum(leaves(v) for _, v in fields)
58
+ return 1
59
+
60
+
61
+ @dataclass(slots=True)
62
+ class _Walk:
63
+ changes: list[Change] = field(default_factory=list)
64
+ unchanged: int = 0
65
+
66
+ def compare(self, e: Value, a: Value, path: Path) -> None:
67
+ if norm(e) == norm(a):
68
+ self.unchanged += leaves(a)
69
+ return
70
+ match e, a:
71
+ case Seq(ek, ei), Seq(ak, ai) if ek == ak:
72
+ for i, (ev, av) in enumerate(zip(ei, ai, strict=False)):
73
+ self.compare(ev, av, (*path, Index(i)))
74
+ for i in range(len(ai), len(ei)):
75
+ self.changes.append(Change((*path, Index(i)), "remove", ei[i], None))
76
+ for i in range(len(ei), len(ai)):
77
+ self.changes.append(Change((*path, Index(i)), "add", None, ai[i]))
78
+ case Set(_, ei), Set(_, ai):
79
+ theirs = {norm(v): v for v in ai}
80
+ for v in ei:
81
+ if theirs.pop(norm(v), None) is None:
82
+ self.changes.append(Change(path, "remove", v, None))
83
+ else:
84
+ self.unchanged += leaves(v)
85
+ for v in theirs.values():
86
+ self.changes.append(Change(path, "add", None, v))
87
+ case Dict(ei), Dict(ai):
88
+ theirs_items = {norm(k): (k, v) for k, v in ai}
89
+ for k, v in ei:
90
+ match theirs_items.pop(norm(k), None):
91
+ case (_, av):
92
+ self.compare(v, av, (*path, Key(k)))
93
+ case None:
94
+ self.changes.append(Change((*path, Key(k)), "remove", v, None))
95
+ for k, v in theirs_items.values():
96
+ self.changes.append(Change((*path, Key(k)), "add", None, v))
97
+ case Dataclass(et, ef), Dataclass(at, af) if et == at:
98
+ for (name, ev), (_, av) in zip(ef, af, strict=True):
99
+ self.compare(ev, av, (*path, Attr(name)))
100
+ case _:
101
+ self.changes.append(Change(path, "replace", e, a))
xpt/expect.py ADDED
@@ -0,0 +1,62 @@
1
+ from __future__ import annotations
2
+
3
+ import sys
4
+
5
+ from xpt import record, report
6
+ from xpt.diff import diff
7
+ from xpt.record import Observation, Status
8
+ from xpt.serialize import UnsupportedValue, serialize
9
+ from xpt.site import locate
10
+ from xpt.value import Value
11
+
12
+ _MISSING = object()
13
+
14
+
15
+ class ExpectationFailed(AssertionError):
16
+ """A failed expect() call, carrying its observation for the pytest report."""
17
+
18
+ def __init__(self, message: str, observation: Observation) -> None:
19
+ super().__init__(message)
20
+ self.observation = observation
21
+
22
+
23
+ def expect(actual: object, expected: object = _MISSING, *, _depth: int = 0) -> None:
24
+ """Fail unless `actual == expected`, explaining a mismatch path by path.
25
+
26
+ Leaving out `expected` always fails, so a new expectation never passes unreviewed.
27
+ A failure is recorded under `.xpt/` for review. A helper that calls `expect` passes
28
+ `_depth=1` so the record points at the helper's caller.
29
+ """
30
+ __tracebackhide__ = True
31
+ if expected is not _MISSING and actual == expected:
32
+ return
33
+ frame = sys._getframe(1 + _depth)
34
+ rec = record.recorder
35
+
36
+ def observe(
37
+ status: Status, want: Value | None, got: Value | None, detail: str = ""
38
+ ) -> Observation:
39
+ test = rec.test or frame.f_code.co_qualname
40
+ return Observation(rec.run, test, locate(frame, rec.root), status, want, got, detail)
41
+
42
+ def save(observation: Observation) -> str:
43
+ try:
44
+ rec.record(observation)
45
+ except OSError as error:
46
+ return f"xpt could not record this failure: {error}"
47
+ return ""
48
+
49
+ try:
50
+ want = None if expected is _MISSING else serialize(expected)
51
+ got = serialize(actual)
52
+ except UnsupportedValue as error:
53
+ if rec.enabled and (note := save(observe("unsupported", None, None, str(error)))):
54
+ error.add_note(note)
55
+ raise
56
+ if want is None:
57
+ status, message = "missing", report.missing(got)
58
+ else:
59
+ status, message = "mismatch", report.mismatch(diff(want, got))
60
+ observation = observe(status, want, got)
61
+ note = save(observation)
62
+ raise ExpectationFailed(f"{message}\n{note}" if note else message, observation)