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/__init__.py +17 -0
- spec2py/_version.py +24 -0
- spec2py/build_ir.py +637 -0
- spec2py/cli.py +351 -0
- spec2py/config.py +199 -0
- spec2py/emit/client.py +435 -0
- spec2py/emit/models.py +239 -0
- spec2py/emit/notes.py +65 -0
- spec2py/emit/package.py +319 -0
- spec2py/emit/pyast.py +372 -0
- spec2py/emit/resources.py +425 -0
- spec2py/emit/unasync.py +113 -0
- spec2py/ir.py +229 -0
- spec2py/jsonpath.py +456 -0
- spec2py/lint.py +316 -0
- spec2py/loader.py +136 -0
- spec2py/naming.py +96 -0
- spec2py/normalize/__init__.py +35 -0
- spec2py/normalize/refs.py +205 -0
- spec2py/normalize/swagger2.py +306 -0
- spec2py/normalize/upgrade.py +76 -0
- spec2py/overlay.py +106 -0
- spec2py/pipeline.py +82 -0
- spec2py/plan.py +1654 -0
- spec2py/py.typed +0 -0
- spec2py/score.py +73 -0
- spec2py/surface.py +214 -0
- spec2py-0.1.0.dist-info/METADATA +228 -0
- spec2py-0.1.0.dist-info/RECORD +32 -0
- spec2py-0.1.0.dist-info/WHEEL +4 -0
- spec2py-0.1.0.dist-info/entry_points.txt +2 -0
- spec2py-0.1.0.dist-info/licenses/LICENSE +21 -0
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)
|