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

pkgs/type_spec/emit_typescript_util.py

@@ -3,23 +3,38 @@ import typing
 from dataclasses import dataclass, field
 
 from . import builder, util
-from .config import TypeScriptConfig
 
 INDENT = "  "
 
 MODIFY_NOTICE = "// DO NOT MODIFY -- This file is generated by type_spec\n"
 
 
+base_name_map = {
+    builder.BaseTypeName.s_boolean: "boolean",
+    builder.BaseTypeName.s_date: "string",  # IMPROVE: Aliased DateStr
+    builder.BaseTypeName.s_date_time: "string",  # IMPROVE: Aliased DateTimeStr
+    # Decimal's are marked as to_string_values thus are strings in the front-end
+    builder.BaseTypeName.s_decimal: "string",
+    builder.BaseTypeName.s_dict: "PartialRecord",
+    builder.BaseTypeName.s_integer: "number",
+    builder.BaseTypeName.s_lossy_decimal: "number",
+    builder.BaseTypeName.s_opaque_key: "string",
+    builder.BaseTypeName.s_none: "null",
+    builder.BaseTypeName.s_string: "string",
+    # UNC: global types
+    builder.BaseTypeName.s_json_value: "JsonValue",
+}
+
+
 @dataclass(kw_only=True)
 class EmitTypescriptContext:
-    config: TypeScriptConfig
     out: io.StringIO
     namespace: builder.SpecNamespace
-    namespaces: typing.Set[builder.SpecNamespace] = field(default_factory=set)
+    namespaces: set[builder.SpecNamespace] = field(default_factory=set)
 
 
 def ts_type_name(name: str) -> str:
-    return "".join([x.capitalize() for x in name.split("_")])
+    return "".join([x.title() for x in name.split("_")])
 
 
 def resolve_namespace_ref(namespace: builder.SpecNamespace) -> str:
@@ -30,4 +45,223 @@ def ts_name(name: str, name_case: builder.NameCase) -> str:
     if name_case == builder.NameCase.preserve:
         return name
     bits = util.split_any_name(name)
-    return "".join([bits[0], *[x.capitalize() for x in bits[1:]]])
+    return "".join([bits[0], *[x.title() for x in bits[1:]]])
+
+
+def emit_value_ts(
+    ctx: EmitTypescriptContext, stype: builder.SpecType, value: typing.Any
+) -> str:
+    """Mimics emit_python even if not all types are used in TypeScript yet"""
+    literal = builder.unwrap_literal_type(stype)
+    if literal is not None:
+        return emit_value_ts(ctx, literal.value_type, literal.value)
+
+    if stype.is_base_type(builder.BaseTypeName.s_string):
+        assert isinstance(value, str)
+        return util.encode_common_string(value)
+    elif stype.is_base_type(builder.BaseTypeName.s_integer):
+        assert isinstance(value, int)
+        return str(value)
+    elif stype.is_base_type(builder.BaseTypeName.s_boolean):
+        assert isinstance(value, bool)
+        return "true" if value else "false"
+    elif stype.is_base_type(builder.BaseTypeName.s_lossy_decimal):
+        return str(value)
+    elif stype.is_base_type(builder.BaseTypeName.s_decimal):
+        return f"'{value}'"
+    elif isinstance(stype, builder.SpecTypeInstance):
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_list):
+            sub_type = stype.parameters[0]
+            return (
+                "[" + ", ".join([emit_value_ts(ctx, sub_type, x) for x in value]) + "]"
+            )
+
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_dict):
+            key_type = stype.parameters[0]
+            value_type = stype.parameters[1]
+            return (
+                "{\n\t"
+                + ",\n\t".join(
+                    (
+                        f"[{emit_value_ts(ctx, key_type, dkey)}]: "
+                        if not key_type.is_base_type(builder.BaseTypeName.s_string)
+                        else f"{dkey}: "
+                    )
+                    + emit_value_ts(ctx, value_type, dvalue)
+                    for dkey, dvalue in value.items()
+                )
+                + "\n}"
+            )
+
+        if stype.defn_type.is_base_type(builder.BaseTypeName.s_optional):
+            sub_type = stype.parameters[0]
+            if value is None:
+                return "null"
+            return emit_value_ts(ctx, sub_type, value)
+
+    elif isinstance(stype, builder.SpecTypeDefnStringEnum):
+        return f"{refer_to(ctx, stype)}.{ts_enum_name(value, stype.name_case)}"
+
+    raise Exception("invalid constant type", value, stype)
+
+
+def emit_type_ts(ctx: EmitTypescriptContext, stype: builder.SpecType) -> None:
+    if not isinstance(stype, builder.SpecTypeDefn):
+        return
+
+    if stype.is_base or stype.is_predefined:
+        return
+
+    ctx.out.write("\n")
+    ctx.out.write(MODIFY_NOTICE)
+
+    if isinstance(stype, builder.SpecTypeDefnExternal):
+        assert not stype.is_exported, "expecting private names"
+        ctx.out.write(stype.external_map["ts"])
+        ctx.out.write("\n")
+        return
+
+    assert stype.is_exported, "expecting exported names"
+    if isinstance(stype, builder.SpecTypeDefnAlias):
+        ctx.out.write(f"export type {stype.name} = {refer_to(ctx, stype.alias)}\n")
+        return
+
+    if isinstance(stype, builder.SpecTypeDefnUnion):
+        ctx.out.write(
+            f"export type {stype.name} = {refer_to(ctx, stype.get_backing_type())}\n"
+        )
+        return
+
+    if isinstance(stype, builder.SpecTypeDefnStringEnum):
+        ctx.out.write(f"export enum {stype.name} {{\n")
+        assert stype.values
+        for name, entry in stype.values.items():
+            ctx.out.write(
+                f'{INDENT}{ts_enum_name(name, stype.name_case)} = "{entry.value}",\n'
+            )
+        ctx.out.write("}\n")
+        return
+
+    assert isinstance(stype, builder.SpecTypeDefnObject)
+    assert stype.base is not None
+
+    base_type = ""
+    if not stype.base.is_base:
+        base_type = f"{refer_to(ctx, stype.base)} & "
+
+    if stype.properties is None and base_type == "":
+        ctx.out.write(f"export type {stype.name} = TEmpty\n")
+    elif stype.properties is None:
+        ctx.out.write(f"export type {stype.name} = {base_type}{{}}\n")
+    else:
+        if isinstance(stype, builder.SpecTypeDefnObject) and len(stype.parameters) > 0:
+            full_type_name = f"{stype.name}<{', '.join(stype.parameters)}>"
+        else:
+            full_type_name = stype.name
+        ctx.out.write(f"export type {full_type_name} = {base_type}{{")
+        ctx.out.write("\n")
+        for prop in stype.properties.values():
+            ref_type = refer_to(ctx, prop.spec_type)
+            prop_name = ts_name(prop.name, prop.name_case)
+            if prop.has_default and not prop.parse_require:
+                # For now, we'll assume the generated types with defaults are meant as
+                # arguments, thus treat like extant==missing
+                # IMPROVE: if we can decide they are meant as output instead, then
+                # they should be marked as required
+                ctx.out.write(f"{INDENT}{prop_name}?: {ref_type}")
+            elif prop.extant == builder.PropertyExtant.missing:
+                # Unlike optional below, missing does not imply null is possible. They
+                # treated distinctly.
+                ctx.out.write(f"{INDENT}{prop_name}?: {ref_type}")
+            elif prop.extant == builder.PropertyExtant.optional:
+                # Need to add in |null since Python side can produce null's right now
+                # IMPROVE: It would be better if the serializer could instead omit the None's
+                # Dropping the null should be forward compatible
+                ctx.out.write(f"{INDENT}{prop_name}?: {ref_type} | null")
+            else:
+                ctx.out.write(f"{INDENT}{prop_name}: {ref_type}")
+            ctx.out.write("\n")
+        ctx.out.write("}\n")
+
+
+def refer_to(ctx: EmitTypescriptContext, stype: builder.SpecType) -> str:
+    return refer_to_impl(ctx, stype)[0]
+
+
+def refer_to_impl(
+    ctx: EmitTypescriptContext, stype: builder.SpecType
+) -> tuple[str, bool]:
+    """
+    @return (string-specific, multiple-types)
+    """
+    if isinstance(stype, builder.SpecTypeInstance):
+        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:
+            parts = []
+            for parameter in stype.parameters:
+                assert isinstance(parameter, builder.SpecTypeLiteralWrapper)
+                parts.append(refer_to(ctx, parameter))
+            return f"({' | '.join(parts)})", False
+        if stype.defn_type.name == builder.BaseTypeName.s_optional:
+            return f"{refer_to(ctx, stype.parameters[0])} | null", True
+        if stype.defn_type.name == builder.BaseTypeName.s_tuple:
+            return f"[{', '.join([refer_to(ctx, p) for p in stype.parameters])}]", False
+        params = ", ".join([refer_to(ctx, p) for p in stype.parameters])
+        return f"{refer_to(ctx, stype.defn_type)}<{params}>", False
+
+    if isinstance(stype, builder.SpecTypeLiteralWrapper):
+        return emit_value_ts(ctx, stype.value_type, stype.value), False
+
+    if isinstance(stype, builder.SpecTypeGenericParameter):
+        return stype.name, False
+
+    assert isinstance(stype, builder.SpecTypeDefn)
+    if stype.is_base:  # assume correct namespace
+        if stype.name == builder.BaseTypeName.s_list:
+            return "any[]", False  # TODO: generic type
+        return base_name_map[builder.BaseTypeName(stype.name)], False
+
+    if stype.namespace == ctx.namespace:
+        return stype.name, False
+
+    ctx.namespaces.add(stype.namespace)
+    return f"{resolve_namespace_ref(stype.namespace)}.{stype.name}", False
+
+
+def ts_enum_name(name: str, name_case: builder.NameCase) -> str:
+    if name_case == builder.NameCase.js_upper:
+        return name.upper()
+    return ts_name(name, name_case)
+
+
+def resolve_namespace_name(namespace: builder.SpecNamespace) -> str:
+    return namespace.name
+
+
+def emit_namespace_imports_ts(
+    namespaces: set[builder.SpecNamespace],
+    out: io.StringIO,
+    current_namespace: builder.SpecNamespace,
+) -> None:
+    for ns in sorted(
+        namespaces,
+        key=lambda name: resolve_namespace_name(name),
+    ):
+        import_as = resolve_namespace_ref(ns)
+        import_path = (
+            "./"
+            if len(current_namespace.path) == 1
+            else "../" * (len(current_namespace.path) - 1)
+        )
+        import_from = f"{import_path}{resolve_namespace_name(ns)}"
+        out.write(f'import * as {import_as} from "{import_from}"\n')  # noqa: E501

pkgs/type_spec/load_types.py

@@ -1,9 +1,11 @@
 import os
-from typing import Callable, Optional
+from collections.abc import Callable
+from io import StringIO
 
-import yaml
 from shelljob import fs
 
+from pkgs.serialization import yaml
+
 from .builder import SpecBuilder
 from .config import Config
 
@@ -12,17 +14,36 @@ 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())
 
 
-def load_types(config: Config) -> Optional[SpecBuilder]:
-    builder = SpecBuilder(api_endpoints=config.api_endpoint)
+def load_types(config: Config) -> SpecBuilder | None:
+    builder = SpecBuilder(
+        api_endpoints=config.api_endpoint, top_namespace=config.top_namespace
+    )
 
     def handle_builder_add(
         file_name: str, file_content: str, handler: Callable[[str, str, str], None]
@@ -31,9 +52,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
@@ -42,7 +70,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
@@ -63,11 +91,28 @@ 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
 
     return builder
-    return True

pkgs/type_spec/open_api_util.py

@@ -1,7 +1,5 @@
 from abc import ABC, abstractmethod
-from enum import Enum
-from io import UnsupportedOperation
-from typing import Optional
+from enum import StrEnum
 
 
 class OpenAPIType(ABC):
@@ -13,10 +11,8 @@ class OpenAPIType(ABC):
         self.nullable = nullable
 
     @abstractmethod
-    def asdict(self) -> dict[str, object]: ...
-
-    def asarguments(self) -> list[dict[str, object]]:
-        raise UnsupportedOperation
+    def asdict(self) -> dict[str, object]:
+        pass
 
     def add_addl_info(self, emitted: dict[str, object]) -> dict[str, object]:
         if self.description is not None:
@@ -40,7 +36,7 @@ class OpenAPIRefType(OpenAPIType):
         return {"$ref": self.source}
 
 
-class OpenAPIPrimitive(str, Enum):
+class OpenAPIPrimitive(StrEnum):
     string = "string"
     boolean = "boolean"
     integer = "integer"
@@ -147,9 +143,6 @@ class OpenAPIFreeFormObjectType(OpenAPIType):
     def asdict(self) -> dict[str, object]:
         return self.add_addl_info({"type": "object"})
 
-    def asarguments(self) -> list[dict[str, object]]:
-        return []
-
 
 class OpenAPIObjectType(OpenAPIType):
     """
@@ -164,7 +157,7 @@ class OpenAPIObjectType(OpenAPIType):
         description: str | None = None,
         nullable: bool = False,
         *,
-        property_desc: Optional[dict[str, str]] = None,
+        property_desc: dict[str, str] | None = None,
     ) -> None:
         self.properties = properties
         if property_desc is None:
@@ -173,31 +166,39 @@ 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 _emit_property(
+        self, property_name: str, property_type: OpenAPIType
+    ) -> dict[str, object]:
+        property_info = {
+            **property_type.asdict(),
+        }
+        property_description = self._emit_property_desc(property_name)
+        if "$ref" in property_info and "description" in property_description:
+            return {"allOf": [property_info, property_description]}
+
+        return property_info | property_description
+
     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),
-                }
+                property_name: self._emit_property(property_name, property_type)
                 for property_name, property_type in self.properties.items()
             },
         })
 
-    def asarguments(self) -> list[dict[str, object]]:
-        argument_types: list[dict[str, object]] = []
-        for property_name, property_type in self.properties.items():
-            desc = self.property_desc.get(property_name)
-            argument_types.append({
-                "name": property_name,
-                "in": "query",
-                "schema": property_type.asdict(),
-                "required": not property_type.nullable,
-                "description": desc or "",
-            })
-        return argument_types
-
 
 class OpenAPIUnionType(OpenAPIType):
     """
@@ -219,12 +220,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) -> list[dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return []
-
 
 class OpenAPIIntersectionType(OpenAPIType):
     """
@@ -245,9 +240,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) -> list[dict[str, object]]:
-        # TODO handle inheritence (allOf and refs); need to inline here...
-        # for now skip this endpoint
-
-        return []

pkgs/type_spec/parts/base.py.prepart

@@ -1,7 +1,8 @@
 """
     Types that type_spec will use in the emitted files.
 """
-from typing import Union, Mapping, Sequence, Any, TYPE_CHECKING
+from typing import Union, Any, TYPE_CHECKING
+from collections.abc import Mapping, Sequence
 
 # These two are part of the core output, thus don't duplicate here
 # from decimal import Decimal
@@ -21,8 +22,8 @@ PureJsonScalar = Union[str, float, bool, None]
 # Regular expressions for identifying ref names and IDs. Ref names should be
 # using this regular expression as a constriant in the database.
 REF_NAME_REGEX = r"^[a-zA-Z0-9_/-]+$"
-# Does not support nonpositive integers at the moment.
-ID_REGEX = r"[1-9][0-9]{0,20}"
+# Ids matching a strict integer number are converted to integers
+ID_REGEX = r"-?[1-9][0-9]{0,20}"
 
 
 if TYPE_CHECKING: