Runtime

provide.foundation.errors.runtime

TODO: Add module docstring.

Classes

ConcurrencyError

ConcurrencyError(
    message: str,
    *,
    conflict_type: str | None = None,
    version_expected: Any = None,
    version_actual: Any = None,
    **kwargs: Any
)

Bases: FoundationError

Raised when concurrency conflicts occur.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the concurrency issue.	required
conflict_type	str | None	Optional type of conflict (lock, version, etc.).	None
version_expected	Any	Optional expected version.	None
version_actual	Any	Optional actual version.	None
**kwargs	Any	Additional context passed to FoundationError.	{}

Examples:

>>> raise ConcurrencyError("Optimistic lock failure")
>>> raise ConcurrencyError("Version mismatch", version_expected=1, version_actual=2)

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

def __init__(
    self,
    message: str,
    *,
    conflict_type: str | None = None,
    version_expected: Any = None,
    version_actual: Any = None,
    **kwargs: Any,
) -> None:
    if conflict_type:
        kwargs.setdefault("context", {})["concurrency.type"] = conflict_type
    if version_expected is not None:
        kwargs.setdefault("context", {})["concurrency.version_expected"] = str(version_expected)
    if version_actual is not None:
        kwargs.setdefault("context", {})["concurrency.version_actual"] = str(version_actual)
    super().__init__(message, **kwargs)

RateLimitExceededError

RateLimitExceededError(
    message: str,
    *,
    limit: float | None = None,
    retry_after: float | None = None,
    current_rate: float | None = None,
    **kwargs: Any
)

Bases: FoundationError

Raised when a rate limit is exceeded.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the rate limit violation.	required
limit	float | None	The rate limit that was exceeded (requests/messages per time unit).	None
retry_after	float | None	Seconds to wait before retrying.	None
current_rate	float | None	Optional current rate at time of error.	None
**kwargs	Any	Additional context passed to FoundationError.	{}

Examples:

>>> raise RateLimitExceededError("Log rate limit exceeded", limit=100.0, retry_after=1.0)
>>> raise RateLimitExceededError("API rate limit", limit=1000, retry_after=60, current_rate=1050)

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

def __init__(
    self,
    message: str,
    *,
    limit: float | None = None,
    retry_after: float | None = None,
    current_rate: float | None = None,
    **kwargs: Any,
) -> None:
    if limit is not None:
        kwargs.setdefault("context", {})["rate_limit.limit"] = limit
    if retry_after is not None:
        kwargs.setdefault("context", {})["rate_limit.retry_after"] = retry_after
    if current_rate is not None:
        kwargs.setdefault("context", {})["rate_limit.current_rate"] = current_rate
    super().__init__(message, **kwargs)

RuntimeError

RuntimeError(
    message: str,
    *,
    operation: str | None = None,
    retry_possible: bool = False,
    **kwargs: Any
)

Bases: FoundationError

Raised for runtime operational errors.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the runtime issue.	required
operation	str | None	Optional operation that failed.	None
retry_possible	bool	Whether the operation can be retried.	False
**kwargs	Any	Additional context passed to FoundationError.	{}

Examples:

>>> raise RuntimeError("Process failed")
>>> raise RuntimeError("Lock timeout", operation="acquire_lock", retry_possible=True)

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

def __init__(
    self,
    message: str,
    *,
    operation: str | None = None,
    retry_possible: bool = False,
    **kwargs: Any,
) -> None:
    if operation:
        kwargs.setdefault("context", {})["runtime.operation"] = operation
    kwargs.setdefault("context", {})["runtime.retry_possible"] = retry_possible
    super().__init__(message, **kwargs)

StateError

StateError(
    message: str,
    *,
    current_state: str | None = None,
    expected_state: str | None = None,
    transition: str | None = None,
    **kwargs: Any
)

Bases: FoundationError

Raised when an operation is invalid for the current state.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the state issue.	required
current_state	str | None	Optional current state.	None
expected_state	str | None	Optional expected state.	None
transition	str | None	Optional attempted transition.	None
**kwargs	Any	Additional context passed to FoundationError.	{}

Examples:

>>> raise StateError("Invalid state transition")
>>> raise StateError("Not ready", current_state="initializing", expected_state="ready")

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

def __init__(
    self,
    message: str,
    *,
    current_state: str | None = None,
    expected_state: str | None = None,
    transition: str | None = None,
    **kwargs: Any,
) -> None:
    if current_state:
        kwargs.setdefault("context", {})["state.current"] = current_state
    if expected_state:
        kwargs.setdefault("context", {})["state.expected"] = expected_state
    if transition:
        kwargs.setdefault("context", {})["state.transition"] = transition
    super().__init__(message, **kwargs)