Repository Public
1#!/usr/bin/env python32"""Generates src/spmail/_generated.py (TypedDicts) from docs/OPENAPI.yaml. Standard library only.34 python3 scripts/generate_types.py write the file5 python3 scripts/generate_types.py --check exit 1 when the file is stale relative to the YAML67The YAML is written by the server's own minimal emitter (JSON scalars, two-space indentation, "-" list items); the8small parser below reads exactly that dialect and fails loudly on anything else.9"""10from __future__ import annotations1112import hashlib13import json14import os15import sys16from pathlib import Path17from typing import Any1819HERE = Path(__file__).resolve().parent20YAML_PATH = Path(os.environ.get("SPMAIL_OPENAPI", HERE / "../../../docs/OPENAPI.yaml")).resolve()21OUT_PATH = (HERE / "../src/spmail/_generated.py").resolve()222324# ---------------------------------------------------------------- YAML subset25def parse_yaml(text: str) -> Any:26 lines = [(len(l) - len(l.lstrip(" ")), l.strip()) for l in text.split("\n") if l.strip()]27 pos = 02829 def scalar(s: str) -> Any:30 if s == "[]":31 return []32 if s == "{}":33 return {}34 return json.loads(s)3536 def split_key(s: str) -> tuple[str, str]:37 if s.startswith('"'):38 end = 139 while s[end] != '"' or s[end - 1] == "\\":40 end += 141 key = json.loads(s[: end + 1])42 rest = s[end + 1:]43 else:44 idx = s.index(":")45 key, rest = s[:idx], s[idx:]46 if not rest.startswith(":"):47 raise ValueError(f"unsupported YAML line: {s!r}")48 return key, rest[1:].strip()4950 def block(indent: int) -> Any:51 nonlocal pos52 if lines[pos][1] == "-" or lines[pos][1].startswith("- "):53 out: list[Any] = []54 while pos < len(lines) and lines[pos][0] == indent and (lines[pos][1] == "-" or lines[pos][1].startswith("- ")):55 s = lines[pos][1]56 pos += 157 out.append(block(indent + 2) if s == "-" else scalar(s[2:]))58 return out59 obj: dict[str, Any] = {}60 while pos < len(lines) and lines[pos][0] == indent:61 key, rest = split_key(lines[pos][1])62 pos += 163 obj[key] = block(indent + 2) if rest == "" else scalar(rest)64 return obj6566 doc = block(0)67 if pos != len(lines):68 raise ValueError(f"YAML parse stopped at line {pos}: {lines[pos]!r}")69 return doc707172# ---------------------------------------------------------------- naming (same table as the TypeScript SDK)73NAMED = [74 ("EmailAddress", "getMessagesId", "200", ["properties", "from", "items"]),75 ("RecipientObject", "postMessagesSend", "body", ["properties", "to", "items", "anyOf", 1]),76 ("AttachmentRef", "postMessagesSend", "body", ["properties", "attachments", "items"]),77 ("FolderRef", "getMessagesId", "200", ["properties", "folders", "items"]),78 ("Attachment", "getMessagesIdAttachments", "200", ["properties", "data", "items"]),79 ("MessageAuth", "getMessagesId", "200", ["properties", "auth"]),80 ("MessageHeader", "getMessagesId", "200", ["properties", "headers", "items"]),81 ("MessageSummary", "getMessages", "200", ["properties", "data", "items"]),82 ("Message", "getMessagesId", "200", []),83 ("MessagePage", "getMessages", "200", []),84 ("MessageUpdateParams", "patchMessagesId", "body", []),85 ("Thread", "getThreadsId", "200", []),86 ("ThreadSummary", "getThreads", "200", ["properties", "data", "items"]),87 ("ThreadPage", "getThreads", "200", []),88 ("Changes", "getMessagesChanges", "200", []),89 ("Folder", "postFolders", "201", []),90 ("OutboundRecipient", "getMessagesOutboundId", "200", ["properties", "recipients", "items"]),91 ("OutboundMessage", "getMessagesOutboundId", "200", []),92 ("OutboundPage", "getMessagesOutbound", "200", []),93 ("SendParams", "postMessagesSend", "body", []),94 ("ReplyParams", "postMessagesIdReply", "body", []),95 ("ForwardParams", "postMessagesIdForward", "body", []),96 ("BatchResultItem", "postMessagesSendBatch", "200", ["properties", "results", "items"]),97 ("BatchResult", "postMessagesSendBatch", "200", []),98 ("DraftCreateParams", "postDrafts", "body", []),99 ("DraftUpdateParams", "patchDraftsId", "body", []),100 ("UploadedFile", "postFiles", "201", []),101 ("Address", "getAddressesId", "200", []),102 ("AddressCreateParams", "postAddresses", "body", []),103 ("AddressUpdateParams", "patchAddressesId", "body", []),104 ("Automation", "getAddressesIdAutomation", "200", []),105 ("AutomationUpdateParams", "putAddressesIdAutomation", "body", []),106 ("Webhook", "getWebhooksId", "200", []),107 ("WebhookCreateParams", "postWebhooks", "body", []),108 ("WebhookUpdateParams", "patchWebhooksId", "body", []),109 ("WebhookDelivery", "postWebhookDeliveriesIdReplay", "200", []),110 ("WebhookDeliveryPage", "getWebhooksIdDeliveries", "200", []),111 ("WebhookTestResult", "postWebhooksIdTest", "200", []),112 ("Event", "getEvents", "200", ["properties", "data", "items"]),113 ("EventPage", "getEvents", "200", []),114 ("TemplateVariable", "getTemplatesId", "200", ["properties", "variables", "items"]),115 ("TemplateSummary", "getTemplates", "200", ["properties", "templates", "items"]),116 ("Template", "getTemplatesId", "200", []),117 ("RenderedTemplate", "postTemplatesIdRender", "200", []),118 ("MeAddress", "getMe", "200", ["properties", "addresses", "items"]),119 ("MeLimits", "getMe", "200", ["properties", "limits"]),120 ("MeUsage", "getMe", "200", ["properties", "usage_today"]),121 ("Me", "getMe", "200", []),122 ("Health", "getHealth", "200", []),123]124125126def canon(v: Any) -> str:127 if isinstance(v, list):128 return "[" + ",".join(canon(x) for x in v) + "]"129 if isinstance(v, dict):130 return "{" + ",".join(f"{json.dumps(k)}:{canon(v[k])}" for k in sorted(v) if k not in ("description", "title", "example", "default")) + "}"131 return json.dumps(v)132133134def generate(source: str) -> str:135 doc = parse_yaml(source)136 ops = {op["operationId"]: op for item in doc["paths"].values() for op in item.values()}137138 def root(op_id: str, where: str) -> Any:139 op = ops[op_id]140 content = op["requestBody"]["content"] if where == "body" else op["responses"][where]["content"]141 return content["application/json"]["schema"]142143 names: dict[str, str] = {}144 named: list[tuple[str, Any]] = []145 for name, op_id, where, pointer in NAMED:146 schema = root(op_id, where)147 for key in pointer:148 schema = schema[key]149 names.setdefault(canon(schema), name)150 named.append((name, schema))151152 def py(schema: Any, self_name: str | None = None) -> str:153 if not schema:154 return "Any"155 known = names.get(canon(schema))156 if known and known != self_name:157 return known158 if "const" in schema:159 return f"Literal[{json.dumps(schema['const'])}]"160 if "enum" in schema:161 return "Literal[" + ", ".join(json.dumps(e) for e in schema["enum"]) + "]"162 alt = schema.get("anyOf") or schema.get("oneOf")163 if alt:164 return "Union[" + ", ".join(py(x) for x in alt) + "]"165 t = schema.get("type")166 if isinstance(t, list):167 parts = [py({**schema, "type": x}) for x in t]168 return parts[0] if len(parts) == 1 else "Union[" + ", ".join(parts) + "]"169 if t == "string":170 return "bytes" if schema.get("format") == "binary" else "str"171 if t == "integer":172 return "int"173 if t == "number":174 return "float"175 if t == "boolean":176 return "bool"177 if t == "null":178 return "None"179 if t == "array":180 return f"List[{py(schema.get('items') or {})}]"181 extra = schema.get("additionalProperties")182 if isinstance(extra, dict) and extra and not schema.get("properties"):183 return f"Dict[str, {py(extra)}]"184 return "Dict[str, Any]"185186 sha = hashlib.sha256(source.encode()).hexdigest()187 out = [188 f'"""GENERATED FILE - do not edit. Source: docs/OPENAPI.yaml (sha256 {sha}).',189 "",190 "Regenerate with `python3 scripts/generate_types.py` in packages/sdk-python; a test fails when this file is stale.",191 "Functional TypedDict syntax is used because the API has a field named `from`.",192 '"""',193 "from __future__ import annotations",194 "",195 "import sys",196 "from typing import Any, Dict, List, Literal, TypedDict, Union",197 "",198 "if sys.version_info >= (3, 11):",199 " from typing import NotRequired",200 "else: # Python 3.10: a transparent stand-in (type checkers use the branch above)",201 " class NotRequired: # type: ignore[no-redef]",202 " def __class_getitem__(cls, item: Any) -> Any:",203 " return item",204 "",205 f"OPENAPI_SHA256 = {json.dumps(sha)}",206 f"OPENAPI_VERSION = {json.dumps(doc['info']['version'])}",207 "",208 "OperationScopes = Dict[str, List[str]]",209 "",210 ]211 exported = ["OPENAPI_SHA256", "OPENAPI_VERSION", "OPERATION_SCOPES"]212 for name, schema in named:213 exported.append(name)214 if names[canon(schema)] != name:215 out += [f"{name} = {names[canon(schema)]}", ""]216 continue217 if schema.get("type") == "object" or "properties" in schema:218 required = set(schema.get("required", []))219 out.append(f'{name} = TypedDict("{name}", {{')220 for key, sub in schema.get("properties", {}).items():221 t = py(sub)222 out.append(f" {json.dumps(key)}: {t if key in required else f'NotRequired[{t}]'},")223 out += ["})", ""]224 else:225 out += [f"{name} = {py(schema, name)}", ""]226 out.append("OPERATION_SCOPES: OperationScopes = {")227 for op_id, op in ops.items():228 out.append(f" {json.dumps(op_id)}: {json.dumps(op.get('x-required-scopes', []))},")229 out += ["}", "", f"__all__ = {json.dumps(sorted(exported))}", ""]230 return "\n".join(out)231232233def main() -> int:234 text = generate(YAML_PATH.read_text(encoding="utf-8"))235 if "--check" in sys.argv:236 current = OUT_PATH.read_text(encoding="utf-8") if OUT_PATH.exists() else ""237 if current != text:238 print("src/spmail/_generated.py is stale relative to docs/OPENAPI.yaml - run scripts/generate_types.py", file=sys.stderr)239 return 1240 print("src/spmail/_generated.py is up to date")241 return 0242 OUT_PATH.write_text(text, encoding="utf-8")243 print(f"{OUT_PATH} written")244 return 0245246247if __name__ == "__main__":248 sys.exit(main())249