donna 0.2.0__py3-none-any.whl

donna/machine/artifacts.py

@@ -0,0 +1,200 @@
+from typing import TYPE_CHECKING, Any
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import ArtifactSectionId, FullArtifactId, FullArtifactSectionId, PythonImportPath
+from donna.machine.errors import (
+    ArtifactPrimarySectionMissing,
+    ArtifactSectionNotFound,
+    MultiplePrimarySectionsError,
+)
+from donna.protocol.cells import Cell
+from donna.protocol.nodes import Node
+
+if TYPE_CHECKING:
+    from donna.world.artifacts import ArtifactRenderContext
+
+
+class ArtifactSectionConfig(BaseEntity):
+    id: ArtifactSectionId
+    kind: PythonImportPath
+
+
+class ArtifactSectionMeta(BaseEntity):
+    def cells_meta(self) -> dict[str, Any]:
+        return {}
+
+
+class ArtifactSection(BaseEntity):
+    id: ArtifactSectionId
+    artifact_id: FullArtifactId
+    kind: PythonImportPath
+    title: str
+    description: str
+    primary: bool = False
+
+    meta: ArtifactSectionMeta
+
+    def node(self) -> "ArtifactSectionNode":
+        return ArtifactSectionNode(self)
+
+    def markdown_blocks(self) -> list[str]:
+        return [f"## {self.title}", self.description]
+
+
+class Artifact(BaseEntity):
+    id: FullArtifactId
+
+    sections: list[ArtifactSection]
+
+    def _primary_sections(self) -> list[ArtifactSection]:
+        return [section for section in self.sections if section.primary]
+
+    def primary_section(self) -> Result[ArtifactSection, ErrorsList]:
+        primary_sections = self._primary_sections()
+        if len(primary_sections) == 0:
+            return Err([ArtifactPrimarySectionMissing(artifact_id=self.id)])
+        if len(primary_sections) > 1:
+            return Err(
+                [
+                    MultiplePrimarySectionsError(
+                        artifact_id=self.id,
+                        primary_sections=sorted(section.id for section in primary_sections),
+                    )
+                ]
+            )
+        return Ok(primary_sections[0])
+
+    def validate_artifact(self) -> Result[None, ErrorsList]:  # noqa: CCR001
+        from donna.machine.primitives import resolve_primitive
+
+        primary_sections = self._primary_sections()
+
+        errors: ErrorsList = []
+
+        if len(primary_sections) == 0:
+            errors.append(ArtifactPrimarySectionMissing(artifact_id=self.id))
+        elif len(primary_sections) > 1:
+            errors.append(
+                MultiplePrimarySectionsError(
+                    artifact_id=self.id,
+                    primary_sections=sorted(section.id for section in primary_sections),
+                )
+            )
+
+        for section in self.sections:
+            primitive_result = resolve_primitive(section.kind)
+            if primitive_result.is_err():
+                errors.extend(primitive_result.unwrap_err())
+                continue
+
+            primitive = primitive_result.unwrap()
+            result = primitive.validate_section(self, section.id)
+
+            if result.is_ok():
+                continue
+
+            errors.extend(result.unwrap_err())
+
+        if errors:
+            return Err(errors)
+
+        return Ok(None)
+
+    def get_section(self, section_id: ArtifactSectionId | None) -> Result[ArtifactSection, ErrorsList]:
+        if section_id is None:
+            return self.primary_section()
+        for section in self.sections:
+            if section.id == section_id:
+                return Ok(section)
+        return Err([ArtifactSectionNotFound(artifact_id=self.id, section_id=section_id)])
+
+    def node(self) -> "ArtifactNode":
+        return ArtifactNode(self)
+
+    @unwrap_to_error
+    def markdown_blocks(self) -> Result[list[str], ErrorsList]:
+        primary_section = self.primary_section().unwrap()
+        blocks = [f"# {primary_section.title}", primary_section.description]
+
+        for section in self.sections:
+            if section.primary:
+                continue
+            blocks.extend(section.markdown_blocks())
+
+        return Ok(blocks)
+
+
+class ArtifactNode(Node):
+    __slots__ = ("_artifact",)
+
+    def __init__(self, artifact: Artifact) -> None:
+        self._artifact = artifact
+
+    def status(self) -> Cell:
+        primary_section_result = self._artifact.primary_section()
+        if primary_section_result.is_err():
+            return primary_section_result.unwrap_err()[0].node().status()
+
+        primary_section = primary_section_result.unwrap()
+        return Cell.build_meta(
+            kind="artifact_status",
+            artifact_id=str(self._artifact.id),
+            artifact_kind=str(primary_section.kind),
+            artifact_title=primary_section.title,
+            artifact_description=primary_section.description,
+        )
+
+    def info(self) -> Cell:
+        primary_section_result = self._artifact.primary_section()
+        if primary_section_result.is_err():
+            return primary_section_result.unwrap_err()[0].node().info()
+
+        primary_section = primary_section_result.unwrap()
+        blocks_result = self._artifact.markdown_blocks()
+        if blocks_result.is_err():
+            return blocks_result.unwrap_err()[0].node().info()
+
+        return Cell.build_markdown(
+            kind="artifact_info",
+            content="\n".join(blocks_result.unwrap()),
+            artifact_id=str(self._artifact.id),
+            artifact_kind=str(primary_section.kind),
+            artifact_title=primary_section.title,
+            artifact_description=primary_section.description,
+        )
+
+    def components(self) -> list["Node"]:
+        return [ArtifactSectionNode(section) for section in self._artifact.sections]
+
+
+class ArtifactSectionNode(Node):
+    __slots__ = ("_section",)
+
+    def __init__(self, section: ArtifactSection) -> None:
+        self._section = section
+
+    def status(self) -> Cell:
+        return Cell.build_markdown(
+            kind="artifact_section_status",
+            content="\n".join(self._section.markdown_blocks()),
+            artifact_id=str(self._section.artifact_id),
+            section_id=str(self._section.id),
+            section_kind=str(self._section.kind),
+            section_primary=self._section.primary,
+            **self._section.meta.cells_meta(),
+        )
+
+
+@unwrap_to_error
+def resolve(
+    target_id: FullArtifactSectionId, render_context: "ArtifactRenderContext"
+) -> Result[ArtifactSection, ErrorsList]:
+    from donna.world import artifacts as world_artifacts
+
+    artifact = world_artifacts.load_artifact(target_id.full_artifact_id, render_context).unwrap()
+
+    section = artifact.get_section(target_id.local_id).unwrap()
+
+    return Ok(section)

donna/machine/changes.py

@@ -0,0 +1,91 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from donna.core.entities import BaseEntity
+from donna.domain.ids import ActionRequestId, FullArtifactSectionId, TaskId, WorkUnitId
+from donna.machine.action_requests import ActionRequest
+from donna.machine.tasks import Task, WorkUnit
+
+if TYPE_CHECKING:
+    from donna.machine.state import MutableState
+
+
+class Change(BaseEntity, ABC):
+    @abstractmethod
+    def apply_to(self, state: "MutableState") -> None: ...  # noqa: E704
+
+
+class ChangeFinishTask(Change):
+    task_id: TaskId
+
+    def apply_to(self, state: "MutableState") -> None:
+        state.finish_workflow(self.task_id)
+
+
+class ChangeAddWorkUnit(Change):
+    task_id: TaskId
+    operation_id: FullArtifactSectionId
+
+    def apply_to(self, state: "MutableState") -> None:
+        work_unit = WorkUnit.build(id=state.next_work_unit_id(), task_id=self.task_id, operation_id=self.operation_id)
+        state.add_work_unit(work_unit)
+
+
+class ChangeAddTask(Change):
+    operation_id: FullArtifactSectionId
+
+    def apply_to(self, state: "MutableState") -> None:
+        task = Task.build(state.next_task_id())
+
+        state.add_task(task)
+
+        work_unit = WorkUnit.build(id=state.next_work_unit_id(), task_id=task.id, operation_id=self.operation_id)
+
+        state.add_work_unit(work_unit)
+
+        state.mark_started()
+
+
+class ChangeRemoveTask(Change):
+    task_id: TaskId
+
+    def apply_to(self, state: "MutableState") -> None:
+        state.remove_task(self.task_id)
+
+
+class ChangeAddActionRequest(Change):
+    action_request: ActionRequest
+
+    def apply_to(self, state: "MutableState") -> None:
+        state.add_action_request(self.action_request)
+
+
+class ChangeRemoveActionRequest(Change):
+    action_request_id: ActionRequestId
+
+    def apply_to(self, state: "MutableState") -> None:
+        state.remove_action_request(self.action_request_id)
+
+
+class ChangeRemoveWorkUnit(Change):
+    work_unit_id: WorkUnitId
+
+    def apply_to(self, state: "MutableState") -> None:
+        state.remove_work_unit(self.work_unit_id)
+
+
+class ChangeSetTaskContext(Change):
+    task_id: TaskId
+    key: str
+    value: object
+
+    def apply_to(self, state: "MutableState") -> None:
+        target_task: Task | None = None
+        for task in state.tasks:
+            if task.id == self.task_id:
+                target_task = task
+                break
+
+        assert target_task is not None
+
+        target_task.context[self.key] = self.value

donna/machine/errors.py

@@ -0,0 +1,122 @@
+from donna.core import errors as core_errors
+from donna.domain.ids import ActionRequestId, ArtifactSectionId, FullArtifactId, FullArtifactSectionId
+
+
+class InternalError(core_errors.InternalError):
+    """Base class for internal errors in donna.machine."""
+
+
+class PrimitiveMethodUnsupported(InternalError):
+    message: str = "Primitive '{primitive_name}' does not support {method_name}."
+    primitive_name: str
+    method_name: str
+
+
+class SessionStateStatusInvalid(InternalError):
+    message: str = "Session state status is invalid."
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """Base class for environment errors in donna.machine."""
+
+    cell_kind: str = "machine_error"
+
+
+class SessionStateNotInitialized(EnvironmentError):
+    code: str = "donna.machine.session_state_not_initialized"
+    message: str = "Session state is not initialized."
+    ways_to_fix: list[str] = ["Run Donna session start to initialize session state."]
+
+
+class ActionRequestNotFound(EnvironmentError):
+    code: str = "donna.machine.action_request_not_found"
+    message: str = "Action request `{error.request_id}` was not found in the current session state."
+    ways_to_fix: list[str] = ["Use an action request id from `sessions details` output."]
+    request_id: ActionRequestId
+
+
+class InvalidOperationTransition(EnvironmentError):
+    code: str = "donna.machine.invalid_operation_transition"
+    message: str = "Operation `{error.operation_id}` cannot transition to `{error.next_operation_id}`."
+    ways_to_fix: list[str] = [
+        "Check the next operation id for typos.",
+        "Use one of the allowed transitions listed in the action request.",
+    ]
+    operation_id: FullArtifactSectionId
+    next_operation_id: FullArtifactSectionId
+
+
+class PrimitiveInvalidImportPath(EnvironmentError):
+    code: str = "donna.machine.primitive_invalid_import_path"
+    message: str = "Primitive `{error.import_path}` is not a valid import path."
+    ways_to_fix: list[str] = ["Use a full Python import path, e.g. `package.module.primitive_instance`."]
+    import_path: str
+
+
+class PrimitiveModuleNotImportable(EnvironmentError):
+    code: str = "donna.machine.primitive_module_not_importable"
+    message: str = "Primitive module `{error.module_path}` is not importable."
+    ways_to_fix: list[str] = [
+        "Check the module path for typos.",
+        "Check specifications for the correct primitive to use.",
+        (
+            "Check the module exists and is importable in the current environment. "
+            "If not, ask the developer to install it."
+        ),
+    ]
+    module_path: str
+
+
+class PrimitiveNotAvailable(EnvironmentError):
+    code: str = "donna.machine.primitive_not_available"
+    message: str = "Primitive `{error.import_path}` is not available in module `{error.module_path}`."
+    ways_to_fix: list[str] = [
+        "Check the primitive name for typos.",
+        "Ensure you are using the correct module for the desired primitive.",
+        "Check specifications for the correct primitive to use.",
+    ]
+    import_path: str
+    module_path: str
+
+
+class PrimitiveNotPrimitive(EnvironmentError):
+    code: str = "donna.machine.primitive_not_primitive"
+    message: str = "`{error.import_path}` is not a Primitive instance."
+    ways_to_fix: list[str] = [
+        "Check the primitive name for typos.",
+        "Ensure you are using the correct module for the desired primitive.",
+        "Check specifications for the correct primitive to use.",
+        "Ensure the referenced object is a `donna.machine.primitives.Primitive` instance.",
+    ]
+    import_path: str
+
+
+class ArtifactValidationError(EnvironmentError):
+    cell_kind: str = "artifact_validation_error"
+    artifact_id: FullArtifactId
+    section_id: ArtifactSectionId | None = None
+
+    def content_intro(self) -> str:
+        if self.section_id:
+            return f"Error in artifact '{self.artifact_id}', section '{self.section_id}'"
+
+        return f"Error in artifact '{self.artifact_id}'"
+
+
+class MultiplePrimarySectionsError(ArtifactValidationError):
+    code: str = "donna.artifacts.multiple_primary_sections"
+    message: str = "Artifact must have exactly one primary section, found multiple: `{error.primary_sections}`"
+    ways_to_fix: list[str] = ["Keep a single primary section in the artifact."]
+    primary_sections: list[ArtifactSectionId]
+
+
+class ArtifactPrimarySectionMissing(ArtifactValidationError):
+    code: str = "donna.artifacts.primary_section_missing"
+    message: str = "Artifact must have exactly one primary section, found none."
+    ways_to_fix: list[str] = ["Keep a single primary section in the artifact."]
+
+
+class ArtifactSectionNotFound(ArtifactValidationError):
+    code: str = "donna.artifacts.section_not_found"
+    message: str = "Section `{error.section_id}` is not available in artifact `{error.artifact_id}`."
+    ways_to_fix: list[str] = ["Check the section id for typos.", "Ensure the section exists in the artifact."]

donna/machine/operations.py

@@ -0,0 +1,31 @@
+import enum
+from typing import TYPE_CHECKING, Any
+
+from donna.domain.ids import ArtifactSectionId
+from donna.machine.artifacts import ArtifactSectionConfig, ArtifactSectionMeta
+from donna.machine.primitives import Primitive
+
+if TYPE_CHECKING:
+    pass
+
+
+class FsmMode(enum.Enum):
+    start = "start"
+    normal = "normal"
+    final = "final"
+
+
+class OperationKind(Primitive):
+    pass
+
+
+class OperationConfig(ArtifactSectionConfig):
+    fsm_mode: FsmMode = FsmMode.normal
+
+
+class OperationMeta(ArtifactSectionMeta):
+    fsm_mode: FsmMode = FsmMode.normal
+    allowed_transtions: set[ArtifactSectionId]
+
+    def cells_meta(self) -> dict[str, Any]:
+        return {"fsm_mode": self.fsm_mode.value, "allowed_transtions": [str(t) for t in self.allowed_transtions]}

donna/machine/primitives.py

@@ -0,0 +1,77 @@
+import importlib
+from typing import TYPE_CHECKING, Any, ClassVar, Iterable
+
+from jinja2.runtime import Context
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import ArtifactSectionId, PythonImportPath
+from donna.machine import errors as machine_errors
+from donna.machine.artifacts import ArtifactSectionConfig
+
+if TYPE_CHECKING:
+    from donna.machine.artifacts import Artifact, ArtifactSection
+    from donna.machine.changes import Change
+    from donna.machine.tasks import Task, WorkUnit
+    from donna.world.config import SourceConfig as SourceConfigModel
+    from donna.world.config import WorldConfig
+    from donna.world.sources.base import SourceConfig as SourceConfigValue
+    from donna.world.worlds.base import World
+
+
+# TODO: Currently is is a kind of God interface. It is convinient for now.
+#       However, in future we should move these methods into specific subclasses.
+class Primitive(BaseEntity):
+    config_class: ClassVar[type[ArtifactSectionConfig]] = ArtifactSectionConfig
+
+    def validate_section(self, artifact: "Artifact", section_id: ArtifactSectionId) -> Result[None, ErrorsList]:
+        return Ok(None)
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", section: "ArtifactSection") -> Iterable["Change"]:
+        raise machine_errors.PrimitiveMethodUnsupported(
+            primitive_name=self.__class__.__name__, method_name="execute_section()"
+        )
+
+    def apply_directive(self, context: Context, *argv: Any, **kwargs: Any) -> Result[Any, ErrorsList]:
+        raise machine_errors.PrimitiveMethodUnsupported(
+            primitive_name=self.__class__.__name__, method_name="apply_directive()"
+        )
+
+    def construct_world(self, config: "WorldConfig") -> "World":
+        raise machine_errors.PrimitiveMethodUnsupported(
+            primitive_name=self.__class__.__name__, method_name="construct_world()"
+        )
+
+    def construct_source(self, config: "SourceConfigModel") -> "SourceConfigValue":
+        raise machine_errors.PrimitiveMethodUnsupported(
+            primitive_name=self.__class__.__name__, method_name="construct_source()"
+        )
+
+
+@unwrap_to_error
+def resolve_primitive(primitive_id: PythonImportPath | str) -> Result[Primitive, ErrorsList]:  # noqa: CCR001
+    if isinstance(primitive_id, PythonImportPath):
+        import_path = str(primitive_id)
+    else:
+        import_path = str(PythonImportPath.parse(primitive_id).unwrap())
+
+    if "." not in import_path:
+        return Err([machine_errors.PrimitiveInvalidImportPath(import_path=import_path)])
+
+    module_path, primitive_name = import_path.rsplit(".", maxsplit=1)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError:
+        return Err([machine_errors.PrimitiveModuleNotImportable(module_path=module_path)])
+
+    try:
+        primitive = getattr(module, primitive_name)
+    except AttributeError:
+        return Err([machine_errors.PrimitiveNotAvailable(import_path=import_path, module_path=module_path)])
+
+    if not isinstance(primitive, Primitive):
+        return Err([machine_errors.PrimitiveNotPrimitive(import_path=import_path)])
+
+    return Ok(primitive)