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/lint.py
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
"""Explain what in a spec will generate poorly, ranked by impact on the output.
|
|
2
|
+
|
|
3
|
+
Every finding says what the generator will do about it. Mechanical problems
|
|
4
|
+
(missing operationIds, an obvious discriminator) can be fixed by a starter
|
|
5
|
+
Overlay that ``spec2py lint --fix-overlay`` writes.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import json
|
|
9
|
+
from collections import defaultdict
|
|
10
|
+
from collections.abc import Iterator
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from typing import Any, Literal
|
|
13
|
+
|
|
14
|
+
from .build_ir import media_rank
|
|
15
|
+
from .ir import API, Kind, Operation, Schema
|
|
16
|
+
from .naming import pascal, singular
|
|
17
|
+
|
|
18
|
+
__all__ = ["Finding", "LintReport", "lint"]
|
|
19
|
+
|
|
20
|
+
type Severity = Literal["error", "warning", "info"]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(slots=True)
|
|
24
|
+
class Finding:
|
|
25
|
+
code: str
|
|
26
|
+
severity: Severity
|
|
27
|
+
message: str
|
|
28
|
+
"""One line, with the affected count."""
|
|
29
|
+
consequence: str
|
|
30
|
+
locations: list[str] = field(default_factory=list[str])
|
|
31
|
+
fix: list[dict[str, Any]] = field(default_factory=list[dict[str, Any]])
|
|
32
|
+
"""Overlay actions that fix it, when the fix is mechanical."""
|
|
33
|
+
|
|
34
|
+
@property
|
|
35
|
+
def impact(self) -> int:
|
|
36
|
+
weight = {"error": 100, "warning": 10, "info": 1}[self.severity]
|
|
37
|
+
return weight * max(len(self.locations), 1)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(slots=True)
|
|
41
|
+
class LintReport:
|
|
42
|
+
findings: list[Finding]
|
|
43
|
+
|
|
44
|
+
def ranked(self) -> list[Finding]:
|
|
45
|
+
return sorted(self.findings, key=lambda f: (-f.impact, f.code))
|
|
46
|
+
|
|
47
|
+
def render(self, *, verbose: bool = False) -> str:
|
|
48
|
+
if not self.findings:
|
|
49
|
+
return "No issues found: this spec should generate cleanly."
|
|
50
|
+
lines: list[str] = []
|
|
51
|
+
for f in self.ranked():
|
|
52
|
+
lines.append(f"[{f.severity}] {f.code}: {f.message}")
|
|
53
|
+
lines.append(f" -> {f.consequence}")
|
|
54
|
+
shown = f.locations if verbose else f.locations[:5]
|
|
55
|
+
lines.extend(f" {loc}" for loc in shown)
|
|
56
|
+
if len(f.locations) > len(shown):
|
|
57
|
+
lines.append(
|
|
58
|
+
f" ... and {len(f.locations) - len(shown)} more (--verbose)"
|
|
59
|
+
)
|
|
60
|
+
fixable = sum(1 for f in self.findings if f.fix)
|
|
61
|
+
if fixable:
|
|
62
|
+
lines.append(
|
|
63
|
+
f"\n{fixable} finding(s) can be fixed mechanically: spec2py lint --fix-overlay fixes.yaml"
|
|
64
|
+
)
|
|
65
|
+
return "\n".join(lines)
|
|
66
|
+
|
|
67
|
+
def to_json(self) -> str:
|
|
68
|
+
return json.dumps(
|
|
69
|
+
[
|
|
70
|
+
{
|
|
71
|
+
"code": f.code,
|
|
72
|
+
"severity": f.severity,
|
|
73
|
+
"message": f.message,
|
|
74
|
+
"consequence": f.consequence,
|
|
75
|
+
"locations": f.locations,
|
|
76
|
+
}
|
|
77
|
+
for f in self.ranked()
|
|
78
|
+
],
|
|
79
|
+
indent=2,
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
def overlay(self, title: str) -> dict[str, Any]:
|
|
83
|
+
actions = [a for f in self.ranked() for a in f.fix]
|
|
84
|
+
return {
|
|
85
|
+
"overlay": "1.0.0",
|
|
86
|
+
"info": {"title": f"spec2py fixes for {title}", "version": "1.0.0"},
|
|
87
|
+
"actions": actions,
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
@property
|
|
91
|
+
def errors(self) -> list[Finding]:
|
|
92
|
+
return [f for f in self.findings if f.severity == "error"]
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _jsonpath_key(key: str) -> str:
|
|
96
|
+
return "'" + key.replace("\\", "\\\\").replace("'", "\\'") + "'"
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _derived_operation_id(op: Operation) -> str:
|
|
100
|
+
statics = [s for s in op.path.split("/") if s and not s.startswith("{")]
|
|
101
|
+
is_item = op.path.rstrip("/").endswith("}")
|
|
102
|
+
verb = {
|
|
103
|
+
("get", False): "list",
|
|
104
|
+
("get", True): "get",
|
|
105
|
+
("post", False): "create",
|
|
106
|
+
("put", True): "update",
|
|
107
|
+
("patch", True): "update",
|
|
108
|
+
("delete", True): "delete",
|
|
109
|
+
}.get((op.method, is_item), op.method)
|
|
110
|
+
nouns = statics[-1:] if statics else ["root"]
|
|
111
|
+
noun = pascal(nouns[0])
|
|
112
|
+
if verb in ("get", "update", "delete", "create"):
|
|
113
|
+
noun = pascal(singular(nouns[0]))
|
|
114
|
+
return verb + noun
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _schemas_in(api: API) -> Iterator[tuple[str, Schema]]:
|
|
118
|
+
def walk(where: str, s: Schema | None) -> Iterator[tuple[str, Schema]]:
|
|
119
|
+
if s is None:
|
|
120
|
+
return
|
|
121
|
+
yield where, s
|
|
122
|
+
for p in s.properties:
|
|
123
|
+
yield from walk(f"{where}.{p.name}", p.schema)
|
|
124
|
+
yield from walk(f"{where}[]", s.items)
|
|
125
|
+
yield from walk(f"{where}{{}}", s.additional)
|
|
126
|
+
for i, v in enumerate(s.variants):
|
|
127
|
+
yield from walk(f"{where}|{i}", v)
|
|
128
|
+
|
|
129
|
+
for name, s in api.schemas.items():
|
|
130
|
+
yield from walk(f"#/components/schemas/{name}", s)
|
|
131
|
+
for op in api.operations:
|
|
132
|
+
if op.request_body:
|
|
133
|
+
yield from walk(f"{op.key} requestBody", op.request_body.schema)
|
|
134
|
+
for r in op.responses:
|
|
135
|
+
yield from walk(f"{op.key} {r.status}", r.schema)
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def _common_tag(api: API, s: Schema) -> str | None:
|
|
139
|
+
"""A property every variant pins to one distinct const/enum value."""
|
|
140
|
+
candidates: dict[str, set[object]] = defaultdict(set)
|
|
141
|
+
for v in s.variants:
|
|
142
|
+
target = api.resolve(v)
|
|
143
|
+
if target.kind is not Kind.OBJECT:
|
|
144
|
+
return None
|
|
145
|
+
for p in target.properties:
|
|
146
|
+
ps = api.resolve(p.schema)
|
|
147
|
+
if ps.kind in (Kind.CONST, Kind.ENUM) and len(ps.values) == 1:
|
|
148
|
+
candidates[p.name].add(ps.values[0])
|
|
149
|
+
for name, values in sorted(candidates.items()):
|
|
150
|
+
if len(values) == len(s.variants):
|
|
151
|
+
return name
|
|
152
|
+
return None
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def lint(api: API) -> LintReport:
|
|
156
|
+
findings: dict[str, Finding] = {}
|
|
157
|
+
|
|
158
|
+
def add(
|
|
159
|
+
code: str,
|
|
160
|
+
severity: Severity,
|
|
161
|
+
message: str,
|
|
162
|
+
consequence: str,
|
|
163
|
+
location: str,
|
|
164
|
+
fix: dict[str, Any] | None = None,
|
|
165
|
+
) -> None:
|
|
166
|
+
f = findings.setdefault(code, Finding(code, severity, message, consequence))
|
|
167
|
+
if location not in f.locations:
|
|
168
|
+
f.locations.append(location)
|
|
169
|
+
if fix is not None:
|
|
170
|
+
f.fix.append(fix)
|
|
171
|
+
|
|
172
|
+
seen_ids: dict[str, str] = {}
|
|
173
|
+
for op in api.operations:
|
|
174
|
+
target = f"$.paths[{_jsonpath_key(op.path)}].{op.method}"
|
|
175
|
+
if not op.operation_id:
|
|
176
|
+
add(
|
|
177
|
+
"missing-operation-id",
|
|
178
|
+
"warning",
|
|
179
|
+
"operations have no operationId",
|
|
180
|
+
"method names are derived from the HTTP method and path",
|
|
181
|
+
op.key,
|
|
182
|
+
{
|
|
183
|
+
"target": target,
|
|
184
|
+
"update": {"operationId": _derived_operation_id(op)},
|
|
185
|
+
},
|
|
186
|
+
)
|
|
187
|
+
elif op.operation_id in seen_ids:
|
|
188
|
+
add(
|
|
189
|
+
"duplicate-operation-id",
|
|
190
|
+
"error",
|
|
191
|
+
"operationIds are not unique",
|
|
192
|
+
"later duplicates get a numeric suffix",
|
|
193
|
+
f"{op.key} (also {seen_ids[op.operation_id]})",
|
|
194
|
+
)
|
|
195
|
+
else:
|
|
196
|
+
seen_ids[op.operation_id] = op.key
|
|
197
|
+
if not op.tags:
|
|
198
|
+
add(
|
|
199
|
+
"missing-tags",
|
|
200
|
+
"info",
|
|
201
|
+
"operations have no tags",
|
|
202
|
+
"they are grouped into resources by their first path segment",
|
|
203
|
+
op.key,
|
|
204
|
+
)
|
|
205
|
+
success = [r for r in op.responses if r.is_success]
|
|
206
|
+
if not success:
|
|
207
|
+
add(
|
|
208
|
+
"no-success-response",
|
|
209
|
+
"warning",
|
|
210
|
+
"operations declare no 2xx response",
|
|
211
|
+
"their methods return None",
|
|
212
|
+
op.key,
|
|
213
|
+
)
|
|
214
|
+
elif any(r.media_type for r in success) and all(
|
|
215
|
+
r.schema is None and r.media_type and media_rank(r.media_type) <= 1
|
|
216
|
+
for r in success
|
|
217
|
+
if r.media_type
|
|
218
|
+
):
|
|
219
|
+
add(
|
|
220
|
+
"untyped-response",
|
|
221
|
+
"warning",
|
|
222
|
+
"JSON responses have no schema",
|
|
223
|
+
"their methods return `object`",
|
|
224
|
+
op.key,
|
|
225
|
+
)
|
|
226
|
+
if not any(not r.is_success for r in op.responses):
|
|
227
|
+
add(
|
|
228
|
+
"no-error-responses",
|
|
229
|
+
"info",
|
|
230
|
+
"operations declare no error responses",
|
|
231
|
+
"errors raise typed exceptions, but bodies are not parsed into models",
|
|
232
|
+
op.key,
|
|
233
|
+
)
|
|
234
|
+
if (
|
|
235
|
+
op.request_body
|
|
236
|
+
and media_rank(op.request_body.media_type) <= 1
|
|
237
|
+
and op.request_body.schema.kind is Kind.ANY
|
|
238
|
+
):
|
|
239
|
+
add(
|
|
240
|
+
"untyped-request-body",
|
|
241
|
+
"warning",
|
|
242
|
+
"request bodies have no schema",
|
|
243
|
+
"the body is accepted as `object` without validation",
|
|
244
|
+
op.key,
|
|
245
|
+
)
|
|
246
|
+
for p in op.parameters:
|
|
247
|
+
if p.schema.lossy:
|
|
248
|
+
add(
|
|
249
|
+
"content-parameter",
|
|
250
|
+
"info",
|
|
251
|
+
"parameters use `content` instead of `schema`",
|
|
252
|
+
"they are sent as plain text",
|
|
253
|
+
f"{op.key} {p.name}",
|
|
254
|
+
)
|
|
255
|
+
|
|
256
|
+
inline_enums: dict[tuple[object, ...], list[str]] = defaultdict(list)
|
|
257
|
+
for where, s in _schemas_in(api):
|
|
258
|
+
if s.kind is Kind.ENUM and not (
|
|
259
|
+
where.startswith("#/components/schemas/") and "." not in where
|
|
260
|
+
):
|
|
261
|
+
inline_enums[tuple(s.values)].append(where)
|
|
262
|
+
if (
|
|
263
|
+
s.kind is Kind.UNION
|
|
264
|
+
and s.union_kind in ("oneOf", "anyOf")
|
|
265
|
+
and s.discriminator is None
|
|
266
|
+
):
|
|
267
|
+
models = [v for v in s.variants if api.resolve(v).kind is Kind.OBJECT]
|
|
268
|
+
if len(models) > 1:
|
|
269
|
+
tag = _common_tag(api, s)
|
|
270
|
+
fix = None
|
|
271
|
+
if (
|
|
272
|
+
tag
|
|
273
|
+
and where.startswith("#/components/schemas/")
|
|
274
|
+
and "." not in where
|
|
275
|
+
and "|" not in where
|
|
276
|
+
):
|
|
277
|
+
name = where.rsplit("/", 1)[-1]
|
|
278
|
+
fix = {
|
|
279
|
+
"target": f"$.components.schemas[{_jsonpath_key(name)}]",
|
|
280
|
+
"update": {"discriminator": {"propertyName": tag}},
|
|
281
|
+
}
|
|
282
|
+
add(
|
|
283
|
+
"union-without-discriminator",
|
|
284
|
+
"warning",
|
|
285
|
+
"unions of objects have no discriminator",
|
|
286
|
+
"pydantic tries each member in order (slower, and ambiguous payloads may pick the wrong model)",
|
|
287
|
+
where + (f" (could discriminate on `{tag}`)" if tag else ""),
|
|
288
|
+
fix,
|
|
289
|
+
)
|
|
290
|
+
for lossy in s.lossy:
|
|
291
|
+
code = "untyped-schema" if lossy == "untyped schema" else "lossy-mapping"
|
|
292
|
+
consequence = (
|
|
293
|
+
"typed as `object`; add a schema with an Overlay"
|
|
294
|
+
if code == "untyped-schema"
|
|
295
|
+
else lossy
|
|
296
|
+
)
|
|
297
|
+
add(
|
|
298
|
+
code,
|
|
299
|
+
"info",
|
|
300
|
+
"schemas map to Python lossily"
|
|
301
|
+
if code == "lossy-mapping"
|
|
302
|
+
else "schemas have no type",
|
|
303
|
+
consequence,
|
|
304
|
+
where,
|
|
305
|
+
)
|
|
306
|
+
for values, wheres in inline_enums.items():
|
|
307
|
+
if len(wheres) > 1:
|
|
308
|
+
add(
|
|
309
|
+
"repeated-inline-enum",
|
|
310
|
+
"info",
|
|
311
|
+
"identical inline enums are repeated",
|
|
312
|
+
"each gets its own type alias; a shared component would give one name",
|
|
313
|
+
f"{list(values)!r}: {', '.join(wheres[:3])}",
|
|
314
|
+
)
|
|
315
|
+
|
|
316
|
+
return LintReport(list(findings.values()))
|
spec2py/loader.py
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""Load stage: read a spec from a file, a URL or a FastAPI app, then apply overlays."""
|
|
2
|
+
|
|
3
|
+
import datetime
|
|
4
|
+
import importlib
|
|
5
|
+
import json
|
|
6
|
+
import pathlib
|
|
7
|
+
import re
|
|
8
|
+
import sys
|
|
9
|
+
from collections.abc import Sequence
|
|
10
|
+
from typing import Any, cast
|
|
11
|
+
|
|
12
|
+
import httpx2
|
|
13
|
+
import yaml
|
|
14
|
+
|
|
15
|
+
from .overlay import OverlayReport, apply_overlay
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"LoadError",
|
|
19
|
+
"is_app_reference",
|
|
20
|
+
"load_document",
|
|
21
|
+
"load_spec",
|
|
22
|
+
"parse_document",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
type JSON = Any
|
|
26
|
+
|
|
27
|
+
_APP_REF = re.compile(r"^[A-Za-z_][\w.]*:[A-Za-z_][\w.]*(\(\))?$")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class LoadError(ValueError):
|
|
31
|
+
pass
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def is_app_reference(source: str) -> bool:
|
|
35
|
+
"""``"myapp.main:app"`` (or ``"pkg.factory:create_app()"``) rather than a path or URL."""
|
|
36
|
+
return bool(_APP_REF.match(source)) and not pathlib.Path(source).exists()
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def is_url(source: str) -> bool:
|
|
40
|
+
return source.startswith(("http://", "https://"))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _plain(value: JSON) -> JSON:
|
|
44
|
+
"""YAML gives int keys (``200:``) and dates; OpenAPI wants strings."""
|
|
45
|
+
if isinstance(value, dict):
|
|
46
|
+
return {str(k): _plain(v) for k, v in cast(dict[Any, Any], value).items()}
|
|
47
|
+
if isinstance(value, list):
|
|
48
|
+
return [_plain(v) for v in cast(list[Any], value)]
|
|
49
|
+
if isinstance(value, datetime.date):
|
|
50
|
+
return value.isoformat()
|
|
51
|
+
return value
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def parse_document(text: str, name: str = "<spec>") -> JSON:
|
|
55
|
+
"""Parse JSON or YAML text."""
|
|
56
|
+
stripped = text.lstrip()
|
|
57
|
+
if stripped.startswith(("{", "[")):
|
|
58
|
+
try:
|
|
59
|
+
return json.loads(text)
|
|
60
|
+
except json.JSONDecodeError:
|
|
61
|
+
pass
|
|
62
|
+
loader = getattr(yaml, "CSafeLoader", yaml.SafeLoader)
|
|
63
|
+
try:
|
|
64
|
+
return _plain(yaml.load(text, Loader=loader))
|
|
65
|
+
except yaml.YAMLError as exc:
|
|
66
|
+
raise LoadError(f"{name}: not valid JSON or YAML: {exc}") from exc
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def fetch_text(url: str) -> str:
|
|
70
|
+
try:
|
|
71
|
+
response = httpx2.get(url, follow_redirects=True, timeout=60)
|
|
72
|
+
response.raise_for_status()
|
|
73
|
+
except httpx2.HTTPError as exc:
|
|
74
|
+
raise LoadError(f"could not fetch {url}: {exc}") from exc
|
|
75
|
+
return response.text
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def load_document(source: str) -> JSON:
|
|
79
|
+
"""Load a JSON/YAML document from a path or URL."""
|
|
80
|
+
if is_url(source):
|
|
81
|
+
return parse_document(fetch_text(source), source)
|
|
82
|
+
path = pathlib.Path(source)
|
|
83
|
+
if not path.is_file():
|
|
84
|
+
raise LoadError(f"spec not found: {source}")
|
|
85
|
+
return parse_document(path.read_text(encoding="utf-8"), source)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def load_fastapi_app(reference: str) -> JSON:
|
|
89
|
+
"""Import ``module:attr`` and return its ``openapi()`` document."""
|
|
90
|
+
module_name, _, attr = reference.partition(":")
|
|
91
|
+
call = attr.endswith("()")
|
|
92
|
+
attr = attr.removesuffix("()")
|
|
93
|
+
cwd = str(pathlib.Path.cwd())
|
|
94
|
+
if cwd not in sys.path:
|
|
95
|
+
sys.path.insert(0, cwd)
|
|
96
|
+
try:
|
|
97
|
+
module = importlib.import_module(module_name)
|
|
98
|
+
except Exception as exc: # an app's import can fail in arbitrary ways
|
|
99
|
+
raise LoadError(f"could not import {module_name!r}: {exc}") from exc
|
|
100
|
+
obj: Any = module
|
|
101
|
+
for part in attr.split("."):
|
|
102
|
+
try:
|
|
103
|
+
obj = getattr(obj, part)
|
|
104
|
+
except AttributeError as exc:
|
|
105
|
+
raise LoadError(f"{module_name!r} has no attribute {attr!r}") from exc
|
|
106
|
+
if call:
|
|
107
|
+
obj = obj()
|
|
108
|
+
openapi = getattr(obj, "openapi", None)
|
|
109
|
+
if not callable(openapi):
|
|
110
|
+
raise LoadError(f"{reference} is not a FastAPI (or Starlette+openapi) app")
|
|
111
|
+
return openapi()
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def load_spec(
|
|
115
|
+
source: str, overlays: Sequence[str] = ()
|
|
116
|
+
) -> tuple[dict[str, JSON], str, list[OverlayReport]]:
|
|
117
|
+
"""Load a spec and apply overlays. Returns ``(document, base_uri, reports)``.
|
|
118
|
+
|
|
119
|
+
``base_uri`` is where relative ``$ref``s resolve from.
|
|
120
|
+
"""
|
|
121
|
+
if is_app_reference(source):
|
|
122
|
+
document = load_fastapi_app(source)
|
|
123
|
+
base = str(pathlib.Path.cwd() / "openapi.json")
|
|
124
|
+
else:
|
|
125
|
+
document = load_document(source)
|
|
126
|
+
base = source if is_url(source) else str(pathlib.Path(source).resolve())
|
|
127
|
+
if not isinstance(document, dict):
|
|
128
|
+
raise LoadError(f"{source}: the document root must be an object")
|
|
129
|
+
spec = cast(dict[str, JSON], document)
|
|
130
|
+
reports: list[OverlayReport] = []
|
|
131
|
+
for overlay_source in overlays:
|
|
132
|
+
overlay = load_document(overlay_source)
|
|
133
|
+
if not isinstance(overlay, dict):
|
|
134
|
+
raise LoadError(f"{overlay_source}: overlay root must be an object")
|
|
135
|
+
reports.append(apply_overlay(spec, cast(dict[str, JSON], overlay)))
|
|
136
|
+
return spec, base, reports
|
spec2py/naming.py
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Stable, collision-free, Pythonic names."""
|
|
2
|
+
|
|
3
|
+
import functools
|
|
4
|
+
import keyword
|
|
5
|
+
import re
|
|
6
|
+
import unicodedata
|
|
7
|
+
from collections.abc import Iterable
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"NameRegistry",
|
|
11
|
+
"camel_words",
|
|
12
|
+
"pascal",
|
|
13
|
+
"safe_identifier",
|
|
14
|
+
"singular",
|
|
15
|
+
"snake",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _ascii(text: str) -> str:
|
|
20
|
+
return unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode()
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
_LOWER_UPPER = re.compile(r"([a-z0-9])([A-Z])")
|
|
24
|
+
_ACRONYM_WORD = re.compile(r"([A-Z]+)([A-Z][a-z])")
|
|
25
|
+
_SEPARATORS = re.compile(r"[^A-Za-z0-9]+")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def camel_words(text: str) -> list[str]:
|
|
29
|
+
"""Split ``"listHTTPInvoices_v2"`` into ``["list", "http", "invoices", "v2"]``."""
|
|
30
|
+
text = _ascii(text)
|
|
31
|
+
text = _LOWER_UPPER.sub(r"\1 \2", text)
|
|
32
|
+
text = _ACRONYM_WORD.sub(r"\1 \2", text)
|
|
33
|
+
return [w.lower() for w in _SEPARATORS.split(text) if w]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# Large specs ask for the same few thousand names ~100k times.
|
|
37
|
+
@functools.cache
|
|
38
|
+
def snake(text: str) -> str:
|
|
39
|
+
return "_".join(camel_words(text))
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@functools.cache
|
|
43
|
+
def pascal(text: str) -> str:
|
|
44
|
+
words = camel_words(text)
|
|
45
|
+
return "".join(w[:1].upper() + w[1:] for w in words)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def safe_identifier(name: str, *, fallback: str = "value") -> str:
|
|
49
|
+
"""Make ``name`` a valid, non-keyword identifier (``class`` -> ``class_``)."""
|
|
50
|
+
name = re.sub(r"\W", "_", _ascii(name))
|
|
51
|
+
if not name:
|
|
52
|
+
name = fallback
|
|
53
|
+
if name[0].isdigit():
|
|
54
|
+
name = f"n_{name}"
|
|
55
|
+
if keyword.iskeyword(name) or name in ("None", "True", "False"):
|
|
56
|
+
name = f"{name}_"
|
|
57
|
+
return name
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def singular(word: str) -> str:
|
|
61
|
+
"""Cheap English singular, good enough for ``line_items`` -> ``line_item``."""
|
|
62
|
+
lower = word.lower()
|
|
63
|
+
if lower.endswith("ies") and len(word) > 4:
|
|
64
|
+
return word[:-3] + ("Y" if word[-3:].isupper() else "y")
|
|
65
|
+
if lower.endswith(("sses", "xes", "ches", "shes")):
|
|
66
|
+
return word[:-2]
|
|
67
|
+
if lower.endswith("s") and not lower.endswith(("ss", "us", "is")) and len(word) > 3:
|
|
68
|
+
return word[:-1]
|
|
69
|
+
return word
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class NameRegistry:
|
|
73
|
+
"""Hands out unique names in one namespace, deterministically."""
|
|
74
|
+
|
|
75
|
+
def __init__(self, reserved: Iterable[str] = ()) -> None:
|
|
76
|
+
self._taken: set[str] = set(reserved)
|
|
77
|
+
|
|
78
|
+
def __contains__(self, name: str) -> bool:
|
|
79
|
+
return name in self._taken
|
|
80
|
+
|
|
81
|
+
def claim(self, name: str, *, suffix: str = "") -> str:
|
|
82
|
+
if name not in self._taken:
|
|
83
|
+
self._taken.add(name)
|
|
84
|
+
return name
|
|
85
|
+
if suffix and f"{name}{suffix}" not in self._taken:
|
|
86
|
+
name = f"{name}{suffix}"
|
|
87
|
+
self._taken.add(name)
|
|
88
|
+
return name
|
|
89
|
+
n = 2
|
|
90
|
+
while f"{name}{n}" in self._taken:
|
|
91
|
+
n += 1
|
|
92
|
+
self._taken.add(f"{name}{n}")
|
|
93
|
+
return f"{name}{n}"
|
|
94
|
+
|
|
95
|
+
def reserve(self, *names: str) -> None:
|
|
96
|
+
self._taken.update(names)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Normalize stage: every input dialect becomes one bundled OpenAPI 3.1 document."""
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from .refs import RefError, bundle, resolve_pointer
|
|
6
|
+
from .swagger2 import swagger2_to_openapi3
|
|
7
|
+
from .upgrade import upgrade_to_31
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"NormalizeError",
|
|
11
|
+
"RefError",
|
|
12
|
+
"bundle",
|
|
13
|
+
"normalize",
|
|
14
|
+
"resolve_pointer",
|
|
15
|
+
"swagger2_to_openapi3",
|
|
16
|
+
"upgrade_to_31",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class NormalizeError(ValueError):
|
|
21
|
+
pass
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def normalize(document: dict[str, Any], base_uri: str) -> dict[str, Any]:
|
|
25
|
+
"""Return ``document`` as bundled OpenAPI 3.1, whatever version it started as."""
|
|
26
|
+
if str(document.get("swagger", "")).startswith("2"):
|
|
27
|
+
document = swagger2_to_openapi3(document)
|
|
28
|
+
version = str(document.get("openapi", ""))
|
|
29
|
+
if not version.startswith("3."):
|
|
30
|
+
raise NormalizeError(
|
|
31
|
+
f"unsupported spec version {version or document.get('swagger')!r}; "
|
|
32
|
+
"expected Swagger 2.0 or OpenAPI 3.0, 3.1 or 3.2"
|
|
33
|
+
)
|
|
34
|
+
document = bundle(document, base_uri)
|
|
35
|
+
return upgrade_to_31(document)
|