UncountablePythonSDK 0.0.20__py3-none-any.whl → 0.0.22__py3-none-any.whl

pkgs/type_spec/builder.py

@@ -10,7 +10,7 @@ import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
 from enum import Enum, StrEnum, auto
-from typing import Any, Optional
+from typing import Any, Optional, Self
 
 from . import util
 from .util import parse_type_str, unused
@@ -184,6 +184,34 @@ class SpecTypeInstance(SpecType):
         return defn_type + self.parameters
 
 
+@dataclass(kw_only=True)
+class SpecEndpointExample:
+    summary: str
+    description: str
+    arguments: dict[str, object]
+    data: dict[str, object]
+
+
+@dataclass(kw_only=True)
+class SpecGuide:
+    title: str
+    markdown_content: str
+    html_content: str
+
+
+@dataclass(kw_only=True, frozen=True)
+class RootGuideKey:
+    pass
+
+
+@dataclass(kw_only=True, frozen=True)
+class EndpointGuideKey:
+    path: str
+
+
+SpecGuideKey = RootGuideKey | EndpointGuideKey
+
+
 class SpecTypeLiteralWrapper(SpecType):
     def __init__(
         self,
@@ -672,6 +700,32 @@ class ResultType(StrEnum):
 RE_ENDPOINT_ROOT = re.compile(r"\${([_a-z]+)}")
 
 
+@dataclass(kw_only=True, frozen=True)
+class _EndpointPathDetails:
+    root: str
+    root_path: str
+    resolved_path: str
+
+
+def _resolve_endpoint_path(
+    path: str, api_endpoints: dict[str, str]
+) -> _EndpointPathDetails:
+    root_path_source = path.split("/")[0]
+    root_match = RE_ENDPOINT_ROOT.fullmatch(root_path_source)
+    if root_match is None:
+        raise Exception(f"invalid-api-path-root:{root_path_source}")
+
+    root_var = root_match.group(1)
+    root_path = api_endpoints[root_var]
+
+    _, *rest_path = path.split("/", 1)
+    resolved_path = "/".join([root_path] + rest_path)
+
+    return _EndpointPathDetails(
+        root=root_var, root_path=root_path, resolved_path=resolved_path
+    )
+
+
 class SpecEndpoint:
     method: RouteMethod
     root: str
@@ -680,9 +734,11 @@ class SpecEndpoint:
     path_basename: str
     data_loader: bool
     is_sdk: bool
+    is_beta: bool
     # Don't emit TypeScript endpoint code
     suppress_ts: bool
     function: Optional[str]
+    async_batch_path: str | None = None
     result_type: ResultType = ResultType.json
     has_attachment: bool = False
     desc: str | None = None
@@ -701,6 +757,8 @@ class SpecEndpoint:
                 "path",
                 "data_loader",
                 "is_sdk",
+                "is_beta",
+                "async_batch_path",
                 "function",
                 "suppress_ts",
                 "desc",
@@ -727,6 +785,15 @@ class SpecEndpoint:
         assert isinstance(is_sdk, bool)
         self.is_sdk = is_sdk
 
+        is_beta = data.get("is_beta", False)
+        assert isinstance(is_beta, bool)
+        self.is_beta = is_beta
+
+        async_batch_path = data.get("async_batch_path")
+        if async_batch_path is not None:
+            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)
@@ -735,14 +802,10 @@ class SpecEndpoint:
 
         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.desc = data.get("desc")
-
-        root_match = RE_ENDPOINT_ROOT.fullmatch(path[0])
-        if root_match is None:
-            raise Exception(f"invalid-api-path-root:{path[0]}")
-
-        self.root = root_match.group(1)
-        self.path_root = builder.api_endpoints[self.root]
         # IMPROVE: remove need for is_external flag
         self.is_external = self.path_root == "api/external"
         self.has_attachment = data.get("has_attachment", False)
@@ -751,6 +814,10 @@ class SpecEndpoint:
             not is_sdk or self.desc is not None
         ), f"Endpoint description required for SDK endpoints, missing: {path}"
 
+    @property
+    def resolved_path(self: Self) -> str:
+        return f"{self.path_root}/{self.path_dirname}/{self.path_basename}"
+
 
 def _parse_const(
     builder: SpecBuilder,
@@ -1001,6 +1068,8 @@ class SpecBuilder:
         self.pending: list[NamespaceDataPair] = []
         self.parts: dict[str, dict[str, str]] = defaultdict(dict)
         self.preparts: dict[str, dict[str, str]] = defaultdict(dict)
+        self.examples: dict[str, list[SpecEndpointExample]] = defaultdict(list)
+        self.guides: dict[SpecGuideKey, list[SpecGuide]] = defaultdict(list)
         self.api_endpoints = api_endpoints
         base_namespace = SpecNamespace(name=base_namespace_name)
         for base_type in BaseTypeName:
@@ -1185,5 +1254,53 @@ class SpecBuilder:
     def add_prepart_file(self, target: str, name: str, data: str) -> None:
         self.preparts[target][name] = data
 
+    def add_example_file(self, data: dict[str, object]) -> None:
+        path_details = _resolve_endpoint_path(str(data["path"]), self.api_endpoints)
+
+        examples_data = data["examples"]
+        if not isinstance(examples_data, list):
+            raise Exception(
+                f"'examples' in example files are expected to be a list, endpoint_path={path_details.resolved_path}"
+            )
+        for example in examples_data:
+            arguments = example["arguments"]
+            data_example = example["data"]
+            if not isinstance(arguments, dict) or not isinstance(data_example, dict):
+                raise Exception(
+                    f"'arguments' and 'data' fields must be dictionaries for each endpoint example, endpoint={path_details.resolved_path}"
+                )
+            self.examples[path_details.resolved_path].append(
+                SpecEndpointExample(
+                    summary=str(example["summary"]),
+                    description=str(example["description"]),
+                    arguments=arguments,
+                    data=data_example,
+                )
+            )
+
+    def add_guide_file(self, file_content: str) -> None:
+        import markdown
+
+        md = markdown.Markdown(extensions=["meta"])
+        html = md.convert(file_content)
+        meta: dict[str, list[str]] = md.Meta  # type: ignore[attr-defined]
+        title_meta: list[str] | None = meta.get("title")
+        if title_meta is None:
+            raise Exception("guides requier a title in the meta section")
+
+        path_meta: list[str] | None = meta.get("path")
+        guide_key: SpecGuideKey = RootGuideKey()
+        if path_meta is not None:
+            path_details = _resolve_endpoint_path("".join(path_meta), self.api_endpoints)
+            guide_key = EndpointGuideKey(path=path_details.resolved_path)
+
+        self.guides[guide_key].append(
+            SpecGuide(
+                title="".join(title_meta),
+                html_content=html,
+                markdown_content=file_content,
+            )
+        )
+
     def resolve_proper_name(self, stype: SpecTypeDefn) -> str:
         return f"{'.'.join(stype.namespace.path)}.{stype.name}"

pkgs/type_spec/config.py

@@ -56,6 +56,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

pkgs/type_spec/emit_open_api.py

@@ -5,18 +5,22 @@ WORK-IN-PROGRESS, DON'T USE!
 """
 
 import dataclasses
+import json
 import re
-from typing import cast
+from typing import Collection, cast
 
 import yaml
 
 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,
     EmitOpenAPITag,
@@ -74,12 +78,23 @@ 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) -> str:
+    return f"""
+        <details>
+        <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) for guide in guides])
+    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 +105,23 @@ 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(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 +132,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(
@@ -141,15 +166,144 @@ def _serialize_global_context(ctx: EmitOpenAPIGlobalContext) -> str:
     return yaml.dump(oa_root, sort_keys=False)
 
 
-def _emit_endpoint_parameters(typ: OpenAPIType | None) -> dict[str, list[dict[str, str]]]:
+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": [
-            {"$ref": f"#/components/schema/Arguments/{prop_name}"}
-            for prop_name in typ.properties
+            {
+                "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_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) for guide in guides])
+    return {
+        "description": description
+        if len(guides) == 0
+        else f"{description}<br/>{full_guides}"
     }
 
 
@@ -159,27 +313,36 @@ 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,
             }
-            | _emit_endpoint_parameters(argument_type)
+            | _emit_endpoint_description(endpoint.description, ctx.endpoint.guides)
+            | _emit_is_beta(endpoint.is_beta)
+            | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
+            | _emit_endpoint_request_body(endpoint, argument_type, ctx.endpoint.examples)
             | {
                 "responses": {
                     "200": {
@@ -188,6 +351,7 @@ def _emit_namespace(
                             "application/json": {
                                 "schema": {"$ref": "#/components/schema/Data"}
                             }
+                            | _emit_endpoint_response_examples(ctx.endpoint.examples)
                         },
                     }
                 },
@@ -226,10 +390,7 @@ 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"
@@ -338,6 +499,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"
@@ -386,6 +549,24 @@ def _emit_endpoint(
         tags=[tag_name],
         summary=f"{'/'.join(namespace.path[path_cutoff:])}",
         description=description,
+        is_beta=namespace.endpoint.is_beta,
+        examples=[
+            EmitOpenAPIEndpointExample(
+                ref_name=f"ex_{i}",
+                summary=example.summary,
+                description=example.description,
+                arguments=example.arguments,
+                data=example.data,
+            )
+            for i, example in enumerate(endpoint_examples)
+        ],
+        guides=[
+            EmitOpenAPIGuide(
+                title=guide.title,
+                html_content=guide.html_content,
+            )
+            for guide in endpoint_guides
+        ],
     )
 
 

pkgs/type_spec/emit_open_api_util.py

@@ -43,6 +43,12 @@ class EmitOpenAPIServer:
     url: str
 
 
+@dataclass(kw_only=True)
+class EmitOpenAPIGuide:
+    title: str
+    html_content: str
+
+
 @dataclass
 class EmitOpenAPIGlobalContext:
     version: str
@@ -56,12 +62,24 @@ 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, object]
+    data: dict[str, object]
+
+
 @dataclass
 class EmitOpenAPIEndpoint:
     method: str
     tags: list[str]
     summary: str
     description: str
+    is_beta: bool
+    examples: list[EmitOpenAPIEndpointExample]
+    guides: list[EmitOpenAPIGuide]
 
 
 @dataclass