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/emit/pyast.py ADDED
@@ -0,0 +1,372 @@
1
+ """Python type expressions and AST-building helpers.
2
+
3
+ The emitter builds every module as an ``ast.Module`` (never string templates),
4
+ so generated code is syntactically valid by construction. Type annotations are
5
+ small ``TypeExpr`` trees that render to AST and record the imports they need.
6
+ """
7
+
8
+ import ast
9
+ import textwrap
10
+ from collections import defaultdict
11
+ from collections.abc import Iterable
12
+ from dataclasses import dataclass, field
13
+ from typing import Any, Final
14
+
15
+ try: # Python 3.14 moved the unparser out of ast.py
16
+ from _ast_unparse import Unparser as _StdUnparser # type: ignore[import-not-found]
17
+ except ImportError: # pragma: no cover
18
+ _StdUnparser = ast._Unparser # type: ignore[attr-defined]
19
+
20
+ __all__ = [
21
+ "MODELS",
22
+ "Imports",
23
+ "TAnnotated",
24
+ "TCall",
25
+ "TLiteral",
26
+ "TName",
27
+ "TNone",
28
+ "TSub",
29
+ "TUnion",
30
+ "TypeExpr",
31
+ "docstring",
32
+ "unparse",
33
+ ]
34
+
35
+ MODELS: Final = "<models>"
36
+ """Pseudo-module for names defined in the generated ``models.py``."""
37
+
38
+
39
+ class Imports:
40
+ """Collects ``from x import y`` statements and resolves local-name clashes."""
41
+
42
+ def __init__(self, *, here: str, reserved: Iterable[str] = ()) -> None:
43
+ self.here = here
44
+ self._names: dict[tuple[str, str], str] = {}
45
+ self._taken: set[str] = set(reserved)
46
+ self._modules: set[str] = set()
47
+ self._preassigned: dict[tuple[str, str], str] = {}
48
+ self.shadowed: set[str] = set()
49
+ """Builtins shadowed by a class attribute (a method named ``list``)."""
50
+ self.model_modules: dict[str, str] | None = None
51
+ """When models are split into a package: model name -> its module."""
52
+ self.deferred: set[tuple[str, str]] = set()
53
+ """Imports needed only by type checkers (emitted under ``TYPE_CHECKING``)."""
54
+
55
+ def preassign(self, module: str, *names: str) -> None:
56
+ """Claim local names for imports that may be used later (e.g. by unasync)."""
57
+ for name in names:
58
+ self._preassigned[(module, name)] = name
59
+ self._taken.add(name)
60
+
61
+ def name(self, module: str | None, name: str) -> str:
62
+ """Return the local name for ``module.name``, importing it if needed."""
63
+ if module == MODELS and self.model_modules is not None:
64
+ target = self.model_modules[name]
65
+ if self.here == f"models.{target}":
66
+ return name
67
+ module = f".{target}"
68
+ if module is None or module == self.here:
69
+ return name
70
+ key = (module, name)
71
+ if key in self._names:
72
+ return self._names[key]
73
+ if key in self._preassigned:
74
+ self._names[key] = self._preassigned[key]
75
+ return name
76
+ local = name
77
+ if local in self._taken:
78
+ local = f"{name}Model" if module == MODELS else f"_{name}"
79
+ n = 2
80
+ while local in self._taken:
81
+ local = f"{name}_{n}"
82
+ n += 1
83
+ self._taken.add(local)
84
+ self._names[key] = local
85
+ return local
86
+
87
+ def used(self) -> list[tuple[tuple[str, str], str]]:
88
+ return sorted(self._names.items())
89
+
90
+ def module(self, module: str) -> str:
91
+ self._modules.add(module)
92
+ return module
93
+
94
+ def _resolve(self, module: str) -> str:
95
+ if module != MODELS:
96
+ return module
97
+ depth = self.here.count(".")
98
+ return "." * (depth + 1) + "models" if depth else ".models"
99
+
100
+ def statements(self) -> list[ast.stmt]:
101
+ grouped: dict[str, list[ast.alias]] = defaultdict(list)
102
+ deferred: dict[str, list[ast.alias]] = defaultdict(list)
103
+ for (module, name), local in sorted(self._names.items()):
104
+ target = deferred if (module, name) in self.deferred else grouped
105
+ target[self._resolve(module)].append(
106
+ ast.alias(name=name, asname=None if local == name else local)
107
+ )
108
+ if deferred:
109
+ grouped["typing"].append(ast.alias(name="TYPE_CHECKING"))
110
+ out: list[ast.stmt] = [
111
+ ast.Import(names=[ast.alias(name=m)]) for m in sorted(self._modules)
112
+ ]
113
+ out.extend(self._from_imports(grouped))
114
+ if deferred:
115
+ out.append(
116
+ ast.If(ast.Name("TYPE_CHECKING"), self._from_imports(deferred), [])
117
+ )
118
+ return out
119
+
120
+ @staticmethod
121
+ def _from_imports(grouped: dict[str, list[ast.alias]]) -> list[ast.stmt]:
122
+ out: list[ast.stmt] = []
123
+ for module, aliases in sorted(grouped.items()):
124
+ level = len(module) - len(module.lstrip("."))
125
+ out.append(
126
+ ast.ImportFrom(
127
+ module=module.lstrip(".") or None, names=aliases, level=level
128
+ )
129
+ )
130
+ return out
131
+
132
+
133
+ class TypeExpr:
134
+ """A Python type annotation."""
135
+
136
+ def static(self) -> TypeExpr:
137
+ """This type without ``Annotated`` metadata (which only pydantic reads)."""
138
+ return self
139
+
140
+ def to_ast(self, imports: Imports) -> ast.expr:
141
+ raise NotImplementedError
142
+
143
+ def render(self) -> str:
144
+ """Readable form, for docs, diffs and snapshots."""
145
+ raise NotImplementedError
146
+
147
+ @property
148
+ def is_none(self) -> bool:
149
+ return False
150
+
151
+
152
+ @dataclass(frozen=True, slots=True)
153
+ class TName(TypeExpr):
154
+ name: str
155
+ module: str | None = None
156
+
157
+ def to_ast(self, imports: Imports) -> ast.expr:
158
+ if self.module is None and self.name in imports.shadowed:
159
+ return ast.Attribute(ast.Name(imports.module("builtins")), self.name)
160
+ return ast.Name(imports.name(self.module, self.name))
161
+
162
+ def render(self) -> str:
163
+ return self.name
164
+
165
+
166
+ @dataclass(frozen=True, slots=True)
167
+ class TNone(TypeExpr):
168
+ def to_ast(self, imports: Imports) -> ast.expr:
169
+ return ast.Constant(None)
170
+
171
+ def render(self) -> str:
172
+ return "None"
173
+
174
+ @property
175
+ def is_none(self) -> bool:
176
+ return True
177
+
178
+
179
+ @dataclass(frozen=True, slots=True)
180
+ class TSub(TypeExpr):
181
+ base: TypeExpr
182
+ args: tuple[TypeExpr, ...]
183
+
184
+ def static(self) -> TypeExpr:
185
+ return TSub(self.base, tuple(a.static() for a in self.args))
186
+
187
+ def to_ast(self, imports: Imports) -> ast.expr:
188
+ args = [a.to_ast(imports) for a in self.args]
189
+ slice_: ast.expr = args[0] if len(args) == 1 else ast.Tuple(args)
190
+ return ast.Subscript(self.base.to_ast(imports), slice_)
191
+
192
+ def render(self) -> str:
193
+ return f"{self.base.render()}[{', '.join(a.render() for a in self.args)}]"
194
+
195
+
196
+ _NOT_GIVEN: Final = TName("NotGiven", "spec2py_runtime")
197
+
198
+
199
+ @dataclass(frozen=True, slots=True)
200
+ class TUnion(TypeExpr):
201
+ members: tuple[TypeExpr, ...]
202
+
203
+ @staticmethod
204
+ def of(*members: TypeExpr) -> TypeExpr:
205
+ flat: list[TypeExpr] = []
206
+ literal_values: list[Any] = []
207
+ for m in members:
208
+ for inner in m.members if isinstance(m, TUnion) else (m,):
209
+ if isinstance(inner, TLiteral):
210
+ # One Literal[...] reads better than a union of them.
211
+ if not literal_values:
212
+ flat.append(inner)
213
+ literal_values.extend(
214
+ v for v in inner.values if v not in literal_values
215
+ )
216
+ elif inner not in flat:
217
+ flat.append(inner)
218
+ if literal_values:
219
+ flat = [
220
+ TLiteral(tuple(literal_values)) if isinstance(m, TLiteral) else m
221
+ for m in flat
222
+ ]
223
+ # None and NotGiven go last, as people write them.
224
+ flat.sort(key=lambda t: 2 if t == _NOT_GIVEN else int(t.is_none))
225
+ return flat[0] if len(flat) == 1 else TUnion(tuple(flat))
226
+
227
+ def static(self) -> TypeExpr:
228
+ return TUnion.of(*(m.static() for m in self.members))
229
+
230
+ def to_ast(self, imports: Imports) -> ast.expr:
231
+ nodes = [m.to_ast(imports) for m in self.members]
232
+ out = nodes[0]
233
+ for node in nodes[1:]:
234
+ out = ast.BinOp(out, ast.BitOr(), node)
235
+ return out
236
+
237
+ def render(self) -> str:
238
+ return " | ".join(m.render() for m in self.members)
239
+
240
+
241
+ @dataclass(frozen=True, slots=True)
242
+ class TLiteral(TypeExpr):
243
+ values: tuple[Any, ...]
244
+
245
+ def to_ast(self, imports: Imports) -> ast.expr:
246
+ consts: list[ast.expr] = [ast.Constant(v) for v in self.values]
247
+ slice_ = consts[0] if len(consts) == 1 else ast.Tuple(consts)
248
+ return ast.Subscript(ast.Name(imports.name("typing", "Literal")), slice_)
249
+
250
+ def render(self) -> str:
251
+ return f"Literal[{', '.join(repr(v) for v in self.values)}]"
252
+
253
+
254
+ @dataclass(frozen=True, slots=True)
255
+ class TCall(TypeExpr):
256
+ """A call used as annotation metadata, e.g. ``Field(discriminator="type")``."""
257
+
258
+ func: TName
259
+ kwargs: tuple[tuple[str, Any], ...] = ()
260
+
261
+ def to_ast(self, imports: Imports) -> ast.expr:
262
+ return ast.Call(
263
+ self.func.to_ast(imports),
264
+ args=[],
265
+ keywords=[ast.keyword(k, ast.Constant(v)) for k, v in self.kwargs],
266
+ )
267
+
268
+ def render(self) -> str:
269
+ args = ", ".join(f"{k}={v!r}" for k, v in self.kwargs)
270
+ return f"{self.func.render()}({args})"
271
+
272
+
273
+ @dataclass(frozen=True, slots=True)
274
+ class TAnnotated(TypeExpr):
275
+ inner: TypeExpr
276
+ metadata: tuple[TypeExpr, ...] = field(default=())
277
+
278
+ def to_ast(self, imports: Imports) -> ast.expr:
279
+ elts = [self.inner.to_ast(imports), *(m.to_ast(imports) for m in self.metadata)]
280
+ return ast.Subscript(
281
+ ast.Name(imports.name("typing", "Annotated")), ast.Tuple(elts)
282
+ )
283
+
284
+ def static(self) -> TypeExpr:
285
+ return self.inner.static()
286
+
287
+ def render(self) -> str:
288
+ meta = ", ".join(m.render() for m in self.metadata)
289
+ return f"Annotated[{self.inner.render()}, {meta}]"
290
+
291
+
292
+ # -- AST helpers -----------------------------------------------------------------
293
+
294
+
295
+ def docstring(*paragraphs: str | None, indent: int = 4, width: int = 80) -> str | None:
296
+ """Join and wrap paragraphs into docstring text (``None`` if all empty).
297
+
298
+ ``indent`` is the column the docstring sits at, so continuation lines and the
299
+ closing quotes line up once unparsed.
300
+ """
301
+ out: list[str] = []
302
+ for para in paragraphs:
303
+ if not para or not para.strip():
304
+ continue
305
+ for block in para.strip().split("\n\n"):
306
+ lines = block.splitlines()
307
+ if any(
308
+ line.startswith((" ", "- ", "* ", "|", "```")) for line in lines
309
+ ) or (len(lines) > 1 and all(len(line) < 60 for line in lines)):
310
+ out.append("\n".join(line.rstrip() for line in lines))
311
+ else:
312
+ out.append(
313
+ textwrap.fill(
314
+ " ".join(line.strip() for line in lines), width=width - indent
315
+ )
316
+ )
317
+ if not out:
318
+ return None
319
+ text = "\n\n".join(out)
320
+ if "\n" not in text:
321
+ return text
322
+ pad = " " * indent
323
+ lines = text.split("\n")
324
+ return (
325
+ "\n".join([lines[0], *(pad + line if line else line for line in lines[1:])])
326
+ + "\n"
327
+ + pad
328
+ )
329
+
330
+
331
+ def doc_expr(text: str) -> ast.Expr:
332
+ return ast.Expr(ast.Constant(text))
333
+
334
+
335
+ class _Unparser(_StdUnparser): # type: ignore[misc]
336
+ """Renders attribute docstrings (string statements after fields) triple-quoted."""
337
+
338
+ def visit_Expr(self, node: ast.Expr) -> None:
339
+ value = node.value
340
+ if isinstance(value, ast.Constant) and isinstance(value.value, str):
341
+ self._write_docstring(value)
342
+ return
343
+ super().visit_Expr(node)
344
+
345
+
346
+ def unparse(module: ast.Module) -> str:
347
+ ast.fix_missing_locations(module)
348
+ return str(_Unparser().visit(module))
349
+
350
+
351
+ def call(func: ast.expr | str, *args: ast.expr, **kwargs: ast.expr) -> ast.Call:
352
+ f = ast.Name(func) if isinstance(func, str) else func
353
+ return ast.Call(f, list(args), [ast.keyword(k, v) for k, v in kwargs.items()])
354
+
355
+
356
+ def attr(*parts: str) -> ast.expr:
357
+ node: ast.expr = ast.Name(parts[0])
358
+ for part in parts[1:]:
359
+ node = ast.Attribute(node, part)
360
+ return node
361
+
362
+
363
+ def const(value: Any) -> ast.expr:
364
+ if isinstance(value, dict):
365
+ return ast.Dict([const(k) for k in value], [const(v) for v in value.values()])
366
+ if isinstance(value, list | tuple):
367
+ return ast.List([const(v) for v in value])
368
+ return ast.Constant(value)
369
+
370
+
371
+ def arg(name: str, annotation: ast.expr | None = None) -> ast.arg:
372
+ return ast.arg(name, annotation)