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/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"
@@ -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 {}