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 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()