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/__init__.py
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""spec2py: a Python-only OpenAPI client generator.
|
|
2
|
+
|
|
3
|
+
The pipeline is a compiler with five stages::
|
|
4
|
+
|
|
5
|
+
load -> normalize -> IR -> plan -> emit
|
|
6
|
+
|
|
7
|
+
Use the ``spec2py`` command, or call :func:`generate` from Python.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
try:
|
|
11
|
+
from ._version import __version__
|
|
12
|
+
except ImportError: # pragma: no cover - running from a source checkout
|
|
13
|
+
__version__ = "0.0.0"
|
|
14
|
+
|
|
15
|
+
from .pipeline import Pipeline, generate, load_api
|
|
16
|
+
|
|
17
|
+
__all__ = ["Pipeline", "__version__", "generate", "load_api"]
|
spec2py/_version.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# file generated by vcs-versioning
|
|
2
|
+
# don't change, don't track in version control
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"__version__",
|
|
7
|
+
"__version_tuple__",
|
|
8
|
+
"version",
|
|
9
|
+
"version_tuple",
|
|
10
|
+
"__commit_id__",
|
|
11
|
+
"commit_id",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
version: str
|
|
15
|
+
__version__: str
|
|
16
|
+
__version_tuple__: tuple[int | str, ...]
|
|
17
|
+
version_tuple: tuple[int | str, ...]
|
|
18
|
+
commit_id: str | None
|
|
19
|
+
__commit_id__: str | None
|
|
20
|
+
|
|
21
|
+
__version__ = version = '0.1.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 1, 0)
|
|
23
|
+
|
|
24
|
+
__commit_id__ = commit_id = None
|
spec2py/build_ir.py
ADDED
|
@@ -0,0 +1,637 @@
|
|
|
1
|
+
"""Build the Model IR from a normalized OpenAPI 3.1 document."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from typing import Any, Final, Literal, cast
|
|
6
|
+
|
|
7
|
+
from .ir import (
|
|
8
|
+
API,
|
|
9
|
+
Discriminator,
|
|
10
|
+
Kind,
|
|
11
|
+
Operation,
|
|
12
|
+
Parameter,
|
|
13
|
+
ParamLocation,
|
|
14
|
+
Property,
|
|
15
|
+
RequestBody,
|
|
16
|
+
Response,
|
|
17
|
+
Schema,
|
|
18
|
+
SecurityScheme,
|
|
19
|
+
Server,
|
|
20
|
+
)
|
|
21
|
+
from .normalize.refs import RefError, resolve_pointer, unescape_pointer
|
|
22
|
+
|
|
23
|
+
__all__ = ["build_ir"]
|
|
24
|
+
|
|
25
|
+
type JSON = Any
|
|
26
|
+
type Obj = dict[str, JSON]
|
|
27
|
+
|
|
28
|
+
METHODS: Final = (
|
|
29
|
+
"get",
|
|
30
|
+
"put",
|
|
31
|
+
"post",
|
|
32
|
+
"delete",
|
|
33
|
+
"options",
|
|
34
|
+
"head",
|
|
35
|
+
"patch",
|
|
36
|
+
"trace",
|
|
37
|
+
"query",
|
|
38
|
+
)
|
|
39
|
+
_IGNORED_HEADERS: Final = frozenset({"accept", "content-type", "authorization"})
|
|
40
|
+
_PRIMITIVES: Final = {
|
|
41
|
+
"string": Kind.STRING,
|
|
42
|
+
"integer": Kind.INTEGER,
|
|
43
|
+
"number": Kind.NUMBER,
|
|
44
|
+
"boolean": Kind.BOOLEAN,
|
|
45
|
+
}
|
|
46
|
+
_STRUCTURAL: Final = frozenset(
|
|
47
|
+
{
|
|
48
|
+
"type",
|
|
49
|
+
"properties",
|
|
50
|
+
"additionalProperties",
|
|
51
|
+
"items",
|
|
52
|
+
"enum",
|
|
53
|
+
"const",
|
|
54
|
+
"oneOf",
|
|
55
|
+
"anyOf",
|
|
56
|
+
"allOf",
|
|
57
|
+
"required",
|
|
58
|
+
"patternProperties",
|
|
59
|
+
"prefixItems",
|
|
60
|
+
}
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def media_base(media: str) -> str:
|
|
65
|
+
"""``"Application/JSON; charset=utf-8"`` -> ``"application/json"``."""
|
|
66
|
+
return media.split(";", maxsplit=1)[0].strip().lower()
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _is_json(media: str) -> bool:
|
|
70
|
+
base = media_base(media)
|
|
71
|
+
return base == "application/json" or base.endswith("+json") or base == "*/*"
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def media_rank(media: str) -> int:
|
|
75
|
+
"""Lower is preferred when an operation offers several media types."""
|
|
76
|
+
base = media_base(media)
|
|
77
|
+
if base == "application/json":
|
|
78
|
+
return 0
|
|
79
|
+
if base.endswith("+json"):
|
|
80
|
+
return 1
|
|
81
|
+
if base in ("multipart/form-data",):
|
|
82
|
+
return 2
|
|
83
|
+
if base == "application/x-www-form-urlencoded":
|
|
84
|
+
return 3
|
|
85
|
+
if base in (
|
|
86
|
+
"text/event-stream",
|
|
87
|
+
"application/x-ndjson",
|
|
88
|
+
"application/jsonl",
|
|
89
|
+
"application/json-seq",
|
|
90
|
+
"application/stream+json",
|
|
91
|
+
):
|
|
92
|
+
return 4
|
|
93
|
+
if base == "application/octet-stream":
|
|
94
|
+
return 5
|
|
95
|
+
if base.startswith("text/"):
|
|
96
|
+
return 6
|
|
97
|
+
return 7
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _pascal_tokens(*tokens: str) -> str:
|
|
101
|
+
words = [w for t in tokens for w in re.split(r"[^A-Za-z0-9]+", t) if w]
|
|
102
|
+
return "".join(w[:1].upper() + w[1:] for w in words) or "Schema"
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class _Builder:
|
|
106
|
+
def __init__(self, document: Obj) -> None:
|
|
107
|
+
self.doc = document
|
|
108
|
+
components = cast(Obj, document.get("components") or {})
|
|
109
|
+
self.raw_schemas = dict(cast(Obj, components.get("schemas") or {}))
|
|
110
|
+
self.api = API(
|
|
111
|
+
title=str(cast(Obj, document.get("info") or {}).get("title") or "API"),
|
|
112
|
+
version=str(cast(Obj, document.get("info") or {}).get("version") or "0"),
|
|
113
|
+
openapi_version=str(document.get("openapi", "3.1.0")),
|
|
114
|
+
description=cast(Obj, document.get("info") or {}).get("description"),
|
|
115
|
+
)
|
|
116
|
+
self.synthetic: dict[str, str] = {}
|
|
117
|
+
|
|
118
|
+
# -- refs --------------------------------------------------------------------
|
|
119
|
+
|
|
120
|
+
def deref(self, node: JSON) -> JSON:
|
|
121
|
+
"""Resolve a non-schema ``$ref`` (parameter, response, ...) to its target."""
|
|
122
|
+
seen: set[str] = set()
|
|
123
|
+
while isinstance(node, dict) and isinstance(node.get("$ref"), str):
|
|
124
|
+
ref = cast(str, node["$ref"])
|
|
125
|
+
if ref in seen or not ref.startswith("#"):
|
|
126
|
+
break
|
|
127
|
+
seen.add(ref)
|
|
128
|
+
node = resolve_pointer(self.doc, ref[1:])
|
|
129
|
+
return node
|
|
130
|
+
|
|
131
|
+
def component_name(self, ref: str) -> str:
|
|
132
|
+
"""Name of the component a schema ``$ref`` points at, hoisting if needed."""
|
|
133
|
+
if not ref.startswith("#"):
|
|
134
|
+
raise RefError(f"unbundled external $ref {ref!r}")
|
|
135
|
+
pointer = ref[1:]
|
|
136
|
+
prefix = "/components/schemas/"
|
|
137
|
+
rest = pointer.removeprefix(prefix)
|
|
138
|
+
if pointer.startswith(prefix) and "/" not in rest:
|
|
139
|
+
return unescape_pointer(rest)
|
|
140
|
+
if pointer in self.synthetic:
|
|
141
|
+
return self.synthetic[pointer]
|
|
142
|
+
tokens = [unescape_pointer(t) for t in pointer.strip("/").split("/")]
|
|
143
|
+
meaningful = [
|
|
144
|
+
t
|
|
145
|
+
for t in tokens
|
|
146
|
+
if t
|
|
147
|
+
not in (
|
|
148
|
+
"components",
|
|
149
|
+
"schemas",
|
|
150
|
+
"properties",
|
|
151
|
+
"content",
|
|
152
|
+
"schema",
|
|
153
|
+
"items",
|
|
154
|
+
"paths",
|
|
155
|
+
"responses",
|
|
156
|
+
"application/json",
|
|
157
|
+
)
|
|
158
|
+
]
|
|
159
|
+
base = _pascal_tokens(*meaningful[-2:]) if meaningful else "Schema"
|
|
160
|
+
name, n = base, 2
|
|
161
|
+
while name in self.raw_schemas or name in self.synthetic.values():
|
|
162
|
+
name, n = f"{base}{n}", n + 1
|
|
163
|
+
self.synthetic[pointer] = name
|
|
164
|
+
self.raw_schemas[name] = resolve_pointer(self.doc, pointer)
|
|
165
|
+
return name
|
|
166
|
+
|
|
167
|
+
def is_object_component(self, name: str, depth: int = 0) -> bool:
|
|
168
|
+
raw = self.raw_schemas.get(name)
|
|
169
|
+
if not isinstance(raw, dict) or depth > 20:
|
|
170
|
+
return False
|
|
171
|
+
node = cast(Obj, raw)
|
|
172
|
+
if isinstance(node.get("$ref"), str) and len(node) == 1:
|
|
173
|
+
return self.is_object_component(
|
|
174
|
+
self.component_name(node["$ref"]), depth + 1
|
|
175
|
+
)
|
|
176
|
+
if any(k in node for k in ("oneOf", "anyOf", "enum", "const", "items")):
|
|
177
|
+
return False
|
|
178
|
+
t = node.get("type")
|
|
179
|
+
if t not in (None, "object") and not (isinstance(t, list) and "object" in t):
|
|
180
|
+
return False
|
|
181
|
+
return bool(node.get("properties")) or "allOf" in node
|
|
182
|
+
|
|
183
|
+
# -- schemas -----------------------------------------------------------------
|
|
184
|
+
|
|
185
|
+
def component(self, name: str) -> Schema:
|
|
186
|
+
if name in self.api.schemas:
|
|
187
|
+
return self.api.schemas[name]
|
|
188
|
+
placeholder = Schema(Kind.ANY)
|
|
189
|
+
self.api.schemas[name] = placeholder
|
|
190
|
+
built = self.schema(self.raw_schemas.get(name, {}))
|
|
191
|
+
built.title = built.title or None
|
|
192
|
+
self.api.schemas[name] = built
|
|
193
|
+
return built
|
|
194
|
+
|
|
195
|
+
def schema(self, node: JSON) -> Schema:
|
|
196
|
+
if node is True or node is None:
|
|
197
|
+
return Schema(Kind.ANY)
|
|
198
|
+
if node is False:
|
|
199
|
+
return Schema(
|
|
200
|
+
Kind.ANY, lossy=["`false` schema (nothing allowed) mapped to object"]
|
|
201
|
+
)
|
|
202
|
+
if not isinstance(node, dict):
|
|
203
|
+
return Schema(Kind.ANY)
|
|
204
|
+
n = cast(Obj, node)
|
|
205
|
+
built = self._schema(n)
|
|
206
|
+
self._meta(built, n)
|
|
207
|
+
return built
|
|
208
|
+
|
|
209
|
+
def _meta(self, s: Schema, n: Obj) -> None:
|
|
210
|
+
s.title = s.title or n.get("title")
|
|
211
|
+
if isinstance(n.get("description"), str):
|
|
212
|
+
s.description = n["description"]
|
|
213
|
+
s.deprecated = s.deprecated or bool(n.get("deprecated"))
|
|
214
|
+
s.read_only = s.read_only or bool(n.get("readOnly"))
|
|
215
|
+
s.write_only = s.write_only or bool(n.get("writeOnly"))
|
|
216
|
+
if "default" in n:
|
|
217
|
+
s.default, s.has_default = n["default"], True
|
|
218
|
+
if "examples" in n and isinstance(n["examples"], list):
|
|
219
|
+
s.examples = list(cast(list[JSON], n["examples"]))
|
|
220
|
+
elif "example" in n:
|
|
221
|
+
s.examples = [n["example"]]
|
|
222
|
+
s.extensions.update({k: v for k, v in n.items() if k.startswith("x-")})
|
|
223
|
+
|
|
224
|
+
def _schema(self, n: Obj) -> Schema:
|
|
225
|
+
if isinstance(n.get("$ref"), str):
|
|
226
|
+
ref = Schema(Kind.REF, ref=self.component_name(n["$ref"]))
|
|
227
|
+
rest = {k: v for k, v in n.items() if k in _STRUCTURAL}
|
|
228
|
+
if rest:
|
|
229
|
+
# 3.1 allows siblings next to $ref: treat as allOf.
|
|
230
|
+
return self._all_of([{"$ref": n["$ref"]}, rest], {})
|
|
231
|
+
return ref
|
|
232
|
+
|
|
233
|
+
raw_type = n.get("type")
|
|
234
|
+
types = (
|
|
235
|
+
[raw_type]
|
|
236
|
+
if isinstance(raw_type, str)
|
|
237
|
+
else list(cast(list[str], raw_type or []))
|
|
238
|
+
)
|
|
239
|
+
nullable = "null" in types
|
|
240
|
+
types = [t for t in types if t != "null"]
|
|
241
|
+
|
|
242
|
+
if "const" in n:
|
|
243
|
+
s = Schema(Kind.CONST, values=[n["const"]])
|
|
244
|
+
if n["const"] is None:
|
|
245
|
+
s = Schema(Kind.NULL)
|
|
246
|
+
elif "enum" in n and isinstance(n["enum"], list):
|
|
247
|
+
values = cast(list[JSON], n["enum"])
|
|
248
|
+
nullable = nullable or None in values
|
|
249
|
+
members = [v for v in values if v is not None]
|
|
250
|
+
s = (
|
|
251
|
+
Schema(Kind.ENUM, values=members, format=types[0] if types else None)
|
|
252
|
+
if members
|
|
253
|
+
else Schema(Kind.NULL)
|
|
254
|
+
)
|
|
255
|
+
elif "oneOf" in n or "anyOf" in n:
|
|
256
|
+
s = self._union(n)
|
|
257
|
+
elif "allOf" in n:
|
|
258
|
+
s = self._all_of(cast(list[JSON], n["allOf"]), n)
|
|
259
|
+
elif len(types) > 1:
|
|
260
|
+
s = Schema(
|
|
261
|
+
Kind.UNION,
|
|
262
|
+
union_kind="type",
|
|
263
|
+
variants=[self.schema({**n, "type": t}) for t in types],
|
|
264
|
+
)
|
|
265
|
+
elif types == ["object"] or (
|
|
266
|
+
not types
|
|
267
|
+
and any(
|
|
268
|
+
k in n
|
|
269
|
+
for k in ("properties", "additionalProperties", "patternProperties")
|
|
270
|
+
)
|
|
271
|
+
):
|
|
272
|
+
s = self._object(n)
|
|
273
|
+
elif types == ["array"] or (not types and ("items" in n or "prefixItems" in n)):
|
|
274
|
+
s = self._array(n)
|
|
275
|
+
elif types and types[0] in _PRIMITIVES:
|
|
276
|
+
s = Schema(_PRIMITIVES[types[0]], format=n.get("format"))
|
|
277
|
+
if types[0] == "string" and s.format is None:
|
|
278
|
+
media = n.get("contentMediaType")
|
|
279
|
+
if (
|
|
280
|
+
isinstance(media, str)
|
|
281
|
+
and not _is_json(media)
|
|
282
|
+
and n.get("contentEncoding") is None
|
|
283
|
+
):
|
|
284
|
+
s.format = "binary"
|
|
285
|
+
s.content_media_type = media if isinstance(media, str) else None
|
|
286
|
+
elif not types and nullable:
|
|
287
|
+
s = Schema(Kind.NULL)
|
|
288
|
+
else:
|
|
289
|
+
s = Schema(Kind.ANY)
|
|
290
|
+
if not types and not any(k in n for k in _STRUCTURAL):
|
|
291
|
+
s.lossy.append("untyped schema")
|
|
292
|
+
if nullable and s.kind is not Kind.NULL:
|
|
293
|
+
s.nullable = True
|
|
294
|
+
return s
|
|
295
|
+
|
|
296
|
+
def _union(self, n: Obj) -> Schema:
|
|
297
|
+
key: Literal["oneOf", "anyOf"] = "oneOf" if "oneOf" in n else "anyOf"
|
|
298
|
+
variants: list[Schema] = []
|
|
299
|
+
nullable = False
|
|
300
|
+
for v in cast(list[JSON], n[key]):
|
|
301
|
+
built = self.schema(v)
|
|
302
|
+
if built.kind is Kind.NULL:
|
|
303
|
+
nullable = True
|
|
304
|
+
continue
|
|
305
|
+
variants.append(built)
|
|
306
|
+
if "properties" in n:
|
|
307
|
+
# Base properties next to oneOf: fold them into each object variant.
|
|
308
|
+
base = self._object(n)
|
|
309
|
+
variants = [self._merge_into(v, base) for v in variants]
|
|
310
|
+
if not variants:
|
|
311
|
+
return Schema(Kind.NULL)
|
|
312
|
+
if len(variants) == 1:
|
|
313
|
+
single = variants[0]
|
|
314
|
+
single.nullable = single.nullable or nullable
|
|
315
|
+
return single
|
|
316
|
+
s = Schema(Kind.UNION, variants=variants, union_kind=key, nullable=nullable)
|
|
317
|
+
disc = n.get("discriminator")
|
|
318
|
+
if isinstance(disc, dict) and isinstance(disc.get("propertyName"), str):
|
|
319
|
+
mapping = {
|
|
320
|
+
str(value): self.component_name(target)
|
|
321
|
+
if target.startswith("#")
|
|
322
|
+
else target
|
|
323
|
+
for value, target in cast(
|
|
324
|
+
dict[str, str], disc.get("mapping") or {}
|
|
325
|
+
).items()
|
|
326
|
+
}
|
|
327
|
+
if not mapping:
|
|
328
|
+
mapping = {
|
|
329
|
+
v.ref: v.ref for v in variants if v.kind is Kind.REF and v.ref
|
|
330
|
+
}
|
|
331
|
+
s.discriminator = Discriminator(
|
|
332
|
+
property=disc["propertyName"], mapping=mapping
|
|
333
|
+
)
|
|
334
|
+
return s
|
|
335
|
+
|
|
336
|
+
def _merge_into(self, variant: Schema, base: Schema) -> Schema:
|
|
337
|
+
if variant.kind is Kind.REF:
|
|
338
|
+
obj = Schema(Kind.OBJECT, bases=[cast(str, variant.ref)])
|
|
339
|
+
obj.properties = list(base.properties)
|
|
340
|
+
return obj
|
|
341
|
+
if variant.kind is Kind.OBJECT:
|
|
342
|
+
names = {p.name for p in variant.properties}
|
|
343
|
+
variant.properties = [
|
|
344
|
+
p for p in base.properties if p.name not in names
|
|
345
|
+
] + variant.properties
|
|
346
|
+
return variant
|
|
347
|
+
|
|
348
|
+
def _all_of(self, parts: list[JSON], n: Obj) -> Schema:
|
|
349
|
+
rest = {k: v for k, v in n.items() if k in _STRUCTURAL and k != "allOf"}
|
|
350
|
+
if rest == {"type": "object"}:
|
|
351
|
+
rest = {} # ``type: object`` next to allOf adds nothing
|
|
352
|
+
if rest:
|
|
353
|
+
parts = [*parts, rest]
|
|
354
|
+
if len(parts) == 1:
|
|
355
|
+
return self.schema(parts[0])
|
|
356
|
+
obj = Schema(Kind.OBJECT)
|
|
357
|
+
required: set[str] = set()
|
|
358
|
+
for part in parts:
|
|
359
|
+
built = self.schema(part)
|
|
360
|
+
if built.kind is Kind.REF:
|
|
361
|
+
assert built.ref is not None
|
|
362
|
+
if self.is_object_component(built.ref):
|
|
363
|
+
obj.bases.append(built.ref)
|
|
364
|
+
continue
|
|
365
|
+
target = self.component(built.ref)
|
|
366
|
+
if target.kind is Kind.ANY:
|
|
367
|
+
continue
|
|
368
|
+
built = target
|
|
369
|
+
if built.kind is Kind.OBJECT:
|
|
370
|
+
obj.bases.extend(b for b in built.bases if b not in obj.bases)
|
|
371
|
+
for prop in built.properties:
|
|
372
|
+
existing = obj.property(prop.name)
|
|
373
|
+
if existing is not None:
|
|
374
|
+
obj.properties.remove(existing)
|
|
375
|
+
prop.required = prop.required or existing.required
|
|
376
|
+
obj.properties.append(prop)
|
|
377
|
+
if built.additional is not None:
|
|
378
|
+
obj.additional = built.additional
|
|
379
|
+
obj.lossy.extend(built.lossy)
|
|
380
|
+
elif built.kind is Kind.ANY or (
|
|
381
|
+
built.kind is Kind.MAP
|
|
382
|
+
and (built.additional is None or built.additional.kind is Kind.ANY)
|
|
383
|
+
):
|
|
384
|
+
continue # an untyped object member constrains nothing
|
|
385
|
+
elif (
|
|
386
|
+
isinstance(part, dict)
|
|
387
|
+
and "required" in part
|
|
388
|
+
and len(cast(Obj, part)) == 1
|
|
389
|
+
):
|
|
390
|
+
required.update(cast(list[str], cast(Obj, part)["required"]))
|
|
391
|
+
else:
|
|
392
|
+
# allOf of non-objects (e.g. string + format): keep the most specific.
|
|
393
|
+
built.lossy.append("allOf of non-object schemas narrowed to one member")
|
|
394
|
+
return built
|
|
395
|
+
for prop in obj.properties:
|
|
396
|
+
if prop.name in required:
|
|
397
|
+
prop.required = True
|
|
398
|
+
if required - {p.name for p in obj.properties}:
|
|
399
|
+
obj.extensions["x-spec2py-required-inherited"] = sorted(
|
|
400
|
+
required - {p.name for p in obj.properties}
|
|
401
|
+
)
|
|
402
|
+
if not obj.properties and len(obj.bases) == 1 and obj.additional is None:
|
|
403
|
+
return Schema(Kind.REF, ref=obj.bases[0])
|
|
404
|
+
return obj
|
|
405
|
+
|
|
406
|
+
def _object(self, n: Obj) -> Schema:
|
|
407
|
+
required = set(cast(list[str], n.get("required") or []))
|
|
408
|
+
props = cast(Obj, n.get("properties") or {})
|
|
409
|
+
additional = n.get("additionalProperties")
|
|
410
|
+
lossy: list[str] = []
|
|
411
|
+
if "patternProperties" in n:
|
|
412
|
+
lossy.append("patternProperties mapped to untyped extra fields")
|
|
413
|
+
if additional is None:
|
|
414
|
+
additional = True
|
|
415
|
+
typed_additional = (
|
|
416
|
+
self.schema(additional)
|
|
417
|
+
if isinstance(additional, dict) and additional
|
|
418
|
+
else None
|
|
419
|
+
)
|
|
420
|
+
if not props:
|
|
421
|
+
if "required" in n and required:
|
|
422
|
+
obj = Schema(Kind.OBJECT, lossy=lossy)
|
|
423
|
+
obj.properties = [
|
|
424
|
+
Property(name, Schema(Kind.ANY), True) for name in sorted(required)
|
|
425
|
+
]
|
|
426
|
+
obj.additional = typed_additional
|
|
427
|
+
return obj
|
|
428
|
+
return Schema(
|
|
429
|
+
Kind.MAP, additional=typed_additional or Schema(Kind.ANY), lossy=lossy
|
|
430
|
+
)
|
|
431
|
+
obj = Schema(Kind.OBJECT, lossy=lossy, additional=typed_additional)
|
|
432
|
+
obj.properties = [
|
|
433
|
+
Property(name, self.schema(value), name in required)
|
|
434
|
+
for name, value in props.items()
|
|
435
|
+
]
|
|
436
|
+
return obj
|
|
437
|
+
|
|
438
|
+
def _array(self, n: Obj) -> Schema:
|
|
439
|
+
if "prefixItems" in n:
|
|
440
|
+
prefix = [self.schema(v) for v in cast(list[JSON], n["prefixItems"])]
|
|
441
|
+
items = (
|
|
442
|
+
prefix[0]
|
|
443
|
+
if len(prefix) == 1
|
|
444
|
+
else Schema(Kind.UNION, variants=prefix, union_kind="anyOf")
|
|
445
|
+
)
|
|
446
|
+
return Schema(
|
|
447
|
+
Kind.ARRAY, items=items, lossy=["tuple (prefixItems) mapped to a list"]
|
|
448
|
+
)
|
|
449
|
+
return Schema(Kind.ARRAY, items=self.schema(n.get("items", True)))
|
|
450
|
+
|
|
451
|
+
# -- operations --------------------------------------------------------------
|
|
452
|
+
|
|
453
|
+
def parameter(self, raw: JSON) -> Parameter | None:
|
|
454
|
+
p = cast(Obj, self.deref(raw))
|
|
455
|
+
location = p.get("in")
|
|
456
|
+
name = p.get("name")
|
|
457
|
+
if location not in ("path", "query", "header", "cookie") or not isinstance(
|
|
458
|
+
name, str
|
|
459
|
+
):
|
|
460
|
+
return None
|
|
461
|
+
if location == "header" and name.lower() in _IGNORED_HEADERS:
|
|
462
|
+
return None
|
|
463
|
+
if "schema" in p:
|
|
464
|
+
schema = self.schema(p["schema"])
|
|
465
|
+
elif isinstance(p.get("content"), dict) and p["content"]:
|
|
466
|
+
media = next(iter(cast(Obj, p["content"]).values()))
|
|
467
|
+
schema = self.schema(cast(Obj, media).get("schema", True))
|
|
468
|
+
schema.lossy.append("content-encoded parameter sent as plain text")
|
|
469
|
+
else:
|
|
470
|
+
schema = Schema(Kind.STRING)
|
|
471
|
+
return Parameter(
|
|
472
|
+
name=name,
|
|
473
|
+
location=cast(ParamLocation, location),
|
|
474
|
+
schema=schema,
|
|
475
|
+
required=bool(p.get("required")) or location == "path",
|
|
476
|
+
description=p.get("description"),
|
|
477
|
+
deprecated=bool(p.get("deprecated")),
|
|
478
|
+
style=p.get("style"),
|
|
479
|
+
explode=p.get("explode"),
|
|
480
|
+
)
|
|
481
|
+
|
|
482
|
+
def request_body(self, raw: JSON) -> RequestBody | None:
|
|
483
|
+
body = cast(Obj, self.deref(raw))
|
|
484
|
+
content = cast(Obj, body.get("content") or {})
|
|
485
|
+
if not content:
|
|
486
|
+
return None
|
|
487
|
+
media_types = list(content)
|
|
488
|
+
media = min(media_types, key=media_rank)
|
|
489
|
+
media_obj = cast(Obj, content[media] or {})
|
|
490
|
+
schema = self.schema(media_obj.get("schema", True))
|
|
491
|
+
if media.startswith("application/octet-stream") or (
|
|
492
|
+
not _is_json(media)
|
|
493
|
+
and not media.startswith(
|
|
494
|
+
("multipart/", "application/x-www-form-urlencoded", "text/")
|
|
495
|
+
)
|
|
496
|
+
):
|
|
497
|
+
schema = Schema(Kind.STRING, format="binary")
|
|
498
|
+
return RequestBody(
|
|
499
|
+
media_type=media,
|
|
500
|
+
schema=schema,
|
|
501
|
+
required=bool(body.get("required")),
|
|
502
|
+
description=body.get("description"),
|
|
503
|
+
media_types=media_types,
|
|
504
|
+
)
|
|
505
|
+
|
|
506
|
+
def response(self, status: str, raw: JSON) -> Response:
|
|
507
|
+
r = cast(Obj, self.deref(raw))
|
|
508
|
+
content = cast(Obj, r.get("content") or {})
|
|
509
|
+
response = Response(status=status.upper(), description=r.get("description"))
|
|
510
|
+
response.media_types = list(content)
|
|
511
|
+
if content:
|
|
512
|
+
media = min(content, key=media_rank)
|
|
513
|
+
media_obj = cast(Obj, content[media] or {})
|
|
514
|
+
response.media_type = media
|
|
515
|
+
if "schema" in media_obj:
|
|
516
|
+
response.schema = self.schema(media_obj["schema"])
|
|
517
|
+
if "itemSchema" in media_obj:
|
|
518
|
+
response.item_schema = self.schema(media_obj["itemSchema"])
|
|
519
|
+
# A streaming alternative next to JSON (``stream: true`` style APIs).
|
|
520
|
+
for other in content:
|
|
521
|
+
if media_rank(other) == 4 and other != media:
|
|
522
|
+
other_obj = cast(Obj, content[other] or {})
|
|
523
|
+
if "itemSchema" in other_obj:
|
|
524
|
+
response.item_schema = self.schema(other_obj["itemSchema"])
|
|
525
|
+
for name, header in cast(Obj, r.get("headers") or {}).items():
|
|
526
|
+
h = cast(Obj, self.deref(header))
|
|
527
|
+
response.headers[name.lower()] = self.schema(
|
|
528
|
+
h.get("schema", {"type": "string"})
|
|
529
|
+
)
|
|
530
|
+
return response
|
|
531
|
+
|
|
532
|
+
def operations(self) -> None:
|
|
533
|
+
paths = cast(Obj, self.doc.get("paths") or {})
|
|
534
|
+
for path, raw_item in paths.items():
|
|
535
|
+
resolved = self.deref(raw_item)
|
|
536
|
+
if not isinstance(resolved, dict):
|
|
537
|
+
continue
|
|
538
|
+
item = cast(Obj, resolved)
|
|
539
|
+
shared = [
|
|
540
|
+
self.parameter(p)
|
|
541
|
+
for p in cast(list[JSON], item.get("parameters") or [])
|
|
542
|
+
]
|
|
543
|
+
ops: list[tuple[str, Obj]] = [
|
|
544
|
+
(m, cast(Obj, item[m]))
|
|
545
|
+
for m in METHODS
|
|
546
|
+
if isinstance(item.get(m), dict)
|
|
547
|
+
]
|
|
548
|
+
for method, op in cast(Obj, item.get("additionalOperations") or {}).items():
|
|
549
|
+
ops.append((method.lower(), cast(Obj, op)))
|
|
550
|
+
for method, op in ops:
|
|
551
|
+
params: dict[tuple[str, str], Parameter] = {
|
|
552
|
+
(p.name, p.location): p for p in shared if p is not None
|
|
553
|
+
}
|
|
554
|
+
for raw in cast(list[JSON], op.get("parameters") or []):
|
|
555
|
+
if (param := self.parameter(raw)) is not None:
|
|
556
|
+
params[(param.name, param.location)] = param
|
|
557
|
+
responses = [
|
|
558
|
+
self.response(str(status), raw)
|
|
559
|
+
for status, raw in cast(Obj, op.get("responses") or {}).items()
|
|
560
|
+
if not str(status).startswith("x-")
|
|
561
|
+
]
|
|
562
|
+
operation = Operation(
|
|
563
|
+
method=method,
|
|
564
|
+
path=path,
|
|
565
|
+
operation_id=op.get("operationId"),
|
|
566
|
+
tags=[str(t) for t in cast(list[JSON], op.get("tags") or [])],
|
|
567
|
+
summary=op.get("summary") or item.get("summary"),
|
|
568
|
+
description=op.get("description") or item.get("description"),
|
|
569
|
+
deprecated=bool(op.get("deprecated")),
|
|
570
|
+
parameters=list(params.values()),
|
|
571
|
+
request_body=self.request_body(op["requestBody"])
|
|
572
|
+
if "requestBody" in op
|
|
573
|
+
else None,
|
|
574
|
+
responses=responses,
|
|
575
|
+
security=cast(
|
|
576
|
+
list[dict[str, list[str]]] | None, op.get("security")
|
|
577
|
+
),
|
|
578
|
+
extensions={k: v for k, v in op.items() if k.startswith("x-")},
|
|
579
|
+
)
|
|
580
|
+
self.api.operations.append(operation)
|
|
581
|
+
|
|
582
|
+
def security_schemes(self) -> None:
|
|
583
|
+
components = cast(Obj, self.doc.get("components") or {})
|
|
584
|
+
for name, raw in cast(Obj, components.get("securitySchemes") or {}).items():
|
|
585
|
+
s = cast(Obj, self.deref(raw))
|
|
586
|
+
kind = s.get("type")
|
|
587
|
+
if kind not in ("apiKey", "http", "oauth2", "openIdConnect", "mutualTLS"):
|
|
588
|
+
continue
|
|
589
|
+
scheme = SecurityScheme(
|
|
590
|
+
name=name, type=kind, description=s.get("description")
|
|
591
|
+
)
|
|
592
|
+
if kind == "apiKey":
|
|
593
|
+
scheme.location = s.get("in", "header")
|
|
594
|
+
scheme.parameter_name = s.get("name")
|
|
595
|
+
elif kind == "http":
|
|
596
|
+
scheme.scheme = str(s.get("scheme", "bearer")).lower()
|
|
597
|
+
elif kind == "oauth2":
|
|
598
|
+
flows = cast(Obj, s.get("flows") or {})
|
|
599
|
+
scheme.flows = list(flows)
|
|
600
|
+
for flow in flows.values():
|
|
601
|
+
f = cast(Obj, flow)
|
|
602
|
+
scheme.token_url = scheme.token_url or f.get("tokenUrl")
|
|
603
|
+
scheme.scopes.extend(sorted(cast(Obj, f.get("scopes") or {})))
|
|
604
|
+
self.api.security_schemes[name] = scheme
|
|
605
|
+
self.api.security = cast(
|
|
606
|
+
list[dict[str, list[str]]], self.doc.get("security") or []
|
|
607
|
+
)
|
|
608
|
+
|
|
609
|
+
def servers(self) -> None:
|
|
610
|
+
for raw in cast(list[JSON], self.doc.get("servers") or []):
|
|
611
|
+
server = cast(Obj, raw)
|
|
612
|
+
url = str(server.get("url", ""))
|
|
613
|
+
for var, spec in cast(
|
|
614
|
+
Mapping[str, Obj], server.get("variables") or {}
|
|
615
|
+
).items():
|
|
616
|
+
url = url.replace("{" + var + "}", str(spec.get("default", "")))
|
|
617
|
+
self.api.servers.append(
|
|
618
|
+
Server(url=url, description=server.get("description"))
|
|
619
|
+
)
|
|
620
|
+
|
|
621
|
+
def build(self) -> API:
|
|
622
|
+
self.servers()
|
|
623
|
+
self.security_schemes()
|
|
624
|
+
self.operations()
|
|
625
|
+
for name in list(self.raw_schemas):
|
|
626
|
+
self.component(name)
|
|
627
|
+
# Hoisting during the passes above may have added synthetic components.
|
|
628
|
+
while missing := [n for n in self.raw_schemas if n not in self.api.schemas]:
|
|
629
|
+
for name in missing:
|
|
630
|
+
self.component(name)
|
|
631
|
+
self.api.extensions = {k: v for k, v in self.doc.items() if k.startswith("x-")}
|
|
632
|
+
return self.api
|
|
633
|
+
|
|
634
|
+
|
|
635
|
+
def build_ir(document: Obj) -> API:
|
|
636
|
+
"""Build the IR for a normalized (bundled, 3.1-semantics) document."""
|
|
637
|
+
return _Builder(document).build()
|