UncountablePythonSDK 0.0.16__py3-none-any.whl → 0.0.18__py3-none-any.whl

pkgs/serialization/serial_class.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import dataclasses
-from typing import Any, Callable, Optional, TypeVar, cast
-
-from pkgs.strenum_compat import StrEnum
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Any, Optional, TypeVar, cast
 
 _ClassT = TypeVar("_ClassT")
 

pkgs/serialization_util/_get_type_for_serialization.py

@@ -1,11 +1,9 @@
 import dataclasses
 import datetime
 import functools
-from enum import Enum
+from enum import Enum, StrEnum
 from typing import Any
 
-from pkgs.strenum_compat import StrEnum
-
 
 class SerializationType(StrEnum):
     NAMED_TUPLE = "NAMED_TUPLE"

pkgs/serialization_util/serialization_helpers.py

@@ -1,13 +1,11 @@
 import datetime
 import enum
+from collections.abc import Callable, Mapping, Sequence
 from decimal import Decimal
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
-    Mapping,
     Optional,
-    Sequence,
     TypeVar,
     Union,
 )

pkgs/strenum_compat/strenum_compat.py

@@ -1,9 +1 @@
-import sys
-from enum import Enum
-
-if sys.version_info >= (3, 11):
-    from enum import StrEnum as StrEnum
-else:
-
-    class StrEnum(str, Enum):
-        pass
+from enum import StrEnum as StrEnum

pkgs/type_spec/actions_registry/__main__.py

@@ -0,0 +1,114 @@
+"""
+This processes the directory main/unc/materials/shared/actions_registry and emits actions_registry/action_definitions.tsx
+"""
+
+import os
+import sys
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import TypeVar
+
+from main.base.types import actions_registry_t
+from pkgs.type_spec import builder
+
+from ...argument_parser import CachedParser
+from ..emit_typescript_util import ts_name
+from ..util import rewrite_file
+from .emit_typescript import emit_action_definitions
+
+key_name = "name"
+key_icon = "icon"
+key_short_description = "short_description"
+key_description = "description"
+
+
+TypeT = TypeVar("TypeT")
+
+
+class InvalidSpecException(Exception):
+    pass
+
+
+@dataclass(kw_only=True)
+class ActionRegistryFileInfo:
+    directories: list[str]
+    filename: str
+    filepath: str
+
+
+ACTIONS_REGISTRY_ROOT = "main/unc/materials/shared/actions_registry/"
+action_definition_parser = CachedParser(
+    dict[str, actions_registry_t.ActionDefinitionYaml]
+)
+
+
+def get_action_registry_files_info() -> list[ActionRegistryFileInfo]:
+    files_info = []
+    for dirname, _, files in os.walk(ACTIONS_REGISTRY_ROOT):
+        directories = dirname.replace(ACTIONS_REGISTRY_ROOT, "").split("/")
+        for filename in files:
+            filepath = os.path.join(dirname, filename)
+            if os.path.isfile(filepath) and filepath.endswith(".yaml"):
+                files_info.append(
+                    ActionRegistryFileInfo(
+                        directories=directories,
+                        filename=filename.replace(".yaml", ""),
+                        filepath=filepath,
+                    )
+                )
+    return files_info
+
+
+def main() -> None:
+    files_info = get_action_registry_files_info()
+    action_definitions: defaultdict[str, list[actions_registry_t.ActionDefinition]] = (
+        defaultdict(list)
+    )
+    all_action_definitions: list[actions_registry_t.ActionDefinition] = []
+
+    for file_info in files_info:
+        in_action_definitions = action_definition_parser.parse_yaml_file(
+            file_info.filepath
+        )
+        if len(in_action_definitions) == 0:
+            continue
+        for ref_name, definition in in_action_definitions.items():
+            modules = [*file_info.directories]
+            # if the actions are stored in index.yaml, parent dir should be treated as module
+            if file_info.filename != "index":
+                modules.append(file_info.filename)
+
+            module_str = "_".join(modules)
+            all_action_definitions.append(
+                actions_registry_t.ActionDefinition(
+                    name=definition.name,
+                    short_description=definition.short_description,
+                    description=definition.description,
+                    icon=definition.icon,
+                    ref_name=ref_name,
+                    module=actions_registry_t.ActionsRegistryModule(
+                        ts_name(module_str, name_case=builder.NameCase.convert)
+                    ),
+                    visibility_scope=[
+                        actions_registry_t.ActionDefinitionVisibilityScope(item)
+                        for item in definition.visibility_scope
+                    ]
+                    if definition.visibility_scope is not None
+                    else None,
+                )
+            )
+    all_action_definitions = sorted(
+        all_action_definitions, key=lambda item: (item.module, item.ref_name)
+    )
+    for action_definition in all_action_definitions:
+        action_definitions[action_definition.module].append(action_definition)
+    ts_content = emit_action_definitions(action_definitions)
+    rewrite_file(
+        "main/site/js/materials/base/actions_registry/action_definitions.tsx",
+        ts_content,
+    )
+
+    sys.exit(0)
+
+
+main()

pkgs/type_spec/actions_registry/emit_typescript.py

@@ -0,0 +1,120 @@
+import io
+from collections import defaultdict
+
+from main.base.types import actions_registry_t
+
+from ...type_spec import builder
+from ..emit_typescript_util import INDENT, MODIFY_NOTICE, ts_name
+from ..util import encode_common_string
+
+
+def _action_symbol_name(action_definition: actions_registry_t.ActionDefinition) -> str:
+    return f"{ts_name(action_definition.ref_name, name_case=builder.NameCase.convert)}"
+
+
+def _action_module_name_base(module: str) -> str:
+    return f"{ts_name(module, name_case=builder.NameCase.convert)}"
+
+
+def _action_module_name_obj(module: str) -> str:
+    return f"{_action_module_name_base(module)}Actions"
+
+
+def _action_module_name(module: str) -> str:
+    return f"ActionsRegistryT.ActionsRegistryModule.{_action_module_name_base(module)}"
+
+
+def emit_action_definitions(
+    action_definitions: defaultdict[str, list[actions_registry_t.ActionDefinition]],
+) -> str:
+    out = io.StringIO()
+    out.write(MODIFY_NOTICE)
+    out.write("\n")
+    out.write('import { ActionsRegistryT } from "unc_mat/types"\n\n')
+    out.write(MODIFY_NOTICE)
+    modules = []
+    for key, values in action_definitions.items():
+        out.write(MODIFY_NOTICE)
+        modules.append(key)
+        out.write(f"export const {_action_module_name_obj(key)} = {{\n")
+        for action_definition in values:
+            out.write(MODIFY_NOTICE)
+            out.write(_emit_action_definition(action_definition, INDENT))
+        out.write("}\n")
+
+    out.write(MODIFY_NOTICE)
+    out.write("\n")
+    out.write("export const actionDefinitions = {\n")
+    for module in modules:
+        out.write(
+            f"{INDENT}[{_action_module_name(module)}]: {_action_module_name_obj(module)},\n"
+        )
+
+    out.write("}\n")
+    out.write(_emit_action_definition_types(modules, indent=""))
+    out.write(MODIFY_NOTICE)
+    out.write("\n")
+
+    return out.getvalue()
+
+
+def _emit_action_definition(
+    action_definition: actions_registry_t.ActionDefinition, indent: str
+) -> str:
+    out = io.StringIO()
+
+    sub_indent = indent + INDENT
+    out.write(f"{indent}{_action_symbol_name(action_definition)}: {{\n")
+    out.write(f"{sub_indent}name: {encode_common_string(action_definition.name)},\n")
+    if action_definition.icon is not None:
+        out.write(f"{sub_indent}icon: {encode_common_string(action_definition.icon)},\n")
+    out.write(
+        f"{sub_indent}shortDescription: {encode_common_string(action_definition.short_description)},\n"
+    )
+    out.write(
+        f"{sub_indent}description: {encode_common_string(action_definition.description)},\n"
+    )
+    out.write(
+        f"{sub_indent}refName: {encode_common_string(action_definition.ref_name)},\n"
+    )
+    out.write(f"{sub_indent}module: {_action_module_name(action_definition.module)},\n")
+    if (
+        action_definition.visibility_scope is not None
+        and len(action_definition.visibility_scope) > 0
+    ):
+        out.write(
+            f"{sub_indent}visibilityScope: {_emit_visibility_scope(action_definition.visibility_scope)},\n"
+        )
+    out.write(f"{indent}}},\n")
+    return out.getvalue()
+
+
+def _emit_action_definition_types(modules: list[str], indent: str) -> str:
+    out = io.StringIO()
+
+    sub_indent = indent + INDENT
+    out.write(
+        f"{indent}type RefNameKeys<M extends ActionsRegistryT.ActionsRegistryModule> = keyof (typeof actionDefinitions)[M]\n"
+    )
+    out.write(
+        f"{indent}type ActionDefinitionIdentifierGetter<M extends ActionsRegistryT.ActionsRegistryModule> = {{ module: M; refName: RefNameKeys<M> }}\n"
+    )
+    out.write(f"{indent}export type ActionDefinitionIdentifier =\n")
+    for module in modules:
+        out.write(
+            f"{sub_indent}| ActionDefinitionIdentifierGetter<{_action_module_name(module)}>\n"
+        )
+    out.write("\n")
+    return out.getvalue()
+
+
+def _emit_visibility_scope(
+    visibility_scope: list[actions_registry_t.ActionDefinitionVisibilityScope],
+) -> str:
+    visibility_scope_types = ",".join([
+        f"ActionsRegistryT.ActionDefinitionVisibilityScope.{ts_name(visibility_item, name_case=builder.NameCase.convert)}"
+        for visibility_item in visibility_scope
+        if visibility_item is not None
+    ])
+
+    return f"[ {visibility_scope_types} ]"

pkgs/type_spec/builder.py

@@ -9,22 +9,22 @@ import os
 import re
 from collections import defaultdict
 from dataclasses import MISSING, dataclass
-from enum import Enum, auto
-from typing import Any, Dict, Optional
+from enum import Enum, StrEnum, auto
+from typing import Any, Optional
 
 from . import util
 from .util import parse_type_str, unused
 
-RawDict = Dict[Any, Any]
+RawDict = dict[Any, Any]
 
 
-class PropertyExtant(str, Enum):
+class PropertyExtant(StrEnum):
     required = "required"
     optional = "optional"
     missing = "missing"
 
 
-class PropertyConvertValue(str, Enum):
+class PropertyConvertValue(StrEnum):
     # Base conversion on underlying types
     auto = "auto"
     # Always convert the value (Not needed yet, thus not supported)
@@ -52,7 +52,7 @@ class SpecProperty:
     ext_info: Any = None
 
 
-class NameCase(str, Enum):
+class NameCase(StrEnum):
     convert = "convert"
     preserve = "preserve"
     # Upper-case in JavaScript, convert otherwise. This is a compatibilty
@@ -60,7 +60,7 @@ class NameCase(str, Enum):
     js_upper = "js_upper"
 
 
-class BaseTypeName(str, Enum):
+class BaseTypeName(StrEnum):
     """
     Base types that are supported.
     """
@@ -92,7 +92,7 @@ class BaseTypeName(str, Enum):
     s_object = "Object"
 
 
-class DefnTypeName(str, Enum):
+class DefnTypeName(StrEnum):
     # Type is a named alias of another type
     s_alias = "Alias"
     # Type is imported from an external source (opaque to type_spec)
@@ -656,7 +656,7 @@ TOKEN_EMIT_TYPE_INFO = "$emit_type_info"
 TOKEN_IMPORT = "$import"
 
 
-class RouteMethod(str, Enum):
+class RouteMethod(StrEnum):
     post = "post"
     get = "get"
     delete = "delete"
@@ -664,7 +664,7 @@ class RouteMethod(str, Enum):
     put = "put"
 
 
-class ResultType(str, Enum):
+class ResultType(StrEnum):
     json = "json"
     binary = "binary"
 
@@ -747,6 +747,10 @@ class SpecEndpoint:
         self.is_external = self.path_root == "api/external"
         self.has_attachment = data.get("has_attachment", False)
 
+        assert (
+            not is_sdk or self.desc is not None
+        ), f"Endpoint description required for SDK endpoints, missing: {path}"
+
 
 def _parse_const(
     builder: SpecBuilder,

pkgs/type_spec/config.py

@@ -1,7 +1,8 @@
 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
 
@@ -96,7 +97,7 @@ 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)
 

pkgs/type_spec/emit_python.py

@@ -2,7 +2,7 @@ import io
 import os
 from dataclasses import dataclass, field
 from decimal import Decimal
-from typing import Any, Optional, Set
+from typing import Any, Optional
 
 from . import builder, util
 from .config import PythonConfig
@@ -25,8 +25,8 @@ END_ALL_EXPORTS = "]\n"
 @dataclass(kw_only=True)
 class TrackingContext:
     namespace: Optional[builder.SpecNamespace] = None
-    namespaces: Set[builder.SpecNamespace] = field(default_factory=set)
-    names: Set[str] = field(default_factory=set)
+    namespaces: set[builder.SpecNamespace] = field(default_factory=set)
+    names: set[str] = field(default_factory=set)
 
     use_enum: bool = False
     use_serial_string_enum: bool = False
@@ -119,6 +119,9 @@ def _emit_value(ctx: TrackingContext, stype: builder.SpecType, value: Any) -> st
         # Note that decimal requires the `!decimal 123.12` style notation in the YAML
         # file since PyYaml parses numbers as float, unfortuantely
         assert isinstance(value, (Decimal, int))
+        if isinstance(value, int):
+            # skip quotes for integers
+            return f"Decimal({value})"
         return f'Decimal("{value}")'
     elif isinstance(stype, builder.SpecTypeInstance):
         if stype.defn_type.is_base_type(builder.BaseTypeName.s_list):
@@ -220,7 +223,7 @@ def _emit_types(*, builder: builder.SpecBuilder, config: PythonConfig) -> None:
     exports_out = io.StringIO()
     exports_out.write(START_ALL_EXPORTS)
 
-    all_dirs: Set[str] = set()
+    all_dirs: set[str] = set()
 
     for namespace in sorted(
         builder.namespaces.values(),
@@ -347,6 +350,34 @@ def _validate_supports_handler_generation(
     return stype
 
 
+def _emit_endpoint_invocation_docstring(
+    ctx: Context,
+    endpoint: builder.SpecEndpoint,
+    arguments_type: builder.SpecTypeDefnObject,
+) -> None:
+    has_argument_desc = arguments_type.properties is not None and any(
+        prop.desc is not None for prop in arguments_type.properties.values()
+    )
+    has_endpoint_desc = endpoint.desc
+    if not has_argument_desc and not has_endpoint_desc:
+        return
+
+    FULL_INDENT = INDENT * 2
+    ctx.out.write(FULL_INDENT)
+    ctx.out.write('"""')
+
+    if endpoint.desc is not None and has_endpoint_desc:
+        ctx.out.write(f"{endpoint.desc}\n")
+        ctx.out.write("\n")
+
+    if arguments_type.properties is not None and has_argument_desc:
+        for prop in arguments_type.properties.values():
+            if prop.desc:
+                ctx.out.write(f"{FULL_INDENT}:param {prop.name}: {prop.desc}\n")
+
+    ctx.out.write(f'{FULL_INDENT}"""\n')
+
+
 def _emit_endpoint_invocation_function(
     ctx: Context, namespace: builder.SpecNamespace
 ) -> None:
@@ -393,8 +424,14 @@ def _emit_endpoint_invocation_function(
             class_out=ctx.out,
         )
     ctx.out.write(f"{INDENT}) -> {refer_to(ctx=ctx, stype=data_type)}:")
-
     ctx.out.write("\n")
+
+    _emit_endpoint_invocation_docstring(
+        ctx=ctx,
+        endpoint=endpoint,
+        arguments_type=arguments_type,
+    )
+
     ctx.out.write(f"{INDENT}{INDENT}args = {refer_to(ctx=ctx, stype=arguments_type)}(")
     if has_arguments:
         assert arguments_type.properties is not None
@@ -466,10 +503,10 @@ def _emit_string_enum(ctx: Context, stype: builder.SpecTypeDefnStringEnum) -> No
 
 @dataclass
 class EmittedPropertiesMetadata:
-    unconverted_keys: Set[str]
-    unconverted_values: Set[str]
-    to_string_values: Set[str]
-    parse_require: Set[str]
+    unconverted_keys: set[str]
+    unconverted_values: set[str]
+    to_string_values: set[str]
+    parse_require: set[str]
 
 
 def _emit_type_properties(
@@ -480,10 +517,10 @@ def _emit_type_properties(
     num_indent: int = 1,
     separator: str = "\n",
 ) -> EmittedPropertiesMetadata:
-    unconverted_keys: Set[str] = set()
-    unconverted_values: Set[str] = set()
-    to_string_values: Set[str] = set()
-    parse_require: Set[str] = set()
+    unconverted_keys: set[str] = set()
+    unconverted_values: set[str] = set()
+    to_string_values: set[str] = set()
+    parse_require: set[str] = set()
 
     if stype.properties is not None and len(stype.properties) > 0:
 
@@ -777,7 +814,7 @@ ROUTES: list[DynamicRouteType] = [
 def _emit_namespace_imports(
     *,
     out: io.StringIO,
-    namespaces: Set[builder.SpecNamespace],
+    namespaces: set[builder.SpecNamespace],
     from_namespace: Optional[builder.SpecNamespace],
     config: PythonConfig,
 ) -> None:
@@ -810,7 +847,7 @@ def _emit_id_source(*, builder: builder.SpecBuilder, config: PythonConfig) -> No
         return None
     enum_out = io.StringIO()
     enum_out.write(f"{LINT_HEADER}{MODIFY_NOTICE}\n")
-    enum_out.write("from typing import Literal, Type, Union\n")
+    enum_out.write("from typing import Literal, Union\n")
     enum_out.write("from pkgs.strenum_compat import StrEnum\n")
 
     ctx = TrackingContext()
@@ -825,13 +862,13 @@ def _emit_id_source(*, builder: builder.SpecBuilder, config: PythonConfig) -> No
     )
 
     known_keys = []
-    enum_out.write("\nENUM_MAP: dict[str, Type[StrEnum]] = {\n")
+    enum_out.write("\nENUM_MAP: dict[str, type[StrEnum]] = {\n")
     for key in sorted(named_enums.keys()):
         enum_out.write(f'"{key}": {named_enums[key]},\n')
         known_keys.append(f'Literal["{key}"]')
     enum_out.write(f"}}\n{MODIFY_NOTICE}\n")
 
-    enum_out.write(f"\nKnownEnumsType = Union[\\\n{INDENT}")
+    enum_out.write(f"\nKnownEnumsType = Union[\n{INDENT}")
     enum_out.write(f",\n{INDENT}".join(known_keys))
     enum_out.write(f"\n]\n{MODIFY_NOTICE}\n")
 

pkgs/type_spec/emit_typescript.py

@@ -1,6 +1,6 @@
 import io
 import os
-from typing import Any, Tuple
+from typing import Any
 
 from . import builder, util
 from .builder import SpecTypeDefnObject
@@ -226,20 +226,20 @@ def _emit_endpoint(
 
     if is_binary:
         tsx_response_part = f"""import {{ {wrap_name} }} from "unc_base/api"
-import {{ Arguments }} from "{type_path}"
+import type {{ Arguments }} from "{type_path}"
 
 export type {{ Arguments }}
 """
     elif has_data and endpoint.has_attachment:
-        tsx_response_part = f"""import {{ {wrap_name}, AttachmentResponse }} from "unc_base/api"
-import {{ Arguments, Data }} from "{type_path}"
+        tsx_response_part = f"""import {{ {wrap_name}, type AttachmentResponse }} from "unc_base/api"
+import type {{ Arguments, Data }} from "{type_path}"
 
 export type {{ Arguments, Data }}
 export type Response = AttachmentResponse<Data>
 """
     elif has_data:
-        tsx_response_part = f"""import {{ {wrap_name}, JsonResponse }} from "unc_base/api"
-import {{ Arguments, Data }} from "{type_path}"
+        tsx_response_part = f"""import {{ {wrap_name}, type JsonResponse }} from "unc_base/api"
+import type {{ Arguments, Data }} from "{type_path}"
 
 export type {{ Arguments, Data }}
 export type Response = JsonResponse<Data>
@@ -248,7 +248,7 @@ export type Response = JsonResponse<Data>
     else:
         assert has_deprecated_result
         tsx_response_part = f"""import {{ {wrap_name} }} from "unc_base/api"
-import {{ Arguments, DeprecatedResult }} from "{type_path}"
+import type {{ Arguments, DeprecatedResult }} from "{type_path}"
 
 export type {{ Arguments }}
 export type Response = DeprecatedResult
@@ -278,7 +278,6 @@ export const apiCall = {wrap_call}(
     if need_index:
         with open(index_path, "a") as index:
             print(f"Updated API Index {index_path}")
-            index.write("\n// eslint-disable-next-line import/first\n")
             index.write(f'import * as {api_name} from "./{namespace.path[-1]}"\n\n')
             index.write(f"export {{ {api_name} }}\n")
 
@@ -387,7 +386,7 @@ def refer_to(ctx: EmitTypescriptContext, stype: builder.SpecType) -> str:
 
 def refer_to_impl(
     ctx: EmitTypescriptContext, stype: builder.SpecType
-) -> Tuple[str, bool]:
+) -> tuple[str, bool]:
     """
     @return (string-specific, multiple-types)
     """

pkgs/type_spec/emit_typescript_util.py

@@ -1,5 +1,4 @@
 import io
-import typing
 from dataclasses import dataclass, field
 
 from . import builder, util
@@ -15,7 +14,7 @@ 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:

pkgs/type_spec/load_types.py

@@ -1,5 +1,6 @@
 import os
-from typing import Callable, Optional
+from collections.abc import Callable
+from typing import Optional
 
 import yaml
 from shelljob import fs

pkgs/type_spec/open_api_util.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from enum import Enum
+from enum import StrEnum
 from io import UnsupportedOperation
 from typing import Optional
 
@@ -41,7 +41,7 @@ class OpenAPIRefType(OpenAPIType):
         return {"$ref": self.source}
 
 
-class OpenAPIPrimitive(str, Enum):
+class OpenAPIPrimitive(StrEnum):
     string = "string"
     boolean = "boolean"
     integer = "integer"

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