UncountablePythonSDK 0.0.7__py3-none-any.whl → 0.0.92__py3-none-any.whl

pkgs/type_spec/builder.py

@@ -9,22 +9,34 @@ import os
 import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
-from enum import Enum, auto
-from typing import Any, Dict, Optional
+from enum import Enum, StrEnum, auto
+from typing import Any, Self
 
 from . import util
 from .util import parse_type_str, unused
 
-RawDict = Dict[Any, Any]
+RawDict = dict[Any, Any]
+EndpointKey = str
 
 
-class PropertyExtant(str, Enum):
+class StabilityLevel(StrEnum):
+    """These are currently used for open api,
+    see: https://github.com/Tufin/oasdiff/blob/main/docs/STABILITY.md
+    """
+
+    draft = "draft"
+    alpha = "alpha"
+    beta = "beta"
+    stable = "stable"
+
+
+class PropertyExtant(StrEnum):
     required = "required"
     optional = "optional"
     missing = "missing"
 
 
-class PropertyConvertValue(str, Enum):
+class PropertyConvertValue(StrEnum):
     # Base conversion on underlying types
     auto = "auto"
     # Always convert the value (Not needed yet, thus not supported)
@@ -36,7 +48,7 @@ class PropertyConvertValue(str, Enum):
 @dataclass
 class SpecProperty:
     name: str
-    label: Optional[str]
+    label: str | None
     spec_type: SpecType
     extant: PropertyExtant
     convert_value: PropertyConvertValue
@@ -52,7 +64,7 @@ class SpecProperty:
     ext_info: Any = None
 
 
-class NameCase(str, Enum):
+class NameCase(StrEnum):
     convert = "convert"
     preserve = "preserve"
     # Upper-case in JavaScript, convert otherwise. This is a compatibilty
@@ -60,7 +72,7 @@ class NameCase(str, Enum):
     js_upper = "js_upper"
 
 
-class BaseTypeName(str, Enum):
+class BaseTypeName(StrEnum):
     """
     Base types that are supported.
     """
@@ -86,13 +98,14 @@ class BaseTypeName(str, Enum):
     s_optional = "Optional"
     s_string = "String"
     s_tuple = "Tuple"
+    s_readonly_array = "ReadonlyArray"
     s_union = "Union"
 
     # For a root class that defines properties
     s_object = "Object"
 
 
-class DefnTypeName(str, Enum):
+class DefnTypeName(StrEnum):
     # Type is a named alias of another type
     s_alias = "Alias"
     # Type is imported from an external source (opaque to type_spec)
@@ -101,6 +114,8 @@ class DefnTypeName(str, Enum):
     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"
@@ -184,6 +199,35 @@ class SpecTypeInstance(SpecType):
         return defn_type + self.parameters
 
 
+@dataclass(kw_only=True)
+class SpecEndpointExample:
+    summary: str
+    description: str
+    arguments: dict[str, object]
+    data: dict[str, object]
+
+
+@dataclass(kw_only=True)
+class SpecGuide:
+    ref_name: str
+    title: str
+    markdown_content: str
+    html_content: str
+
+
+@dataclass(kw_only=True, frozen=True)
+class RootGuideKey:
+    pass
+
+
+@dataclass(kw_only=True, frozen=True)
+class EndpointGuideKey:
+    path: str
+
+
+SpecGuideKey = RootGuideKey | EndpointGuideKey
+
+
 class SpecTypeLiteralWrapper(SpecType):
     def __init__(
         self,
@@ -212,7 +256,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
     ):
@@ -240,7 +284,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
@@ -250,6 +294,7 @@ 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.ext_info: Any = None
 
     def is_value_converted(self) -> bool:
@@ -261,20 +306,38 @@ 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",
+            ]
+            + 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
+
     def _process_property(
         self, builder: SpecBuilder, spec_name: str, data: RawDict
     ) -> SpecProperty:
@@ -313,9 +376,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")
@@ -393,7 +456,7 @@ class SpecTypeGenericParameter(SpecType):
 
 
 class SpecTypeDefnObject(SpecTypeDefn):
-    base: Optional[SpecTypeDefnObject]
+    base: SpecTypeDefnObject | None
     parameters: list[str]
 
     def __init__(
@@ -401,7 +464,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,
@@ -418,7 +481,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
 
@@ -489,13 +552,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):
@@ -517,13 +575,65 @@ 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()
+                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()
+
+    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]
 
@@ -553,7 +663,7 @@ class SpecTypeDefnExternal(SpecTypeDefn):
 class StringEnumEntry:
     name: str
     value: str
-    label: Optional[str] = None
+    label: str | None = None
     deprecated: bool = False
 
 
@@ -569,17 +679,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)
@@ -617,10 +742,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:
@@ -642,9 +770,18 @@ 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"
@@ -656,7 +793,7 @@ TOKEN_EMIT_TYPE_INFO = "$emit_type_info"
 TOKEN_IMPORT = "$import"
 
 
-class RouteMethod(str, Enum):
+class RouteMethod(StrEnum):
     post = "post"
     get = "get"
     delete = "delete"
@@ -664,7 +801,7 @@ class RouteMethod(str, Enum):
     put = "put"
 
 
-class ResultType(str, Enum):
+class ResultType(StrEnum):
     json = "json"
     binary = "binary"
 
@@ -672,20 +809,108 @@ class ResultType(str, Enum):
 RE_ENDPOINT_ROOT = re.compile(r"\${([_a-z]+)}")
 
 
-class SpecEndpoint:
-    method: RouteMethod
-    root: str
+@dataclass(kw_only=True, frozen=True)
+class _EndpointPathDetails:
+    root: EndpointKey
+    root_path: str
+    resolved_path: str
+
+
+def _resolve_endpoint_path(
+    path: str, api_endpoints: dict[EndpointKey, str]
+) -> _EndpointPathDetails:
+    root_path_source = path.split("/")[0]
+    root_match = RE_ENDPOINT_ROOT.fullmatch(root_path_source)
+    if root_match is None:
+        raise Exception(f"invalid-api-path-root:{root_path_source}")
+
+    root_var = root_match.group(1)
+    root_path = api_endpoints[root_var]
+
+    _, *rest_path = path.split("/", 1)
+    resolved_path = "/".join([root_path] + rest_path)
+
+    return _EndpointPathDetails(
+        root=root_var, root_path=root_path, resolved_path=resolved_path
+    )
+
+
+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_sdk: EndpointEmitType
+    is_beta: bool
+    stability_level: StabilityLevel | None
     # Don't emit TypeScript endpoint code
     suppress_ts: bool
-    function: Optional[str]
+    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
+
+    # to be deprecated in favor of path_per_api_endpoint:
+    # default function, path details
+    function: str | None
+    root: EndpointKey
+    path_root: str
+    path_dirname: str
+    path_basename: str
+
+    # function, path details per api endpoint
+    path_per_api_endpoint: dict[str, EndpointSpecificPath]
 
     is_external: bool = False
 
@@ -701,51 +926,122 @@ class SpecEndpoint:
                 "path",
                 "data_loader",
                 "is_sdk",
+                "is_beta",
+                "stability_level",
+                "async_batch_path",
                 "function",
                 "suppress_ts",
                 "desc",
                 "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
 
-        is_sdk = data.get("is_sdk", False)
-        assert isinstance(is_sdk, bool)
+        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:
+                raise ValueError(f"Invalid value for is_sdk: {is_sdk}")
+
+        assert isinstance(is_sdk, EndpointEmitType)
+
         self.is_sdk = is_sdk
 
-        self.function = data.get("function")
+        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
+
+        is_beta = data.get("is_beta", False)
+        assert isinstance(is_beta, bool)
+        self.is_beta = is_beta
+
+        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
 
         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))
-
+        self.has_attachment = data.get("has_attachment", False)
         self.desc = data.get("desc")
 
-        root_match = RE_ENDPOINT_ROOT.fullmatch(path[0])
-        if root_match is None:
-            raise Exception(f"invalid-api-path-root:{path[0]}")
+        default_endpoint_path = parse_endpoint_specific_path(
+            builder,
+            {"path": data.get("path"), "function": data.get("function")},
+        )
+        if default_endpoint_path is not None:
+            self.root = default_endpoint_path.root
+            self.path_per_api_endpoint = {
+                self.root: 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
+            assert self.path_per_api_endpoint != {}
+
+            assert builder.top_namespace in self.path_per_api_endpoint
+            self.root = builder.top_namespace
+
+        default_endpoint_path = self.path_per_api_endpoint[self.root]
+        self.function = default_endpoint_path.function
+        self.path_dirname = default_endpoint_path.path_dirname
+        self.path_basename = default_endpoint_path.path_basename
+        self.path_root = default_endpoint_path.path_root
 
-        self.root = root_match.group(1)
-        self.path_root = builder.api_endpoints[self.root]
         # IMPROVE: remove need for is_external flag
         self.is_external = self.path_root == "api/external"
-        self.has_attachment = data.get("has_attachment", False)
+
+        assert self.is_sdk != EndpointEmitType.EMIT_ENDPOINT or self.desc is not None, (
+            f"Endpoint description required for SDK endpoints, missing: {self.path_dirname}/{self.path_basename}"
+        )
+
+    @property
+    def resolved_path(self: Self) -> str:
+        return f"{self.path_root}/{self.path_dirname}/{self.path_basename}"
 
 
 def _parse_const(
@@ -812,7 +1108,9 @@ 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
 
     raise Exception("unsupported-const-scalar-type", const_type)
@@ -844,7 +1142,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:
@@ -854,14 +1154,14 @@ 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.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:
@@ -919,9 +1219,9 @@ 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
@@ -932,13 +1232,19 @@ class SpecNamespace:
             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
                 )
@@ -954,28 +1260,41 @@ 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]:
+                    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()
 
@@ -990,13 +1309,24 @@ 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, str], top_namespace: str
+    ) -> None:
+        self.top_namespace = top_namespace
         self.where: list[str] = []
         self.namespaces = {}
         self.pending: list[NamespaceDataPair] = []
         self.parts: dict[str, dict[str, str]] = defaultdict(dict)
         self.preparts: dict[str, dict[str, str]] = defaultdict(dict)
+        self.examples: dict[str, list[SpecEndpointExample]] = defaultdict(list)
+        self.guides: dict[SpecGuideKey, list[SpecGuide]] = defaultdict(list)
         self.api_endpoints = api_endpoints
         base_namespace = SpecNamespace(name=base_namespace_name)
         for base_type in BaseTypeName:
@@ -1086,7 +1416,7 @@ class SpecBuilder:
         self,
         path: util.ParsedTypePath,
         namespace: SpecNamespace,
-        scope: Optional[SpecTypeDefn] = None,
+        scope: SpecTypeDefn | None = None,
         top: bool = False,
     ) -> SpecType:
         """
@@ -1167,11 +1497,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
 
@@ -1181,5 +1513,59 @@ class SpecBuilder:
     def add_prepart_file(self, target: str, name: str, data: str) -> None:
         self.preparts[target][name] = data
 
+    def add_example_file(self, data: dict[str, object]) -> None:
+        path_details = _resolve_endpoint_path(str(data["path"]), self.api_endpoints)
+
+        examples_data = data["examples"]
+        if not isinstance(examples_data, list):
+            raise Exception(
+                f"'examples' in example files are expected to be a list, endpoint_path={path_details.resolved_path}"
+            )
+        for example in examples_data:
+            arguments = example["arguments"]
+            data_example = example["data"]
+            if not isinstance(arguments, dict) or not isinstance(data_example, dict):
+                raise Exception(
+                    f"'arguments' and 'data' fields must be dictionaries for each endpoint example, endpoint={path_details.resolved_path}"
+                )
+            self.examples[path_details.resolved_path].append(
+                SpecEndpointExample(
+                    summary=str(example["summary"]),
+                    description=str(example["description"]),
+                    arguments=arguments,
+                    data=data_example,
+                )
+            )
+
+    def add_guide_file(self, file_content: str) -> None:
+        import markdown
+
+        md = markdown.Markdown(extensions=["meta"])
+        html = md.convert(file_content)
+        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 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
+            )
+            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,
+            )
+        )
+
     def resolve_proper_name(self, stype: SpecTypeDefn) -> str:
         return f"{'.'.join(stype.namespace.path)}.{stype.name}"