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/emit/notes.py
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Render ``NOTES.md``: what the generator detected and every lossy decision it made."""
|
|
2
|
+
|
|
3
|
+
from ..plan import Plan
|
|
4
|
+
|
|
5
|
+
__all__ = ["render_notes"]
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def render_notes(plan: Plan) -> str:
|
|
9
|
+
c = plan.client
|
|
10
|
+
lines = [
|
|
11
|
+
f"# {c.title} {c.version}: generation notes",
|
|
12
|
+
"",
|
|
13
|
+
"Generated by spec2py. This file records what the generator detected and",
|
|
14
|
+
"every place it had to approximate the spec. Fix the spec with an Overlay or",
|
|
15
|
+
"`[tool.spec2py]` config rather than editing generated code.",
|
|
16
|
+
"",
|
|
17
|
+
"## Client",
|
|
18
|
+
"",
|
|
19
|
+
f"- Class: `{c.class_name}` / `Async{c.class_name}`",
|
|
20
|
+
f"- Base URL: `{c.base_url}`"
|
|
21
|
+
if c.base_url
|
|
22
|
+
else f"- Base URL: required (`{c.env_prefix}_BASE_URL`)",
|
|
23
|
+
]
|
|
24
|
+
for auth in c.auth:
|
|
25
|
+
params = ", ".join(f"`{py}` (`{env}`)" for py, env in auth.params)
|
|
26
|
+
lines.append(f"- Auth `{auth.scheme}` ({auth.kind}): {params}")
|
|
27
|
+
if c.idempotency_header:
|
|
28
|
+
lines.append(
|
|
29
|
+
f"- Idempotency header: `{c.idempotency_header}` (retried POSTs reuse one key)"
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
paginated = [(r, m) for r in plan.resources for m in r.methods if m.pagination]
|
|
33
|
+
streams = [(r, m) for r in plan.resources for m in r.methods if m.stream]
|
|
34
|
+
if paginated:
|
|
35
|
+
lines += [
|
|
36
|
+
"",
|
|
37
|
+
"## Pagination",
|
|
38
|
+
"",
|
|
39
|
+
"| Method | Strategy | Detected from |",
|
|
40
|
+
"| --- | --- | --- |",
|
|
41
|
+
]
|
|
42
|
+
for r, m in paginated:
|
|
43
|
+
assert m.pagination is not None
|
|
44
|
+
lines.append(
|
|
45
|
+
f"| `{r.attr}.{m.name}` | {m.pagination.strategy} | {m.pagination.reason} |"
|
|
46
|
+
)
|
|
47
|
+
if streams:
|
|
48
|
+
lines += [
|
|
49
|
+
"",
|
|
50
|
+
"## Streaming",
|
|
51
|
+
"",
|
|
52
|
+
"| Method | Format | Event type |",
|
|
53
|
+
"| --- | --- | --- |",
|
|
54
|
+
]
|
|
55
|
+
for r, m in streams:
|
|
56
|
+
assert m.stream is not None
|
|
57
|
+
lines.append(
|
|
58
|
+
f"| `{r.attr}.{m.name}` | {m.stream.format} | `{m.stream.event_type.render()}` |"
|
|
59
|
+
)
|
|
60
|
+
lines += ["", "## Approximations", ""]
|
|
61
|
+
if plan.notes:
|
|
62
|
+
lines += [f"- {note}" for note in plan.notes]
|
|
63
|
+
else:
|
|
64
|
+
lines.append("None: every construct mapped exactly.")
|
|
65
|
+
return "\n".join(lines) + "\n"
|
spec2py/emit/package.py
ADDED
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
"""Assemble a generated package: render modules, format with ruff, write files.
|
|
2
|
+
|
|
3
|
+
Output is deterministic: the same spec and config give byte-identical files
|
|
4
|
+
(for a given ruff version), so diffs in review stay meaningful. Files under
|
|
5
|
+
``_custom/`` are created once and never touched again; a manifest records what
|
|
6
|
+
was generated so stale files can be removed and ``--check`` can compare.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import ast
|
|
10
|
+
import hashlib
|
|
11
|
+
import json
|
|
12
|
+
import pathlib
|
|
13
|
+
import shutil
|
|
14
|
+
import subprocess
|
|
15
|
+
import tempfile
|
|
16
|
+
from collections.abc import Mapping
|
|
17
|
+
from dataclasses import dataclass, field
|
|
18
|
+
|
|
19
|
+
from .. import __version__
|
|
20
|
+
from ..plan import RUNTIME, PAlias, Plan
|
|
21
|
+
from .client import emit_client
|
|
22
|
+
from .models import emit_models
|
|
23
|
+
from .notes import render_notes
|
|
24
|
+
from .pyast import const, doc_expr, unparse
|
|
25
|
+
from .resources import emit_resource, twin_names
|
|
26
|
+
|
|
27
|
+
__all__ = ["MANIFEST", "GeneratedPackage", "render_package", "write_package"]
|
|
28
|
+
|
|
29
|
+
MANIFEST = ".spec2py-manifest.json"
|
|
30
|
+
_HEADER = "# Generated by spec2py from {title} {version}. Do not edit: changes are\n# overwritten on regeneration. Extend the client in `_custom/` instead.\n"
|
|
31
|
+
# The runtime range generated projects depend on. The generator's own dependency
|
|
32
|
+
# in pyproject.toml must be the same string (a test checks it); the policy for
|
|
33
|
+
# changing it is in runtime/README.md.
|
|
34
|
+
RUNTIME_REQUIREMENT = "spec2py-runtime>=0.1.0,<0.2.0"
|
|
35
|
+
|
|
36
|
+
_RUNTIME_REEXPORTS = (
|
|
37
|
+
"NOT_GIVEN",
|
|
38
|
+
"APIConnectionError",
|
|
39
|
+
"APIError",
|
|
40
|
+
"APIResponse",
|
|
41
|
+
"APIResponseValidationError",
|
|
42
|
+
"APIStatusError",
|
|
43
|
+
"APITimeoutError",
|
|
44
|
+
"AsyncPage",
|
|
45
|
+
"AuthenticationError",
|
|
46
|
+
"BadRequestError",
|
|
47
|
+
"ConflictError",
|
|
48
|
+
"Hooks",
|
|
49
|
+
"InternalServerError",
|
|
50
|
+
"NotFoundError",
|
|
51
|
+
"NotGiven",
|
|
52
|
+
"Page",
|
|
53
|
+
"PermissionDeniedError",
|
|
54
|
+
"RateLimitError",
|
|
55
|
+
"UnprocessableEntityError",
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(slots=True)
|
|
60
|
+
class GeneratedPackage:
|
|
61
|
+
package: str
|
|
62
|
+
files: dict[str, str]
|
|
63
|
+
"""Generated files, keyed by path relative to the package directory."""
|
|
64
|
+
scaffold: dict[str, str] = field(default_factory=dict[str, str])
|
|
65
|
+
"""Files written only when missing (relative to the output root)."""
|
|
66
|
+
manifest: dict[str, object] = field(default_factory=dict[str, object])
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _custom_exports(custom_init: pathlib.Path) -> list[str]:
|
|
70
|
+
"""Statically read ``__all__`` from the user's ``_custom/__init__.py``."""
|
|
71
|
+
if not custom_init.is_file():
|
|
72
|
+
return []
|
|
73
|
+
try:
|
|
74
|
+
tree = ast.parse(custom_init.read_text(encoding="utf-8"))
|
|
75
|
+
except SyntaxError:
|
|
76
|
+
return []
|
|
77
|
+
for node in tree.body:
|
|
78
|
+
target: ast.expr | None = None
|
|
79
|
+
value: ast.expr | None = None
|
|
80
|
+
if isinstance(node, ast.Assign) and len(node.targets) == 1:
|
|
81
|
+
target, value = node.targets[0], node.value
|
|
82
|
+
elif isinstance(node, ast.AnnAssign):
|
|
83
|
+
target, value = node.target, node.value
|
|
84
|
+
if (
|
|
85
|
+
isinstance(target, ast.Name)
|
|
86
|
+
and target.id == "__all__"
|
|
87
|
+
and isinstance(value, ast.List | ast.Tuple)
|
|
88
|
+
):
|
|
89
|
+
return [
|
|
90
|
+
e.value
|
|
91
|
+
for e in value.elts
|
|
92
|
+
if isinstance(e, ast.Constant) and isinstance(e.value, str)
|
|
93
|
+
]
|
|
94
|
+
return []
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _init_module(plan: Plan, custom: list[str]) -> ast.Module:
|
|
98
|
+
c = plan.client
|
|
99
|
+
names = [c.class_name, f"Async{c.class_name}"]
|
|
100
|
+
body: list[ast.stmt] = [
|
|
101
|
+
doc_expr(
|
|
102
|
+
f"Python client for the {c.api_name}.\n\nGenerated by spec2py; see NOTES.md for generation details.\n"
|
|
103
|
+
),
|
|
104
|
+
ast.ImportFrom(RUNTIME, [ast.alias(n) for n in _RUNTIME_REEXPORTS], 0),
|
|
105
|
+
ast.ImportFrom(None, [ast.alias("models")], 1),
|
|
106
|
+
ast.ImportFrom("_client", [ast.alias(n) for n in names], 1),
|
|
107
|
+
ast.ImportFrom("_version", [ast.alias("__version__")], 1),
|
|
108
|
+
]
|
|
109
|
+
if custom:
|
|
110
|
+
body.append(ast.ImportFrom("_custom", [ast.alias(n) for n in custom], 1))
|
|
111
|
+
exports = sorted({*names, *_RUNTIME_REEXPORTS, "models", "__version__", *custom})
|
|
112
|
+
body.append(
|
|
113
|
+
ast.Assign([ast.Name("__all__")], ast.List([const(n) for n in exports]))
|
|
114
|
+
)
|
|
115
|
+
return ast.Module(body=body, type_ignores=[])
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _resources_init(plan: Plan) -> ast.Module:
|
|
119
|
+
body: list[ast.stmt] = [doc_expr("API resources, one module per resource.")]
|
|
120
|
+
exports: list[str] = []
|
|
121
|
+
for r in plan.resources:
|
|
122
|
+
twins = twin_names(r.class_name)
|
|
123
|
+
names = [*twins, *twins.values()]
|
|
124
|
+
body.append(ast.ImportFrom(r.attr, [ast.alias(n) for n in names], 1))
|
|
125
|
+
exports.extend(names)
|
|
126
|
+
body.append(
|
|
127
|
+
ast.Assign([ast.Name("__all__")], ast.List([const(n) for n in sorted(exports)]))
|
|
128
|
+
)
|
|
129
|
+
return ast.Module(body=body, type_ignores=[])
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _pyproject(plan: Plan, project_name: str) -> str:
|
|
133
|
+
desc = f"Python client for the {plan.client.api_name}".replace('"', "'")
|
|
134
|
+
return (
|
|
135
|
+
"[project]\n"
|
|
136
|
+
f'name = "{project_name}"\n'
|
|
137
|
+
'dynamic = ["version"]\n'
|
|
138
|
+
f'description = "{desc}"\n'
|
|
139
|
+
'readme = "README.md"\n'
|
|
140
|
+
'requires-python = ">=3.14"\n'
|
|
141
|
+
f'dependencies = ["{RUNTIME_REQUIREMENT}"]\n\n'
|
|
142
|
+
"[build-system]\n"
|
|
143
|
+
'requires = ["hatchling"]\n'
|
|
144
|
+
'build-backend = "hatchling.build"\n\n'
|
|
145
|
+
"[tool.hatch.version]\n"
|
|
146
|
+
f'path = "src/{plan.client.package}/_version.py"\n\n'
|
|
147
|
+
"[tool.hatch.build.targets.wheel]\n"
|
|
148
|
+
f'packages = ["src/{plan.client.package}"]\n'
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _readme(plan: Plan, project_name: str) -> str:
|
|
153
|
+
c = plan.client
|
|
154
|
+
first = plan.resources[0] if plan.resources else None
|
|
155
|
+
example = ""
|
|
156
|
+
if first and first.methods:
|
|
157
|
+
m = first.methods[0]
|
|
158
|
+
example = f"\nresult = client.{first.attr}.{m.name}(...)"
|
|
159
|
+
creds = ", ".join(f"{py}=..." for a in c.auth for py, _ in a.params[:1])
|
|
160
|
+
return (
|
|
161
|
+
f"# {project_name}\n\n"
|
|
162
|
+
f"A typed Python client for the {c.api_name}, generated by "
|
|
163
|
+
"[spec2py](https://github.com/f4hy/spec2py).\n\n"
|
|
164
|
+
"```python\n"
|
|
165
|
+
f"from {c.package} import {c.class_name}\n\n"
|
|
166
|
+
f"client = {c.class_name}({creds}){example}\n"
|
|
167
|
+
"```\n\n"
|
|
168
|
+
f"An async client, `Async{c.class_name}`, has the same API. See `NOTES.md` in the package for\n"
|
|
169
|
+
"what the generator detected (pagination, streaming) and any lossy type mappings.\n"
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def render_package(
|
|
174
|
+
plan: Plan, *, custom_dir: pathlib.Path | None = None
|
|
175
|
+
) -> GeneratedPackage:
|
|
176
|
+
"""Render every generated file for ``plan`` (not yet formatted)."""
|
|
177
|
+
c = plan.client
|
|
178
|
+
header = _HEADER.format(title=c.title, version=c.version)
|
|
179
|
+
aliases = {m.name for m in plan.models if isinstance(m, PAlias)}
|
|
180
|
+
custom = _custom_exports(custom_dir / "__init__.py") if custom_dir else []
|
|
181
|
+
|
|
182
|
+
modules: dict[str, ast.Module] = {
|
|
183
|
+
"__init__.py": _init_module(plan, custom),
|
|
184
|
+
"_client.py": emit_client(plan),
|
|
185
|
+
"resources/__init__.py": _resources_init(plan),
|
|
186
|
+
"_version.py": ast.Module(
|
|
187
|
+
body=[
|
|
188
|
+
ast.Assign(
|
|
189
|
+
[ast.Name("__version__")], const(plan.config.package_version)
|
|
190
|
+
)
|
|
191
|
+
],
|
|
192
|
+
type_ignores=[],
|
|
193
|
+
),
|
|
194
|
+
}
|
|
195
|
+
modules.update(emit_models(plan))
|
|
196
|
+
for resource in plan.resources:
|
|
197
|
+
modules[f"resources/{resource.attr}.py"] = emit_resource(
|
|
198
|
+
plan, resource, aliases
|
|
199
|
+
)
|
|
200
|
+
files = {path: header + unparse(module) + "\n" for path, module in modules.items()}
|
|
201
|
+
files["py.typed"] = ""
|
|
202
|
+
files["NOTES.md"] = render_notes(plan)
|
|
203
|
+
|
|
204
|
+
project_name = plan.config.project_name or c.package.replace("_", "-")
|
|
205
|
+
scaffold = {
|
|
206
|
+
"_custom/__init__.py": (
|
|
207
|
+
'"""Hand-written extensions. Never touched by regeneration.\n\n'
|
|
208
|
+
"Names listed in ``__all__`` are re-exported from the package root.\n"
|
|
209
|
+
'"""\n\n__all__: list[str] = []\n'
|
|
210
|
+
),
|
|
211
|
+
}
|
|
212
|
+
if plan.config.layout == "project":
|
|
213
|
+
scaffold["../../pyproject.toml"] = _pyproject(plan, project_name)
|
|
214
|
+
scaffold["../../README.md"] = _readme(plan, project_name)
|
|
215
|
+
return GeneratedPackage(package=c.package, files=files, scaffold=scaffold)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _ruff() -> str:
|
|
219
|
+
try:
|
|
220
|
+
from ruff.__main__ import find_ruff_bin
|
|
221
|
+
|
|
222
|
+
return str(find_ruff_bin())
|
|
223
|
+
except ImportError, FileNotFoundError:
|
|
224
|
+
found = shutil.which("ruff")
|
|
225
|
+
if found is None:
|
|
226
|
+
raise RuntimeError("ruff is required to format generated code") from None
|
|
227
|
+
return found
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def format_files(files: Mapping[str, str]) -> dict[str, str]:
|
|
231
|
+
"""Sort imports and format Python files with ruff (isolated, pinned settings)."""
|
|
232
|
+
with tempfile.TemporaryDirectory(prefix="spec2py-") as tmp:
|
|
233
|
+
root = pathlib.Path(tmp)
|
|
234
|
+
for rel, text in files.items():
|
|
235
|
+
path = root / rel
|
|
236
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
237
|
+
path.write_text(text, encoding="utf-8")
|
|
238
|
+
common = ["--isolated", "--target-version", "py314", "--line-length", "88"]
|
|
239
|
+
ruff = _ruff()
|
|
240
|
+
for args in (
|
|
241
|
+
[
|
|
242
|
+
"check",
|
|
243
|
+
"--select",
|
|
244
|
+
"I,F401,RUF022",
|
|
245
|
+
"--fix",
|
|
246
|
+
"--quiet",
|
|
247
|
+
"--exit-zero",
|
|
248
|
+
*common,
|
|
249
|
+
],
|
|
250
|
+
["format", "--quiet", *common],
|
|
251
|
+
):
|
|
252
|
+
subprocess.run([ruff, *args, str(root)], check=True, capture_output=True)
|
|
253
|
+
return {rel: (root / rel).read_text(encoding="utf-8") for rel in files}
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def _digest(text: str) -> str:
|
|
257
|
+
return hashlib.sha256(text.encode()).hexdigest()
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def package_dir(plan: Plan, output: pathlib.Path) -> pathlib.Path:
|
|
261
|
+
if plan.config.layout == "project":
|
|
262
|
+
return output / "src" / plan.client.package
|
|
263
|
+
return output / plan.client.package
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def write_package(
|
|
267
|
+
plan: Plan,
|
|
268
|
+
output: pathlib.Path,
|
|
269
|
+
*,
|
|
270
|
+
manifest_extra: Mapping[str, object] | None = None,
|
|
271
|
+
) -> GeneratedPackage:
|
|
272
|
+
"""Render, format and write the package under ``output``."""
|
|
273
|
+
target = package_dir(plan, output)
|
|
274
|
+
generated = render_package(plan, custom_dir=target / "_custom")
|
|
275
|
+
generated.files = format_files(generated.files)
|
|
276
|
+
previous = read_manifest(target)
|
|
277
|
+
target.mkdir(parents=True, exist_ok=True)
|
|
278
|
+
for rel, text in generated.files.items():
|
|
279
|
+
path = target / rel
|
|
280
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
281
|
+
if not path.exists() or path.read_text(encoding="utf-8") != text:
|
|
282
|
+
path.write_text(text, encoding="utf-8")
|
|
283
|
+
for rel, text in generated.scaffold.items():
|
|
284
|
+
path = (target / rel).resolve()
|
|
285
|
+
if not path.exists():
|
|
286
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
287
|
+
path.write_text(text, encoding="utf-8")
|
|
288
|
+
# Remove files a previous generation produced that no longer exist.
|
|
289
|
+
previous_files = previous.get("files")
|
|
290
|
+
old_paths = (
|
|
291
|
+
[str(p) for p in previous_files] if isinstance(previous_files, dict) else []
|
|
292
|
+
)
|
|
293
|
+
for rel in old_paths:
|
|
294
|
+
if rel not in generated.files and not rel.startswith("_custom/"):
|
|
295
|
+
stale = target / rel
|
|
296
|
+
if stale.is_file():
|
|
297
|
+
stale.unlink()
|
|
298
|
+
generated.manifest = {
|
|
299
|
+
"generator": "spec2py",
|
|
300
|
+
"generator_version": __version__,
|
|
301
|
+
"files": {rel: _digest(text) for rel, text in sorted(generated.files.items())},
|
|
302
|
+
**(manifest_extra or {}),
|
|
303
|
+
}
|
|
304
|
+
(target / MANIFEST).write_text(
|
|
305
|
+
json.dumps(generated.manifest, indent=2, sort_keys=True) + "\n",
|
|
306
|
+
encoding="utf-8",
|
|
307
|
+
)
|
|
308
|
+
return generated
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
def read_manifest(target: pathlib.Path) -> dict[str, object]:
|
|
312
|
+
path = target / MANIFEST
|
|
313
|
+
if not path.is_file():
|
|
314
|
+
return {}
|
|
315
|
+
try:
|
|
316
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
317
|
+
except ValueError:
|
|
318
|
+
return {}
|
|
319
|
+
return data if isinstance(data, dict) else {}
|