orchestrata_ultimate.core.base.error

Reference › orchestrata_ultimate › core › base › error

BaseError is the root of the project's custom exceptions, imported by the domaingen generator, reader and Stardog modules and by the plugin exceptions. It extends Exception with structured data: a human-readable message, a machine-readable error_code (for example PKG_CAT_SPECIFIC), a mutable context dictionary and a UTC timestamp. to_dict serialises the error, including the chain of __cause__ exceptions, with a max_depth of 10 so that a cyclic chain terminates.

At a glance


Source	`src/orchestrata_ultimate/core/base/error.py`
Lines of code	66
Classes	1
Functions	0
Imports (internal)	none
Imported by	`orchestrata_ultimate.core.base`, `orchestrata_ultimate.domaingen.generator`, `orchestrata_ultimate.domaingen.reader`, `orchestrata_ultimate.domaingen.stardog`, `orchestrata_ultimate.plugin.exceptions`
Tests that import it	`tests/core/base/test_error.py`, `tests/core/test_base_error.py`, `tests/generated_core/test_base_error_generated.py`, `tests/generated_recovery/test_core_base_error.py`

Class diagram

Dependency diagram

API

Classes

`BaseError`

Bases: Exception · Line 7

Base class for all custom exceptions.

Method	Signature	Summary
`__init__`	`__init__(message: str = '', error_code: str \| None = None, context: dict[str, Any] \| None = None) -> None`	Initialize with message, optional code and context.
`to_dict`	`to_dict(max_depth: int = 10) -> dict[str, Any]`	Serialize error to dictionary, including cause chain.
`__str__`	`__str__() -> str`	String representation with code prefix if present.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/base/error.py

"""BaseError — structured exception with code, message, context."""

from datetime import UTC, datetime
from typing import Any


class BaseError(Exception):
    """Base class for all custom exceptions.

    Provides structured error information: code, message, context
    dict, timestamp, and exception chain serialization.

    Attributes:
        error_code: Machine-readable code (e.g., "PKG_CAT_SPECIFIC").
        message: Human-readable description.
        context: Mutable dict of additional context.
        timestamp: When the error occurred (UTC).
    """

    def __init__(
        self,
        message: str = "",
        error_code: str | None = None,
        context: dict[str, Any] | None = None,
    ) -> None:
        """Initialize with message, optional code and context.

        Args:
            message: Error description.
            error_code: Machine-readable error code.
            context: Additional context dict.
        """
        super().__init__(message)
        self.message = message
        self.error_code = error_code
        self.context = context or {}
        self.timestamp = datetime.now(UTC)

    def to_dict(self, max_depth: int = 10) -> dict[str, Any]:
        """Serialize error to dictionary, including __cause__ chain.

        Args:
            max_depth: Maximum chain depth to prevent cycles.

        Returns:
            Dict with error_code, message, context, timestamp,
            and optional cause chain.
        """
        result: dict[str, Any] = {
            "error_code": self.error_code,
            "message": self.message,
            "context": self.context,
            "timestamp": self.timestamp.isoformat(),
        }
        if self.__cause__ and max_depth > 0:
            if isinstance(self.__cause__, BaseError):
                result["cause"] = self.__cause__.to_dict(max_depth=max_depth - 1)
            else:
                result["cause"] = str(self.__cause__)
        return result

    def __str__(self) -> str:
        """String representation with code prefix if present."""
        if self.error_code:
            return f"[{self.error_code}] {self.message}"
        return self.message