donna 0.2.0__py3-none-any.whl

donna/cli/utils.py

@@ -0,0 +1,53 @@
+import functools
+import sys
+from collections.abc import Iterable
+from typing import Callable, ParamSpec
+
+import typer
+
+from donna.core.errors import EnvironmentError
+from donna.core.result import UnwrapError
+from donna.protocol.cells import Cell
+from donna.protocol.modes import get_cell_formatter
+from donna.world.initialization import initialize_environment
+
+
+def output_cells(cells: Iterable[Cell]) -> None:
+    formatter = get_cell_formatter()
+
+    output = formatter.format_cells(list(cells))
+
+    sys.stdout.buffer.write(output)
+
+
+P = ParamSpec("P")
+
+
+def cells_cli(func: Callable[P, Iterable[Cell]]) -> Callable[P, None]:
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+        try:
+            cells = func(*args, **kwargs)
+        except UnwrapError as e:
+            if isinstance(e.arguments["error"], EnvironmentError):
+                cells = [e.arguments["error"].node().info()]
+            elif isinstance(e.arguments["error"], Iterable):
+                cells = [error.node().info() for error in e.arguments["error"] if isinstance(error, EnvironmentError)]
+            else:
+                raise
+
+        output_cells(cells)
+
+    return wrapper
+
+
+def try_initialize_donna() -> None:
+    result = initialize_environment()
+
+    if result.is_ok():
+        return
+
+    output_cells([error.node().info() for error in result.unwrap_err()])
+
+    raise typer.Exit(code=0)

donna/core/entities.py

@@ -0,0 +1,27 @@
+from typing import Any, TypeVar
+
+import pydantic
+
+BASE_ENTITY = TypeVar("BASE_ENTITY", bound="BaseEntity")
+
+
+class BaseEntity(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(
+        str_strip_whitespace=True,
+        validate_default=True,
+        extra="forbid",
+        frozen=True,
+        validate_assignment=True,
+        from_attributes=False,
+    )
+
+    def replace(self: BASE_ENTITY, **kwargs: Any) -> BASE_ENTITY:
+        return self.model_copy(update=kwargs, deep=True)
+
+    def to_json(self) -> str:
+        # TODO: make indent configurable
+        return self.model_dump_json(indent=2)
+
+    @classmethod
+    def from_json(cls: type[BASE_ENTITY], json_data: str) -> BASE_ENTITY:
+        return cls.model_validate_json(json_data)

donna/core/errors.py

@@ -0,0 +1,126 @@
+from typing import Any
+
+import pydantic
+
+from donna.core.entities import BaseEntity
+from donna.protocol.cells import Cell, MetaValue, to_meta_value
+from donna.protocol.nodes import Node
+
+
+class InternalError(Exception):
+    message = "An internal error occurred"
+
+    def __init__(self, **kwargs: Any) -> None:
+        self.arguments = kwargs
+
+    def error_message(self) -> str:
+        return self.message.format(**self.arguments)
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}: {self.error_message()}"
+
+
+class EnvironmentError(BaseEntity):
+    cell_kind: str
+    cell_media_type: str = "text/markdown"
+
+    code: str
+    message: str
+    ways_to_fix: list[str] = pydantic.Field(default_factory=list)
+
+    def content_intro(self) -> str:
+        return "Error"
+
+    def node(self) -> "EnvironmentErrorNode":
+        return EnvironmentErrorNode(self)
+
+
+class EnvironmentErrorsProxy(InternalError):
+    message = "This is a technical exception to pass an environment error up the call stack."
+
+    def __init__(self, errors: list[EnvironmentError]) -> None:
+        super().__init__(errors=errors)
+
+
+class CoreEnvironmentError(EnvironmentError):
+    """Base class for environment errors in donna.core."""
+
+    cell_kind: str = "core_environment_error"
+
+
+class ProjectDirNotFound(CoreEnvironmentError):
+    code: str = "donna.core.project_dir_not_found"
+    message: str = "Could not find a project directory containing `{error.donna_dir_name}`."
+    ways_to_fix: list[str] = [
+        "Run Donna from within a project directory that contains the donna directory.",
+        "Create the donna directory in the project root if it is missing.",
+    ]
+    donna_dir_name: str
+
+
+class ProjectDirIsHome(CoreEnvironmentError):
+    code: str = "donna.core.project_dir_is_home"
+    message: str = "The discovered `{error.donna_dir_name}` directory is the home directory, not a project directory."
+    ways_to_fix: list[str] = [
+        "Run Donna from within a project directory that contains the donna directory.",
+        "Move the donna directory out of the home folder into the project root if appropriate.",
+    ]
+    donna_dir_name: str
+
+
+class EnvironmentErrorNode(Node):
+    __slots__ = ("_error",)
+
+    def __init__(self, environment_error: EnvironmentError) -> None:
+        self._error = environment_error
+
+    def meta(self) -> dict[str, MetaValue]:
+        meta: dict[str, MetaValue] = {
+            "error_code": self._error.code,
+        }
+
+        for field_name, _field in self._error.model_fields.items():
+            if field_name in ("code", "message", "cell_kind", "cell_media_type", "ways_to_fix"):
+                continue
+
+            value = getattr(self._error, field_name)
+
+            if value is None:
+                continue
+
+            meta[field_name] = to_meta_value(value)
+
+        return meta
+
+    def content(self) -> str:
+        intro = self._error.content_intro()
+
+        message = self._error.message.format(error=self._error).strip()
+
+        ways_to_fix = [fix.format(error=self._error).strip() for fix in self._error.ways_to_fix]
+
+        if "\n" in self._error.message:
+            content = f"{intro}:\n\n{message}"
+        else:
+            content = f"{intro}: {message}"
+
+        if not ways_to_fix:
+            return content
+
+        if len(ways_to_fix) == 1:
+            return f"{content}\nWay to fix: {ways_to_fix[0]}"
+
+        fixes = "\n".join(f"- {fix}" for fix in ways_to_fix)
+
+        return f"{content}\n\nWays to fix:\n\n{fixes}"
+
+    def status(self) -> Cell:
+        return Cell.build(
+            kind=self._error.cell_kind,
+            media_type=self._error.cell_media_type,
+            content=self.content(),
+            **self.meta(),
+        )
+
+
+ErrorsList = list[EnvironmentError]

donna/core/result.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass
+from typing import Callable, Generic, ParamSpec, TypeVar, cast
+
+from donna.core.errors import InternalError
+
+T = TypeVar("T")
+U = TypeVar("U")
+E = TypeVar("E")
+F = TypeVar("F")
+P = ParamSpec("P")
+
+
+class ResultError(InternalError):
+    """Base class for internal errors in donna.core.result."""
+
+
+class UnwrapError(ResultError):
+    message: str = "Called unwrap on an Err value."
+
+
+class UnwrapErrError(ResultError):
+    message: str = "Called unwrap_err on an Ok value."
+
+
+@dataclass(frozen=True, slots=True)
+class Result(Generic[T, E]):
+    _is_ok: bool
+    _value: T | E
+
+    def is_ok(self) -> bool:
+        return self._is_ok
+
+    def is_err(self) -> bool:
+        return not self._is_ok
+
+    def ok(self) -> T | None:
+        if self._is_ok:
+            return cast(T, self._value)
+        return None
+
+    def err(self) -> E | None:
+        if not self._is_ok:
+            return cast(E, self._value)
+        return None
+
+    def unwrap(self) -> T:
+        if self._is_ok:
+            return cast(T, self._value)
+
+        raise UnwrapError(error=self.unwrap_err())
+
+    def unwrap_err(self) -> E:
+        if not self._is_ok:
+            return cast(E, self._value)
+
+        raise UnwrapErrError(value=self.unwrap())
+
+    def unwrap_or(self, default: U) -> T | U:
+        if self._is_ok:
+            return cast(T, self._value)
+        return default
+
+    def map(self, func: Callable[[T], U]) -> "Result[U, E]":
+        if self._is_ok:
+            return Result(True, func(cast(T, self._value)))
+        return Result(False, cast(E, self._value))
+
+    def map_err(self, func: Callable[[E], F]) -> "Result[T, F]":
+        if not self._is_ok:
+            return Result(False, func(cast(E, self._value)))
+        return Result(True, cast(T, self._value))
+
+
+def Ok(value: T) -> Result[T, E]:
+    return Result(True, value)
+
+
+def Err(error: E) -> Result[T, E]:
+    return Result(False, error)
+
+
+def ok(result: Result[T, E]) -> bool:
+    return result.is_ok()
+
+
+def unwrap_to_error(func: Callable[P, Result[T, E]]) -> Callable[P, Result[T, E]]:
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[T, E]:
+
+        try:
+            return func(*args, **kwargs)
+        except UnwrapError as e:
+            return Err(cast(E, e.arguments["error"]))
+
+    return wrapper

donna/core/utils.py

@@ -0,0 +1,37 @@
+import pathlib
+
+from donna.core import errors as core_errors
+from donna.core.result import Err, Ok, Result
+
+
+def first_donna_dir(donna_dir_name: str) -> pathlib.Path | None:
+    """Get the first parent directory containing the donna directory.
+
+    Search from the current working directory upwards for a folder with donna directory (.donna by default).
+    """
+    current_dir = pathlib.Path.cwd().resolve()
+
+    for parent in [current_dir] + list(current_dir.parents):
+        donna_path = parent / donna_dir_name
+        if donna_path.is_dir():
+            return parent
+
+    return None
+
+
+def donna_home_dir(donna_dir_name: str) -> pathlib.Path:
+    """Get the donna home directory in the user's home folder."""
+    return pathlib.Path.home() / donna_dir_name
+
+
+def discover_project_dir(donna_dir_name: str) -> Result[pathlib.Path, core_errors.ErrorsList]:
+    """Discover the project directory by looking for the donna directory in parent folders."""
+    donna_dir = first_donna_dir(donna_dir_name)
+
+    if donna_dir is None:
+        return Err([core_errors.ProjectDirNotFound(donna_dir_name=donna_dir_name)])
+
+    if donna_dir == donna_home_dir(donna_dir_name):
+        return Err([core_errors.ProjectDirIsHome(donna_dir_name=donna_dir_name)])
+
+    return Ok(donna_dir)

donna/domain/errors.py

@@ -0,0 +1,47 @@
+from donna.core import errors as core_errors
+
+
+class InternalError(core_errors.InternalError):
+    """Base class for internal errors in donna.domain."""
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """Base class for environment errors in donna.domain."""
+
+    cell_kind: str = "domain_error"
+
+
+class InvalidInternalId(InternalError):
+    message: str = "Invalid InternalId: '{value}'."
+    value: str
+
+
+class InvalidIdentifier(InternalError):
+    message: str = "Invalid identifier: '{value}'."
+    value: str
+
+
+class InvalidIdPath(InternalError):
+    message: str = "Invalid {id_type}: '{value}'."
+    id_type: str
+    value: str
+
+
+class InvalidIdFormat(EnvironmentError):
+    code: str = "donna.domain.invalid_id_format"
+    message: str = "Invalid {error.id_type}: '{error.value}'."
+    ways_to_fix: list[str] = [
+        "Ensure the value uses the expected format for {error.id_type}.",
+    ]
+    id_type: str
+    value: str
+
+
+class InvalidIdPattern(EnvironmentError):
+    code: str = "donna.domain.invalid_id_pattern"
+    message: str = "Invalid {error.id_type}: '{error.value}'."
+    ways_to_fix: list[str] = [
+        "Use identifiers or '*'/'**' tokens separated by the expected delimiter.",
+    ]
+    id_type: str
+    value: str