UncountablePythonSDK 0.0.21__py3-none-any.whl → 0.0.23__py3-none-any.whl

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,9 +105,14 @@ 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),
     )
 
@@ -112,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(
@@ -144,52 +166,183 @@ 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) -> dict[str, bool]:
+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}"
+    }
+
+
 def _emit_namespace(
     gctx: EmitOpenAPIGlobalContext,
     ctx: EmitOpenAPIContext,
     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_description(endpoint.description, ctx.endpoint.guides)
             | _emit_is_beta(endpoint.is_beta)
-            | _emit_endpoint_parameters(argument_type)
+            | _emit_endpoint_parameters(endpoint, argument_type, ctx.endpoint.examples)
+            | _emit_endpoint_request_body(endpoint, argument_type, ctx.endpoint.examples)
             | {
                 "responses": {
                     "200": {
@@ -198,6 +351,7 @@ def _emit_namespace(
                             "application/json": {
                                 "schema": {"$ref": "#/components/schema/Data"}
                             }
+                            | _emit_endpoint_response_examples(ctx.endpoint.examples)
                         },
                     }
                 },
@@ -236,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"
@@ -348,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"
@@ -397,6 +550,23 @@ def _emit_endpoint(
         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
+        ],
     )
 
 
@@ -464,6 +634,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

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,6 +62,15 @@ 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
@@ -63,6 +78,8 @@ class EmitOpenAPIEndpoint:
     summary: str
     description: str
     is_beta: bool
+    examples: list[EmitOpenAPIEndpointExample]
+    guides: list[EmitOpenAPIGuide]
 
 
 @dataclass

pkgs/type_spec/emit_python.py

@@ -29,7 +29,7 @@ ASYNC_BATCH_REQUEST_STYPE = builder.SpecTypeDefnObject(
     namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="AsyncBatchRequest"
 )
 QUEUED_BATCH_REQUEST_STYPE = builder.SpecTypeDefnObject(
-    namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="QueuedBatchRequest"
+    namespace=ASYNC_BATCH_TYPE_NAMESPACE, name="QueuedAsyncBatchRequest"
 )
 
 
@@ -819,6 +819,7 @@ base_name_map = {
     builder.BaseTypeName.s_opaque_key: "OpaqueKey",
     builder.BaseTypeName.s_string: "str",
     builder.BaseTypeName.s_tuple: "tuple",
+    builder.BaseTypeName.s_readonly_array: "tuple",
     builder.BaseTypeName.s_union: "typing.Union",
     builder.BaseTypeName.s_literal: "typing.Literal",
 }
@@ -827,6 +828,11 @@ base_name_map = {
 def refer_to(ctx: TrackingContext, stype: builder.SpecType) -> str:
     if isinstance(stype, builder.SpecTypeInstance):
         params = ", ".join([refer_to(ctx, p) for p in stype.parameters])
+
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_readonly_array):
+            assert len(stype.parameters) == 1, "Read Only Array takes one parameter"
+            params = f"{params}, ..."
+
         return f"{refer_to(ctx, stype.defn_type)}[{params}]"
 
     if isinstance(stype, builder.SpecTypeLiteralWrapper):

pkgs/type_spec/emit_typescript.py

@@ -394,6 +394,9 @@ def refer_to_impl(
         if stype.defn_type.name == builder.BaseTypeName.s_list:
             spec, multi = refer_to_impl(ctx, stype.parameters[0])
             return f"({spec})[]" if multi else f"{spec}[]", False
+        if stype.defn_type.name == builder.BaseTypeName.s_readonly_array:
+            spec, multi = refer_to_impl(ctx, stype.parameters[0])
+            return f"readonly ({spec})[]" if multi else f"readonly {spec}[]", False
         if stype.defn_type.name == builder.BaseTypeName.s_union:
             return f'({" | ".join([refer_to(ctx, p) for p in stype.parameters])})', False
         if stype.defn_type.name == builder.BaseTypeName.s_literal:

pkgs/type_spec/load_types.py

@@ -1,5 +1,6 @@
 import os
 from collections.abc import Callable
+from io import StringIO
 from typing import Optional
 
 import yaml
@@ -13,11 +14,28 @@ ext_map = {
     ".py": "python",
 }
 
+_DOC_FILE_REFEX = ".*/docs/(examples|guides)/.*yaml"
+_EXAMPLE_FILE_REGEX = ".*/docs/examples/.*yaml"
+_GUIDE_FILE_REGEX = ".*/docs/guides/.*md"
+
 
 def find_and_handle_files(
-    root_folder: str, name_regex: str, handler: Callable[[str, str], None]
+    *,
+    root_folder: str,
+    handler: Callable[[str, str], None],
+    name_regex: str | None = None,
+    not_name_regex: str | None = None,
+    whole_name_regex: str | None = None,
+    not_whole_name_regex: str | None = None,
 ) -> None:
-    for file_name in fs.find(root_folder, name_regex=name_regex, relative=True):
+    for file_name in fs.find(
+        root_folder,
+        name_regex=name_regex,
+        not_name_regex=not_name_regex,
+        whole_name_regex=whole_name_regex,
+        not_whole_name_regex=not_whole_name_regex,
+        relative=True,
+    ):
         with open(os.path.join(root_folder, file_name), encoding="utf-8") as file:
             handler(file_name, file.read())
 
@@ -32,9 +50,16 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
         name, ext = os.path.splitext(by_name)
         handler(ext_map[ext], name, file_content)
 
+    def handle_builder_example_add(file_name: str, file_content: str) -> None:
+        yaml_content = yaml.safe_load(StringIO(file_content))
+        builder.add_example_file(yaml_content)
+
+    def handle_builder_guide_add(file_name: str, file_content: str) -> None:
+        builder.add_guide_file(file_content)
+
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder,
+            root_folder=folder,
             name_regex=".*\\.(ts|py)\\.part",
             handler=lambda file_name, file_content: handle_builder_add(
                 file_name, file_content, builder.add_part_file
@@ -43,7 +68,7 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
 
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder,
+            root_folder=folder,
             name_regex=".*\\.(ts|py)\\.prepart",
             handler=lambda file_name, file_content: handle_builder_add(
                 file_name, file_content, builder.add_prepart_file
@@ -64,9 +89,27 @@ def load_types(config: Config) -> Optional[SpecBuilder]:
 
     for folder in config.type_spec_types:
         find_and_handle_files(
-            folder, name_regex=".*\\.yaml", handler=builder_prescan_file
+            root_folder=folder,
+            name_regex=".*\\.yaml",
+            not_whole_name_regex=_DOC_FILE_REFEX,
+            handler=builder_prescan_file,
         )
 
+    if config.open_api is not None:
+        for folder in config.type_spec_types:
+            find_and_handle_files(
+                root_folder=folder,
+                whole_name_regex=_EXAMPLE_FILE_REGEX,
+                handler=handle_builder_example_add,
+            )
+
+        for folder in config.type_spec_types:
+            find_and_handle_files(
+                root_folder=folder,
+                whole_name_regex=_GUIDE_FILE_REGEX,
+                handler=handle_builder_guide_add,
+            )
+
     if not builder.process():
         return None
 

pkgs/type_spec/open_api_util.py

@@ -1,6 +1,5 @@
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from io import UnsupportedOperation
 from typing import Optional
 
 
@@ -16,9 +15,6 @@ class OpenAPIType(ABC):
     def asdict(self) -> dict[str, object]:
         pass
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        raise UnsupportedOperation
-
     def add_addl_info(self, emitted: dict[str, object]) -> dict[str, object]:
         if self.description is not None:
             emitted["description"] = self.description
@@ -148,9 +144,6 @@ class OpenAPIFreeFormObjectType(OpenAPIType):
     def asdict(self) -> dict[str, object]:
         return self.add_addl_info({"type": "object"})
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        return {}
-
 
 class OpenAPIObjectType(OpenAPIType):
     """
@@ -174,31 +167,30 @@ class OpenAPIObjectType(OpenAPIType):
             self.property_desc = property_desc
         super().__init__(description=description, nullable=nullable)
 
+    def _emit_property_desc(self, property_name: str) -> dict[str, str]:
+        desc = self.property_desc.get(property_name)
+        if desc is None or desc.strip() == "":
+            return {}
+
+        return {"description": desc}
+
     def asdict(self) -> dict[str, object]:
         return self.add_addl_info({
             "type": "object",
+            "required": [
+                property_name
+                for property_name, property_type in self.properties.items()
+                if not property_type.nullable
+            ],
             "properties": {
                 property_name: {
                     **property_type.asdict(),
-                    "description": self.property_desc.get(property_name),
                 }
+                | self._emit_property_desc(property_name)
                 for property_name, property_type in self.properties.items()
             },
         })
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        argument_types: dict[str, dict[str, object]] = {}
-        for property_name, property_type in self.properties.items():
-            desc = self.property_desc.get(property_name)
-            argument_types[property_name] = {
-                "name": property_name,
-                "in": "query",
-                "schema": property_type.asdict(),
-                "required": not property_type.nullable,
-                "description": desc or "",
-            }
-        return argument_types
-
 
 class OpenAPIUnionType(OpenAPIType):
     """
@@ -220,12 +212,6 @@ class OpenAPIUnionType(OpenAPIType):
         # TODO: use parents description and nullable
         return {"oneOf": [base_type.asdict() for base_type in self.base_types]}
 
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return {}
-
 
 class OpenAPIIntersectionType(OpenAPIType):
     """
@@ -246,9 +232,3 @@ class OpenAPIIntersectionType(OpenAPIType):
     def asdict(self) -> dict[str, object]:
         # TODO: use parents description and nullable
         return {"allOf": [base_type.asdict() for base_type in self.base_types]}
-
-    def asarguments(self) -> dict[str, dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return {}

type_spec/external/api/entity/create_entities.yaml

@@ -24,6 +24,7 @@ Arguments:
                     Literal<entity.EntityType.lab_request>,
                     Literal<entity.EntityType.approval>,
                     Literal<entity.EntityType.custom_entity>,
+                    Literal<entity.EntityType.inventory_amount>,
                     Literal<entity.EntityType.task>,
                     Literal<entity.EntityType.project>,
                     Literal<entity.EntityType.equipment>,

type_spec/external/api/entity/create_entity.yaml

@@ -31,6 +31,7 @@ Arguments:
                     Literal<entity.EntityType.lab_request>,
                     Literal<entity.EntityType.approval>,
                     Literal<entity.EntityType.custom_entity>,
+                    Literal<entity.EntityType.inventory_amount>,
                     Literal<entity.EntityType.task>,
                     Literal<entity.EntityType.project>,
                     Literal<entity.EntityType.equipment>,

type_spec/external/api/recipes/edit_recipe_inputs.yaml

@@ -1,6 +1,5 @@
 $endpoint:
     is_sdk: true
-    is_beta: true
     async_batch_path: edit_recipe_inputs
     method: post
     path: ${external}/recipes/edit_recipe_inputs
@@ -77,12 +76,10 @@ Arguments:
             type: identifier.IdentifierKey
             desc: "Identifier for the recipe"
         recipe_workflow_step_identifier:
-            type: recipe_workflow_steps.RecipeWorkflowStepIdentifierType
+            type: recipe_workflow_steps.RecipeWorkflowStepIdentifier
         edits:
             type: List<RecipeInputEdit>
 
 Data:
   type: Object
   properties:
-    result_id:
-      type: ObjectId

uncountable/core/__init__.py

@@ -1,4 +1,5 @@
 from .client import AuthDetailsApiKey, Client
 from .file_upload import MediaFileUpload, UploadedFile
+from .async_batch import AsyncBatchProcessor
 
-__all__: list[str] = ["AuthDetailsApiKey", "Client", "MediaFileUpload", "UploadedFile"]
+__all__: list[str] = ["AuthDetailsApiKey", "AsyncBatchProcessor", "Client", "MediaFileUpload", "UploadedFile"]

uncountable/core/async_batch.py

@@ -0,0 +1,22 @@
+from uncountable.core.client import Client
+from uncountable.types.async_batch import AsyncBatchRequest
+from uncountable.types.async_batch_processor import AsyncBatchProcessorBase
+from uncountable.types import async_batch_t, base_t
+
+
+class AsyncBatchProcessor(AsyncBatchProcessorBase):
+    _client: Client
+    _queue: list[AsyncBatchRequest]
+
+    def __init__(self, *, client: Client) -> None:
+        super().__init__()
+        self._client = client
+        self._queue = []
+
+    def _enqueue(self, req: async_batch_t.AsyncBatchRequest) -> None:
+        self._queue.append(req)
+
+    def send(self) -> base_t.ObjectId:
+        job_id = self._client.execute_batch_load_async(requests=self._queue).job_id
+        self._queue = []
+        return job_id