From defce57d5b9087415bb71ad7362a614fba2d4917 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Thu, 12 Nov 2026 18:40:25 -0800 Subject: [PATCH 1/5] sdk-types: build models on first use (defer_build) Set Pydantic's defer_build on TurnkeyBaseModel so each generated model builds its validator and serializer on first use instead of at import. Only enabled on Pydantic 2.5+; older versions keep the current behavior. Co-Authored-By: Claude Opus 5.5 --- .changeset/sdk-types-defer-build.yml | 10 ++++++++++ codegen/types/generate_types.py | 7 ++++++- .../sdk-types/src/turnkey_sdk_types/generated/types.py | 6 +++++- 3 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 .changeset/sdk-types-defer-build.yml diff --git a/.changeset/sdk-types-defer-build.yml b/.changeset/sdk-types-defer-build.yml new file mode 100644 index 0000000..f958369 --- /dev/null +++ b/.changeset/sdk-types-defer-build.yml @@ -0,0 +1,10 @@ +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`). On Pydantic 2.14, import takes about 0.2s instead of 2-3s, and memory after import drops from about 276MB to about 50MB. + + This is only enabled on Pydantic 2.5 and later. Behavior is unchanged, with a few things to know: + - The first use of each model takes slightly longer, usually a few milliseconds. Activity response models take about 20ms. + - A process that uses most of the activity response types builds a separate copy of the activity schema for each, so its peak memory can be higher than before (about 520MB with every model built, compared with about 280MB). + - 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. + - A model that can't be built would now fail on first use instead of at import. Every current model builds. diff --git a/codegen/types/generate_types.py b/codegen/types/generate_types.py index fe70093..6bf6cae 100644 --- a/codegen/types/generate_types.py +++ b/codegen/types/generate_types.py @@ -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" diff --git a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py index 2483d8a..2631c16 100644 --- a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py +++ b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py @@ -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 --- From cffac2d6c929ab54573fd19146677e710cc8b701 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Fri, 13 Nov 2026 16:06:21 -0800 Subject: [PATCH 2/5] sdk-types: add defer_build tests and run them in CI Checks that every model builds, that serializing before validating works, and that dumps, validation errors and schemas match with defer_build on and off for a sample of models. CI runs only the sdk-types tests, which need no credentials. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/python-build.yml | 3 + packages/sdk-types/tests/test_defer_build.py | 176 +++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 packages/sdk-types/tests/test_defer_build.py diff --git a/.github/workflows/python-build.yml b/.github/workflows/python-build.yml index 41e0107..8ea94d8 100644 --- a/.github/workflows/python-build.yml +++ b/.github/workflows/python-build.yml @@ -35,3 +35,6 @@ jobs: - name: Run type checking run: make typecheck + + - name: Run sdk-types tests + run: pytest packages/sdk-types/tests -v diff --git a/packages/sdk-types/tests/test_defer_build.py b/packages/sdk-types/tests/test_defer_build.py new file mode 100644 index 0000000..5a12338 --- /dev/null +++ b/packages/sdk-types/tests/test_defer_build.py @@ -0,0 +1,176 @@ +"""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 + +# Heaviest models (activity and result types) plus every Nth model by name. +HEAVY = ["v1Activity", "v1ActivityResponse", "v1Result", "v1Intent"] +SAMPLE_EVERY = 25 + +_LIST_MODELS = """ +import inspect +from pydantic import BaseModel +import turnkey_sdk_types.generated.types as T +models = sorted( + (n, o) for n, o in vars(T).items() + if inspect.isclass(o) and issubclass(o, BaseModel) and o.__module__ == T.__name__ +) +""" + + +def _models(): + return sorted( + (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: str, *args: str) -> dict: + out = subprocess.run( + [sys.executable, "-c", code, *args], 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. + models = [ + (n, o) + for n, o in vars(T).items() + if inspect.isclass(o) + and issubclass(o, BaseModel) + and o.__module__ == T.__name__ + ] + for name, cls in models: + cls.model_rebuild(force=True) + assert cls.__pydantic_complete__, name + + +def test_serialize_before_validate(): + # Pydantic 2.1-2.2 crashed here with deferred building. + code = ( + _LIST_MODELS + + """ +import json +failed = [] +for n, cls in models: + try: + cls.model_construct().model_dump(warnings=False) + except Exception as e: + failed.append([n, type(e).__name__, str(e)[:200]]) +print(json.dumps({"failed": failed})) +""" + ) + assert _run(code)["failed"] == [] + + +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": + pydantic.VERSION = "2.4.0" # makes _DEFER_BUILD False +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 + +samples = json.load(sys.stdin) +out = {"defer": T.TurnkeyBaseModel.model_config.get("defer_build"), "models": {}} +for n, data in samples.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)) +""" + + +@pytest.mark.skipif(not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5") +def test_same_behavior_with_defer_off(): + names = [n for i, (n, _) in enumerate(_models()) if i % SAMPLE_EVERY == 0] + names += HEAVY + samples = {} + for n in names: + schema = getattr(T, n).model_json_schema(by_alias=True) + samples[n] = _sample(schema, schema.get("$defs", {})) + + def run(mode): + out = subprocess.run( + [sys.executable, "-c", _COMPARE, mode], + input=json.dumps(samples), + capture_output=True, + text=True, + check=True, + ) + return json.loads(out.stdout) + + on, off = run("on"), run("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 From a5e153c0e15e085aee36622f99a6b7bc01a74819 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Mon, 16 Nov 2026 14:50:08 -0800 Subject: [PATCH 3/5] sdk-types: address review on defer_build tests and changeset Add a test that models are unbuilt after import, share one model-listing helper, and document the sample size and how the test turns deferral off. Tighten the changeset: lead with peak memory and note it depends on build order, drop machine-specific timings, and remove the build-failure note now covered by CI. Co-Authored-By: Claude Opus 5.5 --- .changeset/sdk-types-defer-build.yml | 9 +-- packages/sdk-types/tests/test_defer_build.py | 85 +++++++++----------- 2 files changed, 43 insertions(+), 51 deletions(-) diff --git a/.changeset/sdk-types-defer-build.yml b/.changeset/sdk-types-defer-build.yml index f958369..8eed421 100644 --- a/.changeset/sdk-types-defer-build.yml +++ b/.changeset/sdk-types-defer-build.yml @@ -1,10 +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`). On Pydantic 2.14, import takes about 0.2s instead of 2-3s, and memory after import drops from about 276MB to about 50MB. + 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 unchanged, with a few things to know: - - The first use of each model takes slightly longer, usually a few milliseconds. Activity response models take about 20ms. - - A process that uses most of the activity response types builds a separate copy of the activity schema for each, so its peak memory can be higher than before (about 520MB with every model built, compared with about 280MB). + 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. - - A model that can't be built would now fail on first use instead of at import. Every current model builds. diff --git a/packages/sdk-types/tests/test_defer_build.py b/packages/sdk-types/tests/test_defer_build.py index 5a12338..907ff1f 100644 --- a/packages/sdk-types/tests/test_defer_build.py +++ b/packages/sdk-types/tests/test_defer_build.py @@ -13,68 +13,69 @@ import turnkey_sdk_types.generated.types as T -# Heaviest models (activity and result types) plus every Nth model by name. +# Every 25th model plus the heaviest ones: 58 of 1,326 (about 4%). HEAVY = ["v1Activity", "v1ActivityResponse", "v1Result", "v1Intent"] SAMPLE_EVERY = 25 -_LIST_MODELS = """ -import inspect -from pydantic import BaseModel -import turnkey_sdk_types.generated.types as T -models = sorted( - (n, o) for n, o in vars(T).items() - if inspect.isclass(o) and issubclass(o, BaseModel) and o.__module__ == T.__name__ +needs_defer = pytest.mark.skipif( + not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5" ) -""" def _models(): - return sorted( + """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: str, *args: str) -> dict: +def _run(code, stdin_obj, *args): out = subprocess.run( - [sys.executable, "-c", code, *args], capture_output=True, text=True, check=True + [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. - models = [ - (n, o) - for n, o in vars(T).items() - if inspect.isclass(o) - and issubclass(o, BaseModel) - and o.__module__ == T.__name__ - ] - for name, cls in models: + 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 = ( - _LIST_MODELS - + """ -import json + code = """ +import json, sys +import turnkey_sdk_types.generated.types as T failed = [] -for n, cls in models: +for n in json.load(sys.stdin): try: - cls.model_construct().model_dump(warnings=False) + 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": failed})) +print(json.dumps(failed)) """ - ) - assert _run(code)["failed"] == [] + assert _run(code, [n for n, _ in _models()]) == [] def _sample(schema, defs, seen=()): @@ -110,7 +111,10 @@ def _sample(schema, defs, seen=()): import json, sys import pydantic if sys.argv[1] == "off": - pydantic.VERSION = "2.4.0" # makes _DEFER_BUILD False + # _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 @@ -121,9 +125,8 @@ def errors(cls, data): return [[d["type"], list(d["loc"]), d["msg"]] for d in e.errors()] return None -samples = json.load(sys.stdin) out = {"defer": T.TurnkeyBaseModel.model_config.get("defer_build"), "models": {}} -for n, data in samples.items(): +for n, data in json.load(sys.stdin).items(): cls = getattr(T, n) r = {} try: @@ -145,26 +148,16 @@ def errors(cls, data): """ -@pytest.mark.skipif(not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5") +@needs_defer def test_same_behavior_with_defer_off(): names = [n for i, (n, _) in enumerate(_models()) if i % SAMPLE_EVERY == 0] - names += HEAVY + 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", {})) - def run(mode): - out = subprocess.run( - [sys.executable, "-c", _COMPARE, mode], - input=json.dumps(samples), - capture_output=True, - text=True, - check=True, - ) - return json.loads(out.stdout) - - on, off = run("on"), run("off") + on, off = _run(_COMPARE, samples, "on"), _run(_COMPARE, samples, "off") assert on["defer"] is True assert off["defer"] is False From 268cd3890bfb932faa9804aac6ee5d5e382c08a0 Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Tue, 17 Nov 2026 11:12:40 -0800 Subject: [PATCH 4/5] ci: also run sdk-types tests on Pydantic 2.5.3 2.5 is the oldest version with defer_build enabled, so test it alongside the latest release. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/python-build.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/python-build.yml b/.github/workflows/python-build.yml index 8ea94d8..9383ac8 100644 --- a/.github/workflows/python-build.yml +++ b/.github/workflows/python-build.yml @@ -38,3 +38,8 @@ jobs: - name: Run sdk-types tests run: pytest packages/sdk-types/tests -v + + - name: Run sdk-types tests (Pydantic 2.5.3) + run: | + pip install "pydantic==2.5.3" + pytest packages/sdk-types/tests -v From 7f91ca6f52f2a4d19d5a950eb97f8b181a59ecab Mon Sep 17 00:00:00 2001 From: Hamilton Truong Date: Wed, 18 Nov 2026 12:32:23 -0800 Subject: [PATCH 5/5] sdk-types: make defer_build opt-in via TURNKEY_SDK_DEFER_BUILD Deferred model building is now off by default, so existing apps keep eager building and the same model_config as before. Set TURNKEY_SDK_DEFER_BUILD=1 (or true) before the first Turnkey import to turn it on. Unrecognized values, and Pydantic below 2.5, warn and keep the default. Tests switch the mode with the env var instead of spoofing the Pydantic version, and cover the default, on/off values, and both warnings. Adds a short README section and rewords the changeset as opt-in. Co-Authored-By: Claude Opus 5.5 --- .changeset/sdk-types-defer-build.yml | 7 +- codegen/types/generate_types.py | 53 +++++-- packages/http/README.md | 6 + packages/sdk-types/README.md | 2 + .../src/turnkey_sdk_types/generated/types.py | 34 ++++- packages/sdk-types/tests/test_defer_build.py | 135 ++++++++++++++---- 6 files changed, 193 insertions(+), 44 deletions(-) diff --git a/.changeset/sdk-types-defer-build.yml b/.changeset/sdk-types-defer-build.yml index 8eed421..e36da3b 100644 --- a/.changeset/sdk-types-defer-build.yml +++ b/.changeset/sdk-types-defer-build.yml @@ -1,9 +1,6 @@ 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`). + Adds optional deferred model building. Set `TURNKEY_SDK_DEFER_BUILD=1` before importing the SDK to build each Pydantic model on first use instead of at import, which makes import much faster and uses much less memory. Off by default; existing applications are unchanged. Requires Pydantic 2.5+. - 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. + When enabled, each model's first use is a little slower, and a process that uses nearly every model can use more memory than the default. On Pydantic 2.5–2.10, call `Model.model_rebuild()` before inspecting `model_fields[...].annotation`. diff --git a/codegen/types/generate_types.py b/codegen/types/generate_types.py index 6bf6cae..49f3f34 100644 --- a/codegen/types/generate_types.py +++ b/codegen/types/generate_types.py @@ -32,6 +32,49 @@ ) OUTPUT_FILE = OUTPUT_DIR / "types.py" +# Imports and TurnkeyBaseModel for the generated module. +BASE_MODEL_HEADER = '''import os as _os +import warnings as _warnings +from pydantic import VERSION as _PYDANTIC_VERSION +from pydantic import BaseModel, Field, ConfigDict + + +def _defer_build_enabled() -> bool: + """Opt-in: TURNKEY_SDK_DEFER_BUILD=1 builds each model on first use, not at import. + + Read once, when this module is first imported. + """ + raw = _os.environ.get("TURNKEY_SDK_DEFER_BUILD", "") + value = raw.strip().lower() + if value in ("", "0", "false"): + return False + if value not in ("1", "true"): + _warnings.warn( + f"Ignoring TURNKEY_SDK_DEFER_BUILD={raw!r}: expected 1, true, 0 or false." + ) + return False + if tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) < (2, 5): + _warnings.warn( + f"TURNKEY_SDK_DEFER_BUILD needs Pydantic 2.5+ (found {_PYDANTIC_VERSION}); " + "building models at import." + ) + return False + return True + + +# When off, leave defer_build out so the config is unchanged from before. +_MODEL_CONFIG = ConfigDict(populate_by_name=True) +if _defer_build_enabled(): + _MODEL_CONFIG["defer_build"] = True + + +# Base class with shared configuration +class TurnkeyBaseModel(BaseModel): + model_config = _MODEL_CONFIG + + +''' + def swagger_type_to_python(swagger_type: str, schema: Dict[str, Any]) -> str: """Convert Swagger type to Python type hint.""" @@ -441,15 +484,7 @@ 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, defer_build=_DEFER_BUILD)\n\n" + output += BASE_MODEL_HEADER # --- Base Types --- output += "# --- Base Types from Swagger Definitions ---\n\n" diff --git a/packages/http/README.md b/packages/http/README.md index 76bbf7a..e7bb43f 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -71,6 +71,12 @@ except TurnkeyActivityError as err: print(err.activity_status, err.failure) ``` +## Faster imports (optional) + +Set `TURNKEY_SDK_DEFER_BUILD=1` to build each model on first use instead of at import. Requires Pydantic 2.5+. It's read once at first import, so set it in your environment or before any Turnkey import. + +When enabled, each model's first use is a little slower, and a process that uses nearly every model can use more memory than the default. On Pydantic 2.5–2.10, call `Model.model_rebuild()` before inspecting `model_fields[...].annotation`. + ## Code Generation This package uses code generation to create HTTP client methods from the OpenAPI specification located in `schema/public_api.swagger.json`. diff --git a/packages/sdk-types/README.md b/packages/sdk-types/README.md index 66b5288..00e50d9 100644 --- a/packages/sdk-types/README.md +++ b/packages/sdk-types/README.md @@ -37,6 +37,8 @@ from turnkey_sdk_types import ( ) ``` +To build models on first use instead of at import, see [Faster imports (optional)](../http/README.md#faster-imports-optional). + ## Code Generation This package uses code generation to create type definitions from the OpenAPI specification located in `schema/public_api.swagger.json`. diff --git a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py index 2631c16..3098527 100644 --- a/packages/sdk-types/src/turnkey_sdk_types/generated/types.py +++ b/packages/sdk-types/src/turnkey_sdk_types/generated/types.py @@ -3,16 +3,44 @@ from __future__ import annotations from typing import Any, Dict, List, Optional from enum import Enum +import os as _os +import warnings as _warnings 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) + +def _defer_build_enabled() -> bool: + """Opt-in: TURNKEY_SDK_DEFER_BUILD=1 builds each model on first use, not at import. + + Read once, when this module is first imported. + """ + raw = _os.environ.get("TURNKEY_SDK_DEFER_BUILD", "") + value = raw.strip().lower() + if value in ("", "0", "false"): + return False + if value not in ("1", "true"): + _warnings.warn( + f"Ignoring TURNKEY_SDK_DEFER_BUILD={raw!r}: expected 1, true, 0 or false." + ) + return False + if tuple(int(p) for p in _PYDANTIC_VERSION.split(".")[:2]) < (2, 5): + _warnings.warn( + f"TURNKEY_SDK_DEFER_BUILD needs Pydantic 2.5+ (found {_PYDANTIC_VERSION}); " + "building models at import." + ) + return False + return True + + +# When off, leave defer_build out so the config is unchanged from before. +_MODEL_CONFIG = ConfigDict(populate_by_name=True) +if _defer_build_enabled(): + _MODEL_CONFIG["defer_build"] = True # Base class with shared configuration class TurnkeyBaseModel(BaseModel): - model_config = ConfigDict(populate_by_name=True, defer_build=_DEFER_BUILD) + model_config = _MODEL_CONFIG # --- Base Types from Swagger Definitions --- diff --git a/packages/sdk-types/tests/test_defer_build.py b/packages/sdk-types/tests/test_defer_build.py index 907ff1f..1ed1e10 100644 --- a/packages/sdk-types/tests/test_defer_build.py +++ b/packages/sdk-types/tests/test_defer_build.py @@ -1,24 +1,30 @@ -"""Checks for TurnkeyBaseModel's defer_build setting. +"""Checks for the opt-in TURNKEY_SDK_DEFER_BUILD setting. -Subprocess checks run in a fresh interpreter, so no model has been built yet. +Subprocess checks run in a fresh interpreter, because the setting is read once +at import. """ import inspect import json +import os import subprocess import sys import pytest +from pydantic import VERSION as PYDANTIC_VERSION from pydantic import BaseModel import turnkey_sdk_types.generated.types as T +ENV_VAR = "TURNKEY_SDK_DEFER_BUILD" + # Every 25th model plus the heaviest ones: 58 of 1,326 (about 4%). HEAVY = ["v1Activity", "v1ActivityResponse", "v1Result", "v1Intent"] SAMPLE_EVERY = 25 +SUPPORTS_DEFER = tuple(int(p) for p in PYDANTIC_VERSION.split(".")[:2]) >= (2, 5) needs_defer = pytest.mark.skipif( - not T._DEFER_BUILD, reason="defer_build is off below Pydantic 2.5" + not SUPPORTS_DEFER, reason="defer_build needs Pydantic 2.5+" ) @@ -33,36 +39,117 @@ def _models(): ] -def _run(code, stdin_obj, *args): +def _names(): + return [n for n, _ in _models()] + + +def _run(code, stdin_obj, env_value, *args): + """Run code in a fresh interpreter, with ENV_VAR set to env_value (None unsets it).""" + env = {k: v for k, v in os.environ.items() if k != ENV_VAR} + if env_value is not None: + env[ENV_VAR] = env_value out = subprocess.run( [sys.executable, "-c", code, *args], input=json.dumps(stdin_obj), capture_output=True, text=True, check=True, + env=env, ) 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 +# Imports the models and reports the mode, how many models were built at +# import, and any warnings about the setting. With "old_pydantic", it reports a +# Pydantic version below 2.5 so that path runs on any installed version. +_IMPORT = """ +import json, sys, warnings +import pydantic +if "old_pydantic" in sys.argv: + pydantic.VERSION = "2.4.0" +with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + import turnkey_sdk_types.generated.types as T +names = json.load(sys.stdin) +print(json.dumps({ + "config_keys": sorted(T.TurnkeyBaseModel.model_config), + "defer_build": T.TurnkeyBaseModel.model_config.get("defer_build"), + "built": sum(getattr(T, n).__pydantic_complete__ for n in names), + "warnings": [str(w.message) for w in caught if "TURNKEY_SDK_DEFER_BUILD" in str(w.message)], +})) +""" + + +@pytest.fixture(scope="module") +def baseline(): + """Import with the setting unset.""" + return _run(_IMPORT, _names(), None) + + +def test_off_by_default(baseline): + # Same config as before the setting existed, so models build at import. + assert baseline["config_keys"] == ["populate_by_name"] + assert baseline["warnings"] == [] + + +@pytest.mark.parametrize("value", ["0", "false"]) +def test_off_values_match_default(value, baseline): + assert _run(_IMPORT, _names(), value) == baseline @needs_defer -def test_models_unbuilt_after_import(): +@pytest.mark.parametrize("value", ["1", "True"]) +def test_opt_in_defers(value): + assert _run(_IMPORT, _names(), value) == { + "config_keys": ["defer_build", "populate_by_name"], + "defer_build": True, + "built": 0, + "warnings": [], + } + + +def test_unrecognized_value_warns_and_stays_off(baseline): + assert _run(_IMPORT, _names(), "yes") == { + **baseline, + "warnings": [ + "Ignoring TURNKEY_SDK_DEFER_BUILD='yes': expected 1, true, 0 or false." + ], + } + + +def test_opt_in_on_old_pydantic_warns_and_stays_off(baseline): + assert _run(_IMPORT, _names(), "1", "old_pydantic") == { + **baseline, + "warnings": [ + "TURNKEY_SDK_DEFER_BUILD needs Pydantic 2.5+ (found 2.4.0); " + "building models at import." + ], + } + + +@needs_defer +def test_every_model_builds_when_deferred(): + # Definition order, so dependencies are usually built before the models using them. 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__])) +failed = [] +for n in json.load(sys.stdin): + cls = getattr(T, n) + try: + cls.model_rebuild(force=True) + except Exception as e: + failed.append([n, type(e).__name__, str(e)[:200]]) + else: + if not cls.__pydantic_complete__: + failed.append([n, "incomplete", ""]) +print(json.dumps(failed)) """ - assert _run(code, [n for n, _ in _models()]) == [] + assert _run(code, _names(), "1") == [] -def test_serialize_before_validate(): +@needs_defer +def test_serialize_before_validate_when_deferred(): # Pydantic 2.1-2.2 crashed here with deferred building. code = """ import json, sys @@ -75,7 +162,7 @@ def test_serialize_before_validate(): failed.append([n, type(e).__name__, str(e)[:200]]) print(json.dumps(failed)) """ - assert _run(code, [n for n, _ in _models()]) == [] + assert _run(code, _names(), "1") == [] def _sample(schema, defs, seen=()): @@ -105,16 +192,10 @@ def _sample(schema, defs, seen=()): 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. +# Validates and dumps first, while models are still unbuilt when deferred, +# 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 @@ -149,17 +230,17 @@ def errors(cls, data): @needs_defer -def test_same_behavior_with_defer_off(): - names = [n for i, (n, _) in enumerate(_models()) if i % SAMPLE_EVERY == 0] +def test_same_behavior_with_defer_on_and_off(): + names = [n for i, n in enumerate(_names()) 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") + on, off = _run(_COMPARE, samples, "1"), _run(_COMPARE, samples, None) assert on["defer"] is True - assert off["defer"] is False + assert off["defer"] is None # Guard against the check passing because most samples were rejected. valid = [n for n, r in on["models"].items() if "dump" in r]