UncountablePythonSDK 0.0.83__py3-none-any.whl → 0.0.132__py3-none-any.whl

pkgs/type_spec/emit_python.py

@@ -2,18 +2,19 @@ import dataclasses
 import io
 import os
 from decimal import Decimal
-from typing import Any, Optional
+from typing import Any
 
 from . import builder, util
+from .builder import EndpointEmitType, EndpointSpecificPath, base_namespace_name
 from .config import PythonConfig
+from .cross_output_links import get_path_links
+from .emit_open_api_util import EmitOpenAPIStabilityLevel
 
 INDENT = "    "
 LINE_BREAK = "\n"
 MODIFY_NOTICE = "# DO NOT MODIFY -- This file is generated by type_spec\n"
 # Turn excess line length warning and turn off ruff formatting
-LINT_HEADER = (
-    "# flake8: noqa: F821\n# ruff: noqa: E402 Q003\n# fmt: off\n# isort: skip_file\n"
-)
+LINT_HEADER = "# ruff: noqa: E402 Q003\n# fmt: off\n# isort: skip_file\n"
 LINT_FOOTER = "# fmt: on\n"
 ROUTE_NOTICE = """# Routes are generated from $endpoint specifications in the
 # type_spec API YAML files. Refer to the section on endpoints in the type_spec/README"""
@@ -34,10 +35,15 @@ QUEUED_BATCH_REQUEST_STYPE = builder.SpecTypeDefnObject(
     namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="QueuedAsyncBatchRequest"
 )
 
+CLIENT_CONFIG_TYPE_NAMESPACE = builder.SpecNamespace(name="client_config")
+REQUEST_OPTIONS_STYPE = builder.SpecTypeDefnObject(
+    namespace=CLIENT_CONFIG_TYPE_NAMESPACE, name="RequestOptions"
+)
+
 
 @dataclasses.dataclass(kw_only=True)
 class TrackingContext:
-    namespace: Optional[builder.SpecNamespace] = None
+    namespace: builder.SpecNamespace | None = None
     namespaces: set[builder.SpecNamespace] = dataclasses.field(default_factory=set)
     names: set[str] = dataclasses.field(default_factory=set)
 
@@ -45,6 +51,7 @@ class TrackingContext:
     use_serial_string_enum: bool = False
     use_dataclass: bool = False
     use_serial_union: bool = False
+    use_serial_alias: bool = False
     use_missing: bool = False
     use_opaque_key: bool = False
 
@@ -115,26 +122,36 @@ def _check_type_match(stype: builder.SpecType, value: Any) -> bool:
     raise Exception("invalid type", stype, value)
 
 
-def _emit_value(ctx: TrackingContext, stype: builder.SpecType, value: Any) -> str:
+def _emit_value(
+    ctx: TrackingContext, stype: builder.SpecType, value: Any, indent: int = 0
+) -> str:
     literal = builder.unwrap_literal_type(stype)
     if literal is not None:
         return _emit_value(ctx, literal.value_type, literal.value)
 
     if stype.is_base_type(builder.BaseTypeName.s_string):
-        assert isinstance(value, str)
+        assert isinstance(value, str), (
+            f"Expected str value for {stype.name} but got {value}"
+        )
         return util.encode_common_string(value)
     elif stype.is_base_type(builder.BaseTypeName.s_integer):
-        assert isinstance(value, int)
+        assert isinstance(value, int), (
+            f"Expected int value for {stype.name} but got {value}"
+        )
         return str(value)
     elif stype.is_base_type(builder.BaseTypeName.s_boolean):
-        assert isinstance(value, bool)
+        assert isinstance(value, bool), (
+            f"Expected bool value for {stype.name} but got {value}"
+        )
         return "True" if value else "False"
     elif stype.is_base_type(builder.BaseTypeName.s_decimal) or stype.is_base_type(
         builder.BaseTypeName.s_lossy_decimal
     ):
         # Note that decimal requires the `!decimal 123.12` style notation in the YAML
         # file since PyYaml parses numbers as float, unfortuantely
-        assert isinstance(value, (Decimal, int))
+        assert isinstance(value, (Decimal, int)), (
+            f"Expected decimal value for {stype.name} but got {value} (type: {type(value)})"
+        )
         if isinstance(value, int):
             # skip quotes for integers
             return f"Decimal({value})"
@@ -149,14 +166,14 @@ def _emit_value(ctx: TrackingContext, stype: builder.SpecType, value: Any) -> st
             key_type = stype.parameters[0]
             value_type = stype.parameters[1]
             return (
-                "{\n    "
-                + ",\n    ".join(
+                f"{{\n{INDENT * (indent + 1)}"
+                + f",\n{INDENT * (indent + 1)}".join(
                     _emit_value(ctx, key_type, dkey)
                     + ": "
-                    + _emit_value(ctx, value_type, dvalue)
+                    + _emit_value(ctx, value_type, dvalue, indent=indent + 1)
                     for dkey, dvalue in value.items()
                 )
-                + "\n}"
+                + f"\n{INDENT * indent}}}"
             )
 
         if stype.defn_type.is_base_type(builder.BaseTypeName.s_optional):
@@ -182,6 +199,34 @@ def _emit_value(ctx: TrackingContext, stype: builder.SpecType, value: Any) -> st
         return f"{refer_to(ctx, stype)}.{_resolve_enum_name(value, stype.name_case)}"
     elif isinstance(stype, builder.SpecTypeDefnAlias):
         return _emit_value(ctx, stype.alias, value)
+    elif isinstance(stype, builder.SpecTypeDefnObject):
+        assert isinstance(value, dict), (
+            f"Expected dict value for {stype.name} but got {value}"
+        )
+        if not stype.is_hashable:
+            raise Exception("invalid constant object type, non-hashable", value, stype)
+        obj_out = f"{refer_to(ctx, stype)}("
+        emitted_fields: set[str] = set()
+        for prop_name, prop in (stype.properties or {}).items():
+            if prop_name not in value:
+                continue
+            else:
+                value_to_emit = value[prop_name]
+            emitted_fields.add(prop_name)
+            py_name = python_field_name(prop.name, prop.name_case)
+            obj_out += f"\n{INDENT * (indent + 1)}{py_name}={_emit_value(ctx, prop.spec_type, value_to_emit, indent=indent + 1)},"
+        whitespace = f"\n{INDENT * indent}" if len(emitted_fields) > 0 else ""
+        obj_out += f"{whitespace})"
+
+        if emitted_fields != set(value.keys()):
+            raise Exception(
+                "invalid object type, extra fields found:",
+                value,
+                stype,
+                set(value.keys()) - emitted_fields,
+            )
+
+        return obj_out
 
     raise Exception("invalid constant type", value, stype)
 
@@ -219,12 +264,14 @@ def _emit_types_imports(*, out: io.StringIO, ctx: Context) -> None:
     out.write("import datetime  # noqa: F401\n")
     out.write("from decimal import Decimal  # noqa: F401\n")
     if ctx.use_enum:
-        out.write("from pkgs.strenum_compat import StrEnum\n")
+        out.write("from enum import StrEnum\n")
     if ctx.use_dataclass:
         out.write("import dataclasses\n")
         out.write("from pkgs.serialization import serial_class\n")
     if ctx.use_serial_union:
         out.write("from pkgs.serialization import serial_union_annotation\n")
+    if ctx.use_serial_alias:
+        out.write("from pkgs.serialization import serial_alias_annotation\n")
     if ctx.use_serial_string_enum:
         out.write("from pkgs.serialization import serial_string_enum\n")
     if ctx.use_missing:
@@ -249,7 +296,7 @@ def _emit_types(*, builder: builder.SpecBuilder, config: PythonConfig) -> None:
     ):
         if (
             namespace.endpoint is not None
-            and not namespace.endpoint.is_sdk
+            and namespace.endpoint.is_sdk == EndpointEmitType.EMIT_NOTHING
             and config.sdk_endpoints_only is True
         ):
             continue
@@ -340,16 +387,44 @@ def _emit_types(*, builder: builder.SpecBuilder, config: PythonConfig) -> None:
 
 ENDPOINT_METHOD = "ENDPOINT_METHOD"
 ENDPOINT_PATH = "ENDPOINT_PATH"
+# will be removed in Q1 2025 when ENDPOINT_PATH is made api_endpoint-agnostic
+# is used when the API call has multiple endpoints for the one endpoint that isn't equal to the top_namespace
+ENDPOINT_PATH_ALTERNATE = "ENDPOINT_PATH_ALTERNATE"
+
+
+def _get_epf_root(endpoint_specific_path: EndpointSpecificPath) -> str:
+    return endpoint_specific_path.root
 
 
 def _emit_namespace(ctx: Context, namespace: builder.SpecNamespace) -> None:
     endpoint = namespace.endpoint
     if endpoint is not None:
+        path_links = get_path_links(
+            ctx.builder.cross_output_paths,
+            namespace,
+            current_path_type="Python",
+            endpoint=endpoint,
+        )
+        if path_links != "":
+            ctx.out.write("\n")
+            ctx.out.write(path_links)
+
         ctx.out.write("\n")
         ctx.out.write(f'{ENDPOINT_METHOD} = "{endpoint.method.upper()}"\n')
-        ctx.out.write(
-            f'{ENDPOINT_PATH} = "{endpoint.path_root}/{endpoint.path_dirname}/{endpoint.path_basename}"\n'
-        )
+        for endpoint_specific_path in sorted(
+            endpoint.path_per_api_endpoint.values(), key=_get_epf_root
+        ):
+            endpoint_path_name = ENDPOINT_PATH
+
+            if (
+                len(endpoint.path_per_api_endpoint.keys()) > 1
+                and endpoint_specific_path.root != ctx.builder.top_namespace
+            ):
+                endpoint_path_name = ENDPOINT_PATH_ALTERNATE
+                ctx.names.add(ENDPOINT_PATH_ALTERNATE)
+            ctx.out.write(
+                f'{endpoint_path_name} = "{endpoint_specific_path.path_root}/{endpoint_specific_path.path_dirname}/{endpoint_specific_path.path_basename}"\n'
+            )
 
         ctx.names.add(ENDPOINT_METHOD)
         ctx.names.add(ENDPOINT_PATH)
@@ -439,8 +514,23 @@ def _emit_endpoint_invocation_function_signature(
         else []
     ) + (extra_params if extra_params is not None else [])
 
-    assert endpoint.function is not None
-    function_name = endpoint.function.split(".")[-1]
+    request_options_property = builder.SpecProperty(
+        name="_request_options",
+        label="_request_options",
+        spec_type=REQUEST_OPTIONS_STYPE,
+        extant=builder.PropertyExtant.optional,
+        convert_value=builder.PropertyConvertValue.auto,
+        name_case=builder.NameCase.convert,
+        default=None,
+        has_default=True,
+        desc=None,
+    )
+    all_arguments.append(request_options_property)
+
+    # All endpoints share a function name
+    function = endpoint.path_per_api_endpoint[endpoint.default_endpoint_key].function
+    assert function is not None
+    function_name = function.split(".")[-1]
     ctx.out.write(
         f"""
     def {function_name}(
@@ -486,7 +576,10 @@ def _emit_async_batch_invocation_function(
     endpoint = namespace.endpoint
     if endpoint is None:
         return
-    if endpoint.async_batch_path is None or not endpoint.is_sdk:
+    if (
+        endpoint.async_batch_path is None
+        or endpoint.is_sdk != EndpointEmitType.EMIT_ENDPOINT
+    ):
         return
 
     ctx.out.write("\n")
@@ -568,7 +661,10 @@ def _emit_endpoint_invocation_function(
     endpoint = namespace.endpoint
     if endpoint is None:
         return
-    if not endpoint.is_sdk or endpoint.is_beta:
+    if (
+        endpoint.is_sdk != EndpointEmitType.EMIT_ENDPOINT
+        or endpoint.stability_level == EmitOpenAPIStabilityLevel.draft
+    ):
         return
 
     ctx.out.write("\n")
@@ -601,6 +697,7 @@ def _emit_endpoint_invocation_function(
             method={refer_to(ctx=ctx, stype=endpoint_method_stype)},
             endpoint={refer_to(ctx=ctx, stype=endpoint_path_stype)},
             args=args,
+            request_options=_request_options,
         )
         return self.do_request(api_request=api_request, return_type={refer_to(ctx=ctx, stype=data_type)})"""
     )
@@ -695,39 +792,43 @@ def _emit_properties(
     if len(properties) > 0:
 
         def write_field(prop: builder.SpecProperty) -> None:
+            stype = prop.spec_type
             if prop.name_case == builder.NameCase.preserve:
                 unconverted_keys.add(prop.name)
             py_name = python_field_name(prop.name, prop.name_case)
 
             if prop.convert_value == builder.PropertyConvertValue.no_convert:
                 unconverted_values.add(py_name)
-            elif not prop.spec_type.is_value_converted():
+            elif not stype.is_value_converted():
                 assert prop.convert_value == builder.PropertyConvertValue.auto
                 unconverted_values.add(py_name)
-            if prop.spec_type.is_value_to_string():
+            if stype.is_value_to_string():
                 to_string_values.add(py_name)
 
             if prop.parse_require:
                 parse_require.add(py_name)
 
-            ref_type = refer_to(ctx, prop.spec_type)
+            ref_type = refer_to(ctx, stype)
             default = None
             if prop.extant == builder.PropertyExtant.missing:
                 ref_type = f"MissingType[{ref_type}]"
                 default = "MISSING_SENTRY"
                 ctx.use_missing = True
             elif prop.extant == builder.PropertyExtant.optional:
-                ref_type = f"typing.Optional[{ref_type}]"
+                if isinstance(
+                    stype, builder.SpecTypeInstance
+                ) and stype.defn_type.is_base_type(builder.BaseTypeName.s_optional):
+                    pass  # base type already adds the None union
+                elif ref_type == "None":
+                    pass  # no need to add a None union to a none type
+                else:
+                    ref_type = f"{ref_type} | None"
                 default = "None"
             elif prop.has_default:
-                default = _emit_value(ctx, prop.spec_type, prop.default)
+                default = _emit_value(ctx, stype, prop.default)
                 if (
-                    isinstance(prop.spec_type, builder.SpecTypeInstance)
-                    and (
-                        prop.spec_type.defn_type.is_base_type(
-                            builder.BaseTypeName.s_list
-                        )
-                    )
+                    isinstance(stype, builder.SpecTypeInstance)
+                    and (stype.defn_type.is_base_type(builder.BaseTypeName.s_list))
                     and default == "[]"
                 ):
                     default = "dataclasses.field(default_factory=list)"
@@ -779,7 +880,17 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
         return
 
     if isinstance(stype, builder.SpecTypeDefnAlias):
-        ctx.out.write(f"{stype.name} = {refer_to(ctx, stype.alias)}\n")
+        ctx.use_serial_alias = True
+        ctx.out.write(f"{stype.name} = typing.Annotated[\n")
+        ctx.out.write(f"{INDENT}{refer_to(ctx, stype.alias)},\n")
+        ctx.out.write(f"{INDENT}serial_alias_annotation(\n")
+        ctx.out.write(
+            f"{INDENT}named_type_path={util.encode_common_string(_named_type_path(ctx, stype))},\n"
+        )
+        if stype.is_dynamic_allowed():
+            ctx.out.write(f"{INDENT}is_dynamic_allowed=True,\n")
+        ctx.out.write(f"{INDENT}),\n")
+        ctx.out.write("]\n")
         return
 
     if isinstance(stype, builder.SpecTypeDefnUnion):
@@ -790,6 +901,8 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
         ctx.out.write(
             f"{INDENT}named_type_path={util.encode_common_string(_named_type_path(ctx, stype))},\n"
         )
+        if stype.is_dynamic_allowed():
+            ctx.out.write(f"{INDENT}is_dynamic_allowed=True,\n")
         if stype.discriminator is not None:
             ctx.out.write(
                 f"{INDENT * 2}discriminator={util.encode_common_string(stype.discriminator)},\n"
@@ -818,7 +931,7 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
     if not stype.base.is_base:
         base_class = f"({refer_to(ctx, stype.base)})"
     elif len(generics) > 0:
-        base_class = f"(typing.Generic[{', '.join(generics)}])"
+        base_class = f"[{', '.join(generics)}]"
     class_out.write(f"class {stype.name}{base_class}:\n")
 
     emitted_properties_metadata = _emit_type_properties(
@@ -836,6 +949,8 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
     ctx.out.write(
         f"{INDENT}named_type_path={util.encode_common_string(_named_type_path(ctx, stype))},\n"
     )
+    if stype.is_dynamic_allowed():
+        ctx.out.write(f"{INDENT}is_dynamic_allowed=True,\n")
 
     def write_values(key: str, values: set[str]) -> None:
         if len(values) == 0:
@@ -852,13 +967,19 @@ def _emit_type(ctx: Context, stype: builder.SpecType) -> None:
 
     # Emit dataclass decorator
     dataclass = "@dataclasses.dataclass"
-    dc_args = []
+    refer_to(
+        ctx,
+        builder.SpecTypeDefnAlias(
+            namespace=ctx.builder.namespaces[base_namespace_name], name="ENABLE_SLOTS"
+        ),
+    )
+    dc_args = ["slots=base_t.ENABLE_SLOTS"]
     if stype.is_kw_only():
         dc_args.append("kw_only=True")
     if stype.is_hashable:
         dc_args.extend(["frozen=True", "eq=True"])
     if len(dc_args) > 0:
-        dataclass += f"({', '.join(dc_args)})"
+        dataclass += f"({', '.join(dc_args)})  # type: ignore[literal-required]"
 
     ctx.out.write(f"{dataclass}\n")
     ctx.out.write(class_out.getvalue())
@@ -903,13 +1024,22 @@ base_name_map = {
 
 def refer_to(ctx: TrackingContext, stype: builder.SpecType) -> str:
     if isinstance(stype, builder.SpecTypeInstance):
-        params = ", ".join([refer_to(ctx, p) for p in stype.parameters])
+        params = [refer_to(ctx, p) for p in stype.parameters]
+
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_union):
+            if len(stype.parameters) == 1:
+                return f"typing.Union[{params[0]}]"
+            return " | ".join(params)
 
         if stype.defn_type.is_base_type(builder.BaseTypeName.s_readonly_array):
-            assert len(stype.parameters) == 1, "Read Only Array takes one parameter"
-            params = f"{params}, ..."
+            assert len(params) == 1, "Read Only Array takes one parameter"
+            return f"tuple[{params[0]}, ...]"
 
-        return f"{refer_to(ctx, stype.defn_type)}[{params}]"
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_optional):
+            assert len(params) == 1, "Optional only takes one parameter"
+            return f"{params[0]} | None"
+
+        return f"{refer_to(ctx, stype.defn_type)}[{', '.join(params)}]"
 
     if isinstance(stype, builder.SpecTypeLiteralWrapper):
         return _emit_value(ctx, stype.value_type, stype.value)
@@ -935,23 +1065,21 @@ def refer_to(ctx: TrackingContext, stype: builder.SpecType) -> str:
 SpecEndpoint = builder.SpecEndpoint
 
 
-def _route_identifier(endpoint: builder.SpecEndpoint) -> tuple[str, str, str]:
-    return (endpoint.path_dirname, endpoint.path_basename, endpoint.method)
-
-
 def _emit_routes(*, builder: builder.SpecBuilder, config: PythonConfig) -> None:
     for endpoint_root in builder.api_endpoints:
         endpoints: list[SpecEndpoint] = []
         output = config.routes_output.get(endpoint_root)
         if output is None:
             continue
+        last_endpoint: SpecEndpoint | None = None
         for namespace in builder.namespaces.values():
             endpoint = namespace.endpoint
+            last_endpoint = endpoint
             if endpoint is None:
                 continue
-            if endpoint.root != endpoint_root:
+            if endpoint_root not in endpoint.path_per_api_endpoint:
                 continue
-            if endpoint.function is None:
+            if endpoint.path_per_api_endpoint[endpoint_root].function is None:
                 continue
 
             endpoints.append(endpoint)
@@ -964,6 +1092,15 @@ def _emit_routes(*, builder: builder.SpecBuilder, config: PythonConfig) -> None:
 from main.site.framework.types import StaticRouteType
 """
         )
+
+        def _route_identifier(endpoint: SpecEndpoint) -> tuple[str, str, str]:
+            endpoint_specific_path = endpoint.path_per_api_endpoint[endpoint_root]
+            return (
+                endpoint_specific_path.path_dirname,
+                endpoint_specific_path.path_basename,
+                endpoint.method,
+            )
+
         sorted_endpoints = sorted(endpoints, key=_route_identifier)
 
         assert len(endpoints) == len(set(map(_route_identifier, endpoints))), (
@@ -972,17 +1109,21 @@ from main.site.framework.types import StaticRouteType
 
         path_set = set()
         for endpoint in sorted_endpoints:
-            assert endpoint.function
-            func_bits = endpoint.function.split(".")
+            last_endpoint = endpoint
+            endpoint_function_path = endpoint.path_per_api_endpoint[endpoint_root]
+            assert endpoint_function_path.function
+            func_bits = endpoint_function_path.function.split(".")
             path = ".".join(func_bits[:-1])
             if path in path_set:
                 continue
             path_set.add(path)
             static_out.write(f"import {path}\n")
 
+        assert last_endpoint is not None
+
         static_out.write(
             f"""
-ROUTE_PREFIX = "/{endpoint.path_root}"
+ROUTE_PREFIX = "/{last_endpoint.path_per_api_endpoint[endpoint_root].path_root}"
 
 ROUTES: list[StaticRouteType] = [
 """
@@ -996,20 +1137,21 @@ ROUTES: list[StaticRouteType] = [
 
 from main.site.framework.types import DynamicRouteType
 
-ROUTE_PREFIX = "/{endpoint.path_root}"
+ROUTE_PREFIX = "/{last_endpoint.path_per_api_endpoint[endpoint_root].path_root}"
 
 ROUTES: list[DynamicRouteType] = [
 """
         )
 
         for endpoint in sorted_endpoints:
+            endpoint_function_path = endpoint.path_per_api_endpoint[endpoint_root]
             dynamic_out.write(
-                f'{INDENT}("{endpoint.path_dirname}/{endpoint.path_basename}", "{endpoint.function}", ["{endpoint.method.upper()}"]),\n'
+                f'{INDENT}("{endpoint_function_path.path_dirname}/{endpoint_function_path.path_basename}", "{endpoint_function_path.function}", ["{endpoint.method.upper()}"]),\n'
             )
 
-            assert endpoint.function
+            assert endpoint_function_path.function
             static_out.write(
-                f'{INDENT}("{endpoint.path_dirname}/{endpoint.path_basename}", {endpoint.function}, ["{endpoint.method.upper()}"]),\n'
+                f'{INDENT}("{endpoint_function_path.path_dirname}/{endpoint_function_path.path_basename}", {endpoint_function_path.function}, ["{endpoint.method.upper()}"]),\n'
             )
 
         dynamic_out.write(f"{MODIFY_NOTICE}]\n")
@@ -1025,15 +1167,21 @@ def _emit_namespace_imports(
     *,
     out: io.StringIO,
     namespaces: set[builder.SpecNamespace],
-    from_namespace: Optional[builder.SpecNamespace],
+    from_namespace: builder.SpecNamespace | None,
     config: PythonConfig,
+    skip_non_sdk: bool = False,
 ) -> None:
     for ns in sorted(
         namespaces,
         key=lambda name: _resolve_namespace_name(name),
     ):
+        if (
+            skip_non_sdk
+            and ns.endpoint is not None
+            and ns.endpoint.is_sdk != EndpointEmitType.EMIT_ENDPOINT
+        ):
+            continue
         resolved = _resolve_namespace_name(ns)
-        ref = _resolve_namespace_ref(ns)
         if ns.endpoint is not None:
             import_alias = "_".join(ns.path[2:]) + "_t"
             out.write(
@@ -1057,8 +1205,8 @@ def _emit_id_source(*, builder: builder.SpecBuilder, config: PythonConfig) -> No
         return None
     enum_out = io.StringIO()
     enum_out.write(f"{LINT_HEADER}{MODIFY_NOTICE}\n")
-    enum_out.write("from typing import Literal, Union\n")
-    enum_out.write("from pkgs.strenum_compat import StrEnum\n")
+    enum_out.write("import typing\n")
+    enum_out.write("from enum import StrEnum\n")
 
     ctx = TrackingContext()
     # In this context the propername
@@ -1074,11 +1222,11 @@ def _emit_id_source(*, builder: builder.SpecBuilder, config: PythonConfig) -> No
     known_keys = []
     enum_out.write("\nENUM_MAP: dict[str, type[StrEnum]] = {\n")
     for key in sorted(named_enums.keys()):
-        enum_out.write(f'"{key}": {named_enums[key]},\n')
-        known_keys.append(f'Literal["{key}"]')
+        enum_out.write(f'{INDENT}"{key}": {named_enums[key]},\n')
+        known_keys.append(f'"{key}"')
     enum_out.write(f"}}\n{MODIFY_NOTICE}\n")
 
-    enum_out.write(f"\nKnownEnumsType = Union[\n{INDENT}")
+    enum_out.write(f"\nKnownEnumsType = typing.Literal[\n{INDENT}")
     enum_out.write(f",\n{INDENT}".join(known_keys))
     enum_out.write(f"\n]\n{MODIFY_NOTICE}\n")
 
@@ -1095,21 +1243,36 @@ def _emit_api_stubs(*, builder: builder.SpecBuilder, config: PythonConfig) -> No
 
             if endpoint is None:
                 continue
-            if endpoint.root != endpoint_root:
+            if endpoint_root not in endpoint.path_per_api_endpoint:
                 continue
-            if endpoint.function is None:
+
+            endpoint_function = endpoint.path_per_api_endpoint[endpoint_root].function
+            if endpoint_function is None:
                 continue
 
-            module_dir, file_name, func_name = endpoint.function.rsplit(".", 2)
+            module_dir, file_name, _func_name = endpoint_function.rsplit(".", 2)
             module_path = os.path.abspath(module_dir.replace(".", "/"))
             api_stub_file = f"{module_path}/{file_name}.py"
             if os.path.isfile(api_stub_file):
                 continue
-            _create_api_stub(api_stub_file, file_name, endpoint, config)
+            _create_api_stub(
+                api_stub_file=api_stub_file,
+                file_name=file_name,
+                endpoint=endpoint,
+                config=config,
+                endpoint_root=endpoint_root,
+                top_namespace=builder.top_namespace,
+            )
 
 
 def _create_api_stub(
-    api_stub_file: str, file_name: str, endpoint: SpecEndpoint, config: PythonConfig
+    *,
+    api_stub_file: str,
+    file_name: str,
+    endpoint: SpecEndpoint,
+    config: PythonConfig,
+    endpoint_root: str,
+    top_namespace: str,
 ) -> None:
     assert (
         endpoint.method == builder.RouteMethod.post
@@ -1117,7 +1280,13 @@ def _create_api_stub(
         or endpoint.method == builder.RouteMethod.delete
         or endpoint.method == builder.RouteMethod.patch
     )
-    api_out = _create_api_function(file_name, endpoint, config)
+    api_out = _create_api_function(
+        file_name=file_name,
+        endpoint=endpoint,
+        config=config,
+        endpoint_root=endpoint_root,
+        top_namespace=top_namespace,
+    )
     util.rewrite_file(api_stub_file, api_out.getvalue())
 
 
@@ -1126,15 +1295,22 @@ WRAP_ARGS_END = "\n"
 
 
 def _create_api_function(
-    file_name: str, endpoint: SpecEndpoint, config: PythonConfig
+    *,
+    file_name: str,
+    endpoint: SpecEndpoint,
+    config: PythonConfig,
+    endpoint_root: str,
+    top_namespace: str,
 ) -> io.StringIO:
+    endpoint_specific_path = endpoint.path_per_api_endpoint[endpoint_root]
+    assert endpoint_specific_path is not None
     api_out = io.StringIO()
     python_api_type_root = f"{config.types_package}.api"
-    dot_dirname = endpoint.path_dirname.replace("/", ".")
+    dot_dirname = endpoint_specific_path.path_dirname.replace("/", ".")
     api_import = (
         f"{python_api_type_root}.{dot_dirname}.{file_name}"
         if dot_dirname != ""
-        else f"{python_api_type_root}.{endpoint.path_basename}"
+        else f"{python_api_type_root}.{endpoint_specific_path.path_basename}"
     )
 
     if endpoint.method == builder.RouteMethod.post:
@@ -1146,7 +1322,20 @@ def _create_api_function(
     elif endpoint.method == builder.RouteMethod.patch:
         validated_method = "validated_patch"
 
-    ruff_requires_wrap = len(endpoint.path_basename) > 14
+    ruff_requires_wrap = len(endpoint_specific_path.path_basename) > 14
+
+    account_type = (
+        endpoint_specific_path.root
+        if endpoint_specific_path.root not in ["external", "portal"]
+        else "materials"
+    )
+
+    endpoint_path_name = (
+        ENDPOINT_PATH_ALTERNATE
+        if len(endpoint.path_per_api_endpoint.keys()) > 1
+        and endpoint_specific_path.root != top_namespace
+        else ENDPOINT_PATH
+    )
 
     api_out.write(
         f"""import {api_import} as api
@@ -1154,8 +1343,8 @@ from main.db.session import Session, SessionMaker
 from main.site.decorators import APIError, APIResponse, {validated_method}
 
 
-@{validated_method}(api.ENDPOINT_PATH, "{endpoint.root}", api.Arguments)
-def {endpoint.path_basename}({WRAP_ARGS_START if ruff_requires_wrap else ""}args: api.Arguments, client_sm: SessionMaker{WRAP_ARGS_END if ruff_requires_wrap else ""}) -> APIResponse[api.Data]:
+@{validated_method}(api.{endpoint_path_name}, "{account_type}", api.Arguments)
+def {endpoint_specific_path.path_basename}({WRAP_ARGS_START if ruff_requires_wrap else ""}args: api.Arguments, client_sm: SessionMaker{WRAP_ARGS_END if ruff_requires_wrap else ""}) -> APIResponse[api.Data]:
     with Session(client_sm) as session:
         # return APIResponse(data=api.Data())
         pass
@@ -1177,7 +1366,7 @@ def _emit_api_argument_lookup(
     for endpoint_root in builder.api_endpoints:
         routes_output = config.routes_output[endpoint_root]
 
-        imports = ["import typing", "import dataclasses"]
+        imports = ["import dataclasses"]
         mappings = []
         for namespace in sorted(
             builder.namespaces.values(),
@@ -1187,11 +1376,11 @@ def _emit_api_argument_lookup(
 
             if endpoint is None:
                 continue
-            if endpoint.root != endpoint_root:
+            if endpoint_root not in endpoint.path_per_api_endpoint:
                 continue
-            if endpoint.function is None:
+            if endpoint.path_per_api_endpoint[endpoint_root].function is None:
                 continue
-            if "Arguments" not in namespace.types:
+            if "Arguments" not in namespace.types or "Data" not in namespace.types:
                 continue
 
             import_alias = "_".join(namespace.path[1:])
@@ -1215,7 +1404,7 @@ def _emit_api_argument_lookup(
             mapping += f"{INDENT}{INDENT}route_group={route_group},\n"
             mapping += f"{INDENT}{INDENT}account_type={account_type},\n"
             mapping += f"{INDENT}{INDENT}route={import_alias}.ENDPOINT_PATH,\n"
-            mapping += f'{INDENT}{INDENT}handler="{endpoint.function}",\n'
+            mapping += f'{INDENT}{INDENT}handler="{endpoint.path_per_api_endpoint[endpoint_root].function}",\n'
             mapping += f"{INDENT}{INDENT}method={import_alias}.ENDPOINT_METHOD,\n"
             mapping += f"{INDENT})"
             mappings.append(mapping)
@@ -1226,9 +1415,6 @@ def _emit_api_argument_lookup(
         argument_lookup_out.write(
             f"""{LINE_BREAK.join(imports)}
 
-AT = typing.TypeVar("AT")
-DT = typing.TypeVar("DT")
-
 
 @dataclasses.dataclass(kw_only=True, frozen=True)
 class ApiEndpointKey:
@@ -1237,7 +1423,7 @@ class ApiEndpointKey:
 
 
 @dataclasses.dataclass(kw_only=True)
-class ApiEndpointSpec(typing.Generic[AT, DT]):
+class ApiEndpointSpec[AT, DT]:
     route: str
     arguments_type: type[AT]
     data_type: type[DT]
@@ -1267,10 +1453,10 @@ CLIENT_CLASS_IMPORTS = [
     "import dataclasses",
 ]
 ASYNC_BATCH_PROCESSOR_FILENAME = "async_batch_processor"
-ASYNC_BATCH_PROCESSOR_IMPORTS = [
+ASYNC_BATCH_PROCESSOR_BASE_IMPORTS = [
     "import uuid",
     "from abc import ABC, abstractmethod",
-    "from pkgs.serialization_util.serialization_helpers import serialize_for_api",
+    "from pkgs.serialization_util import serialize_for_api",
 ]
 
 
@@ -1305,8 +1491,11 @@ def _emit_async_batch_processor(
         config=config,
     )
 
+    imports = ASYNC_BATCH_PROCESSOR_BASE_IMPORTS.copy()
+    if ctx.use_dataclass:
+        imports.append("import dataclasses")
     async_batch_processor_out.write(
-        f"""{LINE_BREAK.join(ASYNC_BATCH_PROCESSOR_IMPORTS)}
+        f"""{LINE_BREAK.join(imports)}
 
 
 class AsyncBatchProcessorBase(ABC):
@@ -1355,6 +1544,7 @@ def _emit_client_class(
         namespaces=ctx.namespaces,
         from_namespace=None,
         config=config,
+        skip_non_sdk=True,
     )
 
     client_base_out.write(
@@ -1368,6 +1558,7 @@ class APIRequest:
     method: str
     endpoint: str
     args: typing.Any
+    request_options: {refer_to(ctx=ctx, stype=REQUEST_OPTIONS_STYPE)} | None = None
 
 
 class ClientMethods(ABC):