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/client.py
ADDED
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
"""Emit ``_client.py``: the client classes, with resources as attributes."""
|
|
2
|
+
|
|
3
|
+
import ast
|
|
4
|
+
|
|
5
|
+
from ..loader import is_url
|
|
6
|
+
from ..plan import RUNTIME, PAuth, Plan, PResource
|
|
7
|
+
from .pyast import (
|
|
8
|
+
Imports,
|
|
9
|
+
TName,
|
|
10
|
+
TNone,
|
|
11
|
+
TSub,
|
|
12
|
+
TUnion,
|
|
13
|
+
arg,
|
|
14
|
+
attr,
|
|
15
|
+
call,
|
|
16
|
+
const,
|
|
17
|
+
doc_expr,
|
|
18
|
+
docstring,
|
|
19
|
+
)
|
|
20
|
+
from .resources import twin_names
|
|
21
|
+
from .unasync import RUNTIME_RENAMES, twin_module
|
|
22
|
+
|
|
23
|
+
__all__ = ["emit_client"]
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class _ClientEmitter:
|
|
27
|
+
def __init__(self, plan: Plan) -> None:
|
|
28
|
+
self.plan = plan
|
|
29
|
+
self.client = plan.client
|
|
30
|
+
self.renames = twin_names(self.client.class_name)
|
|
31
|
+
for r in plan.resources:
|
|
32
|
+
self.renames.update(twin_names(r.class_name))
|
|
33
|
+
self.custom_locals: dict[str, str] = {}
|
|
34
|
+
self.imports = Imports(
|
|
35
|
+
here="_client",
|
|
36
|
+
reserved=[*self.renames, *self.renames.values()],
|
|
37
|
+
)
|
|
38
|
+
self.imports.preassign(RUNTIME, *RUNTIME_RENAMES.values(), "AsyncAPIClient")
|
|
39
|
+
|
|
40
|
+
def rt(self, name: str) -> ast.expr:
|
|
41
|
+
return ast.Name(self.imports.name(RUNTIME, name))
|
|
42
|
+
|
|
43
|
+
def resource_import(self, r: PResource, *, raw: bool = False) -> None:
|
|
44
|
+
module = f".resources.{r.attr}"
|
|
45
|
+
names = twin_names(r.class_name)
|
|
46
|
+
for async_name, sync_name in names.items():
|
|
47
|
+
if raw == async_name.endswith("WithRawResponse"):
|
|
48
|
+
self.imports.preassign(module, async_name, sync_name)
|
|
49
|
+
self.imports.name(module, async_name)
|
|
50
|
+
self.imports.name(module, sync_name)
|
|
51
|
+
if r.custom and not raw:
|
|
52
|
+
# The user's subclass usually reuses the generated class's name, so
|
|
53
|
+
# it's imported under a clash-safe local name.
|
|
54
|
+
module = "._custom." + r.custom[0].removeprefix("_custom.").removeprefix(
|
|
55
|
+
"."
|
|
56
|
+
)
|
|
57
|
+
async_local = self.imports.name(module, f"Async{r.custom[1]}")
|
|
58
|
+
sync_local = self.imports.name(module, r.custom[1])
|
|
59
|
+
self.renames[async_local] = sync_local
|
|
60
|
+
self.custom_locals[r.attr] = async_local
|
|
61
|
+
|
|
62
|
+
def auth_statements(self) -> list[ast.stmt]:
|
|
63
|
+
"""Read credentials (argument, then environment) and build ``auth``."""
|
|
64
|
+
out: list[ast.stmt] = []
|
|
65
|
+
for auth in self.client.auth:
|
|
66
|
+
for py, env in auth.params:
|
|
67
|
+
out.append(
|
|
68
|
+
ast.Assign(
|
|
69
|
+
[ast.Attribute(ast.Name("self"), py)],
|
|
70
|
+
ast.IfExp(
|
|
71
|
+
ast.Compare(ast.Name(py), [ast.IsNot()], [const(None)]),
|
|
72
|
+
ast.Name(py),
|
|
73
|
+
call(
|
|
74
|
+
attr(self.imports.module("os"), "environ", "get"),
|
|
75
|
+
const(env),
|
|
76
|
+
),
|
|
77
|
+
),
|
|
78
|
+
)
|
|
79
|
+
)
|
|
80
|
+
if not self.client.auth:
|
|
81
|
+
return out
|
|
82
|
+
auths_ann = ast.Subscript(
|
|
83
|
+
ast.Name("list"),
|
|
84
|
+
ast.Attribute(ast.Name(self.imports.module("httpx2")), "Auth"),
|
|
85
|
+
)
|
|
86
|
+
build: list[ast.stmt] = [
|
|
87
|
+
ast.AnnAssign(ast.Name("auths"), auths_ann, ast.List([]), simple=1)
|
|
88
|
+
]
|
|
89
|
+
for auth in self.client.auth:
|
|
90
|
+
build.append(self.auth_append(auth))
|
|
91
|
+
build.append(
|
|
92
|
+
ast.Assign(
|
|
93
|
+
[ast.Name("auth")],
|
|
94
|
+
ast.IfExp(
|
|
95
|
+
ast.Compare(call("len", ast.Name("auths")), [ast.Eq()], [const(1)]),
|
|
96
|
+
ast.Subscript(ast.Name("auths"), const(0)),
|
|
97
|
+
ast.IfExp(
|
|
98
|
+
ast.Name("auths"),
|
|
99
|
+
call(self.rt("MultiAuth"), ast.Name("auths")),
|
|
100
|
+
const(None),
|
|
101
|
+
),
|
|
102
|
+
),
|
|
103
|
+
)
|
|
104
|
+
)
|
|
105
|
+
out.append(
|
|
106
|
+
ast.If(ast.Compare(ast.Name("auth"), [ast.Is()], [const(None)]), build, [])
|
|
107
|
+
)
|
|
108
|
+
return out
|
|
109
|
+
|
|
110
|
+
def auth_append(self, auth: PAuth) -> ast.stmt:
|
|
111
|
+
attrs = [ast.Attribute(ast.Name("self"), py) for py, _ in auth.params]
|
|
112
|
+
conds: list[ast.expr] = [
|
|
113
|
+
ast.Compare(a, [ast.IsNot()], [const(None)]) for a in attrs
|
|
114
|
+
]
|
|
115
|
+
test: ast.expr = conds[0] if len(conds) == 1 else ast.BoolOp(ast.And(), conds)
|
|
116
|
+
match auth.kind:
|
|
117
|
+
case "api_key":
|
|
118
|
+
value = call(
|
|
119
|
+
self.rt("ApiKeyAuth"),
|
|
120
|
+
attrs[0],
|
|
121
|
+
name=const(auth.parameter_name or "X-API-Key"),
|
|
122
|
+
location=const(auth.location or "header"),
|
|
123
|
+
)
|
|
124
|
+
case "bearer":
|
|
125
|
+
value = call(self.rt("BearerAuth"), attrs[0])
|
|
126
|
+
case "basic":
|
|
127
|
+
value = call(self.rt("BasicAuth"), attrs[0], attrs[1])
|
|
128
|
+
case "oauth2":
|
|
129
|
+
token_url = auth.token_url or "/oauth/token"
|
|
130
|
+
token_expr: ast.expr = const(token_url)
|
|
131
|
+
if not is_url(token_url):
|
|
132
|
+
token_expr = call(
|
|
133
|
+
"str",
|
|
134
|
+
call(
|
|
135
|
+
ast.Attribute(
|
|
136
|
+
call(
|
|
137
|
+
ast.Attribute(
|
|
138
|
+
ast.Name(self.imports.module("httpx2")), "URL"
|
|
139
|
+
),
|
|
140
|
+
ast.Name("resolved_base_url"),
|
|
141
|
+
),
|
|
142
|
+
"join",
|
|
143
|
+
),
|
|
144
|
+
const(token_url),
|
|
145
|
+
),
|
|
146
|
+
)
|
|
147
|
+
value = call(
|
|
148
|
+
self.rt("OAuth2ClientCredentials"),
|
|
149
|
+
token_url=token_expr,
|
|
150
|
+
client_id=attrs[0],
|
|
151
|
+
client_secret=attrs[1],
|
|
152
|
+
scopes=ast.Tuple([const(s) for s in auth.scopes]),
|
|
153
|
+
)
|
|
154
|
+
append = ast.Expr(call(ast.Attribute(ast.Name("auths"), "append"), value))
|
|
155
|
+
return ast.If(test, [append], [])
|
|
156
|
+
|
|
157
|
+
def init(self) -> ast.AsyncFunctionDef | ast.FunctionDef:
|
|
158
|
+
c = self.client
|
|
159
|
+
kwonly: list[ast.arg] = []
|
|
160
|
+
defaults: list[ast.expr | None] = []
|
|
161
|
+
str_or_none = TUnion.of(TName("str"), TNone())
|
|
162
|
+
|
|
163
|
+
def add(name: str, ann: ast.expr, default: ast.expr) -> None:
|
|
164
|
+
kwonly.append(arg(name, ann))
|
|
165
|
+
defaults.append(default)
|
|
166
|
+
|
|
167
|
+
for auth in c.auth:
|
|
168
|
+
for py, _ in auth.params:
|
|
169
|
+
add(py, str_or_none.to_ast(self.imports), const(None))
|
|
170
|
+
httpx = self.imports.module("httpx2")
|
|
171
|
+
add("base_url", str_or_none.to_ast(self.imports), const(None))
|
|
172
|
+
add(
|
|
173
|
+
"auth",
|
|
174
|
+
ast.BinOp(ast.Attribute(ast.Name(httpx), "Auth"), ast.BitOr(), const(None)),
|
|
175
|
+
const(None),
|
|
176
|
+
)
|
|
177
|
+
add(
|
|
178
|
+
"timeout",
|
|
179
|
+
ast.Name(self.imports.name(RUNTIME, "TimeoutTypes")),
|
|
180
|
+
self.rt("DEFAULT_TIMEOUT"),
|
|
181
|
+
)
|
|
182
|
+
add("max_retries", ast.Name("int"), self.rt("DEFAULT_MAX_RETRIES"))
|
|
183
|
+
|
|
184
|
+
def mapping(value: str) -> ast.expr:
|
|
185
|
+
mapping_type = TSub(
|
|
186
|
+
TName("Mapping", "collections.abc"), (TName("str"), TName(value))
|
|
187
|
+
)
|
|
188
|
+
return TUnion.of(mapping_type, TNone()).to_ast(self.imports)
|
|
189
|
+
|
|
190
|
+
add("default_headers", mapping("str"), const(None))
|
|
191
|
+
add("default_query", mapping("object"), const(None))
|
|
192
|
+
add(
|
|
193
|
+
"hooks",
|
|
194
|
+
TUnion.of(TName("Hooks", RUNTIME), TNone()).to_ast(self.imports),
|
|
195
|
+
const(None),
|
|
196
|
+
)
|
|
197
|
+
add("strict_response_validation", ast.Name("bool"), const(True))
|
|
198
|
+
add(
|
|
199
|
+
"trusted_pagination_origins",
|
|
200
|
+
TSub(TName("Collection", "collections.abc"), (TName("str"),)).to_ast(
|
|
201
|
+
self.imports
|
|
202
|
+
),
|
|
203
|
+
ast.Tuple([], ast.Load()),
|
|
204
|
+
)
|
|
205
|
+
add(
|
|
206
|
+
"http_client",
|
|
207
|
+
ast.BinOp(
|
|
208
|
+
ast.Attribute(ast.Name(httpx), "AsyncClient"), ast.BitOr(), const(None)
|
|
209
|
+
),
|
|
210
|
+
const(None),
|
|
211
|
+
)
|
|
212
|
+
add(
|
|
213
|
+
"transport",
|
|
214
|
+
ast.BinOp(
|
|
215
|
+
ast.Attribute(ast.Name(httpx), "AsyncBaseTransport"),
|
|
216
|
+
ast.BitOr(),
|
|
217
|
+
const(None),
|
|
218
|
+
),
|
|
219
|
+
const(None),
|
|
220
|
+
)
|
|
221
|
+
|
|
222
|
+
env_base = f"{c.env_prefix}_BASE_URL"
|
|
223
|
+
environ_get = call(
|
|
224
|
+
attr(self.imports.module("os"), "environ", "get"),
|
|
225
|
+
const(env_base),
|
|
226
|
+
)
|
|
227
|
+
base_value: ast.expr = ast.BoolOp(ast.Or(), [ast.Name("base_url"), environ_get])
|
|
228
|
+
if c.base_url:
|
|
229
|
+
base_value.values.append(const(c.base_url)) # type: ignore[attr-defined]
|
|
230
|
+
body: list[ast.stmt] = []
|
|
231
|
+
arg_docs = [
|
|
232
|
+
*(
|
|
233
|
+
f"{py}: Defaults to the ``{env}`` environment variable."
|
|
234
|
+
for a in c.auth
|
|
235
|
+
for py, env in a.params
|
|
236
|
+
),
|
|
237
|
+
f"base_url: Defaults to ``{env_base}``, then ``{c.base_url}``."
|
|
238
|
+
if c.base_url
|
|
239
|
+
else f"base_url: Required; defaults to ``{env_base}``.",
|
|
240
|
+
"auth: A custom ``httpx2.Auth``; overrides the credentials above.",
|
|
241
|
+
"timeout: Seconds (or an ``httpx2.Timeout``) per request.",
|
|
242
|
+
"max_retries: Retries for connection errors, 408/409/429 and 5xx.",
|
|
243
|
+
"hooks: Request/response middleware (logging, signing, test doubles).",
|
|
244
|
+
"trusted_pagination_origins: Other origins (``https://host[:port]``) "
|
|
245
|
+
"that next-page URLs may point at; they receive this client's "
|
|
246
|
+
"credentials.",
|
|
247
|
+
"http_client: Bring your own ``httpx2`` client (proxies, mTLS, pooling).",
|
|
248
|
+
"transport: A custom transport, e.g. ``httpx2.MockTransport`` in tests.",
|
|
249
|
+
]
|
|
250
|
+
body.append(
|
|
251
|
+
doc_expr(
|
|
252
|
+
docstring(
|
|
253
|
+
f"Create a client for the {c.api_name}.",
|
|
254
|
+
"Args:\n" + "\n".join(" " + d for d in arg_docs),
|
|
255
|
+
indent=8,
|
|
256
|
+
)
|
|
257
|
+
or ""
|
|
258
|
+
)
|
|
259
|
+
)
|
|
260
|
+
body.append(ast.Assign([ast.Name("resolved_base_url")], base_value))
|
|
261
|
+
if not c.base_url:
|
|
262
|
+
body.append(
|
|
263
|
+
ast.If(
|
|
264
|
+
ast.UnaryOp(ast.Not(), ast.Name("resolved_base_url")),
|
|
265
|
+
[
|
|
266
|
+
ast.Raise(
|
|
267
|
+
call(
|
|
268
|
+
"ValueError",
|
|
269
|
+
const(f"base_url is required (or set {env_base})"),
|
|
270
|
+
),
|
|
271
|
+
None,
|
|
272
|
+
)
|
|
273
|
+
],
|
|
274
|
+
[],
|
|
275
|
+
)
|
|
276
|
+
)
|
|
277
|
+
body.extend(self.auth_statements())
|
|
278
|
+
super_kwargs: dict[str, ast.expr] = {
|
|
279
|
+
"base_url": ast.Name("resolved_base_url"),
|
|
280
|
+
"auth": ast.Name("auth"),
|
|
281
|
+
"timeout": ast.Name("timeout"),
|
|
282
|
+
"max_retries": ast.Name("max_retries"),
|
|
283
|
+
"default_headers": ast.Name("default_headers"),
|
|
284
|
+
"default_query": ast.Name("default_query"),
|
|
285
|
+
"hooks": ast.Name("hooks"),
|
|
286
|
+
"strict_response_validation": ast.Name("strict_response_validation"),
|
|
287
|
+
"trusted_pagination_origins": ast.Name("trusted_pagination_origins"),
|
|
288
|
+
"http_client": ast.Name("http_client"),
|
|
289
|
+
"transport": ast.Name("transport"),
|
|
290
|
+
}
|
|
291
|
+
if c.idempotency_header:
|
|
292
|
+
super_kwargs["idempotency_header"] = const(c.idempotency_header)
|
|
293
|
+
body.append(
|
|
294
|
+
ast.Expr(call(ast.Attribute(call("super"), "__init__"), **super_kwargs))
|
|
295
|
+
)
|
|
296
|
+
return ast.FunctionDef(
|
|
297
|
+
name="__init__",
|
|
298
|
+
args=ast.arguments(
|
|
299
|
+
posonlyargs=[],
|
|
300
|
+
args=[arg("self")],
|
|
301
|
+
vararg=None,
|
|
302
|
+
kwonlyargs=kwonly,
|
|
303
|
+
kw_defaults=defaults,
|
|
304
|
+
kwarg=None,
|
|
305
|
+
defaults=[],
|
|
306
|
+
),
|
|
307
|
+
body=body,
|
|
308
|
+
decorator_list=[],
|
|
309
|
+
returns=const(None),
|
|
310
|
+
type_params=[],
|
|
311
|
+
)
|
|
312
|
+
|
|
313
|
+
def cached(
|
|
314
|
+
self, name: str, returns: ast.expr, value: ast.expr, doc: str | None = None
|
|
315
|
+
) -> ast.FunctionDef:
|
|
316
|
+
body: list[ast.stmt] = [doc_expr(doc)] if doc else []
|
|
317
|
+
body.append(ast.Return(value))
|
|
318
|
+
return ast.FunctionDef(
|
|
319
|
+
name=name,
|
|
320
|
+
args=ast.arguments(
|
|
321
|
+
posonlyargs=[],
|
|
322
|
+
args=[arg("self")],
|
|
323
|
+
vararg=None,
|
|
324
|
+
kwonlyargs=[],
|
|
325
|
+
kw_defaults=[],
|
|
326
|
+
kwarg=None,
|
|
327
|
+
defaults=[],
|
|
328
|
+
),
|
|
329
|
+
body=body,
|
|
330
|
+
decorator_list=[
|
|
331
|
+
ast.Name(self.imports.name("functools", "cached_property"))
|
|
332
|
+
],
|
|
333
|
+
returns=returns,
|
|
334
|
+
type_params=[],
|
|
335
|
+
)
|
|
336
|
+
|
|
337
|
+
def client_class(self) -> ast.ClassDef:
|
|
338
|
+
c = self.client
|
|
339
|
+
name = f"Async{c.class_name}"
|
|
340
|
+
body: list[ast.stmt] = []
|
|
341
|
+
doc = docstring(
|
|
342
|
+
f"Client for the {c.api_name} (version {c.version}).", c.description
|
|
343
|
+
)
|
|
344
|
+
if doc:
|
|
345
|
+
body.append(doc_expr(doc))
|
|
346
|
+
body.append(ast.Assign([ast.Name("_package")], const(c.package)))
|
|
347
|
+
body.append(
|
|
348
|
+
ast.Assign(
|
|
349
|
+
[ast.Name("_version")],
|
|
350
|
+
ast.Name(self.imports.name("._version", "__version__")),
|
|
351
|
+
)
|
|
352
|
+
)
|
|
353
|
+
body.append(self.init())
|
|
354
|
+
for r in self.plan.resources:
|
|
355
|
+
self.resource_import(r)
|
|
356
|
+
klass = self.custom_locals.get(r.attr, f"Async{r.class_name}")
|
|
357
|
+
body.append(
|
|
358
|
+
self.cached(r.attr, ast.Name(klass), call(klass, ast.Name("self")))
|
|
359
|
+
)
|
|
360
|
+
raw = f"Async{c.class_name}WithRawResponse"
|
|
361
|
+
body.append(
|
|
362
|
+
self.cached(
|
|
363
|
+
"with_raw_response",
|
|
364
|
+
ast.Name(raw),
|
|
365
|
+
call(raw, ast.Name("self")),
|
|
366
|
+
"Same resources, but methods return ``APIResponse`` (status, headers, ``parse()``).",
|
|
367
|
+
)
|
|
368
|
+
)
|
|
369
|
+
return ast.ClassDef(
|
|
370
|
+
name=name,
|
|
371
|
+
bases=[self.rt("AsyncAPIClient")],
|
|
372
|
+
keywords=[],
|
|
373
|
+
body=body,
|
|
374
|
+
decorator_list=[],
|
|
375
|
+
type_params=[],
|
|
376
|
+
)
|
|
377
|
+
|
|
378
|
+
def raw_class(self) -> ast.ClassDef:
|
|
379
|
+
c = self.client
|
|
380
|
+
name = f"Async{c.class_name}WithRawResponse"
|
|
381
|
+
init = ast.FunctionDef(
|
|
382
|
+
name="__init__",
|
|
383
|
+
args=ast.arguments(
|
|
384
|
+
posonlyargs=[],
|
|
385
|
+
args=[arg("self"), arg("client", ast.Name(f"Async{c.class_name}"))],
|
|
386
|
+
vararg=None,
|
|
387
|
+
kwonlyargs=[],
|
|
388
|
+
kw_defaults=[],
|
|
389
|
+
kwarg=None,
|
|
390
|
+
defaults=[],
|
|
391
|
+
),
|
|
392
|
+
body=[
|
|
393
|
+
ast.Assign(
|
|
394
|
+
[ast.Attribute(ast.Name("self"), "_client")], ast.Name("client")
|
|
395
|
+
)
|
|
396
|
+
],
|
|
397
|
+
decorator_list=[],
|
|
398
|
+
returns=const(None),
|
|
399
|
+
type_params=[],
|
|
400
|
+
)
|
|
401
|
+
body: list[ast.stmt] = [init]
|
|
402
|
+
for r in self.plan.resources:
|
|
403
|
+
self.resource_import(r, raw=True)
|
|
404
|
+
klass = f"Async{r.class_name}WithRawResponse"
|
|
405
|
+
body.append(
|
|
406
|
+
self.cached(
|
|
407
|
+
r.attr,
|
|
408
|
+
ast.Name(klass),
|
|
409
|
+
call(
|
|
410
|
+
klass,
|
|
411
|
+
attr("self", "_client", r.attr),
|
|
412
|
+
),
|
|
413
|
+
)
|
|
414
|
+
)
|
|
415
|
+
return ast.ClassDef(
|
|
416
|
+
name=name,
|
|
417
|
+
bases=[],
|
|
418
|
+
keywords=[],
|
|
419
|
+
body=body,
|
|
420
|
+
decorator_list=[],
|
|
421
|
+
type_params=[],
|
|
422
|
+
)
|
|
423
|
+
|
|
424
|
+
def module(self) -> ast.Module:
|
|
425
|
+
return twin_module(
|
|
426
|
+
f"Clients for the {self.client.api_name}.",
|
|
427
|
+
self.imports,
|
|
428
|
+
self.renames,
|
|
429
|
+
self.client_class,
|
|
430
|
+
self.raw_class,
|
|
431
|
+
)
|
|
432
|
+
|
|
433
|
+
|
|
434
|
+
def emit_client(plan: Plan) -> ast.Module:
|
|
435
|
+
return _ClientEmitter(plan).module()
|
spec2py/emit/models.py
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
"""Emit ``models.py``: Pydantic models and type aliases."""
|
|
2
|
+
|
|
3
|
+
import ast
|
|
4
|
+
import builtins
|
|
5
|
+
|
|
6
|
+
from ..naming import camel_words
|
|
7
|
+
from ..plan import MISSING, RUNTIME, PAlias, PField, Plan, PModel
|
|
8
|
+
from .pyast import MODELS, Imports, TName, call, const, doc_expr, docstring
|
|
9
|
+
|
|
10
|
+
__all__ = ["emit_models"]
|
|
11
|
+
|
|
12
|
+
_BUILTINS = frozenset(dir(builtins))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _field_value(f: PField, imports: Imports) -> ast.expr | None:
|
|
16
|
+
kwargs: dict[str, ast.expr] = {}
|
|
17
|
+
if f.alias:
|
|
18
|
+
kwargs["alias"] = const(f.alias)
|
|
19
|
+
if f.deprecated:
|
|
20
|
+
kwargs["deprecated"] = const(True)
|
|
21
|
+
if not kwargs:
|
|
22
|
+
return None if f.default is MISSING else const(f.default)
|
|
23
|
+
if f.default is not MISSING:
|
|
24
|
+
kwargs = {"default": const(f.default), **kwargs}
|
|
25
|
+
return call(ast.Name(imports.name("pydantic", "Field")), **kwargs)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _model(model: PModel, imports: Imports) -> ast.ClassDef:
|
|
29
|
+
# Under PEP 649 a field named like a builtin (``object``, ``type``) shadows it
|
|
30
|
+
# in every annotation of the class, so those annotations say ``builtins.x``.
|
|
31
|
+
imports.shadowed = {f.py_name for f in model.fields} & _BUILTINS
|
|
32
|
+
try:
|
|
33
|
+
return _model_body(model, imports)
|
|
34
|
+
finally:
|
|
35
|
+
imports.shadowed = set()
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _model_body(model: PModel, imports: Imports) -> ast.ClassDef:
|
|
39
|
+
body: list[ast.stmt] = []
|
|
40
|
+
extra = None
|
|
41
|
+
if model.extra is not None:
|
|
42
|
+
# A typed ``__pydantic_extra__`` would be an incompatible override for
|
|
43
|
+
# pyright and ty, so the value type is documented instead.
|
|
44
|
+
extra = f"Additional properties are kept in ``model_extra`` (values: ``{model.extra.render()}``)."
|
|
45
|
+
if text := docstring(model.doc, "Deprecated." if model.deprecated else None, extra):
|
|
46
|
+
body.append(doc_expr(text))
|
|
47
|
+
for f in model.fields:
|
|
48
|
+
body.append(
|
|
49
|
+
ast.AnnAssign(
|
|
50
|
+
target=ast.Name(f.py_name),
|
|
51
|
+
annotation=f.type.to_ast(imports),
|
|
52
|
+
value=_field_value(f, imports),
|
|
53
|
+
simple=1,
|
|
54
|
+
)
|
|
55
|
+
)
|
|
56
|
+
if text := docstring(f.doc):
|
|
57
|
+
body.append(doc_expr(text))
|
|
58
|
+
if not body:
|
|
59
|
+
body.append(ast.Pass())
|
|
60
|
+
bases = [TName(b, MODELS).to_ast(imports) for b in model.bases] or [
|
|
61
|
+
ast.Name(imports.name(RUNTIME, "BaseModel"))
|
|
62
|
+
]
|
|
63
|
+
return ast.ClassDef(
|
|
64
|
+
name=model.name,
|
|
65
|
+
bases=bases,
|
|
66
|
+
keywords=[],
|
|
67
|
+
body=body,
|
|
68
|
+
decorator_list=[],
|
|
69
|
+
type_params=[],
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _alias(alias: PAlias, imports: Imports) -> list[ast.stmt]:
|
|
74
|
+
out: list[ast.stmt] = [
|
|
75
|
+
ast.TypeAlias(
|
|
76
|
+
name=ast.Name(alias.name), type_params=[], value=alias.type.to_ast(imports)
|
|
77
|
+
)
|
|
78
|
+
]
|
|
79
|
+
if text := docstring(alias.doc, indent=0):
|
|
80
|
+
out.append(doc_expr(text))
|
|
81
|
+
return out
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
SPLIT_THRESHOLD = 400
|
|
85
|
+
"""Specs with more models than this get a ``models/`` package instead of one
|
|
86
|
+
module: type checkers (pyright in particular) stop resolving symbols in very
|
|
87
|
+
large files."""
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _module(decls: list[PModel | PAlias], imports: Imports) -> list[ast.stmt]:
|
|
91
|
+
body: list[ast.stmt] = []
|
|
92
|
+
for decl in decls:
|
|
93
|
+
if isinstance(decl, PModel):
|
|
94
|
+
body.append(_model(decl, imports))
|
|
95
|
+
else:
|
|
96
|
+
body.extend(_alias(decl, imports))
|
|
97
|
+
return body
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _field_names(decls: list[PModel | PAlias]) -> set[str]:
|
|
101
|
+
"""Field names shadow module names in their class's annotations (PEP 649), so
|
|
102
|
+
an import that collides with one (a field called ``datetime``) gets an alias."""
|
|
103
|
+
return {f.py_name for d in decls if isinstance(d, PModel) for f in d.fields}
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _link(imports: Imports) -> ast.stmt:
|
|
107
|
+
return ast.Expr(
|
|
108
|
+
call(ast.Name(imports.name(RUNTIME, "link_models")), call("globals"))
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def emit_models(plan: Plan) -> dict[str, ast.Module]:
|
|
113
|
+
"""Build the models module (or package, for large specs), keyed by path."""
|
|
114
|
+
if len(plan.models) > SPLIT_THRESHOLD:
|
|
115
|
+
return _emit_split(plan)
|
|
116
|
+
names = [m.name for m in plan.models]
|
|
117
|
+
imports = Imports(
|
|
118
|
+
here=MODELS,
|
|
119
|
+
reserved=[*names, *_field_names(plan.models)],
|
|
120
|
+
)
|
|
121
|
+
body = _module(plan.models, imports)
|
|
122
|
+
header: list[ast.stmt] = [
|
|
123
|
+
doc_expr(f"Models for the {plan.client.api_name}."),
|
|
124
|
+
*imports.statements(),
|
|
125
|
+
ast.Assign([ast.Name("__all__")], ast.List([const(n) for n in sorted(names)])),
|
|
126
|
+
]
|
|
127
|
+
return {"models.py": ast.Module(body=[*header, *body], type_ignores=[])}
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
CHUNK_SIZE = 150
|
|
131
|
+
"""Most models per module before a group splits on its next name word."""
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def _chunk_layout(names: list[str]) -> dict[str, str]:
|
|
135
|
+
"""Group model names into modules, deterministically and diff-stably.
|
|
136
|
+
|
|
137
|
+
Models start grouped by first letter (``_w``). A group larger than
|
|
138
|
+
``CHUNK_SIZE`` gives each big name-prefix family its own module
|
|
139
|
+
(``_w_webhook``, then ``_w_webhook_issues`` if still too big); the
|
|
140
|
+
stragglers stay in the parent group. Adding a model only moves models
|
|
141
|
+
within its own family.
|
|
142
|
+
"""
|
|
143
|
+
layout: dict[str, str] = {}
|
|
144
|
+
|
|
145
|
+
def place(group: list[str], key: str, depth: int) -> None:
|
|
146
|
+
if len(group) <= CHUNK_SIZE:
|
|
147
|
+
layout.update(dict.fromkeys(group, key))
|
|
148
|
+
return
|
|
149
|
+
families: dict[str, list[str]] = {}
|
|
150
|
+
for name in group:
|
|
151
|
+
words = camel_words(name)
|
|
152
|
+
if len(words) >= depth:
|
|
153
|
+
families.setdefault("_".join(words[:depth]), []).append(name)
|
|
154
|
+
else:
|
|
155
|
+
layout[name] = key
|
|
156
|
+
for prefix, members in families.items():
|
|
157
|
+
if (len(members) >= CHUNK_SIZE // 3 and len(families) > 1) or depth == 1:
|
|
158
|
+
place(members, f"{key}_{prefix}" if depth > 1 else key, depth + 1)
|
|
159
|
+
else:
|
|
160
|
+
layout.update(dict.fromkeys(members, key))
|
|
161
|
+
|
|
162
|
+
letters: dict[str, list[str]] = {}
|
|
163
|
+
for name in names:
|
|
164
|
+
first = name[0].lower()
|
|
165
|
+
letters.setdefault(f"_{first}" if first.isalpha() else "_other", []).append(
|
|
166
|
+
name
|
|
167
|
+
)
|
|
168
|
+
for key, group in letters.items():
|
|
169
|
+
place(group, key, 1)
|
|
170
|
+
return layout
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _emit_split(plan: Plan) -> dict[str, ast.Module]:
|
|
174
|
+
"""Split models across modules without runtime import cycles.
|
|
175
|
+
|
|
176
|
+
``_bases`` holds every class another class inherits from (and its own
|
|
177
|
+
bases), so subclasses import their base eagerly from one place. Type aliases
|
|
178
|
+
live in ``_aliases``, which imports models eagerly because alias values are
|
|
179
|
+
evaluated lazily in that module's namespace. Every other cross-module
|
|
180
|
+
reference is a ``TYPE_CHECKING`` import; ``link_models`` makes those names
|
|
181
|
+
resolvable at runtime, and each model builds lazily on first use.
|
|
182
|
+
"""
|
|
183
|
+
by_name = {d.name: d for d in plan.models}
|
|
184
|
+
bases: set[str] = set()
|
|
185
|
+
pending = [b for d in plan.models if isinstance(d, PModel) for b in d.bases]
|
|
186
|
+
while pending:
|
|
187
|
+
name = pending.pop()
|
|
188
|
+
if name not in bases:
|
|
189
|
+
bases.add(name)
|
|
190
|
+
decl = by_name.get(name)
|
|
191
|
+
if isinstance(decl, PModel):
|
|
192
|
+
pending.extend(decl.bases)
|
|
193
|
+
layout = _chunk_layout(
|
|
194
|
+
[d.name for d in plan.models if isinstance(d, PModel) and d.name not in bases]
|
|
195
|
+
)
|
|
196
|
+
layout.update({d.name: "_aliases" for d in plan.models if isinstance(d, PAlias)})
|
|
197
|
+
layout.update({name: "_bases" for name in bases if name in by_name})
|
|
198
|
+
chunks: dict[str, list[PModel | PAlias]] = {}
|
|
199
|
+
for decl in plan.models:
|
|
200
|
+
chunks.setdefault(layout[decl.name], []).append(decl)
|
|
201
|
+
|
|
202
|
+
out: dict[str, ast.Module] = {}
|
|
203
|
+
for chunk, decls in sorted(chunks.items()):
|
|
204
|
+
own = [d.name for d in decls]
|
|
205
|
+
imports = Imports(
|
|
206
|
+
here=f"models.{chunk}",
|
|
207
|
+
reserved=[*own, *_field_names(decls)],
|
|
208
|
+
)
|
|
209
|
+
imports.model_modules = layout
|
|
210
|
+
body = _module(decls, imports)
|
|
211
|
+
if chunk != "_aliases":
|
|
212
|
+
eager = {b for d in decls if isinstance(d, PModel) for b in d.bases}
|
|
213
|
+
for (module, name), _ in imports.used():
|
|
214
|
+
if module.startswith(".") and name not in eager:
|
|
215
|
+
imports.deferred.add((module, name))
|
|
216
|
+
out[f"models/{chunk}.py"] = ast.Module(
|
|
217
|
+
body=[
|
|
218
|
+
doc_expr(
|
|
219
|
+
f"Models for the {plan.client.api_name} ({chunk.lstrip('_')})."
|
|
220
|
+
),
|
|
221
|
+
*imports.statements(),
|
|
222
|
+
ast.Assign(
|
|
223
|
+
[ast.Name("__all__")], ast.List([const(n) for n in sorted(own)])
|
|
224
|
+
),
|
|
225
|
+
*body,
|
|
226
|
+
],
|
|
227
|
+
type_ignores=[],
|
|
228
|
+
)
|
|
229
|
+
imports = Imports(here="models")
|
|
230
|
+
init: list[ast.stmt] = [doc_expr(f"Models for the {plan.client.api_name}.")]
|
|
231
|
+
for chunk, decls in sorted(chunks.items()):
|
|
232
|
+
init.append(ast.ImportFrom(chunk, [ast.alias(d.name) for d in decls], 1))
|
|
233
|
+
link = _link(imports)
|
|
234
|
+
init[1:1] = imports.statements()
|
|
235
|
+
names = sorted(by_name)
|
|
236
|
+
init.append(ast.Assign([ast.Name("__all__")], ast.List([const(n) for n in names])))
|
|
237
|
+
init.append(link)
|
|
238
|
+
out["models/__init__.py"] = ast.Module(body=init, type_ignores=[])
|
|
239
|
+
return out
|