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

pkgs/type_spec/config.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 from typing import Self, TypeVar
 
 from pkgs.serialization import yaml
+from pkgs.type_spec.builder import APIEndpointInfo, EndpointKey
 
 ConfigValueType = str | None | Mapping[str, str | None] | list[str]
 
@@ -19,6 +20,22 @@ def _parse_string_lookup(
     }
 
 
+VT = TypeVar("VT")
+
+
+def _parse_data_lookup(
+    key: str,
+    raw_value: ConfigValueType,
+    conv_func: type[VT],
+) -> dict[str, VT]:
+    assert isinstance(raw_value, dict), f"{key} must be key/values"
+    return {
+        k: conv_func(**v)
+        for k, v in raw_value.items()
+        if v is not None and isinstance(v, dict)
+    }
+
+
 @dataclass(kw_only=True)
 class BaseLanguageConfig:
     types_output: (
@@ -31,18 +48,28 @@ class BaseLanguageConfig:
 
 @dataclass(kw_only=True)
 class TypeScriptConfig(BaseLanguageConfig):
-    routes_output: str  # folder for generate route files will be located.
+    endpoint_to_routes_output: dict[
+        EndpointKey, str
+    ]  # folder for generate route files will be located.
     type_info_output: str  # folder for generated type info files
     id_source_output: str | None = None  # folder for emitted id source maps.
+    endpoint_to_frontend_app_type: dict[
+        str, str
+    ]  # map from api_endpoint to frontend app type
 
     def __post_init__(self: Self) -> None:
-        self.routes_output = self.routes_output
+        self.endpoint_to_routes_output = self.endpoint_to_routes_output
         self.type_info_output = os.path.abspath(self.type_info_output)
         self.id_source_output = (
             os.path.abspath(self.id_source_output)
             if self.id_source_output is not None
             else None
         )
+        self.endpoint_to_frontend_app_type = _parse_string_lookup(
+            "typescript_endpoint_to_frontend_app_type",
+            self.endpoint_to_frontend_app_type,
+            lambda x: x,
+        )
 
 
 @dataclass(kw_only=True)
@@ -59,6 +86,7 @@ class PythonConfig(BaseLanguageConfig):
     emit_client_class: bool = False  # emit the base class for the api client
     all_named_type_exports: bool = False  # emit __all__ for all named type exports
     sdk_endpoints_only: bool = False  # only emit is_sdk endpoints
+    type_info_output: str | None = None  # folder for generated type info files
 
     def __post_init__(self: Self) -> None:
         self.routes_output = _parse_string_lookup(
@@ -70,6 +98,9 @@ class PythonConfig(BaseLanguageConfig):
             else None
         )
 
+        if self.type_info_output is not None:
+            self.type_info_output = os.path.abspath(self.type_info_output)
+
 
 @dataclass(kw_only=True)
 class OpenAPIConfig(BaseLanguageConfig):
@@ -88,17 +119,17 @@ class OpenAPIConfig(BaseLanguageConfig):
 class Config:
     top_namespace: str
     type_spec_types: list[str]  # folders containing the yaml type spec definitions
-    api_endpoint: dict[str, str]
+    api_endpoint: dict[str, APIEndpointInfo]
     # languages
     typescript: TypeScriptConfig | None
     python: PythonConfig
     open_api: OpenAPIConfig | None
 
 
-_T = TypeVar("_T")
+T = TypeVar("T")
 
 
-def _parse_language(config_class: type[_T], raw_value: ConfigValueType) -> _T:
+def _parse_language(config_class: type[T], raw_value: ConfigValueType) -> T:
     assert isinstance(raw_value, dict), "expecting language config to have key/values."
     return config_class(**raw_value)
 
@@ -113,8 +144,10 @@ def parse_yaml_config(config_file: str) -> Config:
     )
     type_spec_types = [os.path.abspath(folder) for folder in raw_type_spec_types]
 
-    api_endpoint = _parse_string_lookup(
-        "api_endpoint", raw_config.get("api_endpoint", {}), lambda x: x
+    api_endpoint = _parse_data_lookup(
+        "api_endpoint",
+        raw_config.get("api_endpoint", {}),
+        APIEndpointInfo,
     )
 
     raw_typescript = raw_config.get("typescript")

pkgs/type_spec/cross_output_links.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import os
+
+from . import builder
+from .builder_types import CrossOutputPaths
+
+
+def get_python_stub_file_path(
+    function_name: str | None,
+) -> str | None:
+    if function_name is None:
+        return None
+    module_dir, file_name, _func_name = function_name.rsplit(".", 2)
+    module_path = os.path.relpath(module_dir.replace(".", "/"))
+    api_stub_file = f"{module_path}/{file_name}.py"
+    return api_stub_file
+
+
+def get_python_api_file_path(
+    cross_output_paths: CrossOutputPaths,
+    namespace: builder.SpecNamespace,
+) -> str:
+    return f"{cross_output_paths.python_types_output}/{'/'.join(namespace.path)}{'' if len(namespace.path) > 1 else '_t'}.py"
+
+
+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_by_endpoint[endpoint_key]}/{'/'.join(namespace.path)}.tsx"
+
+
+def get_yaml_api_file_path(
+    cross_output_paths: CrossOutputPaths,
+    namespace: builder.SpecNamespace,
+) -> str:
+    abs_path = next(
+        (
+            path
+            for path in cross_output_paths.typespec_files_input
+            if (
+                namespace.endpoint is None
+                or namespace.endpoint.default_endpoint_key in path
+            )
+        ),
+        cross_output_paths.typespec_files_input[0],
+    )
+    return f"{os.path.relpath(abs_path)}/{'/'.join(namespace.path)}.yaml"
+
+
+def get_return_to_root_path(path: str) -> str:
+    return "../" * (path.count("/"))
+
+
+def get_path_links(
+    cross_output_paths: CrossOutputPaths | None,
+    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, endpoint.default_endpoint_key
+        ),
+        "YAML": get_yaml_api_file_path(cross_output_paths, namespace),
+    }
+
+    assert current_path_type in api_paths
+
+    comment_prefix = "#"
+    if current_path_type == "TypeScript":
+        comment_prefix = "//"
+
+    return_to_root_path = get_return_to_root_path(api_paths[current_path_type])
+    del api_paths[current_path_type]
+
+    paths_string = ""
+    for path_name, path in api_paths.items():
+        paths_string += (
+            f"{comment_prefix} {path_name}: file://./{return_to_root_path}{path}\n"
+        )
+
+    if namespace.endpoint is not None:
+        for (
+            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_key}: file://./{return_to_root_path}{path_from_root}\n"
+    return paths_string

pkgs/type_spec/emit_open_api.py

@@ -7,10 +7,11 @@ WORK-IN-PROGRESS, DON'T USE!
 import dataclasses
 import json
 import re
-from typing import Collection, cast
+from enum import StrEnum
+from typing import Collection, assert_never, cast
 
 from pkgs.serialization import yaml
-from pkgs.serialization_util.serialization_helpers import serialize_for_api
+from pkgs.serialization_util import serialize_for_api
 
 from . import builder, util
 from .builder import EndpointGuideKey, RootGuideKey
@@ -62,6 +63,10 @@ base_name_map = {
 }
 
 
+class OpenAPIDefaultBehavior(StrEnum):
+    OPTIONAL_WITH_DEFAULT = "optional_with_default"
+
+
 def _rewrite_with_notice(
     file_path: str, file_content: str, *, notice: str = MODIFY_NOTICE
 ) -> bool:
@@ -126,7 +131,11 @@ def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> Non
     for namespace in sorted(builder.namespaces.values(), key=lambda ns: ns.name):
         ctx = EmitOpenAPIContext(namespace=namespace)
 
-        if ctx.namespace.endpoint is not None and ctx.namespace.endpoint.is_beta:
+        if (
+            ctx.namespace.endpoint is not None
+            and ctx.namespace.endpoint.stability_level
+            == EmitOpenAPIStabilityLevel.draft
+        ):
             continue
 
         if ctx.namespace.name == "base":
@@ -252,18 +261,35 @@ def _emit_endpoint_parameters(
     } | _emit_endpoint_parameter_examples(examples)
 
 
-def _emit_is_beta(is_beta: bool) -> DictApiSchema:
-    if is_beta:
-        return {"x-beta": True}
-    return {}
+def _emit_endpoint_deprecated(deprecated: bool) -> DictApiSchema:
+    return {"deprecated": True} if deprecated else {}
 
 
 def _emit_stability_level(
     stability_level: EmitOpenAPIStabilityLevel | None,
 ) -> DictApiSchema:
-    if stability_level is not None:
-        return {"x-stability-level": str(stability_level)}
-    return {}
+    stability_info: dict[str, ApiSchema] = {}
+    resolved_stability_level = (
+        stability_level
+        if stability_level is not None
+        else EmitOpenAPIStabilityLevel.stable
+    )
+    stability_info["x-stability-level"] = str(resolved_stability_level)
+    match resolved_stability_level:
+        case EmitOpenAPIStabilityLevel.draft:
+            stability_info["x-beta"] = True
+        case EmitOpenAPIStabilityLevel.beta:
+            stability_info["x-badges"] = [
+                {
+                    "name": "Beta",
+                    "color": "DarkOrange",
+                }
+            ]
+        case EmitOpenAPIStabilityLevel.stable:
+            pass
+        case _:
+            assert_never(stability_level)
+    return stability_info
 
 
 def _emit_endpoint_request_body(
@@ -313,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(
@@ -359,8 +424,10 @@ def _emit_namespace(
                 "tags": endpoint.tags,
                 "summary": endpoint.summary,
             }
-            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
-            | _emit_is_beta(endpoint.is_beta)
+            | _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(
@@ -421,6 +488,18 @@ def _emit_namespace(
     _rewrite_with_notice(path, yaml.dumps(oa_namespace, sort_keys=False))
 
 
+def _get_openapi_default_behavior(
+    prop: builder.SpecProperty,
+) -> OpenAPIDefaultBehavior | None:
+    if prop.ext_info is None or prop.ext_info.get("open_api") is None:
+        return None
+    value_passed = prop.ext_info["open_api"].get("default_required_behavior")
+    if value_passed is None:
+        return None
+    assert isinstance(value_passed, str)
+    return OpenAPIDefaultBehavior(value_passed)
+
+
 def _emit_type(
     ctx: EmitOpenAPIContext,
     stype: builder.SpecType,
@@ -446,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
 
@@ -484,6 +573,16 @@ def _emit_type(
                 # arguments, thus treat like extant==missing
                 # IMPROVE: if we can decide they are meant as output instead, then
                 # they should be marked as required
+                openapi_default_beahvior = _get_openapi_default_behavior(prop)
+                match openapi_default_beahvior:
+                    case None:
+                        pass
+                    case OpenAPIDefaultBehavior.OPTIONAL_WITH_DEFAULT:
+                        ref_type.nullable = True
+                        assert prop.default is not None, (
+                            "optional_with_default requires default"
+                        )
+                        ref_type.default = prop.default
                 properties[prop_name] = ref_type
             elif prop.extant == builder.PropertyExtant.missing:
                 # Unlike optional below, missing does not imply null is possible. They
@@ -511,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,
@@ -563,7 +650,7 @@ def _emit_endpoint(
     ep = namespace.endpoint
     gctx.paths.append(
         EmitOpenAPIPath(
-            path=f"/{ep.path_root}/{ep.path_dirname}/{ep.path_basename}",
+            path=f"/{ep.resolved_path}",
             ref=ref_path,
         )
     )
@@ -579,7 +666,7 @@ def _emit_endpoint(
         tags=[tag_name],
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
-        is_beta=namespace.endpoint.is_beta,
+        deprecated=namespace.endpoint.deprecated,
         stability_level=namespace.endpoint.stability_level,
         examples=[
             EmitOpenAPIEndpointExample(

pkgs/type_spec/emit_open_api_util.py

@@ -7,16 +7,16 @@ WORK-IN-PROGRESS, DON'T USE!
 from collections import defaultdict
 from dataclasses import dataclass, field
 
-from pkgs.serialization_util.serialization_helpers import JsonValue
+from pkgs.serialization_util import JsonValue
 
 from . import builder
 from .open_api_util import OpenAPIType
 
 MODIFY_NOTICE = "# DO NOT MODIFY -- This file is generated by type_spec"
 
-type GlobalContextInfo = dict[str, str | dict[str, str]]
-type TagGroupToNamedTags = dict[str, str | list[str]]
-type TagPathsToRef = dict[str, dict[str, str]]
+GlobalContextInfo = dict[str, str | dict[str, str]]
+TagGroupToNamedTags = dict[str, str | list[str]]
+TagPathsToRef = dict[str, dict[str, str]]
 
 
 @dataclass
@@ -82,7 +82,7 @@ class EmitOpenAPIEndpoint:
     tags: list[str]
     summary: str
     description: str
-    is_beta: bool
+    deprecated: bool
     stability_level: EmitOpenAPIStabilityLevel | None
     examples: list[EmitOpenAPIEndpointExample]
     guides: list[EmitOpenAPIGuide]