Integration

provide.foundation.errors.integration

TODO: Add module docstring.

Classes

IntegrationError

IntegrationError(
    message: str,
    *,
    service: str | None = None,
    endpoint: str | None = None,
    status_code: int | None = None,
    **kwargs: Any
)

Bases: FoundationError

Raised when external service integration fails.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the integration failure.	required
service	str | None	Optional service name that failed.	None
endpoint	str | None	Optional endpoint that was called.	None
status_code	int | None	Optional HTTP status code.	None
**kwargs	Any	Additional context passed to FoundationError.	{}

Examples:

>>> raise IntegrationError("API call failed")
>>> raise IntegrationError("Auth failed", service="github", status_code=401)

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

def __init__(
    self,
    message: str,
    *,
    service: str | None = None,
    endpoint: str | None = None,
    status_code: int | None = None,
    **kwargs: Any,
) -> None:
    if service:
        kwargs.setdefault("context", {})["integration.service"] = service
    if endpoint:
        kwargs.setdefault("context", {})["integration.endpoint"] = endpoint
    if status_code:
        kwargs.setdefault("context", {})["integration.status_code"] = status_code
    super().__init__(message, **kwargs)

NetworkError

NetworkError(
    message: str,
    *,
    host: str | None = None,
    port: int | None = None,
    **kwargs: Any
)

Bases: IntegrationError

Raised for network-related failures.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the network issue.	required
host	str | None	Optional hostname or IP address.	None
port	int | None	Optional port number.	None
**kwargs	Any	Additional context passed to IntegrationError.	{}

Examples:

>>> raise NetworkError("Connection refused")
>>> raise NetworkError("DNS resolution failed", host="api.example.com")

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

def __init__(
    self,
    message: str,
    *,
    host: str | None = None,
    port: int | None = None,
    **kwargs: Any,
) -> None:
    if host:
        kwargs.setdefault("context", {})["network.host"] = host
    if port:
        kwargs.setdefault("context", {})["network.port"] = port
    super().__init__(message, **kwargs)

TimeoutError

TimeoutError(
    message: str,
    *,
    timeout_seconds: float | None = None,
    elapsed_seconds: float | None = None,
    **kwargs: Any
)

Bases: IntegrationError

Raised when operations exceed time limits.

Parameters:

Name	Type	Description	Default
message	str	Error message describing the timeout.	required
timeout_seconds	float | None	Optional timeout limit in seconds.	None
elapsed_seconds	float | None	Optional actual elapsed time.	None
**kwargs	Any	Additional context passed to IntegrationError.	{}

Examples:

>>> raise TimeoutError("Request timed out")
>>> raise TimeoutError("Operation exceeded limit", timeout_seconds=30, elapsed_seconds=31.5)

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

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