UncountablePythonSDK 0.0.115__py3-none-any.whl → 0.0.142.dev0__py3-none-any.whl

pkgs/type_spec/cross_output_links.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
 
-from pkgs.type_spec import builder
+from . import builder
+from .builder_types import CrossOutputPaths
 
 
 def get_python_stub_file_path(
@@ -17,14 +17,6 @@ def get_python_stub_file_path(
     return api_stub_file
 
 
-@dataclass(kw_only=True, frozen=True)
-class CrossOutputPaths:
-    python_types_output: str
-    typescript_types_output: str
-    typescript_routes_output: str
-    typespec_files_input: list[str]
-
-
 def get_python_api_file_path(
     cross_output_paths: CrossOutputPaths,
     namespace: builder.SpecNamespace,
@@ -35,10 +27,9 @@ def get_python_api_file_path(
 def get_typescript_api_file_path(
     cross_output_paths: CrossOutputPaths,
     namespace: builder.SpecNamespace,
+    endpoint_key: builder.EndpointKey,
 ) -> str:
-    return (
-        f"{cross_output_paths.typescript_routes_output}/{'/'.join(namespace.path)}.tsx"
-    )
+    return f"{cross_output_paths.typescript_routes_output_by_endpoint[endpoint_key]}/{'/'.join(namespace.path)}.tsx"
 
 
 def get_yaml_api_file_path(
@@ -68,13 +59,16 @@ def get_path_links(
     namespace: builder.SpecNamespace,
     *,
     current_path_type: str,
+    endpoint: builder.SpecEndpoint,
 ) -> str:
     if cross_output_paths is None:
         return ""
 
     api_paths = {
         "Python": get_python_api_file_path(cross_output_paths, namespace),
-        "TypeScript": get_typescript_api_file_path(cross_output_paths, namespace),
+        "TypeScript": get_typescript_api_file_path(
+            cross_output_paths, namespace, endpoint.default_endpoint_key
+        ),
         "YAML": get_yaml_api_file_path(cross_output_paths, namespace),
     }
 
@@ -95,11 +89,11 @@ def get_path_links(
 
     if namespace.endpoint is not None:
         for (
-            endpoint,
+            endpoint_key,
             path_specific_endpoint,
         ) in namespace.endpoint.path_per_api_endpoint.items():
             path_from_root = get_python_stub_file_path(path_specific_endpoint.function)
             if path_from_root is None:
                 continue
-            paths_string += f"{comment_prefix} Implementation for {endpoint}: file://./{return_to_root_path}{path_from_root}\n"
+            paths_string += f"{comment_prefix} Implementation for {endpoint_key}: file://./{return_to_root_path}{path_from_root}\n"
     return paths_string

pkgs/type_spec/emit_open_api.py

@@ -261,6 +261,10 @@ def _emit_endpoint_parameters(
     } | _emit_endpoint_parameter_examples(examples)
 
 
+def _emit_endpoint_deprecated(deprecated: bool) -> DictApiSchema:
+    return {"deprecated": True} if deprecated else {}
+
+
 def _emit_stability_level(
     stability_level: EmitOpenAPIStabilityLevel | None,
 ) -> DictApiSchema:
@@ -275,7 +279,12 @@ def _emit_stability_level(
         case EmitOpenAPIStabilityLevel.draft:
             stability_info["x-beta"] = True
         case EmitOpenAPIStabilityLevel.beta:
-            stability_info["x-badges"] = [{"name": "Beta", "color": "DarkOrange"}]
+            stability_info["x-badges"] = [
+                {
+                    "name": "Beta",
+                    "color": "DarkOrange",
+                }
+            ]
         case EmitOpenAPIStabilityLevel.stable:
             pass
         case _:
@@ -330,18 +339,57 @@ def _emit_endpoint_response_examples(
     return {"examples": response_examples}
 
 
+def _create_warning_banner(api_type: str, message: str) -> str:
+    return (
+        f'<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; '
+        f'border-radius: 4px; padding: 12px; margin-bottom: 16px;">'
+        f"<strong>⚠️ {api_type} API:</strong> {message}"
+        f"</div>"
+    )
+
+
+def _get_stability_warning(
+    stability_level: EmitOpenAPIStabilityLevel | None,
+) -> str:
+    resolved_stability_level = (
+        stability_level
+        if stability_level is not None
+        else EmitOpenAPIStabilityLevel.stable
+    )
+
+    match resolved_stability_level:
+        case EmitOpenAPIStabilityLevel.draft:
+            return _create_warning_banner(
+                "Draft",
+                "This endpoint is in draft status and may change significantly. Not recommended for production use.",
+            )
+        case EmitOpenAPIStabilityLevel.beta:
+            return _create_warning_banner(
+                "Beta",
+                "This endpoint is in beta and its required parameters may change. Use with caution in production environments.",
+            )
+        case EmitOpenAPIStabilityLevel.stable:
+            return ""
+
+
 def _emit_endpoint_description(
-    description: str, guides: list[EmitOpenAPIGuide]
+    description: str,
+    guides: list[EmitOpenAPIGuide],
+    stability_level: EmitOpenAPIStabilityLevel | None = None,
 ) -> dict[str, str]:
+    stability_warning = _get_stability_warning(stability_level)
+
     full_guides = "<br/>".join([
         _write_guide_as_html(guide, is_open=False)
         for guide in sorted(guides, key=lambda g: g.ref_name)
     ])
-    return {
-        "description": description
-        if len(guides) == 0
-        else f"{description}<br/>{full_guides}"
-    }
+
+    full_description_parts = [
+        part for part in [stability_warning, description, full_guides] if part
+    ]
+    full_description = "<br/>".join(full_description_parts)
+
+    return {"description": full_description}
 
 
 def _emit_namespace(
@@ -376,7 +424,10 @@ def _emit_namespace(
                 "tags": endpoint.tags,
                 "summary": endpoint.summary,
             }
-            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
+            | _emit_endpoint_deprecated(endpoint.deprecated)
+            | _emit_endpoint_description(
+                endpoint.description, ctx.endpoint.guides, endpoint.stability_level
+            )
             | _emit_stability_level(endpoint.stability_level)
             | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
             | _emit_endpoint_request_body(
@@ -474,8 +525,18 @@ def _emit_type(
         return
 
     if isinstance(stype, builder.SpecTypeDefnUnion):
-        ctx.types[stype.name] = open_api_type(
-            ctx, stype.get_backing_type(), config=config
+        converted_discriminator_map: dict[str, OpenAPIRefType] = dict()
+        if stype.discriminator_map is not None:
+            for discriminator_value, base_type in stype.discriminator_map.items():
+                converted_base_type = open_api_type(ctx, base_type, config=config)
+                assert isinstance(converted_base_type, OpenAPIRefType)
+                converted_discriminator_map[discriminator_value] = converted_base_type
+        ctx.types[stype.name] = OpenAPIUnionType(
+            [open_api_type(ctx, p, config=config) for p in stype.types],
+            discriminator=stype.discriminator,
+            discriminator_map=converted_discriminator_map
+            if stype.discriminator_map is not None
+            else None,
         )
         return
 
@@ -549,18 +610,6 @@ def _emit_type(
     ctx.types[stype.name] = final_type
 
 
-def _emit_constant(ctx: EmitOpenAPIContext, sconst: builder.SpecConstant) -> None:
-    if sconst.value_type.is_base_type(builder.BaseTypeName.s_string):
-        value = util.encode_common_string(cast(str, sconst.value))
-    elif sconst.value_type.is_base_type(builder.BaseTypeName.s_integer):
-        value = str(sconst.value)
-    else:
-        raise Exception("invalid constant type", sconst.name)
-
-    const_name = sconst.name.upper()
-    print("_emit_constant", value, const_name)
-
-
 def _emit_endpoint(
     gctx: EmitOpenAPIGlobalContext,
     ctx: EmitOpenAPIContext,
@@ -617,6 +666,7 @@ def _emit_endpoint(
         tags=[tag_name],
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
+        deprecated=namespace.endpoint.deprecated,
         stability_level=namespace.endpoint.stability_level,
         examples=[
             EmitOpenAPIEndpointExample(

pkgs/type_spec/emit_open_api_util.py

@@ -82,6 +82,7 @@ class EmitOpenAPIEndpoint:
     tags: list[str]
     summary: str
     description: str
+    deprecated: bool
     stability_level: EmitOpenAPIStabilityLevel | None
     examples: list[EmitOpenAPIEndpointExample]
     guides: list[EmitOpenAPIGuide]

pkgs/type_spec/emit_python.py

@@ -35,6 +35,11 @@ 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:
@@ -117,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})"
@@ -151,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):
@@ -184,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)
 
@@ -357,7 +400,10 @@ 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"
+            ctx.builder.cross_output_paths,
+            namespace,
+            current_path_type="Python",
+            endpoint=endpoint,
         )
         if path_links != "":
             ctx.out.write("\n")
@@ -468,6 +514,19 @@ def _emit_endpoint_invocation_function_signature(
         else []
     ) + (extra_params if extra_params is not None else [])
 
+    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
@@ -638,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)})"""
     )
@@ -1393,7 +1453,7 @@ 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 import serialize_for_api",
@@ -1431,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):
@@ -1495,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):

pkgs/type_spec/emit_typescript.py

@@ -1,17 +1,18 @@
 import io
 import os
+from typing import assert_never
 
 from . import builder, util
-from .builder import EndpointKey, EndpointSpecificPath
+from .builder import EndpointKey, EndpointSpecificPath, PathMapping
 from .config import TypeScriptConfig
 from .cross_output_links import get_path_links
 from .emit_io_ts import emit_type_io_ts
 from .emit_typescript_util import (
     MODIFY_NOTICE,
     EmitTypescriptContext,
+    emit_constant_ts,
     emit_namespace_imports_ts,
     emit_type_ts,
-    emit_value_ts,
     resolve_namespace_name,
     resolve_namespace_ref,
     ts_type_name,
@@ -37,6 +38,7 @@ def _emit_types(builder: builder.SpecBuilder, config: TypeScriptConfig) -> None:
             out=io.StringIO(),
             namespace=namespace,
             cross_output_paths=builder.cross_output_paths,
+            api_endpoints=builder.api_endpoints,
         )
 
         _emit_namespace(ctx, config, namespace)
@@ -78,6 +80,7 @@ def _emit_types(builder: builder.SpecBuilder, config: TypeScriptConfig) -> None:
             full.write("\n")
             full.write(MODIFY_NOTICE)
             full.write(f"// === START section from {namespace.name}.ts.part ===\n")
+            full.write("\n")
             full.write(part)
             full.write(f"// === END section from {namespace.name}.ts.part ===\n")
 
@@ -112,7 +115,7 @@ def _emit_namespace(
             emit_type_ts(ctx, stype)
 
     for sconst in namespace.constants.values():
-        _emit_constant(ctx, sconst)
+        emit_constant_ts(ctx, sconst)
 
     if namespace.endpoint is not None:
         _emit_endpoint(ctx, config, namespace, namespace.endpoint)
@@ -145,7 +148,10 @@ def _emit_endpoint(
         assert endpoint.result_type == builder.ResultType.json
 
     paths_string = get_path_links(
-        ctx.cross_output_paths, namespace, current_path_type="TypeScript"
+        ctx.cross_output_paths,
+        namespace,
+        current_path_type="TypeScript",
+        endpoint=endpoint,
     )
 
     data_loader_head = ""
@@ -155,7 +161,7 @@ def _emit_endpoint(
         assert has_data
 
         data_loader_head = (
-            'import { buildApiDataLoader, argsKey } from "unc_base/data_manager"\n'
+            'import { argsKey, buildApiDataLoader } from "unc_base/data_manager"\n'
         )
         data_loader_body = (
             "\nexport const data = buildApiDataLoader(argsKey(), apiCall)\n"
@@ -175,38 +181,56 @@ def _emit_endpoint(
     unc_base_api_imports = (
         f"appSpecificApiPath, {wrap_name}" if has_multiple_endpoints else wrap_name
     )
+    path_mapping = ctx.api_endpoints[endpoint.default_endpoint_key].path_mapping
+
+    match path_mapping:
+        case PathMapping.NO_MAPPING:
+            path_mapping_part = (
+                "\n  { pathMapping: ApplicationT.APIPathMapping.noMapping },"
+            )
+        case PathMapping.DEFAULT_MAPPING:
+            path_mapping_part = ""
+        case _:
+            assert_never(path_mapping)
+
     unc_types_imports = (
-        'import { ApplicationT } from "unc_types"\n' if has_multiple_endpoints else ""
+        'import { ApplicationT } from "unc_types"\n'
+        if has_multiple_endpoints or path_mapping_part != ""
+        else ""
     )
 
     type_path = f"unc_types/{'/'.join(namespace.path)}"
 
     if is_binary:
-        tsx_response_part = f"""import {{ {unc_base_api_imports} }} from "unc_base/api"
-import type {{ Arguments }} from "{type_path}"
-{unc_types_imports}
+        tsx_response_head = f"""import {{ {unc_base_api_imports} }} from "unc_base/api"
+"""
+        tsx_response_part = f"""import type {{ Arguments }} from "{type_path}"
+
 export type {{ Arguments }}
 """
     elif has_data and endpoint.has_attachment:
-        tsx_response_part = f"""import {{ {unc_base_api_imports}, type AttachmentResponse }} from "unc_base/api"
-import type {{ Arguments, Data }} from "{type_path}"
-{unc_types_imports}
+        tsx_response_head = f"""import {{ type AttachmentResponse, {unc_base_api_imports} }} from "unc_base/api"
+"""
+        tsx_response_part = f"""import type {{ Arguments, Data }} from "{type_path}"
+
 export type {{ Arguments, Data }}
 export type Response = AttachmentResponse<Data>
 """
     elif has_data:
-        tsx_response_part = f"""import {{ {unc_base_api_imports}, type JsonResponse }} from "unc_base/api"
-import type {{ Arguments, Data }} from "{type_path}"
-{unc_types_imports}
+        tsx_response_head = f"""import {{ {unc_base_api_imports}, type JsonResponse }} from "unc_base/api"
+"""
+        tsx_response_part = f"""import type {{ Arguments, Data }} from "{type_path}"
+
 export type {{ Arguments, Data }}
 export type Response = JsonResponse<Data>
 """
 
     else:
         assert has_deprecated_result
-        tsx_response_part = f"""import {{ {unc_base_api_imports} }} from "unc_base/api"
-import type {{ Arguments, DeprecatedResult }} from "{type_path}"
-{unc_types_imports}
+        tsx_response_head = f"""import {{ {unc_base_api_imports} }} from "unc_base/api"
+"""
+        tsx_response_part = f"""import type {{ Arguments, DeprecatedResult }} from "{type_path}"
+
 export type {{ Arguments }}
 export type Response = DeprecatedResult
 """
@@ -247,41 +271,33 @@ export type Response = DeprecatedResult
 
     # tsx_api = f"""{MODIFY_NOTICE}
     tsx_api = f"""{MODIFY_NOTICE}{paths_string}
-{data_loader_head}{tsx_response_part}
+{tsx_response_head}{data_loader_head}{unc_types_imports}{tsx_response_part}
 export const apiCall = {wrap_call}(
-  {endpoint_path_part}
+  {endpoint_path_part}{path_mapping_part}
 )
 {data_loader_body}"""
 
-    output = f"{config.routes_output}/{'/'.join(namespace.path)}.tsx"
+    output = f"{config.endpoint_to_routes_output[endpoint.default_endpoint_key]}/{'/'.join(namespace.path)}.tsx"
     util.rewrite_file(output, tsx_api)
 
     # Hacky index support, until enough is migrated to regen entirely
     # Emits the import into the UI API index file
-    index_path = f"{config.routes_output}/{'/'.join(namespace.path[0:-1])}/index.tsx"
+    index_path = f"{config.endpoint_to_routes_output[endpoint.default_endpoint_key]}/{'/'.join(namespace.path[0:-1])}/index.tsx"
     api_name = f"Api{ts_type_name(namespace.path[0 - 1])}"
     if os.path.exists(index_path):
-        with open(index_path) as index:
+        with open(index_path, encoding="utf-8") as index:
             index_data = index.read()
             need_index = index_data.find(api_name) == -1
     else:
         need_index = True
 
     if need_index:
-        with open(index_path, "a") as index:
+        with open(index_path, "a", encoding="utf-8") as index:
             print(f"Updated API Index {index_path}")
             index.write(f'import * as {api_name} from "./{namespace.path[-1]}"\n\n')
             index.write(f"export {{ {api_name} }}\n")
 
 
-def _emit_constant(ctx: EmitTypescriptContext, sconst: builder.SpecConstant) -> None:
-    ctx.out.write("\n\n")
-    ctx.out.write(MODIFY_NOTICE)
-    value = emit_value_ts(ctx, sconst.value_type, sconst.value)
-    const_name = sconst.name.upper()
-    ctx.out.write(f"export const {const_name} = {value}\n")
-
-
 def _emit_id_source(builder: builder.SpecBuilder, config: TypeScriptConfig) -> None:
     id_source_output = config.id_source_output
     if id_source_output is None: