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

pkgs/type_spec/config.py

@@ -1,9 +1,9 @@
 import os
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
-from decimal import Decimal
-from typing import Callable, Mapping, Self, Type, TypeVar
+from typing import Self, TypeVar
 
-import yaml
+from pkgs.serialization import yaml
 
 ConfigValueType = str | None | Mapping[str, str | None] | list[str]
 
@@ -34,6 +34,9 @@ class TypeScriptConfig(BaseLanguageConfig):
     routes_output: 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
@@ -43,6 +46,11 @@ class TypeScriptConfig(BaseLanguageConfig):
             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)
@@ -55,6 +63,7 @@ class PythonConfig(BaseLanguageConfig):
     emit_api_argument_lookup: bool = (
         False  # emit a lookup for api endpoint path to argument type.
     )
+    emit_async_batch_processor: bool = False  # emit the async batch wrapping functions
     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
@@ -85,6 +94,7 @@ class OpenAPIConfig(BaseLanguageConfig):
 
 @dataclass(kw_only=True)
 class Config:
+    top_namespace: str
     type_spec_types: list[str]  # folders containing the yaml type spec definitions
     api_endpoint: dict[str, str]
     # languages
@@ -96,30 +106,19 @@ class Config:
 _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)
 
 
-def _decimal_constructor(loader, node):  # type:ignore
-    value = loader.construct_scalar(node)
-    return Decimal(value)
-
-
-# A semi-acceptable patch to force a number to be parsed as a decimal, since pyyaml
-# parses them as lossy floats otherwise. Though a bit ugly, at least this way we have
-# support for decimal constants
-yaml.SafeLoader.add_constructor("!decimal", _decimal_constructor)
-
-
 def parse_yaml_config(config_file: str) -> Config:
     with open(config_file, encoding="utf-8") as input:
         raw_config: dict[str, ConfigValueType] = yaml.safe_load(input)
 
     raw_type_spec_types = raw_config["type_spec_types"]
-    assert isinstance(
-        raw_type_spec_types, list
-    ), "type_spec_types, must be a list of folders"
+    assert isinstance(raw_type_spec_types, list), (
+        "type_spec_types, must be a list of folders"
+    )
     type_spec_types = [os.path.abspath(folder) for folder in raw_type_spec_types]
 
     api_endpoint = _parse_string_lookup(
@@ -135,10 +134,16 @@ def parse_yaml_config(config_file: str) -> Config:
     python = _parse_language(PythonConfig, raw_config["python"])
     raw_open_api = raw_config.get("open_api")
     open_api = (
-        _parse_language(OpenAPIConfig, raw_open_api) if raw_open_api is not None else None
+        _parse_language(OpenAPIConfig, raw_open_api)
+        if raw_open_api is not None
+        else None
     )
 
+    top_namespace = raw_config["top_namespace"]
+    assert isinstance(top_namespace, str)
+
     return Config(
+        top_namespace=top_namespace,
         type_spec_types=type_spec_types,
         api_endpoint=api_endpoint,
         typescript=typescript,

pkgs/type_spec/emit_io_ts.py

@@ -118,11 +118,14 @@ def refer_to_io_ts(
     stype: builder.SpecType,
 ) -> str:
     if isinstance(stype, builder.SpecTypeInstance):
-        if stype.defn_type.name == builder.BaseTypeName.s_list:
+        if (
+            stype.defn_type.name == builder.BaseTypeName.s_list
+            or stype.defn_type.name == builder.BaseTypeName.s_readonly_array
+        ):
             spec = refer_to_io_ts(ctx, stype.parameters[0])
             return f"IO.array({spec})"
         if stype.defn_type.name == builder.BaseTypeName.s_union:
-            return f'IO.union([{", ".join([refer_to_io_ts(ctx, p) for p in stype.parameters])}])'
+            return f"IO.union([{', '.join([refer_to_io_ts(ctx, p) for p in stype.parameters])}])"
         if stype.defn_type.name == builder.BaseTypeName.s_optional:
             return f"IO.optional({refer_to_io_ts(ctx, stype.parameters[0])})"
         if stype.defn_type.name == builder.BaseTypeName.s_tuple:

pkgs/type_spec/emit_open_api.py

@@ -5,20 +5,26 @@ WORK-IN-PROGRESS, DON'T USE!
 """
 
 import dataclasses
+import json
 import re
-from typing import cast
+from typing import Collection, cast
 
-import yaml
+from pkgs.serialization import yaml
+from pkgs.serialization_util import serialize_for_api
 
 from . import builder, util
+from .builder import EndpointGuideKey, RootGuideKey
 from .config import OpenAPIConfig
 from .emit_open_api_util import (
     MODIFY_NOTICE,
     EmitOpenAPIContext,
     EmitOpenAPIEndpoint,
+    EmitOpenAPIEndpointExample,
     EmitOpenAPIGlobalContext,
+    EmitOpenAPIGuide,
     EmitOpenAPIPath,
     EmitOpenAPIServer,
+    EmitOpenAPIStabilityLevel,
     EmitOpenAPITag,
     GlobalContextInfo,
     TagGroupToNamedTags,
@@ -59,7 +65,7 @@ base_name_map = {
 def _rewrite_with_notice(
     file_path: str, file_content: str, *, notice: str = MODIFY_NOTICE
 ) -> bool:
-    pattern = re.compile("^\S", re.MULTILINE)
+    pattern = re.compile(r"^\S", re.MULTILINE)
 
     file_lines = file_content.split("\n")
     comment_lines = []
@@ -74,12 +80,26 @@ def _rewrite_with_notice(
     return util.rewrite_file(file_path, f"{notice}\n{modified_file_content}")
 
 
-def _open_api_info(config: OpenAPIConfig) -> GlobalContextInfo:
-    description = config.description
+def _write_guide_as_html(guide: EmitOpenAPIGuide, *, is_open: bool) -> str:
+    return f"""
+        <details id="{guide.ref_name}" {"open" if is_open else ""}>
+        <summary>{guide.title}</summary>
+        {guide.html_content}
+        </details>"""
+
+
+def _open_api_info(
+    config: OpenAPIConfig, guides: list[EmitOpenAPIGuide]
+) -> GlobalContextInfo:
+    full_guides = "<br/>".join([
+        _write_guide_as_html(guide, is_open=True)
+        for guide in sorted(guides, key=lambda g: g.ref_name)
+    ])
+    full_description = f"{config.description}<br/>{full_guides}"
     info: GlobalContextInfo = dict()
     info["version"] = "1.0.0"
     info["title"] = "Uncountable API Documentation"
-    info["description"] = description
+    info["description"] = full_description
     info["x-logo"] = {"url": "../static/images/logo_blue.png", "altText": "Logo"}
     return info
 
@@ -90,15 +110,25 @@ def _open_api_servers(config: OpenAPIConfig) -> list[EmitOpenAPIServer]:
 
 
 def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> None:
+    root_guides = builder.guides.get(RootGuideKey(), [])
+    openapi_guides = [
+        EmitOpenAPIGuide(
+            ref_name=guide.ref_name, title=guide.title, html_content=guide.html_content
+        )
+        for guide in root_guides
+    ]
     gctx = EmitOpenAPIGlobalContext(
         version="3.0.0",
-        info=_open_api_info(config),
+        info=_open_api_info(config, openapi_guides),
         servers=_open_api_servers(config),
     )
 
     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:
+            continue
+
         if ctx.namespace.name == "base":
             # TODO: add additional base defintions here
             ctx.types["ObjectId"] = OpenAPIIntegerT()
@@ -109,6 +139,8 @@ def emit_open_api(builder: builder.SpecBuilder, *, config: OpenAPIConfig) -> Non
             ctx,
             namespace=namespace,
             config=config,
+            examples=builder.examples,
+            guides=builder.guides,
         )
 
     _rewrite_with_notice(
@@ -138,7 +170,161 @@ def _serialize_global_context(ctx: EmitOpenAPIGlobalContext) -> str:
         oa_paths[path.path] = {"$ref": path.ref}
     oa_root["paths"] = oa_paths
 
-    return yaml.dump(oa_root, sort_keys=False)
+    return yaml.dumps(oa_root, sort_keys=False)
+
+
+def _is_empty_object_type(typ: OpenAPIType) -> bool:
+    if not isinstance(typ, OpenAPIObjectType):
+        return False
+    return len(typ.properties) == 0
+
+
+_QUERY_PARM_METHODS = ("get", "head", "options")
+_REQUEST_BODY_METHODS = ("put", "post", "patch", "delete")
+
+ApiSchema = dict[str, "ApiSchema"] | Collection["ApiSchema"] | str | bool
+DictApiSchema = dict[str, ApiSchema]
+
+
+def _emit_endpoint_argument_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if len(examples) == 0:
+        return {}
+
+    response_examples = {}
+    for example in examples:
+        response_examples[example.ref_name] = {
+            "summary": example.summary,
+            "description": example.description,
+            "value": example.arguments,
+        }
+    return {"examples": response_examples}
+
+
+def _emit_endpoint_parameter_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if len(examples) == 0:
+        return {}
+
+    paramater_examples = []
+    comment_new_line = "\n// "
+    new_line = "\n"
+    for example in examples:
+        javascript_description = (
+            f"// {comment_new_line.join(example.description.split(new_line))}"
+        )
+        javascript_json_payload = f"{json.dumps(example.arguments, indent=2)}"
+        paramater_examples.append({
+            "lang": "JavaScript",
+            "label": f"Payload - {example.summary}",
+            "source": f"{javascript_description}\n{javascript_json_payload}",
+        })
+    return {"x-codeSamples": paramater_examples}
+
+
+def _emit_endpoint_parameters(
+    endpoint: EmitOpenAPIEndpoint,
+    argument_type: OpenAPIType | None,
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if (
+        endpoint.method.lower() not in _QUERY_PARM_METHODS
+        or argument_type is None
+        or _is_empty_object_type(argument_type)
+    ):
+        return {}
+
+    return {
+        "parameters": [
+            {
+                "name": "data",
+                "required": True,
+                "in": "query",
+                "content": {
+                    "application/json": {
+                        "schema": {"$ref": "#/components/schema/Arguments"}
+                    }
+                },
+            }
+        ]
+    } | _emit_endpoint_parameter_examples(examples)
+
+
+def _emit_is_beta(is_beta: bool) -> DictApiSchema:
+    if is_beta:
+        return {"x-beta": True}
+    return {}
+
+
+def _emit_stability_level(
+    stability_level: EmitOpenAPIStabilityLevel | None,
+) -> DictApiSchema:
+    if stability_level is not None:
+        return {"x-stability-level": str(stability_level)}
+    return {}
+
+
+def _emit_endpoint_request_body(
+    endpoint: EmitOpenAPIEndpoint,
+    arguments_type: OpenAPIType | None,
+    examples: list[EmitOpenAPIEndpointExample],
+) -> DictApiSchema:
+    if (
+        endpoint.method.lower() not in _REQUEST_BODY_METHODS
+        or arguments_type is None
+        or _is_empty_object_type(arguments_type)
+    ):
+        return {}
+
+    return {
+        "requestBody": {
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "title": "Body",
+                        "required": ["data"],
+                        "properties": {
+                            "data": {"$ref": "#/components/schema/Arguments"}
+                        },
+                    }
+                }
+                | _emit_endpoint_argument_examples(examples)
+            },
+        }
+    }
+
+
+def _emit_endpoint_response_examples(
+    examples: list[EmitOpenAPIEndpointExample],
+) -> dict[str, dict[str, object]]:
+    if len(examples) == 0:
+        return {}
+
+    response_examples: dict[str, object] = {}
+    for example in examples:
+        response_examples[example.ref_name] = {
+            "summary": example.summary,
+            "description": example.description,
+            "value": example.data,
+        }
+    return {"examples": response_examples}
+
+
+def _emit_endpoint_description(
+    description: str, guides: list[EmitOpenAPIGuide]
+) -> dict[str, str]:
+    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}"
+    }
 
 
 def _emit_namespace(
@@ -147,35 +333,53 @@ def _emit_namespace(
     namespace: builder.SpecNamespace,
     *,
     config: OpenAPIConfig,
+    examples: dict[str, list[builder.SpecEndpointExample]],
+    guides: dict[builder.SpecGuideKey, list[builder.SpecGuide]],
 ) -> None:
     for stype in namespace.types.values():
         _emit_type(ctx, stype, config=config)
 
     if namespace.endpoint is not None:
-        _emit_endpoint(gctx, ctx, namespace, namespace.endpoint)
+        endpoint_examples = examples.get(namespace.endpoint.resolved_path, [])
+        endpoint_guides = guides.get(
+            EndpointGuideKey(path=namespace.endpoint.resolved_path), []
+        )
+        _emit_endpoint(
+            gctx, ctx, namespace, namespace.endpoint, endpoint_examples, endpoint_guides
+        )
 
     oa_components: dict[str, object] = dict()
 
     if ctx.endpoint is not None:
         endpoint = ctx.endpoint
-
+        argument_type = ctx.types.get("Arguments")
         oa_endpoint = dict()
-        oa_endpoint[endpoint.method] = {
-            "tags": endpoint.tags,
-            "summary": endpoint.summary,
-            "description": endpoint.description,
-            "parameters": {"$ref": "#/components/schema/Arguments"},
-            "responses": {
-                "200": {
-                    "description": "OK",
-                    "content": {
-                        "application/json": {
-                            "schema": {"$ref": "#/components/schema/Data"}
-                        }
-                    },
-                }
-            },
-        }
+        oa_endpoint[endpoint.method] = (
+            {
+                "tags": endpoint.tags,
+                "summary": endpoint.summary,
+            }
+            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
+            | _emit_is_beta(endpoint.is_beta)
+            | _emit_stability_level(endpoint.stability_level)
+            | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
+            | _emit_endpoint_request_body(
+                endpoint, argument_type, ctx.endpoint.examples
+            )
+            | {
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": "#/components/schema/Data"}
+                            }
+                            | _emit_endpoint_response_examples(ctx.endpoint.examples)
+                        },
+                    }
+                },
+            }
+        )
         oa_components["endpoint"] = oa_endpoint
 
     types = ctx.types
@@ -209,15 +413,12 @@ def _emit_namespace(
 
     oa_components["schema"] = cast(
         object,
-        {
-            name: (value.asdict() if name != "Arguments" else value.asarguments())
-            for name, value in types.items()
-        },
+        {name: value.asdict() for name, value in types.items()},
     )
 
     path = f"{config.types_output}/common/{'/'.join(namespace.path)}.yaml"
     oa_namespace = {"components": oa_components}
-    _rewrite_with_notice(path, yaml.dump(oa_namespace, sort_keys=False))
+    _rewrite_with_notice(path, yaml.dumps(oa_namespace, sort_keys=False))
 
 
 def _emit_type(
@@ -244,6 +445,12 @@ def _emit_type(
         ctx.types[stype.name] = open_api_type(ctx, stype.alias, config=config)
         return
 
+    if isinstance(stype, builder.SpecTypeDefnUnion):
+        ctx.types[stype.name] = open_api_type(
+            ctx, stype.get_backing_type(), config=config
+        )
+        return
+
     if isinstance(stype, builder.SpecTypeDefnStringEnum):
         # TODO: check that these are always string enums
         # IMPROVE: reflect the enum names in the description
@@ -321,6 +528,8 @@ def _emit_endpoint(
     ctx: EmitOpenAPIContext,
     namespace: builder.SpecNamespace,
     endpoint: builder.SpecEndpoint,
+    endpoint_examples: list[builder.SpecEndpointExample],
+    endpoint_guides: list[builder.SpecGuide],
 ) -> None:
     assert namespace.endpoint is not None
     assert namespace.path[0] == "api"
@@ -364,11 +573,32 @@ def _emit_endpoint(
         description = f"**[External API-Endpoint]** <br/> {description}"
 
     path_cutoff = min(3, len(namespace.path) - 1)
+
     ctx.endpoint = EmitOpenAPIEndpoint(
         method=namespace.endpoint.method.lower(),
         tags=[tag_name],
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
+        is_beta=namespace.endpoint.is_beta,
+        stability_level=namespace.endpoint.stability_level,
+        examples=[
+            EmitOpenAPIEndpointExample(
+                ref_name=f"ex_{i}",
+                summary=example.summary,
+                description=example.description,
+                arguments=serialize_for_api(example.arguments),
+                data=serialize_for_api(example.data),
+            )
+            for i, example in enumerate(endpoint_examples)
+        ],
+        guides=[
+            EmitOpenAPIGuide(
+                ref_name=guide.ref_name,
+                title=guide.title,
+                html_content=guide.html_content,
+            )
+            for guide in endpoint_guides
+        ],
     )
 
 
@@ -436,6 +666,10 @@ def open_api_type(
                 [open_api_type(ctx, p, config=config) for p in stype.parameters],
                 description="TupleType",
             )
+        if stype.defn_type.name == builder.BaseTypeName.s_readonly_array:
+            return OpenAPIArrayType(
+                open_api_type(ctx, stype.parameters[0], config=config)
+            )
 
         # TODO: generics are not supported by OpenAPI
         # map to Free-Form Object and add description
@@ -460,5 +694,5 @@ def open_api_type(
     ctx.namespaces.add(stype.namespace)
     # external namespace resolution
     return OpenAPIRefType(
-        source=f"{resolve_namespace_ref(ctx, stype.namespace, config=config)}/{stype.name}"
+        source=f"{resolve_namespace_ref(source_path=ctx.namespace.path, ref_path=stype.namespace.path, ref='/components/schema')}/{stype.name}"
     )

pkgs/type_spec/emit_open_api_util.py

@@ -6,17 +6,17 @@ WORK-IN-PROGRESS, DON'T USE!
 
 from collections import defaultdict
 from dataclasses import dataclass, field
-from typing import TypeAlias
+
+from pkgs.serialization_util import JsonValue
 
 from . import builder
-from .config import OpenAPIConfig
 from .open_api_util import OpenAPIType
 
 MODIFY_NOTICE = "# DO NOT MODIFY -- This file is generated by type_spec"
 
-GlobalContextInfo: TypeAlias = dict[str, str | dict[str, str]]
-TagGroupToNamedTags: TypeAlias = dict[str, str | list[str]]
-TagPathsToRef: TypeAlias = dict[str, dict[str, str]]
+type GlobalContextInfo = dict[str, str | dict[str, str]]
+type TagGroupToNamedTags = dict[str, str | list[str]]
+type TagPathsToRef = dict[str, dict[str, str]]
 
 
 @dataclass
@@ -44,6 +44,13 @@ class EmitOpenAPIServer:
     url: str
 
 
+@dataclass(kw_only=True)
+class EmitOpenAPIGuide:
+    ref_name: str
+    title: str
+    html_content: str
+
+
 @dataclass
 class EmitOpenAPIGlobalContext:
     version: str
@@ -57,12 +64,28 @@ class EmitOpenAPIGlobalContext:
     paths: list[EmitOpenAPIPath] = field(default_factory=list)
 
 
+@dataclass(kw_only=True)
+class EmitOpenAPIEndpointExample:
+    ref_name: str
+    summary: str
+    description: str
+    arguments: dict[str, JsonValue]
+    data: dict[str, JsonValue]
+
+
+EmitOpenAPIStabilityLevel = builder.StabilityLevel
+
+
 @dataclass
 class EmitOpenAPIEndpoint:
     method: str
     tags: list[str]
     summary: str
     description: str
+    is_beta: bool
+    stability_level: EmitOpenAPIStabilityLevel | None
+    examples: list[EmitOpenAPIEndpointExample]
+    guides: list[EmitOpenAPIGuide]
 
 
 @dataclass
@@ -75,12 +98,8 @@ class EmitOpenAPIContext:
 
 
 def resolve_namespace_ref(
-    ctx: EmitOpenAPIContext,
-    namespace: builder.SpecNamespace,
-    *,
-    config: OpenAPIConfig,
+    *, source_path: list[str], ref_path: list[str], ref: str
 ) -> str:
-    # TODO: Handle namespaces not in root directory
-    if len(ctx.namespace.path) == 1:
-        return f"{namespace.name}.yaml#/components/schema"
-    return f"{config.static_url_path}/common/{namespace.name}.yaml#/components/schema"
+    to_root = "/".join(".." for _ in source_path)
+    location = "/".join(ref_path)
+    return f"{to_root}/common/{location}.yaml#{ref}"