diff --git a/.changeset/sdk-types-defer-build.yml b/.changeset/sdk-types-defer-build.yml new file mode 100644 index 0000000..e36da3b --- /dev/null +++ b/.changeset/sdk-types-defer-build.yml @@ -0,0 +1,6 @@ +type: minor +packages: [ sdk-types ] +changelog: |- + 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+. + + 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/.github/workflows/python-build.yml b/.github/workflows/python-build.yml index 41e0107..9383ac8 100644 --- a/.github/workflows/python-build.yml +++ b/.github/workflows/python-build.yml @@ -35,3 +35,11 @@ jobs: - name: Run type checking run: make typecheck + + - 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 diff --git a/codegen/types/generate_types.py b/codegen/types/generate_types.py index fe70093..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,10 +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 BaseModel, Field, ConfigDict\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 += 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 2483d8a..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,12 +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 +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) + 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 new file mode 100644 index 0000000..1ed1e10 --- /dev/null +++ b/packages/sdk-types/tests/test_defer_build.py @@ -0,0 +1,250 @@ +"""Checks for the opt-in TURNKEY_SDK_DEFER_BUILD setting. + +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 SUPPORTS_DEFER, reason="defer_build needs 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 _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) + + +# 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 +@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 +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, _names(), "1") == [] + + +@needs_defer +def test_serialize_before_validate_when_deferred(): + # 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, _names(), "1") == [] + + +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") + + +# Validates and dumps first, while models are still unbuilt when deferred, +# then generates schemas. +_COMPARE = """ +import json, sys +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_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, "1"), _run(_COMPARE, samples, None) + assert on["defer"] is True + 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] + assert len(valid) >= 0.9 * len(names), sorted(set(names) - set(valid)) + + for n in names: + assert on["models"][n] == off["models"][n], n