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/cli.py ADDED
@@ -0,0 +1,351 @@
1
+ """The ``spec2py`` command line.
2
+
3
+ ::
4
+
5
+ spec2py generate openapi.yaml -o clients/acme
6
+ spec2py fastapi myapp.main:app -o clients/myapp
7
+ spec2py lint openapi.yaml --fix-overlay fixes.yaml
8
+ spec2py update # re-pull, diff the API, suggest a version
9
+ spec2py update --check # CI: fail if the committed client is stale
10
+ spec2py diff old.yaml new.yaml
11
+ spec2py score openapi.yaml
12
+ """
13
+
14
+ import argparse
15
+ import json
16
+ import pathlib
17
+ import sys
18
+ import tempfile
19
+ from collections.abc import Sequence
20
+
21
+ import yaml
22
+
23
+ from . import __version__
24
+ from .config import Config, ConfigError, load_config
25
+ from .emit.package import MANIFEST, package_dir, read_manifest
26
+ from .ir import to_jsonable
27
+ from .lint import lint
28
+ from .loader import LoadError
29
+ from .normalize import NormalizeError, RefError
30
+ from .overlay import OverlayError
31
+ from .pipeline import Pipeline, generate, load_api, load_ir, write_pipeline
32
+ from .score import scorecard
33
+ from .surface import api_surface, diff_surfaces, suggest_version
34
+
35
+ __all__ = ["main"]
36
+
37
+
38
+ class CLIError(Exception):
39
+ pass
40
+
41
+
42
+ def _config(args: argparse.Namespace) -> Config:
43
+ config = load_config(
44
+ pathlib.Path(args.config) if getattr(args, "config", None) else None
45
+ )
46
+ overrides: dict[str, object] = {}
47
+ for key in (
48
+ "package",
49
+ "client_name",
50
+ "base_url",
51
+ "layout",
52
+ "group_by",
53
+ "package_version",
54
+ "project_name",
55
+ ):
56
+ value = getattr(args, key, None)
57
+ if value is not None:
58
+ overrides[key] = value
59
+ if getattr(args, "overlay", None):
60
+ overrides["overlays"] = (*config.overlays, *args.overlay)
61
+ if getattr(args, "output", None):
62
+ overrides["output"] = pathlib.Path(args.output)
63
+ return config.replace(**overrides) if overrides else config
64
+
65
+
66
+ def _spec(args: argparse.Namespace, config: Config) -> str:
67
+ spec = getattr(args, "spec", None) or config.spec
68
+ if not spec:
69
+ raise CLIError("no spec given: pass one or set `spec` in [tool.spec2py]")
70
+ return str(spec)
71
+
72
+
73
+ def _add_generation_options(p: argparse.ArgumentParser) -> None:
74
+ p.add_argument(
75
+ "-o",
76
+ "--output",
77
+ help="output directory (default: [tool.spec2py] output, or ./client)",
78
+ )
79
+ p.add_argument(
80
+ "--package", help="Python package name (default: from the API title)"
81
+ )
82
+ p.add_argument(
83
+ "--client-name", help="client class name (default: from the API title)"
84
+ )
85
+ p.add_argument(
86
+ "--base-url", help="default base URL (default: the spec's first server)"
87
+ )
88
+ p.add_argument(
89
+ "--layout",
90
+ choices=["project", "package"],
91
+ help="'project' adds pyproject.toml + src/ (default); 'package' writes only the package",
92
+ )
93
+ p.add_argument(
94
+ "--group-by",
95
+ choices=["tag", "path"],
96
+ help="how operations group into resources",
97
+ )
98
+ p.add_argument(
99
+ "--package-version", help="version written to the package's _version.py"
100
+ )
101
+ p.add_argument(
102
+ "--project-name", help="distribution name in the scaffolded pyproject.toml"
103
+ )
104
+ p.add_argument(
105
+ "--overlay", action="append", help="Overlay document to apply (repeatable)"
106
+ )
107
+ p.add_argument("--config", help="pyproject.toml to read [tool.spec2py] from")
108
+
109
+
110
+ def cmd_generate(args: argparse.Namespace) -> int:
111
+ config = _config(args)
112
+ spec = _spec(args, config)
113
+ if args.check:
114
+ return _check(load_api(spec, config))
115
+ generated = generate(spec, config.output, config)
116
+ print(
117
+ f"Generated {generated.package} ({len(generated.files)} files) in {config.output}"
118
+ )
119
+ if args.verbose:
120
+ for rel in sorted(generated.files):
121
+ print(f" {rel}")
122
+ return 0
123
+
124
+
125
+ def cmd_fastapi(args: argparse.Namespace) -> int:
126
+ args.spec = args.app
127
+ args.check = False
128
+ return cmd_generate(args)
129
+
130
+
131
+ def _check(pipeline: Pipeline) -> int:
132
+ """Regenerate into a temp dir and compare with what's on disk."""
133
+ config = pipeline.config
134
+ current = package_dir(pipeline.plan, config.output)
135
+ with tempfile.TemporaryDirectory(prefix="spec2py-check-") as tmp:
136
+ fresh_root = pathlib.Path(tmp)
137
+ write_pipeline(pipeline, fresh_root)
138
+ fresh = package_dir(pipeline.plan, fresh_root)
139
+ stale: list[str] = []
140
+ for path in sorted(fresh.rglob("*")):
141
+ relative = path.relative_to(fresh)
142
+ if (
143
+ path.is_dir()
144
+ or relative.parts[0] == "_custom"
145
+ or relative.name == MANIFEST
146
+ ):
147
+ continue
148
+ existing = current / relative
149
+ if not existing.is_file() or existing.read_bytes() != path.read_bytes():
150
+ stale.append(str(relative))
151
+ old = read_manifest(current).get("files")
152
+ if isinstance(old, dict):
153
+ stale.extend(
154
+ sorted(
155
+ f"{rel} (should be removed)"
156
+ for rel in old
157
+ if not (fresh / rel).exists()
158
+ )
159
+ )
160
+ if stale:
161
+ print(f"Client in {current} is out of date with the spec:", file=sys.stderr)
162
+ for rel in stale:
163
+ print(f" {rel}", file=sys.stderr)
164
+ print(
165
+ "Run `spec2py update` (or `spec2py generate`) to regenerate.",
166
+ file=sys.stderr,
167
+ )
168
+ return 1
169
+ print(f"Client in {current} is up to date.")
170
+ return 0
171
+
172
+
173
+ def cmd_update(args: argparse.Namespace) -> int:
174
+ config = _config(args)
175
+ spec = _spec(args, config)
176
+ pipeline = load_api(spec, config)
177
+ target = package_dir(pipeline.plan, config.output)
178
+ manifest = read_manifest(target)
179
+ old_surface = manifest.get("surface")
180
+ new_surface = api_surface(pipeline.plan)
181
+ current_version = str(manifest.get("package_version") or config.package_version)
182
+ if isinstance(old_surface, dict):
183
+ diff = diff_surfaces(old_surface, new_surface)
184
+ print(diff.render())
185
+ if diff.bump != "none":
186
+ print(
187
+ f"Suggested version: {current_version} -> {suggest_version(current_version, diff.bump)} ({diff.bump})"
188
+ )
189
+ else:
190
+ print("No previous generation found; generating from scratch.")
191
+ if args.check:
192
+ return _check(pipeline)
193
+ write_pipeline(pipeline)
194
+ print(f"Regenerated {pipeline.plan.client.package} in {config.output}")
195
+ return 0
196
+
197
+
198
+ def cmd_lint(args: argparse.Namespace) -> int:
199
+ config = _config(args)
200
+ _, api, _ = load_ir(_spec(args, config), config)
201
+ report = lint(api)
202
+ print(
203
+ report.to_json()
204
+ if args.format == "json"
205
+ else report.render(verbose=args.verbose)
206
+ )
207
+ if args.fix_overlay:
208
+ overlay = report.overlay(api.title)
209
+ pathlib.Path(args.fix_overlay).write_text(
210
+ yaml.safe_dump(overlay, sort_keys=False), encoding="utf-8"
211
+ )
212
+ print(f"\nWrote {len(overlay['actions'])} fix(es) to {args.fix_overlay}")
213
+ return 1 if args.strict and report.findings else 0
214
+
215
+
216
+ def cmd_diff(args: argparse.Namespace) -> int:
217
+ config = _config(args)
218
+ old = api_surface(load_api(args.old, config).plan)
219
+ new = api_surface(load_api(args.new, config).plan)
220
+ diff = diff_surfaces(old, new)
221
+ print(diff.render())
222
+ if diff.bump != "none":
223
+ print(f"Semver impact: {diff.bump}")
224
+ return 1 if args.fail_on_breaking and diff.breaking else 0
225
+
226
+
227
+ def cmd_ir(args: argparse.Namespace) -> int:
228
+ config = _config(args)
229
+ document, api, _ = load_ir(_spec(args, config), config)
230
+ data = to_jsonable(api) if args.stage == "ir" else document
231
+ print(json.dumps(data, indent=2, sort_keys=args.stage != "ir"))
232
+ return 0
233
+
234
+
235
+ def cmd_score(args: argparse.Namespace) -> int:
236
+ config = _config(args)
237
+ card = scorecard(_spec(args, config), config, typecheck=args.typecheck)
238
+ print(json.dumps(card, indent=2) if args.format == "json" else card_text(card))
239
+ return 0
240
+
241
+
242
+ def card_text(card: dict[str, object]) -> str:
243
+ width = max(len(k) for k in card)
244
+ return "\n".join(f"{k.ljust(width)} {v}" for k, v in card.items())
245
+
246
+
247
+ def build_parser() -> argparse.ArgumentParser:
248
+ parser = argparse.ArgumentParser(
249
+ prog="spec2py",
250
+ description="Generate first-class Python clients from OpenAPI specs.",
251
+ suggest_on_error=True,
252
+ )
253
+ parser.add_argument("--version", action="version", version=f"spec2py {__version__}")
254
+ sub = parser.add_subparsers(dest="command", required=True)
255
+
256
+ p = sub.add_parser("generate", help="generate a client package")
257
+ p.add_argument("spec", nargs="?", help="path, URL or FastAPI app (module:app)")
258
+ _add_generation_options(p)
259
+ p.add_argument(
260
+ "--check",
261
+ action="store_true",
262
+ help="don't write; fail if the client on disk is stale",
263
+ )
264
+ p.add_argument("-v", "--verbose", action="store_true")
265
+ p.set_defaults(func=cmd_generate)
266
+
267
+ p = sub.add_parser(
268
+ "fastapi", help="generate a client from a FastAPI app (module:app)"
269
+ )
270
+ p.add_argument("app", help="import path of the app, e.g. myapp.main:app")
271
+ _add_generation_options(p)
272
+ p.add_argument("-v", "--verbose", action="store_true")
273
+ p.set_defaults(func=cmd_fastapi)
274
+
275
+ p = sub.add_parser(
276
+ "update", help="regenerate, print the API diff and suggest a version"
277
+ )
278
+ p.add_argument("spec", nargs="?")
279
+ _add_generation_options(p)
280
+ p.add_argument(
281
+ "--check",
282
+ action="store_true",
283
+ help="CI mode: fail if the committed client is stale",
284
+ )
285
+ p.set_defaults(func=cmd_update)
286
+
287
+ p = sub.add_parser("lint", help="explain what in a spec will generate poorly")
288
+ p.add_argument("spec", nargs="?")
289
+ p.add_argument("--overlay", action="append")
290
+ p.add_argument("--config")
291
+ p.add_argument(
292
+ "--fix-overlay",
293
+ metavar="FILE",
294
+ help="write a starter Overlay fixing mechanical issues",
295
+ )
296
+ p.add_argument("--format", choices=["text", "json"], default="text")
297
+ p.add_argument(
298
+ "--strict", action="store_true", help="exit 1 if there are any findings"
299
+ )
300
+ p.add_argument("-v", "--verbose", action="store_true")
301
+ p.set_defaults(func=cmd_lint)
302
+
303
+ p = sub.add_parser("diff", help="compare the client API of two specs")
304
+ p.add_argument("old")
305
+ p.add_argument("new")
306
+ p.add_argument("--config")
307
+ p.add_argument("--fail-on-breaking", action="store_true")
308
+ p.set_defaults(func=cmd_diff)
309
+
310
+ p = sub.add_parser(
311
+ "score", help="quality scorecard for the client a spec generates"
312
+ )
313
+ p.add_argument("spec", nargs="?")
314
+ p.add_argument("--config")
315
+ p.add_argument("--overlay", action="append")
316
+ p.add_argument(
317
+ "--typecheck", action="store_true", help="also run mypy --strict on the output"
318
+ )
319
+ p.add_argument("--format", choices=["text", "json"], default="text")
320
+ p.set_defaults(func=cmd_score)
321
+
322
+ p = sub.add_parser(
323
+ "ir", help="print the normalized spec or the IR as JSON (debugging)"
324
+ )
325
+ p.add_argument("spec", nargs="?")
326
+ p.add_argument("--config")
327
+ p.add_argument("--overlay", action="append")
328
+ p.add_argument("--stage", choices=["normalized", "ir"], default="ir")
329
+ p.set_defaults(func=cmd_ir)
330
+ return parser
331
+
332
+
333
+ def main(argv: Sequence[str] | None = None) -> int:
334
+ parser = build_parser()
335
+ args = parser.parse_args(argv)
336
+ try:
337
+ return int(args.func(args))
338
+ except (
339
+ CLIError,
340
+ ConfigError,
341
+ LoadError,
342
+ NormalizeError,
343
+ OverlayError,
344
+ RefError,
345
+ ) as exc:
346
+ print(f"spec2py: error: {exc}", file=sys.stderr)
347
+ return 2
348
+
349
+
350
+ if __name__ == "__main__": # pragma: no cover
351
+ raise SystemExit(main())
spec2py/config.py ADDED
@@ -0,0 +1,199 @@
1
+ """Generator configuration, read from ``[tool.spec2py]`` in ``pyproject.toml``.
2
+
3
+ ::
4
+
5
+ [tool.spec2py]
6
+ spec = "https://api.acme.com/openapi.json"
7
+ output = "clients/acme"
8
+ package = "acme"
9
+ client-name = "Acme"
10
+ overlays = ["overlays/fixes.yaml"]
11
+ group-by = "tag" # or "path"
12
+ exclude-paths = ["/internal/*"]
13
+ idempotency-header = "Idempotency-Key"
14
+
15
+ [tool.spec2py.rename-models]
16
+ InvoiceDTO = "Invoice"
17
+
18
+ [tool.spec2py.operations."GET /invoices"]
19
+ name = "list"
20
+ resource = "invoices"
21
+ pagination = { style = "cursor", items = "data", cursor-param = "after", next-cursor = "last_id" }
22
+
23
+ [tool.spec2py.operations.createCompletion]
24
+ stream = "sse"
25
+
26
+ Keys may be written kebab-case or snake_case.
27
+ """
28
+
29
+ import dataclasses
30
+ import pathlib
31
+ import tomllib
32
+ from collections.abc import Mapping
33
+ from dataclasses import dataclass, field
34
+ from typing import Any, Literal, cast
35
+
36
+ from .loader import is_url
37
+
38
+ __all__ = [
39
+ "Config",
40
+ "ConfigError",
41
+ "OperationConfig",
42
+ "PaginationConfig",
43
+ "load_config",
44
+ ]
45
+
46
+ type PaginationStyle = Literal["cursor", "offset", "page", "link"]
47
+
48
+
49
+ class ConfigError(ValueError):
50
+ pass
51
+
52
+
53
+ @dataclass(frozen=True, slots=True, kw_only=True)
54
+ class PaginationConfig:
55
+ """Explicit pagination for one operation (overrides detection)."""
56
+
57
+ style: PaginationStyle
58
+ items: str | None = "data"
59
+ cursor_param: str = "cursor"
60
+ next_cursor: str | None = "next_cursor"
61
+ cursor_from_item: str | None = None
62
+ has_more: str | None = None
63
+ offset_param: str = "offset"
64
+ limit_param: str | None = "limit"
65
+ page_param: str = "page"
66
+ total: str | None = None
67
+ total_pages: str | None = None
68
+
69
+
70
+ @dataclass(frozen=True, slots=True, kw_only=True)
71
+ class OperationConfig:
72
+ """Per-operation overrides, keyed by operationId or ``"METHOD /path"``."""
73
+
74
+ name: str | None = None
75
+ resource: str | None = None
76
+ pagination: PaginationConfig | Literal[False] | None = None
77
+ stream: Literal["sse", "ndjson"] | Literal[False] | None = None
78
+ exclude: bool = False
79
+
80
+
81
+ @dataclass(frozen=True, slots=True, kw_only=True)
82
+ class Config:
83
+ spec: str | None = None
84
+ output: pathlib.Path = pathlib.Path("client")
85
+ package: str | None = None
86
+ client_name: str | None = None
87
+ project_name: str | None = None
88
+ package_version: str = "0.1.0"
89
+ layout: Literal["project", "package"] = "project"
90
+ overlays: tuple[str, ...] = ()
91
+ group_by: Literal["tag", "path"] = "tag"
92
+ base_url: str | None = None
93
+ env_prefix: str | None = None
94
+ idempotency_header: str | None = None
95
+ stream_terminator: str | None = "[DONE]"
96
+ exclude_paths: tuple[str, ...] = ()
97
+ include_tags: tuple[str, ...] = ()
98
+ exclude_tags: tuple[str, ...] = ()
99
+ rename_models: Mapping[str, str] = field(default_factory=dict[str, str])
100
+ operations: Mapping[str, OperationConfig] = field(
101
+ default_factory=dict[str, OperationConfig]
102
+ )
103
+ custom_resources: Mapping[str, str] = field(default_factory=dict[str, str])
104
+ base_dir: pathlib.Path = pathlib.Path()
105
+
106
+ def replace(self, **changes: Any) -> Config:
107
+ return dataclasses.replace(self, **changes)
108
+
109
+ def operation(
110
+ self, operation_id: str | None, method: str, path: str
111
+ ) -> OperationConfig:
112
+ by_route = self.operations.get(f"{method.upper()} {path}")
113
+ if by_route is not None:
114
+ return by_route
115
+ if operation_id and operation_id in self.operations:
116
+ return self.operations[operation_id]
117
+ return OperationConfig()
118
+
119
+
120
+ def _snake(table: Mapping[str, Any]) -> dict[str, Any]:
121
+ return {k.replace("-", "_"): v for k, v in table.items()}
122
+
123
+
124
+ def _check_keys(table: Mapping[str, Any], klass: type, where: str) -> None:
125
+ known = {f.name for f in dataclasses.fields(klass)}
126
+ unknown = sorted(set(table) - known)
127
+ if unknown:
128
+ raise ConfigError(f"unknown key(s) in {where}: {', '.join(unknown)}")
129
+
130
+
131
+ def _pagination(raw: Any, where: str) -> PaginationConfig | Literal[False] | None:
132
+ if raw is None:
133
+ return None
134
+ if raw is False:
135
+ return False
136
+ if isinstance(raw, str):
137
+ raw = {"style": raw}
138
+ if not isinstance(raw, dict):
139
+ raise ConfigError(f"{where}.pagination must be a table, a style name or false")
140
+ table = _snake(cast(dict[str, Any], raw))
141
+ _check_keys(table, PaginationConfig, f"{where}.pagination")
142
+ if table.get("style") not in ("cursor", "offset", "page", "link"):
143
+ raise ConfigError(
144
+ f"{where}.pagination.style must be cursor, offset, page or link"
145
+ )
146
+ return PaginationConfig(**table)
147
+
148
+
149
+ def _operation(raw: Mapping[str, Any], where: str) -> OperationConfig:
150
+ table = _snake(raw)
151
+ _check_keys(table, OperationConfig, where)
152
+ table["pagination"] = _pagination(table.get("pagination"), where)
153
+ stream = table.get("stream")
154
+ if stream is True:
155
+ table["stream"] = "sse"
156
+ elif stream not in (None, False, "sse", "ndjson"):
157
+ raise ConfigError(f"{where}.stream must be 'sse', 'ndjson' or false")
158
+ return OperationConfig(**table)
159
+
160
+
161
+ def config_from_table(table: Mapping[str, Any], base_dir: pathlib.Path) -> Config:
162
+ data = _snake(table)
163
+ _check_keys(data, Config, "[tool.spec2py]")
164
+ for key in ("overlays", "exclude_paths", "include_tags", "exclude_tags"):
165
+ if key in data:
166
+ data[key] = tuple(data[key])
167
+ if "output" in data:
168
+ data["output"] = base_dir / data["output"]
169
+ data["overlays"] = tuple(
170
+ o if is_url(o) else str(base_dir / o) for o in data.get("overlays", ())
171
+ )
172
+ spec = data.get("spec")
173
+ if spec and not is_url(spec) and (base_dir / spec).exists():
174
+ data["spec"] = str(base_dir / spec)
175
+ data["operations"] = {
176
+ key: _operation(value, f"[tool.spec2py.operations.{key!r}]")
177
+ for key, value in dict(data.get("operations", {})).items()
178
+ }
179
+ data["base_dir"] = base_dir
180
+ return Config(**data)
181
+
182
+
183
+ def load_config(pyproject: pathlib.Path | None = None) -> Config:
184
+ """Load config from ``pyproject`` (default: the nearest one upward from cwd)."""
185
+ if pyproject is None:
186
+ here = pathlib.Path.cwd()
187
+ for directory in (here, *here.parents):
188
+ candidate = directory / "pyproject.toml"
189
+ if candidate.is_file():
190
+ pyproject = candidate
191
+ break
192
+ if pyproject is None or not pyproject.is_file():
193
+ return Config()
194
+ with pyproject.open("rb") as f:
195
+ document = tomllib.load(f)
196
+ table = document.get("tool", {}).get("spec2py")
197
+ if table is None:
198
+ return Config(base_dir=pyproject.parent)
199
+ return config_from_table(table, pyproject.parent)