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