Types

provide.foundation.errors.types

TODO: Add module docstring.

Classes

ErrorCode

Bases: str, Enum

Standard error codes for programmatic error handling.

Use these codes for consistent error identification across the system. Codes are grouped by category with prefixes: - CFG: Configuration errors - VAL: Validation errors - INT: Integration errors - RES: Resource errors - AUTH: Authentication/Authorization errors - SYS: System errors

ErrorMetadata

Additional metadata for error tracking and debugging.

Attributes:

Name	Type	Description
request_id	str | None	Optional request identifier for tracing.
user_id	str | None	Optional user identifier.
session_id	str | None	Optional session identifier.
correlation_id	str | None	Optional correlation ID for distributed tracing.
retry_count	int	Number of retry attempts made.
retry_after	float | None	Seconds to wait before retry.
help_url	str | None	Optional URL for more information.
support_id	str | None	Optional support ticket/case ID.

Examples:

>>> meta = ErrorMetadata(
...     request_id="req_123",
...     user_id="user_456",
...     retry_count=2
... )

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dictionary, excluding None values.

Returns:

Type	Description
dict[str, Any]	Dictionary with non-None metadata fields.

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

def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary, excluding None values.

    Returns:
        Dictionary with non-None metadata fields.

    """
    result = {}
    for key in [
        "request_id",
        "user_id",
        "session_id",
        "correlation_id",
        "retry_count",
        "retry_after",
        "help_url",
        "support_id",
    ]:
        value = getattr(self, key)
        if value is not None:
            result[key] = value
    return result

ErrorResponse

Structured error response for APIs and external interfaces.

Attributes:

Name	Type	Description
error_code	str	Machine-readable error code.
message	str	Human-readable error message.
details	dict[str, Any] | None	Optional additional error details.
metadata	ErrorMetadata | None	Optional error metadata.
timestamp	str	When the error occurred.

Examples:

>>> response = ErrorResponse(
...     error_code="VAL_001",
...     message="Invalid email format",
...     details={"field": "email", "value": "not-an-email"}
... )

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dictionary for JSON serialization.

Returns:

Type	Description
dict[str, Any]	Dictionary representation of error response.

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

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

    Returns:
        Dictionary representation of error response.

    """
    result: dict[str, Any] = {
        "error_code": self.error_code,
        "message": self.message,
        "timestamp": self.timestamp,
    }

    if self.details:
        result["details"] = self.details

    if self.metadata:
        result["metadata"] = self.metadata.to_dict()

    return result

to_json

to_json() -> str

Convert to JSON string.

Returns:

Type	Description
str	JSON representation of error response.

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

def to_json(self) -> str:
    """Convert to JSON string.

    Returns:
        JSON representation of error response.

    """
    return json_dumps(self.to_dict(), indent=2)

Functions