UncountablePythonSDK 0.0.24__py3-none-any.whl → 0.0.131__py3-none-any.whl

pkgs/type_spec/builder.py

@@ -10,12 +10,36 @@ import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
 from enum import Enum, StrEnum, auto
-from typing import Any, Optional, Self
+from typing import Any, Self
 
 from . import util
-from .util import parse_type_str, unused
+from .builder_types import CrossOutputPaths
+from .non_discriminated_union_exceptions import NON_DISCRIMINATED_UNION_EXCEPTIONS
+from .util import parse_type_str
 
 RawDict = dict[Any, Any]
+EndpointKey = str
+
+
+class PathMapping(StrEnum):
+    NO_MAPPING = "no_mapping"
+    DEFAULT_MAPPING = "default_mapping"
+
+
+@dataclass(kw_only=True)
+class APIEndpointInfo:
+    root_path: str
+    path_mapping: PathMapping
+
+
+class StabilityLevel(StrEnum):
+    """These are currently used for open api,
+    see: https://github.com/Tufin/oasdiff/blob/main/docs/STABILITY.md
+    """
+
+    draft = "draft"
+    beta = "beta"
+    stable = "stable"
 
 
 class PropertyExtant(StrEnum):
@@ -36,7 +60,7 @@ class PropertyConvertValue(StrEnum):
 @dataclass
 class SpecProperty:
     name: str
-    label: Optional[str]
+    label: str | None
     spec_type: SpecType
     extant: PropertyExtant
     convert_value: PropertyConvertValue
@@ -50,6 +74,7 @@ class SpecProperty:
     # Holds extra information that will be emitted along with type_info. The builder knows nothing
     # about the contents of this information.
     ext_info: Any = None
+    explicit_default: bool = False
 
 
 class NameCase(StrEnum):
@@ -102,6 +127,8 @@ class DefnTypeName(StrEnum):
     s_string_enum = "StringEnum"
     # a particular literal value
     s_string_literal = "_StringLiteral"
+    # A union of several other types
+    s_union = "Union"
 
 
 base_namespace_name = "base"
@@ -195,6 +222,7 @@ class SpecEndpointExample:
 
 @dataclass(kw_only=True)
 class SpecGuide:
+    ref_name: str
     title: str
     markdown_content: str
     html_content: str
@@ -241,7 +269,7 @@ class SpecTypeLiteralWrapper(SpecType):
         return [self.value_type]
 
 
-def unwrap_literal_type(stype: SpecType) -> Optional[SpecTypeLiteralWrapper]:
+def unwrap_literal_type(stype: SpecType) -> SpecTypeLiteralWrapper | None:
     if isinstance(stype, SpecTypeInstance) and stype.defn_type.is_base_type(
         BaseTypeName.s_literal
     ):
@@ -269,7 +297,7 @@ class SpecTypeDefn(SpecType):
     ) -> None:
         self.namespace = namespace
         self.name = name
-        self.label: Optional[str] = None
+        self.label: str | None = None
 
         self.is_predefined = is_predefined
         self.name_case = NameCase.convert
@@ -279,6 +307,8 @@ class SpecTypeDefn(SpecType):
         self._is_value_converted = _is_value_converted
         self._is_value_to_string = False
         self._is_valid_parameter = True
+        self._is_dynamic_allowed = False
+        self._default_extant: PropertyExtant | None = None
         self.ext_info: Any = None
 
     def is_value_converted(self) -> bool:
@@ -290,20 +320,43 @@ class SpecTypeDefn(SpecType):
     def is_valid_parameter(self) -> bool:
         return self._is_valid_parameter
 
+    def is_dynamic_allowed(self) -> bool:
+        return self._is_dynamic_allowed
+
     def is_base_type(self, type_: BaseTypeName) -> bool:
         return self.is_base and self.name == type_
 
+    def can_process(self, builder: SpecBuilder, data: RawDict) -> bool:
+        return True
+
     @abc.abstractmethod
     def process(self, builder: SpecBuilder, data: RawDict) -> None: ...
 
     def base_process(
         self, builder: SpecBuilder, data: RawDict, extra_names: list[str]
     ) -> None:
-        util.check_fields(data, ["ext_info", "label"] + extra_names)
+        util.check_fields(
+            data,
+            [
+                "ext_info",
+                "label",
+                "is_dynamic_allowed",
+                "default_extant",
+            ]
+            + extra_names,
+        )
 
         self.ext_info = data.get("ext_info")
         self.label = data.get("label")
 
+        is_dynamic_allowed = data.get("is_dynamic_allowed", False)
+        assert isinstance(is_dynamic_allowed, bool)
+        self._is_dynamic_allowed = is_dynamic_allowed
+
+        default_extant = data.get("default_extant")
+        if default_extant is not None:
+            self._default_extant = PropertyExtant(default_extant)
+
     def _process_property(
         self, builder: SpecBuilder, spec_name: str, data: RawDict
     ) -> SpecProperty:
@@ -322,18 +375,18 @@ class SpecTypeDefn(SpecType):
             ],
         )
         try:
-            extant_type = data.get("extant")
+            extant_type_str = data.get("extant")
+            extant_type = (
+                PropertyExtant(extant_type_str) if extant_type_str is not None else None
+            )
+            extant = extant_type or self._default_extant
             if spec_name.endswith("?"):
-                if extant_type is not None:
+                if extant is not None:
                     raise Exception("cannot specify extant with ?")
                 extant = PropertyExtant.optional
                 name = spec_name[:-1]
             else:
-                extant = (
-                    PropertyExtant.required
-                    if extant_type is None
-                    else PropertyExtant(extant_type)
-                )
+                extant = extant or PropertyExtant.required
                 name = spec_name
 
             property_name_case = self.name_case
@@ -342,9 +395,9 @@ class SpecTypeDefn(SpecType):
                 property_name_case = NameCase(name_case_raw)
 
             if property_name_case != NameCase.preserve:
-                assert util.is_valid_property_name(
-                    name
-                ), f"{name} is not a valid property name"
+                assert util.is_valid_property_name(name), (
+                    f"{name} is not a valid property name"
+                )
 
             data_type = data.get("type")
             builder.ensure(data_type is not None, "missing `type` entry")
@@ -355,6 +408,7 @@ class SpecTypeDefn(SpecType):
             ptype = builder.parse_type(self.namespace, data_type, scope=self)
 
             default_spec = data.get("default", MISSING)
+            explicit_default = default_spec != MISSING
             if default_spec == MISSING:
                 has_default = False
                 default = None
@@ -362,7 +416,10 @@ class SpecTypeDefn(SpecType):
                 has_default = True
                 # IMPROVE: check the type against the ptype
                 default = default_spec
-
+            if extant == PropertyExtant.missing and explicit_default:
+                raise Exception(
+                    f"cannot have extant missing and default for property {name}"
+                )
             parse_require = False
             literal = unwrap_literal_type(ptype)
             if literal is not None:
@@ -385,6 +442,7 @@ class SpecTypeDefn(SpecType):
                 parse_require=parse_require,
                 desc=data.get("desc", None),
                 ext_info=ext_info,
+                explicit_default=explicit_default,
             )
         finally:
             builder.pop_where()
@@ -422,7 +480,7 @@ class SpecTypeGenericParameter(SpecType):
 
 
 class SpecTypeDefnObject(SpecTypeDefn):
-    base: Optional[SpecTypeDefnObject]
+    base: SpecTypeDefnObject | None
     parameters: list[str]
 
     def __init__(
@@ -430,7 +488,7 @@ class SpecTypeDefnObject(SpecTypeDefn):
         namespace: SpecNamespace,
         name: str,
         *,
-        parameters: Optional[list[str]] = None,
+        parameters: list[str] | None = None,
         is_base: bool = False,
         is_predefined: bool = False,
         is_hashable: bool = False,
@@ -447,7 +505,7 @@ class SpecTypeDefnObject(SpecTypeDefn):
         self.parameters = parameters if parameters is not None else []
         self.is_hashable = is_hashable
         self.base = None
-        self.properties: Optional[dict[str, SpecProperty]] = None
+        self.properties: dict[str, SpecProperty] | None = None
         self._kw_only: bool = True
         self.desc: str | None = None
 
@@ -518,13 +576,8 @@ class SpecTypeDefnObject(SpecTypeDefn):
         base_type: list[SpecType] = [self.base] if self.base is not None else []
         return base_type + prop_types
 
-    def get_generic(self) -> Optional[str]:
-        if len(self.parameters) > 0:
-            assert (
-                len(self.parameters) == 1
-            ), "Only single generic parameters current supported"
-            return self.parameters[0]
-        return None
+    def get_generics(self) -> list[str]:
+        return self.parameters
 
 
 class SpecTypeDefnAlias(SpecTypeDefn):
@@ -546,13 +599,75 @@ class SpecTypeDefnAlias(SpecTypeDefn):
         super().base_process(builder, data, ["type", "desc", "alias", "discriminator"])
         self.alias = builder.parse_type(self.namespace, data["alias"])
         self.desc = data.get("desc", None)
-        # Should be limited to Union type aliases
         self.discriminator = data.get("discriminator", None)
 
     def get_referenced_types(self) -> list[SpecType]:
         return [self.alias]
 
 
+class SpecTypeDefnUnion(SpecTypeDefn):
+    def __init__(self, namespace: SpecNamespace, name: str) -> None:
+        super().__init__(namespace, name)
+        self.discriminator: str | None = None
+        self.types: list[SpecType] = []
+        self._alias_type: SpecType | None = None
+        self.discriminator_map: dict[str, SpecType] | None = None
+        self.desc: str | None = None
+
+    def process(self, builder: SpecBuilder, data: RawDict) -> None:
+        super().base_process(builder, data, ["type", "desc", "types", "discriminator"])
+
+        self.desc = data.get("desc", None)
+        self.discriminator = data.get("discriminator", None)
+
+        for sub_type_str in data["types"]:
+            sub_type = builder.parse_type(self.namespace, sub_type_str)
+            self.types.append(sub_type)
+
+        base_type = builder.namespaces[base_namespace_name].types[BaseTypeName.s_union]
+        self._backing_type = SpecTypeInstance(base_type, self.types)
+
+        if self.discriminator is not None:
+            self.discriminator_map = {}
+            for sub_type in self.types:
+                builder.push_where(sub_type.name)
+                assert isinstance(sub_type, SpecTypeDefnObject), (
+                    "union-type-must-be-object"
+                )
+                assert sub_type.properties is not None
+                discriminator_type = sub_type.properties.get(self.discriminator)
+                assert discriminator_type is not None, (
+                    f"missing-discriminator-field: {sub_type}"
+                )
+                prop_type = unwrap_literal_type(discriminator_type.spec_type)
+                assert prop_type is not None
+                assert prop_type.is_value_to_string()
+                value_type = prop_type.value_type
+                if isinstance(value_type, SpecTypeDefnStringEnum):
+                    assert isinstance(prop_type.value, str)
+                    discriminant = value_type.values[prop_type.value].value
+                else:
+                    discriminant = str(prop_type.value)
+                assert discriminant not in self.discriminator_map, (
+                    f"duplicated-discriminant, {discriminant} in {sub_type}"
+                )
+                self.discriminator_map[discriminant] = sub_type
+
+                builder.pop_where()
+        elif (
+            f"{self.namespace.name}.{self.name}"
+            not in NON_DISCRIMINATED_UNION_EXCEPTIONS
+        ):
+            raise Exception(f"union requires a discriminator: {self.name}")
+
+    def get_referenced_types(self) -> list[SpecType]:
+        return self.types
+
+    def get_backing_type(self) -> SpecType:
+        assert self._backing_type is not None
+        return self._backing_type
+
+
 class SpecTypeDefnExternal(SpecTypeDefn):
     external_map: dict[str, str]
 
@@ -582,7 +697,7 @@ class SpecTypeDefnExternal(SpecTypeDefn):
 class StringEnumEntry:
     name: str
     value: str
-    label: Optional[str] = None
+    label: str | None = None
     deprecated: bool = False
 
 
@@ -598,17 +713,32 @@ class SpecTypeDefnStringEnum(SpecTypeDefn):
         )
         self.values: dict[str, StringEnumEntry] = {}
         self.desc: str | None = None
-        self.sql_type_name: Optional[str] = None
+        self.sql_type_name: str | None = None
         self.emit_id_source = False
+        self.source_enums: list[SpecType] = []
+
+    def can_process(self, builder: SpecBuilder, data: dict[Any, Any]) -> bool:
+        source_enums = data.get("source_enums")
+        try:
+            for sub_type_str in source_enums or []:
+                sub_type = builder.parse_type(self.namespace, sub_type_str)
+                assert isinstance(sub_type, SpecTypeDefnStringEnum)
+                assert len(sub_type.values) > 0
+        except AssertionError:
+            return False
+        return super().can_process(builder, data)
 
     def process(self, builder: SpecBuilder, data: RawDict) -> None:
         super().base_process(
-            builder, data, ["type", "desc", "values", "name_case", "sql", "emit"]
+            builder,
+            data,
+            ["type", "desc", "values", "name_case", "sql", "emit", "source_enums"],
         )
         self.name_case = NameCase(data.get("name_case", "convert"))
         self.values = {}
-        data_values = data["values"]
+        data_values = data.get("values")
         self.desc = data.get("desc", None)
+        source_enums = data.get("source_enums", None)
         if isinstance(data_values, dict):
             for name, value in data_values.items():
                 builder.push_where(name)
@@ -621,6 +751,8 @@ class SpecTypeDefnStringEnum(SpecTypeDefn):
                     builder.ensure(
                         isinstance(enum_value, str), "enum value should be string"
                     )
+                    assert isinstance(enum_value, str)
+
                     deprecated = value.get("deprecated", False)
                     builder.ensure(
                         isinstance(deprecated, bool),
@@ -646,10 +778,13 @@ class SpecTypeDefnStringEnum(SpecTypeDefn):
         elif isinstance(data_values, list):
             for value in data_values:
                 if value in self.values:
-                    raise Exception("duplicate value in typespec enum", self.name, value)
+                    raise Exception(
+                        "duplicate value in typespec enum", self.name, value
+                    )
                 self.values[value] = StringEnumEntry(name=value, value=value)
         else:
-            raise Exception("unsupported values type")
+            if source_enums is None or data_values is not None:
+                raise Exception("unsupported values type")
 
         sql_data = data.get("sql")
         if sql_data is not None:
@@ -671,14 +806,24 @@ class SpecTypeDefnStringEnum(SpecTypeDefn):
                 builder.ensure(
                     entry.label is not None, f"need-label-for-id-source:{entry.name}"
                 )
+        for sub_type_str in source_enums or []:
+            sub_type = builder.parse_type(self.namespace, sub_type_str)
+            self.source_enums.append(sub_type)
+
+        for sub_type in self.source_enums:
+            builder.push_where(sub_type.name)
+            if isinstance(sub_type, SpecTypeDefnStringEnum):
+                self.values.update(sub_type.values)
+            builder.pop_where()
 
     def get_referenced_types(self) -> list[SpecType]:
-        return []
+        return self.source_enums
 
 
 TOKEN_ENDPOINT = "$endpoint"
 TOKEN_EMIT_IO_TS = "$emit_io_ts"
 TOKEN_EMIT_TYPE_INFO = "$emit_type_info"
+TOKEN_EMIT_TYPE_INFO_PYTHON = "$emit_type_info_python"
 # The import token is only for explicit ordering of the files, to process constants
 # and enums correctly. It does not impact the final generation of files, or the
 # language imports. Those are still auto-resolved.
@@ -703,13 +848,13 @@ RE_ENDPOINT_ROOT = re.compile(r"\${([_a-z]+)}")
 
 @dataclass(kw_only=True, frozen=True)
 class _EndpointPathDetails:
-    root: str
+    root: EndpointKey
     root_path: str
     resolved_path: str
 
 
 def _resolve_endpoint_path(
-    path: str, api_endpoints: dict[str, str]
+    path: str, api_endpoints: dict[EndpointKey, APIEndpointInfo]
 ) -> _EndpointPathDetails:
     root_path_source = path.split("/")[0]
     root_match = RE_ENDPOINT_ROOT.fullmatch(root_path_source)
@@ -717,7 +862,7 @@ def _resolve_endpoint_path(
         raise Exception(f"invalid-api-path-root:{root_path_source}")
 
     root_var = root_match.group(1)
-    root_path = api_endpoints[root_var]
+    root_path = api_endpoints[root_var].root_path
 
     _, *rest_path = path.split("/", 1)
     resolved_path = "/".join([root_path] + rest_path)
@@ -727,22 +872,75 @@ def _resolve_endpoint_path(
     )
 
 
-class SpecEndpoint:
-    method: RouteMethod
-    root: str
+class EndpointEmitType(StrEnum):
+    EMIT_ENDPOINT = "emit_endpoint"
+    EMIT_TYPES = "emit_types"
+    EMIT_NOTHING = "emit_nothing"
+
+
+@dataclass(kw_only=True, frozen=True)
+class EndpointSpecificPath:
+    root: EndpointKey
     path_root: str
     path_dirname: str
     path_basename: str
+    function: str | None
+
+
+def parse_endpoint_specific_path(
+    builder: SpecBuilder,
+    data_per_endpoint: RawDict | None,
+) -> EndpointSpecificPath | None:
+    if data_per_endpoint is None:
+        return None
+    util.check_fields(
+        data_per_endpoint,
+        [
+            "path",
+            "function",
+        ],
+    )
+
+    if "path" not in data_per_endpoint or data_per_endpoint["path"] is None:
+        return None
+
+    path = data_per_endpoint["path"].split("/")
+
+    assert len(path) > 1, "invalid-endpoint-path"
+
+    path_details = _resolve_endpoint_path(
+        data_per_endpoint["path"], builder.api_endpoints
+    )
+
+    result = EndpointSpecificPath(
+        function=data_per_endpoint.get("function"),
+        path_dirname="/".join(path[1:-1]),
+        path_basename=path[-1],
+        root=path_details.root,
+        path_root=path_details.root_path,
+    )
+
+    return result
+
+
+class SpecEndpoint:
+    method: RouteMethod
     data_loader: bool
-    is_sdk: bool
-    is_beta: bool
+    is_sdk: EndpointEmitType
+    stability_level: StabilityLevel | None
     # Don't emit TypeScript endpoint code
     suppress_ts: bool
-    function: Optional[str]
+    deprecated: bool = False
     async_batch_path: str | None = None
     result_type: ResultType = ResultType.json
     has_attachment: bool = False
     desc: str | None = None
+    account_type: str | None
+    route_group: str | None
+
+    # function, path details per api endpoint
+    path_per_api_endpoint: dict[str, EndpointSpecificPath]
+    default_endpoint_key: EndpointKey
 
     is_external: bool = False
 
@@ -750,15 +948,15 @@ class SpecEndpoint:
         pass
 
     def process(self, builder: SpecBuilder, data: RawDict) -> None:
-        unused(builder)
         util.check_fields(
             data,
             [
                 "method",
                 "path",
                 "data_loader",
+                "deprecated",
                 "is_sdk",
-                "is_beta",
+                "stability_level",
                 "async_batch_path",
                 "function",
                 "suppress_ts",
@@ -766,58 +964,121 @@ class SpecEndpoint:
                 "deprecated",
                 "result_type",
                 "has_attachment",
-            ],
+                "account_type",
+                "route_group",
+            ]
+            + list(builder.api_endpoints.keys()),
         )
         self.method = RouteMethod(data["method"])
 
-        path = data["path"].split("/")
-
-        assert len(path) > 1, "invalid-endpoint-path"
-
-        # handle ${external} in the same way we handle ${materials} for now
-        self.path_dirname = "/".join(path[1:-1])
-        self.path_basename = path[-1]
-
         data_loader = data.get("data_loader", False)
         assert isinstance(data_loader, bool)
         self.data_loader = data_loader
+        self.deprecated = data.get("deprecated", False)
+
+        is_sdk = data.get("is_sdk", EndpointEmitType.EMIT_NOTHING)
+
+        # backwards compatibility
+        if isinstance(is_sdk, bool):
+            if is_sdk is True:
+                is_sdk = EndpointEmitType.EMIT_ENDPOINT
+            else:
+                is_sdk = EndpointEmitType.EMIT_NOTHING
+        elif isinstance(is_sdk, str):
+            try:
+                is_sdk = EndpointEmitType(is_sdk)
+            except ValueError as e:
+                raise ValueError(f"Invalid value for is_sdk: {is_sdk}") from e
+
+        assert isinstance(is_sdk, EndpointEmitType)
 
-        is_sdk = data.get("is_sdk", False)
-        assert isinstance(is_sdk, bool)
         self.is_sdk = is_sdk
 
-        is_beta = data.get("is_beta", False)
-        assert isinstance(is_beta, bool)
-        self.is_beta = is_beta
+        route_group = data.get("route_group")
+        assert route_group is None or isinstance(route_group, str)
+        self.route_group = route_group
+
+        account_type = data.get("account_type")
+        assert account_type is None or isinstance(account_type, str)
+        self.account_type = account_type
+
+        stability_level_raw = data.get("stability_level")
+        assert stability_level_raw is None or isinstance(stability_level_raw, str)
+        self.stability_level = (
+            StabilityLevel(stability_level_raw)
+            if stability_level_raw is not None
+            else None
+        )
 
         async_batch_path = data.get("async_batch_path")
         if async_batch_path is not None:
             assert isinstance(async_batch_path, str)
             self.async_batch_path = async_batch_path
 
-        self.function = data.get("function")
-
         suppress_ts = data.get("suppress_ts", False)
         assert isinstance(suppress_ts, bool)
         self.suppress_ts = suppress_ts
 
         self.result_type = ResultType(data.get("result_type", ResultType.json.value))
-
-        path_details = _resolve_endpoint_path(data["path"], builder.api_endpoints)
-        self.root = path_details.root
-        self.path_root = path_details.root_path
+        self.has_attachment = data.get("has_attachment", False)
         self.desc = data.get("desc")
+
+        # compatibility with single-endpoint files
+        default_endpoint_path = parse_endpoint_specific_path(
+            builder,
+            {"path": data.get("path"), "function": data.get("function")},
+        )
+        if default_endpoint_path is not None:
+            assert default_endpoint_path.root in builder.api_endpoints, (
+                "Default endpoint is not a valid API endpoint"
+            )
+            self.default_endpoint_key = default_endpoint_path.root
+            self.path_per_api_endpoint = {
+                self.default_endpoint_key: default_endpoint_path,
+            }
+        else:
+            self.path_per_api_endpoint = {}
+            shared_function_name = None
+            for endpoint_key in builder.api_endpoints:
+                endpoint_specific_path = parse_endpoint_specific_path(
+                    builder,
+                    data.get(endpoint_key),
+                )
+                if endpoint_specific_path is not None:
+                    self.path_per_api_endpoint[endpoint_key] = endpoint_specific_path
+                    if endpoint_specific_path.function is not None:
+                        fn_name = endpoint_specific_path.function.split(".")[-1]
+                        if shared_function_name is None:
+                            shared_function_name = fn_name
+                        assert shared_function_name == fn_name
+
+            if builder.top_namespace in self.path_per_api_endpoint:
+                self.default_endpoint_key = builder.top_namespace
+            elif len(self.path_per_api_endpoint) == 1:
+                self.default_endpoint_key = next(
+                    iter(self.path_per_api_endpoint.keys())
+                )
+            else:
+                raise RuntimeError("no clear default endpoint")
+
+        assert len(self.path_per_api_endpoint) > 0, (
+            "Missing API endpoint path and function definitions for API call"
+        )
+
         # IMPROVE: remove need for is_external flag
-        self.is_external = self.path_root == "api/external"
-        self.has_attachment = data.get("has_attachment", False)
+        self.is_external = (
+            self.path_per_api_endpoint[self.default_endpoint_key].path_root
+            == "api/external"
+        )
 
-        assert (
-            not is_sdk or self.desc is not None
-        ), f"Endpoint description required for SDK endpoints, missing: {path}"
+        assert self.is_sdk != EndpointEmitType.EMIT_ENDPOINT or self.desc is not None, (
+            f"Endpoint description required for SDK endpoints, missing: {self.resolved_path}"
+        )
 
     @property
     def resolved_path(self: Self) -> str:
-        return f"{self.path_root}/{self.path_dirname}/{self.path_basename}"
+        default_endpoint_path = self.path_per_api_endpoint[self.default_endpoint_key]
+        return f"{default_endpoint_path.path_root}/{default_endpoint_path.path_dirname}/{default_endpoint_path.path_basename}"
 
 
 def _parse_const(
@@ -840,7 +1101,7 @@ def _parse_const(
         elif const_type.defn_type.name == BaseTypeName.s_dict:
             assert isinstance(value, dict)
             builder.ensure(
-                len(const_type.parameters) == 2, "constant-dict-expects-one-type"
+                len(const_type.parameters) == 2, "constant-dict-expects-two-types"
             )
             key_type = const_type.parameters[0]
             value_type = const_type.parameters[1]
@@ -884,7 +1145,14 @@ def _parse_const(
             return value
 
         if const_type.name == BaseTypeName.s_boolean:
-            builder.ensure(isinstance(value, bool), "invalid value for boolean constant")
+            builder.ensure(
+                isinstance(value, bool), "invalid value for boolean constant"
+            )
+            return value
+
+        if not const_type.is_base:
+            # IMPROVE: validate the object type properties before emission stage
+            builder.ensure(isinstance(value, dict), "invalid value for object constant")
             return value
 
     raise Exception("unsupported-const-scalar-type", const_type)
@@ -916,7 +1184,9 @@ class SpecConstant:
             assert isinstance(self.value, dict)
             # the parsing checks that the values are correct, so a simple length check
             # should be enough to check completeness
-            builder.ensure(len(key_type.values) == len(self.value), "incomplete-enum-map")
+            builder.ensure(
+                len(key_type.values) == len(self.value), "incomplete-enum-map"
+            )
 
 
 class SpecNamespace:
@@ -926,14 +1196,15 @@ class SpecNamespace:
     ):
         self.types: dict[str, SpecTypeDefn] = {}
         self.constants: dict[str, SpecConstant] = {}
-        self.endpoint: Optional[SpecEndpoint] = None
+        self.endpoint: SpecEndpoint | None = None
         self.emit_io_ts = False
         self.emit_type_info = False
+        self.emit_type_info_python = False
         self.derive_types_from_io_ts = False
-        self._imports: Optional[list[str]] = None
+        self._imports: list[str] | None = None
         self.path = name.split(".")
         self.name = self.path[-1]
-        self._order: Optional[int] = None
+        self._order: int | None = None
 
     def _update_order(self, builder: SpecBuilder, recurse: int = 0) -> int:
         if self._order is not None:
@@ -983,6 +1254,11 @@ class SpecNamespace:
                 self.emit_type_info = defn
                 continue
 
+            if name == TOKEN_EMIT_TYPE_INFO_PYTHON:
+                assert defn in (True, False)
+                self.emit_type_info_python = defn
+                continue
+
             if name == TOKEN_IMPORT:
                 assert self._imports is None
                 imports = [defn] if isinstance(defn, str) else defn
@@ -991,26 +1267,33 @@ class SpecNamespace:
                 continue
 
             if "value" in defn:
-                assert util.is_valid_property_name(
-                    name
-                ), f"{name} is not a valid constant name"
+                assert util.is_valid_property_name(name), (
+                    f"{name} is not a valid constant name"
+                )
                 spec_constant = SpecConstant(self, name)
                 self.constants[name] = spec_constant
                 continue
 
             assert util.is_valid_type_name(name), f"{name} is not a valid type name"
             assert name not in self.types, f"{name} is duplicate"
-            defn_type = defn["type"]
+            defn_type = defn.get("type")
+            assert isinstance(defn_type, str), f"{name} requires a string type"
             spec_type: SpecTypeDefn
             if defn_type == DefnTypeName.s_alias:
                 spec_type = SpecTypeDefnAlias(self, name)
+            elif defn_type == DefnTypeName.s_union:
+                spec_type = SpecTypeDefnUnion(self, name)
             elif defn_type == DefnTypeName.s_external:
                 spec_type = SpecTypeDefnExternal(self, name)
             elif defn_type == DefnTypeName.s_string_enum:
                 spec_type = SpecTypeDefnStringEnum(self, name)
             else:
                 parameters = (
-                    [parameter.name for parameter in parsed_name.parameters[0]]
+                    [
+                        parameter.name
+                        for name_parameters in parsed_name.parameters
+                        for parameter in name_parameters
+                    ]
                     if parsed_name.parameters is not None
                     else None
                 )
@@ -1026,28 +1309,46 @@ class SpecNamespace:
         Complete the definition of each type.
         """
         builder.push_where(self.name)
-        for full_name, defn in data.items():
-            parsed_name = parse_type_str(full_name)[0]
-            name = parsed_name.name
+        items_to_process: list[NameDataPair] = [
+            NameDataPair(full_name=full_name, data=defn)
+            for full_name, defn in data.items()
+        ]
+        while len(items_to_process) > 0:
+            deferred_items: list[NameDataPair] = []
+            for item in items_to_process:
+                full_name = item.full_name
+                defn = item.data
+                parsed_name = parse_type_str(full_name)[0]
+                name = parsed_name.name
+
+                if name in [
+                    TOKEN_EMIT_IO_TS,
+                    TOKEN_EMIT_TYPE_INFO,
+                    TOKEN_IMPORT,
+                    TOKEN_EMIT_TYPE_INFO_PYTHON,
+                ]:
+                    continue
 
-            if name in [TOKEN_EMIT_IO_TS, TOKEN_EMIT_TYPE_INFO, TOKEN_IMPORT]:
-                continue
+                builder.push_where(name)
 
-            builder.push_where(name)
+                if "value" in defn:
+                    spec_constant = self.constants[name]
+                    spec_constant.process(builder, defn)
 
-            if "value" in defn:
-                spec_constant = self.constants[name]
-                spec_constant.process(builder, defn)
+                elif name == TOKEN_ENDPOINT:
+                    assert self.endpoint
+                    self.endpoint.process(builder, defn)
 
-            elif name == TOKEN_ENDPOINT:
-                assert self.endpoint
-                self.endpoint.process(builder, defn)
-
-            else:
-                spec_type = self.types[name]
-                spec_type.process(builder, defn)
+                else:
+                    spec_type = self.types[name]
+                    if spec_type.can_process(builder, defn):
+                        spec_type.process(builder, defn)
+                    else:
+                        deferred_items.append(item)
 
-            builder.pop_where()
+                builder.pop_where()
+            assert len(deferred_items) < len(items_to_process)
+            items_to_process = [deferred for deferred in deferred_items]
 
         builder.pop_where()
 
@@ -1062,8 +1363,21 @@ class NamespaceDataPair:
     data: RawDict
 
 
+@dataclass(kw_only=True)
+class NameDataPair:
+    full_name: str
+    data: RawDict
+
+
 class SpecBuilder:
-    def __init__(self, *, api_endpoints: dict[str, str]) -> None:
+    def __init__(
+        self,
+        *,
+        api_endpoints: dict[EndpointKey, APIEndpointInfo],
+        top_namespace: str,
+        cross_output_paths: CrossOutputPaths | None,
+    ) -> None:
+        self.top_namespace = top_namespace
         self.where: list[str] = []
         self.namespaces = {}
         self.pending: list[NamespaceDataPair] = []
@@ -1072,6 +1386,7 @@ class SpecBuilder:
         self.examples: dict[str, list[SpecEndpointExample]] = defaultdict(list)
         self.guides: dict[SpecGuideKey, list[SpecGuide]] = defaultdict(list)
         self.api_endpoints = api_endpoints
+        self.cross_output_paths = cross_output_paths
         base_namespace = SpecNamespace(name=base_namespace_name)
         for base_type in BaseTypeName:
             defn = SpecTypeDefnObject(base_namespace, base_type, is_base=True)
@@ -1089,9 +1404,13 @@ class SpecBuilder:
         self.emit_id_source_enums: set[SpecTypeDefnStringEnum] = set()
 
         this_dir = os.path.dirname(os.path.realpath(__file__))
-        with open(f"{this_dir}/parts/base.py.prepart") as py_base_part:
+        with open(
+            f"{this_dir}/parts/base.py.prepart", encoding="utf-8"
+        ) as py_base_part:
             self.preparts["python"][base_namespace_name] = py_base_part.read()
-        with open(f"{this_dir}/parts/base.ts.prepart") as ts_base_part:
+        with open(
+            f"{this_dir}/parts/base.ts.prepart", encoding="utf-8"
+        ) as ts_base_part:
             self.preparts["typescript"][base_namespace_name] = ts_base_part.read()
 
         base_namespace.types["ObjectId"] = SpecTypeDefnObject(
@@ -1160,7 +1479,7 @@ class SpecBuilder:
         self,
         path: util.ParsedTypePath,
         namespace: SpecNamespace,
-        scope: Optional[SpecTypeDefn] = None,
+        scope: SpecTypeDefn | None = None,
         top: bool = False,
     ) -> SpecType:
         """
@@ -1218,8 +1537,10 @@ class SpecBuilder:
         if len(path) == 2:
             if isinstance(defn_type, SpecTypeDefnStringEnum):
                 assert path[1].parameters is None
+                statement = f"$import: [{defn_type.namespace.name}]"
                 self.ensure(
-                    path[1].name in defn_type.values, f"missing-enum-value: {path}"
+                    path[1].name in defn_type.values,
+                    f"missing-enum-value: {path} have you specified the dependency in an import statement: {statement}",
                 )
                 return SpecTypeLiteralWrapper(
                     value=path[1].name,
@@ -1241,11 +1562,13 @@ class SpecBuilder:
         )
 
     def parse_type(
-        self, namespace: SpecNamespace, spec: str, scope: Optional[SpecTypeDefn] = None
+        self, namespace: SpecNamespace, spec: str, scope: SpecTypeDefn | None = None
     ) -> SpecType:
         self.push_where(spec)
         parsed_type = util.parse_type_str(spec)
-        result = self._convert_parsed_type(parsed_type, namespace, top=True, scope=scope)
+        result = self._convert_parsed_type(
+            parsed_type, namespace, top=True, scope=scope
+        )
         self.pop_where()
         return result
 
@@ -1287,16 +1610,22 @@ class SpecBuilder:
         meta: dict[str, list[str]] = md.Meta  # type: ignore[attr-defined]
         title_meta: list[str] | None = meta.get("title")
         if title_meta is None:
-            raise Exception("guides requier a title in the meta section")
+            raise Exception("guides require a title in the meta section")
+        id_meta: list[str] | None = meta.get("id")
+        if id_meta is None:
+            raise Exception("guides require an id in the meta section")
 
         path_meta: list[str] | None = meta.get("path")
         guide_key: SpecGuideKey = RootGuideKey()
         if path_meta is not None:
-            path_details = _resolve_endpoint_path("".join(path_meta), self.api_endpoints)
+            path_details = _resolve_endpoint_path(
+                "".join(path_meta), self.api_endpoints
+            )
             guide_key = EndpointGuideKey(path=path_details.resolved_path)
 
         self.guides[guide_key].append(
             SpecGuide(
+                ref_name="".join(id_meta),
                 title="".join(title_meta),
                 html_content=html,
                 markdown_content=file_content,