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

pkgs/type_spec/builder.py

@@ -10,12 +10,26 @@ 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):
@@ -24,7 +38,6 @@ class StabilityLevel(StrEnum):
     """
 
     draft = "draft"
-    alpha = "alpha"
     beta = "beta"
     stable = "stable"
 
@@ -47,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
@@ -61,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):
@@ -255,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
     ):
@@ -283,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
@@ -293,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:
@@ -304,6 +320,9 @@ 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_
 
@@ -316,11 +335,28 @@ class SpecTypeDefn(SpecType):
     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:
@@ -339,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
@@ -372,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
@@ -379,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:
@@ -402,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()
@@ -439,7 +480,7 @@ class SpecTypeGenericParameter(SpecType):
 
 
 class SpecTypeDefnObject(SpecTypeDefn):
-    base: Optional[SpecTypeDefnObject]
+    base: SpecTypeDefnObject | None
     parameters: list[str]
 
     def __init__(
@@ -447,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,
@@ -464,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
 
@@ -601,13 +642,23 @@ class SpecTypeDefnUnion(SpecTypeDefn):
                 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)
+                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
@@ -646,7 +697,7 @@ class SpecTypeDefnExternal(SpecTypeDefn):
 class StringEnumEntry:
     name: str
     value: str
-    label: Optional[str] = None
+    label: str | None = None
     deprecated: bool = False
 
 
@@ -662,7 +713,7 @@ 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] = []
 
@@ -700,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),
@@ -770,6 +823,7 @@ class SpecTypeDefnStringEnum(SpecTypeDefn):
 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.
@@ -794,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)
@@ -808,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)
@@ -818,19 +872,65 @@ 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
@@ -838,21 +938,24 @@ class SpecEndpoint:
     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
 
     def __init__(self) -> None:
         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",
@@ -863,24 +966,32 @@ class SpecEndpoint:
                 "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
 
         route_group = data.get("route_group")
@@ -891,10 +1002,6 @@ class SpecEndpoint:
         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 = (
@@ -908,29 +1015,70 @@ class SpecEndpoint:
             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(
@@ -953,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]
@@ -1002,6 +1150,11 @@ def _parse_const(
             )
             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)
 
 
@@ -1043,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:
@@ -1100,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
@@ -1117,7 +1276,8 @@ class SpecNamespace:
 
             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)
@@ -1161,7 +1321,12 @@ class SpecNamespace:
                 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]:
+                if name in [
+                    TOKEN_EMIT_IO_TS,
+                    TOKEN_EMIT_TYPE_INFO,
+                    TOKEN_IMPORT,
+                    TOKEN_EMIT_TYPE_INFO_PYTHON,
+                ]:
                     continue
 
                 builder.push_where(name)
@@ -1205,7 +1370,13 @@ class NameDataPair:
 
 
 class SpecBuilder:
-    def __init__(self, *, api_endpoints: dict[str, str], top_namespace: 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 = {}
@@ -1215,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)
@@ -1232,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(
@@ -1303,7 +1479,7 @@ class SpecBuilder:
         self,
         path: util.ParsedTypePath,
         namespace: SpecNamespace,
-        scope: Optional[SpecTypeDefn] = None,
+        scope: SpecTypeDefn | None = None,
         top: bool = False,
     ) -> SpecType:
         """
@@ -1361,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,
@@ -1384,7 +1562,7 @@ 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)

pkgs/type_spec/builder_types.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass(kw_only=True, frozen=True)
+class CrossOutputPaths:
+    python_types_output: str
+    typescript_types_output: str
+    typescript_routes_output_by_endpoint: dict[str, str]
+    typespec_files_input: list[str]