donna 0.2.0__py3-none-any.whl

donna/world/artifacts_discovery.py

@@ -0,0 +1,90 @@
+import pathlib
+from functools import lru_cache
+from typing import Iterable, Protocol
+
+from donna.domain.ids import ArtifactId, FullArtifactId, FullArtifactIdPattern, WorldId
+from donna.world.config import config
+
+
+class ArtifactListingNode(Protocol):
+    name: str
+
+    def is_dir(self) -> bool:
+        """Return True when node is a directory."""
+        ...
+
+    def is_file(self) -> bool:
+        """Return True when node is a file."""
+        ...
+
+    def iterdir(self) -> Iterable["ArtifactListingNode"]:
+        """Iterate over child nodes."""
+        ...
+
+
+def list_artifacts_by_pattern(  # noqa: CCR001
+    *,
+    world_id: WorldId,
+    root: ArtifactListingNode | None,
+    pattern: FullArtifactIdPattern,
+) -> list[ArtifactId]:
+    if pattern[0] not in {"*", "**"} and pattern[0] != str(world_id):
+        return []
+
+    if root is None or not root.is_dir():
+        return []
+
+    pattern_parts = tuple(pattern)
+    world_prefix = (str(world_id),)
+    supported_extensions = config().supported_extensions()
+    artifacts: set[ArtifactId] = set()
+
+    def walk(node: ArtifactListingNode, parts: list[str]) -> None:  # noqa: CCR001
+        for entry in sorted(node.iterdir(), key=lambda item: item.name):
+            if entry.is_dir():
+                next_parts = parts + [entry.name]
+                if not _pattern_allows_prefix(pattern_parts, world_prefix + tuple(next_parts)):
+                    continue
+                walk(entry, next_parts)
+                continue
+
+            if not entry.is_file():
+                continue
+
+            extension = pathlib.Path(entry.name).suffix.lower()
+            if extension not in supported_extensions:
+                continue
+
+            stem = entry.name[: -len(extension)]
+            artifact_name = ":".join(parts + [stem])
+            if ArtifactId.validate(artifact_name):
+                artifact_id = ArtifactId(artifact_name)
+                full_id = FullArtifactId((world_id, artifact_id))
+                if pattern.matches_full_id(full_id):
+                    artifacts.add(artifact_id)
+
+    walk(root, [])
+
+    return list(sorted(artifacts))
+
+
+def _pattern_allows_prefix(pattern_parts: tuple[str, ...], prefix_parts: tuple[str, ...]) -> bool:
+    @lru_cache(maxsize=None)
+    def match_at(p_index: int, v_index: int) -> bool:  # noqa: CCR001
+        if v_index >= len(prefix_parts):
+            return True
+
+        if p_index >= len(pattern_parts):
+            return False
+
+        token = pattern_parts[p_index]
+
+        if token == "**":  # noqa: S105
+            return match_at(p_index + 1, v_index) or match_at(p_index, v_index + 1)
+
+        if token == "*" or token == prefix_parts[v_index]:  # noqa: S105
+            return match_at(p_index + 1, v_index + 1)
+
+        return False
+
+    return match_at(0, 0)

donna/world/config.py

@@ -0,0 +1,198 @@
+import pathlib
+from typing import Any
+
+import pydantic
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.domain.ids import PythonImportPath, WorldId
+from donna.machine.primitives import resolve_primitive
+from donna.world import errors as world_errors
+from donna.world.sources.base import SourceConfig as SourceConfigValue
+from donna.world.sources.base import SourceConstructor
+from donna.world.worlds.base import World as BaseWorld
+from donna.world.worlds.base import WorldConstructor
+
+DONNA_DIR_NAME = ".donna"
+DONNA_CONFIG_NAME = "config.toml"
+DONNA_WORLD_SESSION_DIR_NAME = "session"
+DONNA_WORLD_PROJECT_DIR_NAME = "project"
+DONNA_WORLD_HOME_DIR_NAME = "home"
+
+
+class WorldConfig(BaseEntity):
+    kind: PythonImportPath
+    id: WorldId
+    readonly: bool
+    session: bool
+
+    model_config = pydantic.ConfigDict(extra="allow")
+
+
+class SourceConfig(BaseEntity):
+    kind: PythonImportPath
+
+    model_config = pydantic.ConfigDict(extra="allow")
+
+
+def _default_sources() -> list[SourceConfig]:
+    return [
+        SourceConfig.model_validate(
+            {
+                "kind": "donna.lib.sources.markdown",
+            }
+        ),
+    ]
+
+
+def _create_default_worlds(project_dir: pathlib.Path) -> list[WorldConfig]:
+    return [
+        WorldConfig.model_validate(
+            {
+                "id": WorldId("donna"),
+                "kind": "donna.lib.worlds.python",
+                "readonly": True,
+                "session": False,
+                "package": "donna",
+            }
+        ),
+        WorldConfig.model_validate(
+            {
+                "id": WorldId("home"),
+                "kind": "donna.lib.worlds.filesystem",
+                "readonly": True,
+                "session": False,
+                "path": pathlib.Path.home() / DONNA_DIR_NAME / DONNA_WORLD_HOME_DIR_NAME,
+            }
+        ),
+        WorldConfig.model_validate(
+            {
+                "id": WorldId("project"),
+                "kind": "donna.lib.worlds.filesystem",
+                "readonly": False,
+                "session": False,
+                "path": project_dir / DONNA_DIR_NAME / DONNA_WORLD_PROJECT_DIR_NAME,
+            }
+        ),
+        WorldConfig.model_validate(
+            {
+                "id": WorldId("session"),
+                "kind": "donna.lib.worlds.filesystem",
+                "readonly": False,
+                "session": True,
+                "path": project_dir / DONNA_DIR_NAME / DONNA_WORLD_SESSION_DIR_NAME,
+            }
+        ),
+    ]
+
+
+def _default_worlds() -> list[WorldConfig]:
+    return _create_default_worlds(project_dir())
+
+
+class Config(BaseEntity):
+    worlds: list[WorldConfig] = pydantic.Field(default_factory=_default_worlds)
+    sources: list[SourceConfig] = pydantic.Field(default_factory=_default_sources)
+    _worlds_instances: list[BaseWorld] = pydantic.PrivateAttr(default_factory=list)
+    _sources_instances: list[SourceConfigValue] = pydantic.PrivateAttr(default_factory=list)
+
+    tmp_dir: pathlib.Path = pathlib.Path("./tmp")
+
+    def model_post_init(self, __context: Any) -> None:  # noqa: CCR001
+        worlds: list[BaseWorld] = []
+        sources: list[SourceConfigValue] = []
+
+        for world_config in self.worlds:
+            primitive_result = resolve_primitive(world_config.kind)
+            if primitive_result.is_err():
+                error = primitive_result.unwrap_err()[0]
+                raise ValueError(error.message.format(error=error))
+
+            primitive = primitive_result.unwrap()
+
+            if not isinstance(primitive, WorldConstructor):
+                raise ValueError(f"World constructor '{world_config.kind}' is not supported")
+
+            worlds.append(primitive.construct_world(world_config))
+
+        for source_config in self.sources:
+            primitive_result = resolve_primitive(source_config.kind)
+            if primitive_result.is_err():
+                error = primitive_result.unwrap_err()[0]
+                raise ValueError(error.message.format(error=error))
+
+            primitive = primitive_result.unwrap()
+
+            if not isinstance(primitive, SourceConstructor):
+                raise ValueError(f"Source constructor '{source_config.kind}' is not supported")
+
+            sources.append(primitive.construct_source(source_config))
+
+        object.__setattr__(self, "_worlds_instances", worlds)
+        object.__setattr__(self, "_sources_instances", sources)
+
+    def get_world(self, world_id: WorldId) -> Result[BaseWorld, ErrorsList]:
+        for world in self._worlds_instances:
+            if world.id == world_id:
+                return Ok(world)
+
+        return Err([world_errors.WorldNotConfigured(world_id=world_id)])
+
+    @property
+    def worlds_instances(self) -> list[BaseWorld]:
+        return list(self._worlds_instances)
+
+    @property
+    def sources_instances(self) -> list[SourceConfigValue]:
+        return list(self._sources_instances)
+
+    def get_source_config(self, kind: str) -> Result[SourceConfigValue, ErrorsList]:
+        for source in self._sources_instances:
+            if source.kind == kind:
+                return Ok(source)
+
+        return Err([world_errors.SourceConfigNotConfigured(kind=kind)])
+
+    def find_source_for_extension(self, extension: str) -> SourceConfigValue | None:
+        for source in self._sources_instances:
+            if source.supports_extension(extension):
+                return source
+
+        return None
+
+    def supported_extensions(self) -> set[str]:
+        extensions: set[str] = set()
+
+        for source in self._sources_instances:
+            for extension in source.supported_extensions:
+                extensions.add(extension)
+
+        return extensions
+
+
+class GlobalConfig[V]():
+    __slots__ = ("_value",)
+
+    def __init__(self) -> None:
+        self._value: V | None = None
+
+    def set(self, value: V) -> None:
+        if self._value is not None:
+            raise world_errors.GlobalConfigAlreadySet()
+
+        self._value = value
+
+    def get(self) -> V:
+        if self._value is None:
+            raise world_errors.GlobalConfigNotSet()
+
+        return self._value
+
+    def __call__(self) -> V:
+        return self.get()
+
+
+project_dir = GlobalConfig[pathlib.Path]()
+config_dir = GlobalConfig[pathlib.Path]()
+config = GlobalConfig[Config]()

donna/world/errors.py

@@ -0,0 +1,232 @@
+import pathlib
+
+from donna.core import errors as core_errors
+from donna.domain.ids import ArtifactId, FullArtifactId, WorldId
+
+
+class InternalError(core_errors.InternalError):
+    """Base class for internal errors in donna.world."""
+
+
+class WorldError(core_errors.EnvironmentError):
+    cell_kind: str = "world_error"
+
+
+class WorldConfigError(WorldError):
+    cell_kind: str = "world_config_error"
+    config_path: pathlib.Path
+
+    def content_intro(self) -> str:
+        return f"Error in world config file '{self.config_path}'"
+
+
+class ConfigParseFailed(WorldConfigError):
+    code: str = "donna.world.config_parse_failed"
+    message: str = "Failed to parse config file: {error.details}"
+    details: str
+
+
+class ConfigValidationFailed(WorldConfigError):
+    code: str = "donna.world.config_validation_failed"
+    message: str = "Failed to validate config file: {error.details}"
+    details: str
+
+
+class WorldNotConfigured(WorldError):
+    code: str = "donna.world.world_not_configured"
+    message: str = "World with id `{error.world_id}` is not configured"
+    world_id: WorldId
+
+
+class SourceConfigNotConfigured(WorldError):
+    code: str = "donna.world.source_config_not_configured"
+    message: str = "Source config `{error.kind}` is not configured"
+    kind: str
+
+
+class WorldReadonly(WorldError):
+    code: str = "donna.world.world_readonly"
+    message: str = "World `{error.world_id}` is read-only"
+    ways_to_fix: list[str] = [
+        "Use a world configured with readonly = false. Most likely they are `project` and `session`.",
+    ]
+    world_id: WorldId
+
+
+class WorldStateStorageUnsupported(WorldError):
+    code: str = "donna.world.state_storage_unsupported"
+    message: str = "World `{error.world_id}` does not support state storage"
+    ways_to_fix: list[str] = [
+        "Use the session world.",
+    ]
+    world_id: WorldId
+
+
+class ArtifactError(WorldError):
+    cell_kind: str = "artifact_error"
+    artifact_id: ArtifactId
+    world_id: WorldId
+
+    def content_intro(self) -> str:
+        return f"Error for artifact '{self.artifact_id}' in world '{self.world_id}'"
+
+
+class ArtifactNotFound(ArtifactError):
+    code: str = "donna.world.artifact_not_found"
+    message: str = "Artifact `{error.artifact_id}` does not exist in world `{error.world_id}`"
+    ways_to_fix: list[str] = [
+        "Check the artifact id for typos.",
+        "Ensure the artifact exists in the specified world.",
+    ]
+
+
+class ArtifactMultipleFiles(ArtifactError):
+    code: str = "donna.world.artifact_multiple_files"
+    message: str = "Artifact `{error.artifact_id}` has multiple files in world `{error.world_id}`"
+    ways_to_fix: list[str] = [
+        "Keep a single source file per artifact in the world.",
+    ]
+
+
+class UnsupportedArtifactSourceExtension(ArtifactError):
+    code: str = "donna.world.unsupported_artifact_source_extension"
+    message: str = "Unsupported artifact source extension `{error.extension}` in world `{error.world_id}`"
+    ways_to_fix: list[str] = [
+        "Use a supported extension for the configured sources.",
+    ]
+    extension: str
+
+
+class MarkdownError(WorldError):
+    cell_kind: str = "markdown_error"
+    artifact_id: FullArtifactId | None = None
+
+    def content_intro(self) -> str:
+        if self.artifact_id is None:
+            return "Error in markdown source"
+
+        return f"Error in markdown artifact '{self.artifact_id}'"
+
+
+class TemplateDirectiveError(WorldError):
+    cell_kind: str = "template_directive_error"
+    artifact_id: FullArtifactId | None = None
+
+    def content_intro(self) -> str:
+        if self.artifact_id is None:
+            return "Error in template directive"
+
+        return f"Error in template directive for artifact '{self.artifact_id}'"
+
+
+class DirectivePathIncomplete(TemplateDirectiveError):
+    code: str = "donna.world.directive_path_incomplete"
+    message: str = "Directive path must include module and directive parts, got `{error.path}`."
+    ways_to_fix: list[str] = ["Use a directive path with both module and directive names."]
+    path: str
+
+
+class DirectiveModuleNotImportable(TemplateDirectiveError):
+    code: str = "donna.world.directive_module_not_importable"
+    message: str = "Directive module `{error.module_path}` is not importable."
+    ways_to_fix: list[str] = [
+        "Check the module path for typos.",
+        "Ensure the module exists and is importable in the current environment.",
+    ]
+    module_path: str
+
+
+class DirectiveNotAvailable(TemplateDirectiveError):
+    code: str = "donna.world.directive_not_available"
+    message: str = "Directive `{error.module_path}.{error.directive_name}` is not available."
+    ways_to_fix: list[str] = [
+        "Check the directive name for typos.",
+        "Ensure the directive is defined in the module.",
+    ]
+    module_path: str
+    directive_name: str
+
+
+class DirectiveNotDirective(TemplateDirectiveError):
+    code: str = "donna.world.directive_not_directive"
+    message: str = "`{error.module_path}.{error.directive_name}` is not a directive."
+    ways_to_fix: list[str] = [
+        "Check the directive path for typos.",
+        "Check if you use the right primitive for the task.",
+        "Ensure the referenced object is a `donna.machine.templates.Directive` instance.",
+    ]
+    module_path: str
+    directive_name: str
+
+
+class DirectiveUnexpectedError(TemplateDirectiveError):
+    code: str = "donna.world.directive_unexpected_error"
+    message: str = "Unexpected error while applying directive `{error.directive_path}`: {error.details}"
+    ways_to_fix: list[str] = [
+        "Check the documentation for the directive to ensure correct usage.",
+        "Ask the developer to help debug the issue.",
+    ]
+    directive_path: str
+    details: str
+
+
+class MarkdownUnsupportedCodeFormat(MarkdownError):
+    code: str = "donna.world.markdown_unsupported_code_format"
+    message: str = "Unsupported code block format `{error.format}`"
+    ways_to_fix: list[str] = [
+        "Use one of the supported formats: json, yaml, yml, toml.",
+    ]
+    format: str
+
+
+class MarkdownMultipleH1Sections(MarkdownError):
+    code: str = "donna.world.markdown_multiple_h1_sections"
+    message: str = "Multiple H1 sections are not supported"
+    ways_to_fix: list[str] = [
+        "Keep a single H1 section in the artifact.",
+    ]
+
+
+class MarkdownMultipleH1Titles(MarkdownError):
+    code: str = "donna.world.markdown_multiple_h1_titles"
+    message: str = "Multiple H1 titles are not supported"
+    ways_to_fix: list[str] = [
+        "Keep a single H1 title in the artifact.",
+    ]
+
+
+class MarkdownH2BeforeH1Title(MarkdownError):
+    code: str = "donna.world.markdown_h2_before_h1_title"
+    message: str = "H2 section found before H1 title"
+    ways_to_fix: list[str] = [
+        "Ensure the first heading is an H1 title before any H2 sections.",
+    ]
+
+
+class MarkdownArtifactWithoutSections(MarkdownError):
+    code: str = "donna.world.markdown_artifact_without_sections"
+    message: str = "Artifact MUST have at least one section"
+
+
+class PrimitiveDoesNotSupportMarkdown(MarkdownError):
+    code: str = "donna.world.primitive_does_not_support_markdown"
+    message: str = "Primitive {error.primitive_id} cannot construct artifact section from the Markdown source"
+    ways_to_fix: list[str] = [
+        "Ensure the section kind points to a primitive that supports Markdown sections.",
+    ]
+    primitive_id: str
+
+
+class MarkdownSectionsCountMismatch(InternalError):
+    message = (
+        "Artifact `{artifact_id}` has {original_count} sections in the original render "
+        "and {analyzed_count} sections in the analysis render."
+    )
+
+
+class GlobalConfigAlreadySet(InternalError):
+    message = "Global config value is already set"
+
+
+class GlobalConfigNotSet(InternalError):
+    message = "Global config value is not set"

donna/world/initialization.py

@@ -0,0 +1,42 @@
+import tomllib
+
+from donna.core import errors as core_errors
+from donna.core import utils
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.world import config
+from donna.world import errors as world_errors
+
+
+@unwrap_to_error
+def initialize_environment() -> Result[None, core_errors.ErrorsList]:
+    """Initialize the environment for the application.
+
+    This function MUST be called before any other operations.
+    """
+    project_dir = utils.discover_project_dir(config.DONNA_DIR_NAME).unwrap()
+
+    config.project_dir.set(project_dir)
+
+    config_dir = project_dir / config.DONNA_DIR_NAME
+
+    config.config_dir.set(config_dir)
+
+    config_path = config_dir / config.DONNA_CONFIG_NAME
+
+    if not config_path.exists():
+        config.config.set(config.Config())
+        return Ok(None)
+
+    try:
+        data = tomllib.loads(config_path.read_text())
+    except tomllib.TOMLDecodeError as e:
+        return Err([world_errors.ConfigParseFailed(config_path=config_path, details=str(e))])
+
+    try:
+        loaded_config = config.Config.model_validate(data)
+    except Exception as e:
+        return Err([world_errors.ConfigValidationFailed(config_path=config_path, details=str(e))])
+
+    config.config.set(loaded_config)
+
+    return Ok(None)