spec2py 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.
spec2py/ir.py ADDED
@@ -0,0 +1,229 @@
1
+ """Model IR: a typed, language-neutral graph of an API.
2
+
3
+ Built from a normalized OpenAPI 3.1 document. Every later stage reads only the
4
+ IR, never raw YAML, so the IR can be snapshot-tested on its own
5
+ (``spec2py ir spec.yaml`` prints it as JSON).
6
+ """
7
+
8
+ import dataclasses
9
+ import enum
10
+ from dataclasses import dataclass, field
11
+ from typing import Any, Literal
12
+
13
+ __all__ = [
14
+ "API",
15
+ "Discriminator",
16
+ "Kind",
17
+ "Operation",
18
+ "Parameter",
19
+ "Property",
20
+ "RequestBody",
21
+ "Response",
22
+ "Schema",
23
+ "SecurityScheme",
24
+ "Server",
25
+ "to_jsonable",
26
+ ]
27
+
28
+ type JSON = Any
29
+ type ParamLocation = Literal["path", "query", "header", "cookie"]
30
+
31
+
32
+ class Kind(enum.StrEnum):
33
+ OBJECT = "object"
34
+ ARRAY = "array"
35
+ MAP = "map"
36
+ STRING = "string"
37
+ INTEGER = "integer"
38
+ NUMBER = "number"
39
+ BOOLEAN = "boolean"
40
+ NULL = "null"
41
+ ANY = "any"
42
+ ENUM = "enum"
43
+ CONST = "const"
44
+ UNION = "union"
45
+ REF = "ref"
46
+
47
+
48
+ @dataclass(slots=True)
49
+ class Discriminator:
50
+ property: str
51
+ mapping: dict[str, str] = field(default_factory=dict[str, str])
52
+ """Wire value -> component schema name."""
53
+
54
+
55
+ @dataclass(slots=True)
56
+ class Property:
57
+ name: str
58
+ schema: Schema
59
+ required: bool = False
60
+
61
+
62
+ @dataclass(slots=True, eq=False)
63
+ class Schema:
64
+ """One schema node. ``kind`` says which of the other fields matter."""
65
+
66
+ kind: Kind
67
+ nullable: bool = False
68
+ ref: str | None = None
69
+ """Component name, for ``Kind.REF``."""
70
+ title: str | None = None
71
+ description: str | None = None
72
+ deprecated: bool = False
73
+ read_only: bool = False
74
+ write_only: bool = False
75
+ format: str | None = None
76
+ default: JSON = None
77
+ has_default: bool = False
78
+ examples: list[JSON] = field(default_factory=list[JSON])
79
+ properties: list[Property] = field(default_factory=list[Property])
80
+ additional: Schema | None = None
81
+ """Typed ``additionalProperties`` (objects and maps)."""
82
+ bases: list[str] = field(default_factory=list[str])
83
+ """Component names this object extends (from ``allOf``)."""
84
+ items: Schema | None = None
85
+ values: list[JSON] = field(default_factory=list[JSON])
86
+ """Enum members, or the single ``const`` value."""
87
+ variants: list[Schema] = field(default_factory=list["Schema"])
88
+ discriminator: Discriminator | None = None
89
+ union_kind: Literal["oneOf", "anyOf", "type"] | None = None
90
+ content_media_type: str | None = None
91
+ lossy: list[str] = field(default_factory=list[str])
92
+ """Constructs Python can't express, recorded for NOTES.md."""
93
+ extensions: dict[str, JSON] = field(default_factory=dict[str, JSON])
94
+
95
+ def property(self, name: str) -> Property | None:
96
+ return next((p for p in self.properties if p.name == name), None)
97
+
98
+
99
+ @dataclass(slots=True)
100
+ class Parameter:
101
+ name: str
102
+ location: ParamLocation
103
+ schema: Schema
104
+ required: bool = False
105
+ description: str | None = None
106
+ deprecated: bool = False
107
+ style: str | None = None
108
+ explode: bool | None = None
109
+
110
+
111
+ @dataclass(slots=True)
112
+ class RequestBody:
113
+ media_type: str
114
+ schema: Schema
115
+ required: bool = False
116
+ description: str | None = None
117
+ media_types: list[str] = field(default_factory=list[str])
118
+
119
+
120
+ @dataclass(slots=True)
121
+ class Response:
122
+ status: str
123
+ description: str | None = None
124
+ media_type: str | None = None
125
+ schema: Schema | None = None
126
+ item_schema: Schema | None = None
127
+ """OpenAPI 3.2 ``itemSchema`` for sequential media types (SSE, NDJSON)."""
128
+ media_types: list[str] = field(default_factory=list[str])
129
+ headers: dict[str, Schema] = field(default_factory=dict[str, Schema])
130
+
131
+ @property
132
+ def is_success(self) -> bool:
133
+ return self.status.startswith("2")
134
+
135
+
136
+ @dataclass(slots=True)
137
+ class Operation:
138
+ method: str
139
+ path: str
140
+ operation_id: str | None = None
141
+ tags: list[str] = field(default_factory=list[str])
142
+ summary: str | None = None
143
+ description: str | None = None
144
+ deprecated: bool = False
145
+ parameters: list[Parameter] = field(default_factory=list[Parameter])
146
+ request_body: RequestBody | None = None
147
+ responses: list[Response] = field(default_factory=list[Response])
148
+ security: list[dict[str, list[str]]] | None = None
149
+ """``None`` inherits the API default; ``[]`` means no auth."""
150
+ extensions: dict[str, JSON] = field(default_factory=dict[str, JSON])
151
+
152
+ @property
153
+ def key(self) -> str:
154
+ return f"{self.method.upper()} {self.path}"
155
+
156
+
157
+ @dataclass(slots=True)
158
+ class SecurityScheme:
159
+ name: str
160
+ type: Literal["apiKey", "http", "oauth2", "openIdConnect", "mutualTLS"]
161
+ scheme: str | None = None
162
+ """For ``http``: ``bearer``, ``basic``..."""
163
+ location: Literal["header", "query", "cookie"] | None = None
164
+ parameter_name: str | None = None
165
+ token_url: str | None = None
166
+ flows: list[str] = field(default_factory=list[str])
167
+ scopes: list[str] = field(default_factory=list[str])
168
+ description: str | None = None
169
+
170
+
171
+ @dataclass(slots=True)
172
+ class Server:
173
+ url: str
174
+ description: str | None = None
175
+
176
+
177
+ @dataclass(slots=True)
178
+ class API:
179
+ title: str
180
+ version: str
181
+ openapi_version: str
182
+ description: str | None = None
183
+ servers: list[Server] = field(default_factory=list[Server])
184
+ schemas: dict[str, Schema] = field(default_factory=dict[str, Schema])
185
+ operations: list[Operation] = field(default_factory=list[Operation])
186
+ security_schemes: dict[str, SecurityScheme] = field(
187
+ default_factory=dict[str, SecurityScheme]
188
+ )
189
+ security: list[dict[str, list[str]]] = field(
190
+ default_factory=list[dict[str, list[str]]]
191
+ )
192
+ extensions: dict[str, JSON] = field(default_factory=dict[str, JSON])
193
+
194
+ def resolve(self, schema: Schema) -> Schema:
195
+ """Follow ``Kind.REF`` chains to the component they name."""
196
+ seen: set[str] = set()
197
+ while schema.kind is Kind.REF and schema.ref in self.schemas:
198
+ assert schema.ref is not None
199
+ if schema.ref in seen:
200
+ break
201
+ seen.add(schema.ref)
202
+ schema = self.schemas[schema.ref]
203
+ return schema
204
+
205
+
206
+ def _empty(value: object) -> bool:
207
+ if value is None or value is False:
208
+ return True
209
+ return isinstance(value, list | dict) and not value
210
+
211
+
212
+ def to_jsonable(value: Any) -> JSON:
213
+ """Dump IR to plain JSON, omitting empty/default fields for compact snapshots."""
214
+ if dataclasses.is_dataclass(value) and not isinstance(value, type):
215
+ out: dict[str, JSON] = {}
216
+ for f in dataclasses.fields(value):
217
+ v = getattr(value, f.name)
218
+ keep_default = f.name == "default" and getattr(value, "has_default", False)
219
+ if _empty(v) and not keep_default:
220
+ continue
221
+ out[f.name] = to_jsonable(v)
222
+ return out
223
+ if isinstance(value, enum.Enum):
224
+ return value.value
225
+ if isinstance(value, list):
226
+ return [to_jsonable(v) for v in value] # pyright: ignore[reportUnknownVariableType]
227
+ if isinstance(value, dict):
228
+ return {k: to_jsonable(v) for k, v in value.items()} # pyright: ignore[reportUnknownVariableType]
229
+ return value
spec2py/jsonpath.py ADDED
@@ -0,0 +1,456 @@
1
+ """A small RFC 9535 JSONPath engine that returns mutable locations.
2
+
3
+ Overlays need to *change* what a path selects, so every match carries its
4
+ parent container and key. Supported: ``$``, ``@``, ``.name``, ``['name']``,
5
+ ``*``, ``..`` (descendants), indices, slices, unions, and filters with
6
+ comparisons, ``&&``, ``||``, ``!``, existence tests and the ``length()``,
7
+ ``count()``, ``match()`` and ``search()`` functions. The legacy ``[?(...)]``
8
+ form works because parentheses group.
9
+ """
10
+
11
+ import re
12
+ from collections.abc import Callable, Iterator, Sequence
13
+ from dataclasses import dataclass
14
+ from typing import Any, Final, cast
15
+
16
+ __all__ = ["JSONPathError", "Location", "compile_path", "find"]
17
+
18
+ type JSON = Any
19
+
20
+
21
+ class JSONPathError(ValueError):
22
+ pass
23
+
24
+
25
+ @dataclass(frozen=True, slots=True)
26
+ class Location:
27
+ """One match: its value, the container holding it and its key there."""
28
+
29
+ value: JSON
30
+ parent: JSON
31
+ key: str | int | None
32
+ path: tuple[str | int, ...]
33
+
34
+ def set(self, value: JSON) -> None:
35
+ if self.parent is None or self.key is None:
36
+ raise JSONPathError("cannot replace the document root")
37
+ self.parent[self.key] = value
38
+
39
+
40
+ # -- tokenizer -------------------------------------------------------------------
41
+
42
+ _TOKEN_RE: Final = re.compile(
43
+ r"""
44
+ (?P<ws>\s+)
45
+ | (?P<string>'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")
46
+ | (?P<number>-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)
47
+ | (?P<op>\.\.|==|!=|<=|>=|&&|\|\||[$@.\[\]*,:?()!<>])
48
+ | (?P<name>[A-Za-z_\u0080-\U0010ffff][\w\u0080-\U0010ffff-]*)
49
+ """,
50
+ re.VERBOSE,
51
+ )
52
+
53
+
54
+ @dataclass(frozen=True, slots=True)
55
+ class _Tok:
56
+ kind: str
57
+ text: str
58
+ pos: int
59
+
60
+
61
+ def _tokenize(source: str) -> list[_Tok]:
62
+ tokens: list[_Tok] = []
63
+ pos = 0
64
+ while pos < len(source):
65
+ m = _TOKEN_RE.match(source, pos)
66
+ if not m:
67
+ raise JSONPathError(f"unexpected character {source[pos]!r} at {pos}")
68
+ kind = cast(str, m.lastgroup)
69
+ if kind != "ws":
70
+ tokens.append(_Tok(kind, m.group(), pos))
71
+ pos = m.end()
72
+ tokens.append(_Tok("eof", "", pos))
73
+ return tokens
74
+
75
+
76
+ def _unquote(text: str) -> str:
77
+ body = text[1:-1]
78
+ return re.sub(
79
+ r"\\(u[0-9a-fA-F]{4}|.)",
80
+ lambda m: (
81
+ chr(int(m.group(1)[1:], 16))
82
+ if m.group(1).startswith("u")
83
+ else {"n": "\n", "t": "\t", "r": "\r", "b": "\b", "f": "\f"}.get(
84
+ m.group(1), m.group(1)
85
+ )
86
+ ),
87
+ body,
88
+ )
89
+
90
+
91
+ # -- AST -------------------------------------------------------------------------
92
+
93
+ type _Node = tuple[JSON, JSON, str | int | None, tuple[str | int, ...]]
94
+ type _Selector = Callable[[_Node, JSON], Iterator[_Node]]
95
+
96
+
97
+ def _children(node: _Node) -> Iterator[_Node]:
98
+ value, _, _, path = node
99
+ if isinstance(value, dict):
100
+ for k, v in cast(dict[str, JSON], value).items():
101
+ yield (v, value, k, (*path, k))
102
+ elif isinstance(value, list):
103
+ for i, v in enumerate(cast(list[JSON], value)):
104
+ yield (v, value, i, (*path, i))
105
+
106
+
107
+ def _descendants(node: _Node) -> Iterator[_Node]:
108
+ yield node
109
+ for child in _children(node):
110
+ yield from _descendants(child)
111
+
112
+
113
+ def _name_selector(name: str) -> _Selector:
114
+ def select(node: _Node, root: JSON) -> Iterator[_Node]:
115
+ value, _, _, path = node
116
+ if isinstance(value, dict) and name in value:
117
+ yield (value[name], value, name, (*path, name))
118
+
119
+ return select
120
+
121
+
122
+ def _wildcard(node: _Node, root: JSON) -> Iterator[_Node]:
123
+ yield from _children(node)
124
+
125
+
126
+ def _index_selector(index: int) -> _Selector:
127
+ def select(node: _Node, root: JSON) -> Iterator[_Node]:
128
+ value, _, _, path = node
129
+ if isinstance(value, list):
130
+ items = cast(list[JSON], value)
131
+ i = index + len(items) if index < 0 else index
132
+ if 0 <= i < len(items):
133
+ yield (items[i], value, i, (*path, i))
134
+
135
+ return select
136
+
137
+
138
+ def _slice_selector(start: int | None, stop: int | None, step: int | None) -> _Selector:
139
+ def select(node: _Node, root: JSON) -> Iterator[_Node]:
140
+ value, _, _, path = node
141
+ if isinstance(value, list):
142
+ items = cast(list[JSON], value)
143
+ for i in range(len(items))[slice(start, stop, step)]:
144
+ yield (items[i], value, i, (*path, i))
145
+
146
+ return select
147
+
148
+
149
+ type _Expr = Callable[[_Node, JSON], JSON]
150
+ _NOTHING: Final = object()
151
+
152
+
153
+ def _filter_selector(expr: _Expr) -> _Selector:
154
+ def select(node: _Node, root: JSON) -> Iterator[_Node]:
155
+ for child in _children(node):
156
+ if _truthy(expr(child, root)):
157
+ yield child
158
+
159
+ return select
160
+
161
+
162
+ def _truthy(value: JSON) -> bool:
163
+ if isinstance(value, _NodeList):
164
+ return bool(value.nodes)
165
+ return value is True
166
+
167
+
168
+ class _NodeList:
169
+ """The result of a path inside a filter (distinct from a JSON value)."""
170
+
171
+ __slots__ = ("nodes",)
172
+
173
+ def __init__(self, nodes: list[_Node]) -> None:
174
+ self.nodes = nodes
175
+
176
+ def single(self) -> JSON:
177
+ return self.nodes[0][0] if len(self.nodes) == 1 else _NOTHING
178
+
179
+
180
+ def _value(v: JSON) -> JSON:
181
+ return v.single() if isinstance(v, _NodeList) else v
182
+
183
+
184
+ def _compare(op: str, left: JSON, right: JSON) -> bool:
185
+ a, b = _value(left), _value(right)
186
+ if op in ("==", "!="):
187
+ equal = (
188
+ a is b
189
+ if a is _NOTHING or b is _NOTHING
190
+ else (type(a) is type(b) or _both_numbers(a, b)) and a == b
191
+ )
192
+ return equal if op == "==" else not equal
193
+ if a is _NOTHING or b is _NOTHING:
194
+ return False
195
+ if _both_numbers(a, b) or (isinstance(a, str) and isinstance(b, str)):
196
+ match op:
197
+ case "<":
198
+ return bool(a < b)
199
+ case "<=":
200
+ return bool(a <= b)
201
+ case ">":
202
+ return bool(a > b)
203
+ case ">=":
204
+ return bool(a >= b)
205
+ return False
206
+
207
+
208
+ def _both_numbers(a: JSON, b: JSON) -> bool:
209
+ return all(isinstance(x, int | float) and not isinstance(x, bool) for x in (a, b))
210
+
211
+
212
+ def _fn_length(args: Sequence[JSON]) -> JSON:
213
+ v = _value(args[0])
214
+ if isinstance(v, str | list | dict):
215
+ return len(cast(Sequence[Any], v))
216
+ return _NOTHING
217
+
218
+
219
+ def _fn_count(args: Sequence[JSON]) -> JSON:
220
+ v = args[0]
221
+ return len(v.nodes) if isinstance(v, _NodeList) else _NOTHING
222
+
223
+
224
+ def _fn_match(args: Sequence[JSON]) -> JSON:
225
+ s, pattern = _value(args[0]), _value(args[1])
226
+ if isinstance(s, str) and isinstance(pattern, str):
227
+ return re.fullmatch(pattern, s) is not None
228
+ return False
229
+
230
+
231
+ def _fn_search(args: Sequence[JSON]) -> JSON:
232
+ s, pattern = _value(args[0]), _value(args[1])
233
+ if isinstance(s, str) and isinstance(pattern, str):
234
+ return re.search(pattern, s) is not None
235
+ return False
236
+
237
+
238
+ _FUNCTIONS: Final[dict[str, Callable[[Sequence[JSON]], JSON]]] = {
239
+ "length": _fn_length,
240
+ "count": _fn_count,
241
+ "match": _fn_match,
242
+ "search": _fn_search,
243
+ "value": lambda args: _value(args[0]),
244
+ }
245
+
246
+
247
+ def _either(left: _Expr, right: _Expr) -> _Expr:
248
+ return lambda n, r: _truthy(left(n, r)) or _truthy(right(n, r))
249
+
250
+
251
+ def _both(left: _Expr, right: _Expr) -> _Expr:
252
+ return lambda n, r: _truthy(left(n, r)) and _truthy(right(n, r))
253
+
254
+
255
+ # -- parser ----------------------------------------------------------------------
256
+
257
+
258
+ class _Parser:
259
+ def __init__(self, source: str) -> None:
260
+ self.source = source
261
+ self.tokens = _tokenize(source)
262
+ self.i = 0
263
+
264
+ @property
265
+ def tok(self) -> _Tok:
266
+ return self.tokens[self.i]
267
+
268
+ def take(self, text: str | None = None, kind: str | None = None) -> _Tok:
269
+ tok = self.tok
270
+ if (text is not None and tok.text != text) or (
271
+ kind is not None and tok.kind != kind
272
+ ):
273
+ want = text or kind
274
+ raise JSONPathError(
275
+ f"expected {want!r} at {tok.pos} in {self.source!r}, got {tok.text!r}"
276
+ )
277
+ self.i += 1
278
+ return tok
279
+
280
+ def accept(self, text: str) -> bool:
281
+ if self.tok.text == text and self.tok.kind in ("op", "name"):
282
+ self.i += 1
283
+ return True
284
+ return False
285
+
286
+ def parse_query(self, anchor: str) -> list[tuple[bool, list[_Selector]]]:
287
+ self.take(anchor)
288
+ return self.parse_segments()
289
+
290
+ def parse_segments(self) -> list[tuple[bool, list[_Selector]]]:
291
+ segments: list[tuple[bool, list[_Selector]]] = []
292
+ while True:
293
+ if self.accept(".."):
294
+ if self.tok.text == "[":
295
+ segments.append((True, self.parse_bracket()))
296
+ elif self.accept("*"):
297
+ segments.append((True, [_wildcard]))
298
+ else:
299
+ segments.append(
300
+ (True, [_name_selector(self.take(kind="name").text)])
301
+ )
302
+ elif self.accept("."):
303
+ if self.accept("*"):
304
+ segments.append((False, [_wildcard]))
305
+ else:
306
+ segments.append(
307
+ (False, [_name_selector(self.take(kind="name").text)])
308
+ )
309
+ elif self.tok.text == "[":
310
+ segments.append((False, self.parse_bracket()))
311
+ else:
312
+ return segments
313
+
314
+ def parse_bracket(self) -> list[_Selector]:
315
+ self.take("[")
316
+ selectors = [self.parse_selector()]
317
+ while self.accept(","):
318
+ selectors.append(self.parse_selector())
319
+ self.take("]")
320
+ return selectors
321
+
322
+ def parse_selector(self) -> _Selector:
323
+ tok = self.tok
324
+ if tok.kind == "string":
325
+ self.i += 1
326
+ return _name_selector(_unquote(tok.text))
327
+ if self.accept("*"):
328
+ return _wildcard
329
+ if self.accept("?"):
330
+ return _filter_selector(self.parse_or())
331
+ if tok.kind == "number" or tok.text == ":":
332
+ return self.parse_index_or_slice()
333
+ raise JSONPathError(
334
+ f"bad selector {tok.text!r} at {tok.pos} in {self.source!r}"
335
+ )
336
+
337
+ def parse_index_or_slice(self) -> _Selector:
338
+ parts: list[int | None] = [None]
339
+ if self.tok.kind == "number":
340
+ parts[0] = int(self.take(kind="number").text)
341
+ if self.tok.text != ":":
342
+ assert parts[0] is not None
343
+ return _index_selector(parts[0])
344
+ while self.accept(":"):
345
+ if self.tok.kind == "number":
346
+ parts.append(int(self.take(kind="number").text))
347
+ else:
348
+ parts.append(None)
349
+ start, stop, step = [*parts, None, None][:3]
350
+ return _slice_selector(start, stop, step)
351
+
352
+ # filter expressions
353
+ def parse_or(self) -> _Expr:
354
+ left = self.parse_and()
355
+ while self.accept("||"):
356
+ right = self.parse_and()
357
+ left = _either(left, right)
358
+ return left
359
+
360
+ def parse_and(self) -> _Expr:
361
+ left = self.parse_not()
362
+ while self.accept("&&"):
363
+ right = self.parse_not()
364
+ left = _both(left, right)
365
+ return left
366
+
367
+ def parse_not(self) -> _Expr:
368
+ if self.accept("!"):
369
+ inner = self.parse_not()
370
+ return lambda n, r: not _truthy(inner(n, r))
371
+ return self.parse_comparison()
372
+
373
+ def parse_comparison(self) -> _Expr:
374
+ left = self.parse_primary()
375
+ if self.tok.text in ("==", "!=", "<", "<=", ">", ">="):
376
+ op = self.take().text
377
+ right = self.parse_primary()
378
+ return lambda n, r: _compare(op, left(n, r), right(n, r))
379
+ return left
380
+
381
+ def parse_primary(self) -> _Expr:
382
+ tok = self.tok
383
+ if self.accept("("):
384
+ inner = self.parse_or()
385
+ self.take(")")
386
+ return inner
387
+ if tok.kind == "string":
388
+ self.i += 1
389
+ text = _unquote(tok.text)
390
+ return lambda n, r: text
391
+ if tok.kind == "number":
392
+ self.i += 1
393
+ num: float | int = (
394
+ float(tok.text) if any(c in tok.text for c in ".eE") else int(tok.text)
395
+ )
396
+ return lambda n, r: num
397
+ if tok.kind == "name" and tok.text in ("true", "false", "null"):
398
+ self.i += 1
399
+ const = {"true": True, "false": False, "null": None}[tok.text]
400
+ return lambda n, r: const
401
+ if tok.text in ("@", "$"):
402
+ relative = tok.text == "@"
403
+ segments = self.parse_query(tok.text)
404
+
405
+ def run(n: _Node, r: JSON) -> JSON:
406
+ start: _Node = n if relative else (r, None, None, ())
407
+ return _NodeList(_evaluate(start, r, segments))
408
+
409
+ return run
410
+ if tok.kind == "name" and self.tokens[self.i + 1].text == "(":
411
+ name = self.take(kind="name").text
412
+ fn = _FUNCTIONS.get(name)
413
+ if fn is None:
414
+ raise JSONPathError(f"unknown function {name}()")
415
+ self.take("(")
416
+ args: list[_Expr] = []
417
+ if self.tok.text != ")":
418
+ args.append(self.parse_or())
419
+ while self.accept(","):
420
+ args.append(self.parse_or())
421
+ self.take(")")
422
+ return lambda n, r: fn([a(n, r) for a in args])
423
+ raise JSONPathError(f"unexpected {tok.text!r} at {tok.pos} in {self.source!r}")
424
+
425
+
426
+ def _evaluate(
427
+ start: _Node, root: JSON, segments: list[tuple[bool, list[_Selector]]]
428
+ ) -> list[_Node]:
429
+ nodes = [start]
430
+ for descendant, selectors in segments:
431
+ sources = [d for n in nodes for d in _descendants(n)] if descendant else nodes
432
+ nodes = [out for n in sources for sel in selectors for out in sel(n, root)]
433
+ return nodes
434
+
435
+
436
+ @dataclass(frozen=True, slots=True)
437
+ class CompiledPath:
438
+ source: str
439
+ segments: list[tuple[bool, list[_Selector]]]
440
+
441
+ def find(self, document: JSON) -> list[Location]:
442
+ nodes = _evaluate((document, None, None, ()), document, self.segments)
443
+ return [Location(v, p, k, path) for v, p, k, path in nodes]
444
+
445
+
446
+ def compile_path(source: str) -> CompiledPath:
447
+ parser = _Parser(source.strip())
448
+ segments = parser.parse_query("$")
449
+ if parser.tok.kind != "eof":
450
+ raise JSONPathError(f"unexpected {parser.tok.text!r} at {parser.tok.pos}")
451
+ return CompiledPath(source, segments)
452
+
453
+
454
+ def find(document: JSON, path: str) -> list[Location]:
455
+ """Return every location ``path`` selects in ``document``."""
456
+ return compile_path(path).find(document)