Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/sdk-types-defer-build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
type: minor
packages: [ sdk-types ]
changelog: |-
Importing `turnkey_sdk_types` is much faster and uses much less memory: each generated model now builds its validator and serializer the first time it's used, instead of all of them at import (Pydantic `defer_build`).

This is only enabled on Pydantic 2.5 and later. Behavior is the same, with a few things to know:
- Peak memory depends on the order models are first used. A process that uses nearly every model can end up above today's level (about 520MB in the worst order we measured, compared with about 280MB). Typical use, which touches a few models, stays well below it.
- The first use of each model takes a little longer: usually a few milliseconds, and tens of milliseconds for activity response models.
- On Pydantic 2.10 and earlier, `Model.model_fields[...].annotation` can show an unresolved `ForwardRef` until the model is first used. Field names, aliases, and defaults are unaffected. Call `Model.model_rebuild()` first if you inspect annotations right after import.
3 changes: 3 additions & 0 deletions .github/workflows/python-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,6 @@ jobs:

- name: Run type checking
run: make typecheck

- name: Run sdk-types tests
run: pytest packages/sdk-types/tests -v
7 changes: 6 additions & 1 deletion codegen/types/generate_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -441,10 +441,15 @@ def main():
output += "from __future__ import annotations\n"
output += "from typing import Any, Dict, List, Optional\n"
output += "from enum import Enum\n"
output += "from pydantic import VERSION as _PYDANTIC_VERSION\n"
output += "from pydantic import BaseModel, Field, ConfigDict\n\n"
output += (
"# Build models on first use, not at import. Needs Pydantic 2.5+.\n"
'_DEFER_BUILD = tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) >= (2, 5)\n\n'
)
output += "\n# Base class with shared configuration\n"
output += "class TurnkeyBaseModel(BaseModel):\n"
output += " model_config = ConfigDict(populate_by_name=True)\n\n"
output += " model_config = ConfigDict(populate_by_name=True, defer_build=_DEFER_BUILD)\n\n"

# --- Base Types ---
output += "# --- Base Types from Swagger Definitions ---\n\n"
Expand Down
6 changes: 5 additions & 1 deletion packages/sdk-types/src/turnkey_sdk_types/generated/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,16 @@
from __future__ import annotations
from typing import Any, Dict, List, Optional
from enum import Enum
from pydantic import VERSION as _PYDANTIC_VERSION
from pydantic import BaseModel, Field, ConfigDict

# Build models on first use, not at import. Needs Pydantic 2.5+.
_DEFER_BUILD = tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) >= (2, 5)


# Base class with shared configuration
class TurnkeyBaseModel(BaseModel):
model_config = ConfigDict(populate_by_name=True)
model_config = ConfigDict(populate_by_name=True, defer_build=_DEFER_BUILD)


# --- Base Types from Swagger Definitions ---
Expand Down
169 changes: 169 additions & 0 deletions packages/sdk-types/tests/test_defer_build.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
"""Checks for TurnkeyBaseModel's defer_build setting.

Subprocess checks run in a fresh interpreter, so no model has been built yet.
"""

import inspect
import json
import subprocess
import sys

import pytest
from pydantic import BaseModel

import turnkey_sdk_types.generated.types as T

# Every 25th model plus the heaviest ones: 58 of 1,326 (about 4%).
HEAVY = ["v1Activity", "v1ActivityResponse", "v1Result", "v1Intent"]
SAMPLE_EVERY = 25

needs_defer = pytest.mark.skipif(
not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5"
)


def _models():
"""Generated models, in definition order."""
return [
(n, o)
for n, o in vars(T).items()
if inspect.isclass(o)
and issubclass(o, BaseModel)
and o.__module__ == T.__name__
]


def _run(code, stdin_obj, *args):
out = subprocess.run(
[sys.executable, "-c", code, *args],
input=json.dumps(stdin_obj),
capture_output=True,
text=True,
check=True,
)
return json.loads(out.stdout)


def test_every_model_builds():
# Definition order, so dependencies are usually built before the models using them.
for name, cls in _models():
cls.model_rebuild(force=True)
assert cls.__pydantic_complete__, name


@needs_defer
def test_models_unbuilt_after_import():
code = """
import json, sys
import turnkey_sdk_types.generated.types as T
names = json.load(sys.stdin)
print(json.dumps([n for n in names if getattr(T, n).__pydantic_complete__]))
"""
assert _run(code, [n for n, _ in _models()]) == []


def test_serialize_before_validate():
# Pydantic 2.1-2.2 crashed here with deferred building.
code = """
import json, sys
import turnkey_sdk_types.generated.types as T
failed = []
for n in json.load(sys.stdin):
try:
getattr(T, n).model_construct().model_dump(warnings=False)
except Exception as e:
failed.append([n, type(e).__name__, str(e)[:200]])
print(json.dumps(failed))
"""
assert _run(code, [n for n, _ in _models()]) == []


def _sample(schema, defs, seen=()):
"""Build input data that should validate against a JSON schema."""
if "$ref" in schema:
name = schema["$ref"].split("/")[-1]
return None if name in seen else _sample(defs[name], defs, seen + (name,))
for key in ("allOf", "anyOf"):
if key in schema:
opts = [o for o in schema[key] if o.get("type") != "null"]
return _sample(opts[0], defs, seen) if opts else None
if "enum" in schema:
return schema["enum"][0]
if "const" in schema: # single-value enums on older Pydantic
return schema["const"]
t = schema.get("type")
if t == "object" or "properties" in schema:
out = {}
for k, v in schema.get("properties", {}).items():
val = _sample(v, defs, seen)
if val is not None or k in schema.get("required", []):
out[k] = val
return out
if t == "array":
item = _sample(schema.get("items", {}), defs, seen)
return [] if item is None else [item]
return {"integer": 1, "number": 1.5, "boolean": True}.get(t, "x")


# Runs in a fresh interpreter with defer_build on or off. Validates and dumps
# first, while models are still unbuilt, then generates schemas.
_COMPARE = """
import json, sys
import pydantic
if sys.argv[1] == "off":
# _DEFER_BUILD is computed from pydantic.VERSION when types.py is imported.
# Reporting a version below 2.5 turns deferral off, giving a baseline to
# compare against in the same environment.
pydantic.VERSION = "2.4.0"
from pydantic import ValidationError
import turnkey_sdk_types.generated.types as T

def errors(cls, data):
try:
cls.model_validate(data)
except ValidationError as e:
return [[d["type"], list(d["loc"]), d["msg"]] for d in e.errors()]
return None

out = {"defer": T.TurnkeyBaseModel.model_config.get("defer_build"), "models": {}}
for n, data in json.load(sys.stdin).items():
cls = getattr(T, n)
r = {}
try:
m = cls.model_validate(data)
r["dump"] = m.model_dump(mode="json")
r["dump_alias"] = m.model_dump(by_alias=True, exclude_none=True, mode="json")
r["dump_json"] = m.model_dump_json(by_alias=True)
except ValidationError:
r["sample_errors"] = errors(cls, data)
r["empty_errors"] = errors(cls, {})
r["wrong_type_errors"] = errors(cls, {k: [[]] for k in data or {}})
r["not_dict_errors"] = errors(cls, "x")
r["schemas"] = [
cls.model_json_schema(mode="validation"),
cls.model_json_schema(mode="serialization"),
]
out["models"][n] = r
print(json.dumps(out))
"""


@needs_defer
def test_same_behavior_with_defer_off():
names = [n for i, (n, _) in enumerate(_models()) if i % SAMPLE_EVERY == 0]
names += [n for n in HEAVY if n not in names]
samples = {}
for n in names:
schema = getattr(T, n).model_json_schema(by_alias=True)
samples[n] = _sample(schema, schema.get("$defs", {}))

on, off = _run(_COMPARE, samples, "on"), _run(_COMPARE, samples, "off")
assert on["defer"] is True
assert off["defer"] is False

# Guard against the check passing because most samples were rejected.
valid = [n for n, r in on["models"].items() if "dump" in r]
assert len(valid) >= 0.9 * len(names), sorted(set(names) - set(valid))

for n in names:
assert on["models"][n] == off["models"][n], n
Loading