Base

provide.foundation.errors.base

TODO: Add module docstring.

Classes

FoundationError

FoundationError(
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any
)

Bases: Exception

Base exception for all Foundation errors.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message.	required
code	str | None	Optional error code for programmatic handling.	None
context	dict[str, Any] | None	Optional context dictionary with diagnostic data.	None
cause	Exception | None	Optional underlying exception that caused this error.	None
**extra_context	Any	Additional key-value pairs added to context.	{}

Examples:

>>> raise FoundationError("Operation failed")
>>> raise FoundationError("Operation failed", code="OP_001")
>>> raise FoundationError("Operation failed", user_id=123, retry_count=3)

Source code in provide/foundation/errors/base.py

def __init__(
    self,
    message: str,
    *,
    code: str | None = None,
    context: dict[str, Any] | None = None,
    cause: Exception | None = None,
    **extra_context: Any,
) -> None:
    self.message = message
    self.code = code or self._default_code()
    self.context = context or {}
    self.context.update(extra_context)
    self.cause = cause
    if cause:
        self.__cause__ = cause
    super().__init__(message)

Functions

add_context

add_context(key: str, value: Any) -> FoundationError

Add context data to the error.

Parameters:

Name	Type	Description	Default
key	str	Context key (use dots for namespacing, e.g., 'aws.region').	required
value	Any	Context value.	required

Returns:

Type	Description
FoundationError	Self for method chaining.

Source code in provide/foundation/errors/base.py

def add_context(self, key: str, value: Any) -> FoundationError:
    """Add context data to the error.

    Args:
        key: Context key (use dots for namespacing, e.g., 'aws.region').
        value: Context value.

    Returns:
        Self for method chaining.

    """
    self.context[key] = value
    return self

to_dict

to_dict() -> dict[str, Any]

Convert exception to dictionary for structured logging.

Returns:

Type	Description
dict[str, Any]	Dictionary representation suitable for logging/serialization.

Source code in provide/foundation/errors/base.py

def to_dict(self) -> dict[str, Any]:
    """Convert exception to dictionary for structured logging.

    Returns:
        Dictionary representation suitable for logging/serialization.

    """
    result = {
        "error.type": self.__class__.__name__,
        "error.message": self.message,
        "error.code": self.code,
    }

    # Add context with error prefix
    for key, value in self.context.items():
        # If key already has a prefix, use it; otherwise add error prefix
        if "." in key:
            result[key] = value
        else:
            result[f"error.{key}"] = value

    if self.cause:
        result["error.cause"] = str(self.cause)
        result["error.cause_type"] = type(self.cause).__name__

    return result