code0-hercules 1.3.0__py3-none-any.whl

hercules/map/runtime_function.py

@@ -0,0 +1,64 @@
+"""Runtime function mapping (port of ``src/map/runtime_function.map.ts``)."""
+from __future__ import annotations
+
+from dataclasses import replace
+
+from hercules._metadata import get_metadata
+from hercules.models.function import FunctionParameterProps
+from hercules.models.runtime_function import RuntimeFunctionProps
+
+
+def _fill_parameter(param: FunctionParameterProps) -> FunctionParameterProps:
+    return replace(
+        param,
+        name=param.name or [],
+        description=param.description or [],
+        documentation=param.documentation or [],
+        hidden=param.hidden or False,
+        optional=param.optional or False,
+    )
+
+
+def runtime_function_map(klass: type) -> RuntimeFunctionProps:
+    identifier = get_metadata("hercules:identifier", klass)
+    runtime_parameters = get_metadata("hercules:function_parameters", klass) or []
+    name = get_metadata("hercules:name", klass) or []
+    display_message = get_metadata("hercules:display_message", klass) or []
+    description = get_metadata("hercules:description", klass) or []
+    deprecation_message = get_metadata("hercules:deprecation_message", klass) or []
+    alias = get_metadata("hercules:alias", klass) or []
+    documentation = get_metadata("hercules:documentation", klass) or []
+    signature = get_metadata("hercules:signature", klass)
+    display_icon = get_metadata("hercules:display_icon", klass) or ""
+    throws_error = get_metadata("hercules:throws_error", klass) or False
+    design = get_metadata("hercules:design", klass)
+
+    if not identifier:
+        raise ValueError(
+            f"Runtime function class {klass.__name__} is missing an identifier. "
+            f'Add @Identifier("your_identifier") to the class.'
+        )
+    if not signature:
+        raise ValueError(
+            f"Runtime function class {klass.__name__} is missing a signature. "
+            f'Add @Signature("(param1: TYPE_1): RETURN_TYPE") to the class.'
+        )
+
+    instance = klass()
+    handler = instance.run
+
+    return RuntimeFunctionProps(
+        runtime_name=identifier,
+        signature=signature,
+        throws_error=throws_error,
+        name=name,
+        description=description,
+        documentation=documentation,
+        deprecation_message=deprecation_message,
+        display_message=display_message,
+        alias=alias,
+        display_icon=display_icon or "tabler:note",
+        design=design,
+        parameters=[_fill_parameter(p) for p in runtime_parameters],
+        handler=handler,
+    )

hercules/models/datatype.py

@@ -0,0 +1,49 @@
+"""Data type models (port of ``src/models/datatype.model.ts``)."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from hercules.schema import Schema
+from hercules.internal.schema import pydantic_to_rules, pydantic_to_type_string
+from hercules.types import Translation
+
+
+class DataTypeProps:
+    """A resolved data type definition.
+
+    ``type`` is computed lazily from the schema so that errors (e.g. a recursive
+    schema that cannot be inlined) surface only when the type string is read.
+    """
+
+    def __init__(
+        self,
+        identifier: str,
+        schema: Schema,
+        name: Optional[List[Translation]] = None,
+        display_message: Optional[List[Translation]] = None,
+        alias: Optional[List[Translation]] = None,
+        generic_keys: Optional[List[str]] = None,
+        type_string: Optional[str] = None,
+    ) -> None:
+        self.identifier = identifier
+        self.schema = schema
+        self.name = name or []
+        self.display_message = display_message or []
+        self.alias = alias or []
+        self.generic_keys = generic_keys or []
+        # ``type_string`` is an explicit TypeScript type to emit verbatim. The
+        # generated built-in definitions use it to keep cross-data-type identifier
+        # references byte-exact; user-authored data types leave it unset and the
+        # type is derived from the Pydantic schema instead.
+        self._type_string = type_string
+        self.rules = pydantic_to_rules(schema)
+
+    @property
+    def type(self) -> str:
+        if self._type_string is not None:
+            return self._type_string
+        return pydantic_to_type_string(self.schema)
+
+
+class DataTypeRunnable:
+    """Base class for data type definitions."""

hercules/models/event.py

@@ -0,0 +1,35 @@
+"""Event (flow type) models (port of ``src/models/event.model.ts``)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from hercules._tucana.helpers import PlainValue
+from hercules.types import FlowTypeSetting_UniquenessScope, Translation
+
+
+@dataclass
+class EventSettingProps:
+    identifier: str
+    unique: Optional[Union[int, str]] = None
+    linked_data_type_identifiers: Optional[List[str]] = None
+    default_value: Optional[PlainValue] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    optional: Optional[bool] = None
+    hidden: Optional[bool] = None
+
+
+@dataclass
+class EventModel:
+    identifier: str
+    signature: str
+    settings: Optional[List[EventSettingProps]] = None
+    editable: Optional[bool] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    documentation: Optional[List[Translation]] = None
+    display_message: Optional[List[Translation]] = None
+    alias: Optional[List[Translation]] = None
+    display_icon: Optional[str] = None
+    runtime_identifier: Optional[str] = None

hercules/models/function.py

@@ -0,0 +1,37 @@
+"""Function definition models (port of ``src/models/function.model.ts``)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from hercules._tucana.helpers import PlainValue
+from hercules.types import Translation
+
+
+@dataclass
+class FunctionParameterProps:
+    runtime_name: str
+    default_value: Optional[PlainValue] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    documentation: Optional[List[Translation]] = None
+    hidden: Optional[bool] = None
+    optional: Optional[bool] = None
+    runtime_definition_name: Optional[str] = None
+
+
+@dataclass
+class FunctionProps:
+    runtime_definition_name: str
+    runtime_name: str
+    signature: str
+    parameters: Optional[List[FunctionParameterProps]] = None
+    throws_error: Optional[bool] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    documentation: Optional[List[Translation]] = None
+    deprecation_message: Optional[List[Translation]] = None
+    display_message: Optional[List[Translation]] = None
+    alias: Optional[List[Translation]] = None
+    display_icon: Optional[str] = None
+    design: Optional[str] = None

hercules/models/runtime_event.py

@@ -0,0 +1,29 @@
+"""Runtime event (runtime flow type) models.
+
+Port of ``src/models/runtime_event.model.ts``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from hercules.models.event import EventSettingProps
+from hercules.types import Translation
+
+
+class RuntimeEventRunnable:
+    """Base class for runtime events (runtime flow types)."""
+
+
+@dataclass
+class RuntimeEventProps:
+    identifier: str
+    signature: str
+    settings: Optional[List[EventSettingProps]] = None
+    editable: Optional[bool] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    documentation: Optional[List[Translation]] = None
+    display_message: Optional[List[Translation]] = None
+    alias: Optional[List[Translation]] = None
+    display_icon: Optional[str] = None

hercules/models/runtime_function.py

@@ -0,0 +1,33 @@
+"""Runtime function models (port of ``src/models/runtime_function.model.ts``)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+from hercules._tucana.helpers import PlainValue
+from hercules.models.function import FunctionParameterProps
+from hercules.types import Translation
+
+
+class RuntimeFunctionRunnable:
+    """Base class for runtime functions. Subclasses implement ``run``."""
+
+    def run(self, *args):  # pragma: no cover - overridden by subclasses
+        raise NotImplementedError
+
+
+@dataclass
+class RuntimeFunctionProps:
+    runtime_name: str
+    signature: str
+    handler: Callable[..., PlainValue]
+    parameters: Optional[List[FunctionParameterProps]] = None
+    throws_error: Optional[bool] = None
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    documentation: Optional[List[Translation]] = None
+    deprecation_message: Optional[List[Translation]] = None
+    display_message: Optional[List[Translation]] = None
+    alias: Optional[List[Translation]] = None
+    display_icon: Optional[str] = None
+    design: Optional[str] = None

hercules/schema.py

@@ -0,0 +1,38 @@
+"""Data-type schema surface, built on Pydantic v2.
+
+Data types are described with plain Pydantic models. Object shapes are ordinary
+``BaseModel`` subclasses; scalar/primitive shapes (a bare ``number``, a
+constrained ``string``, ``Record<string, unknown>``, ...) use ``RootModel``. The
+model is turned into a TypeScript type string and validation rules by
+:mod:`hercules.internal.schema`.
+
+Example::
+
+    from hercules.schema import BaseModel, RootModel, Annotated, StringConstraints
+
+    class Email(RootModel[Annotated[str, StringConstraints(pattern=r"^[^@]+@[^@]+$")]]):
+        pass
+
+    class User(BaseModel):
+        name: str
+        email: Email
+"""
+from __future__ import annotations
+
+from typing import Type
+
+from typing_extensions import Annotated
+from pydantic import BaseModel, RootModel, Field, StringConstraints, ConfigDict
+
+# A data-type schema is any Pydantic model class (``RootModel`` is a ``BaseModel``).
+Schema = Type[BaseModel]
+
+__all__ = [
+    "Schema",
+    "BaseModel",
+    "RootModel",
+    "Field",
+    "StringConstraints",
+    "ConfigDict",
+    "Annotated",
+]

hercules/types.py

@@ -0,0 +1,88 @@
+"""Shared types for the hercules SDK (port of ``src/types.ts``)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, List, Optional, Protocol, Union
+
+from hercules._tucana.helpers import PlainValue
+from tucana.generated.shared.flow_type_pb2 import FlowTypeSetting
+from tucana.generated.shared.runtime_flow_type_pb2 import RuntimeFlowTypeSetting
+from tucana.generated.shared.struct_pb2 import Struct
+
+# Re-export the uniqueness scope enums (mirror the TS re-exports).
+FlowTypeSetting_UniquenessScope = FlowTypeSetting.UniquenessScope
+RuntimeFlowTypeSetting_UniquenessScope = RuntimeFlowTypeSetting.UniquenessScope
+
+__all__ = [
+    "PlainValue",
+    "Struct",
+    "FlowTypeSetting_UniquenessScope",
+    "RuntimeFlowTypeSetting_UniquenessScope",
+    "Translation",
+    "SubFlow",
+    "FunctionContext",
+    "ProjectConfiguration",
+    "ConfigurationDefinition",
+    "RuntimeError",
+]
+
+
+@dataclass
+class Translation:
+    code: str
+    content: str
+
+
+class SubFlow(Protocol):
+    """A sub flow passed as a parameter (e.g. a CONSUMER).
+
+    Call it with the sub flow's parameters to execute it and await its result.
+    The input/output schema declared for the sub flow by the caller are exposed
+    via :attr:`input_schema` / :attr:`output_schema` (either may be ``None`` if
+    the caller omitted it).
+    """
+
+    input_schema: Optional[Struct]
+    output_schema: Optional[Struct]
+
+    def __call__(self, *args: PlainValue) -> Awaitable[PlainValue]: ...
+
+
+@dataclass
+class ProjectConfiguration:
+    project_id: int
+    config_values: List[dict] = field(default_factory=list)
+    find_config: Callable[[str], Optional[PlainValue]] = lambda identifier: None
+
+
+@dataclass
+class FunctionContext:
+    project_id: int
+    execution_id: str
+    matched_config: ProjectConfiguration
+    execute_flow: Callable[..., Awaitable[PlainValue]]
+
+
+@dataclass
+class ConfigurationDefinition:
+    identifier: str
+    type: str
+    name: Optional[List[Translation]] = None
+    description: Optional[List[Translation]] = None
+    hidden: Optional[bool] = None
+    optional: Optional[bool] = None
+    linked_data_types: Optional[List[str]] = None
+    default_value: Optional[PlainValue] = None
+
+
+class RuntimeError(Exception):
+    """Raised (or reported) when a runtime function fails with a known code."""
+
+    def __init__(self, code: str, description: Optional[str] = None) -> None:
+        message = f"Runtime error with code {code} occurred." + (
+            f" Description: {description}" if description else ""
+        )
+        super().__init__(message)
+        self.name = "RuntimeErrorException"
+        self.code = code
+        self.description = description