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