API Reference

Models for healthchecks.

HealthCheckResult dataclass

Result of a healthcheck.

Attributes:

Name	Type	Description
name	str	Name of the healthcheck.
healthy	bool	Whether the healthcheck passed.
error_details	str | None	Details of the error if the healthcheck failed.

Source code in fast_healthchecks/models.py

@dataclass
class HealthCheckResult:
    """Result of a healthcheck.

    Attributes:
        name: Name of the healthcheck.
        healthy: Whether the healthcheck passed.
        error_details: Details of the error if the healthcheck failed.
    """

    name: str
    healthy: bool
    error_details: str | None = None

    def __str__(self) -> str:
        """Return a string representation of the result."""
        return f"{self.name}: {'healthy' if self.healthy else 'unhealthy'}"

__str__()

Return a string representation of the result.

Source code in fast_healthchecks/models.py

def __str__(self) -> str:
    """Return a string representation of the result."""
    return f"{self.name}: {'healthy' if self.healthy else 'unhealthy'}"

HealthcheckReport dataclass

Report of healthchecks.

Attributes:

Name	Type	Description
healthy	bool	Whether all healthchecks passed.
results	list[HealthCheckResult]	List of healthcheck results.

Source code in fast_healthchecks/models.py

@dataclass
class HealthcheckReport:
    """Report of healthchecks.

    Attributes:
        healthy: Whether all healthchecks passed.
        results: List of healthcheck results.
    """

    results: list[HealthCheckResult]
    allow_partial_failure: bool = False

    def __str__(self) -> str:
        """Return a string representation of the report."""
        return "\n".join(str(result) for result in self.results)

    @property
    def healthy(self) -> bool:
        """Return whether all healthchecks passed."""
        return all(result.healthy for result in self.results) or self.allow_partial_failure

healthy: bool property

Return whether all healthchecks passed.

__str__()

Return a string representation of the report.

Source code in fast_healthchecks/models.py

def __str__(self) -> str:
    """Return a string representation of the report."""
    return "\n".join(str(result) for result in self.results)

FastAPI integration for health checks.

HealthcheckRouter

Bases: APIRouter

A router for health checks.

Parameters:

Name	Type	Description	Default
probes	Probe	An iterable of probes to run.	()
debug	bool	Whether to include the probes in the schema. Defaults to False.	False

Source code in fast_healthchecks/integrations/fastapi.py

class HealthcheckRouter(APIRouter):
    """A router for health checks.

    Args:
        probes: An iterable of probes to run.
        debug: Whether to include the probes in the schema. Defaults to False.
    """

    def __init__(  # noqa: PLR0913
        self,
        *probes: Probe,
        success_handler: HandlerType = default_handler,
        failure_handler: HandlerType = default_handler,
        success_status: int = status.HTTP_204_NO_CONTENT,
        failure_status: int = status.HTTP_503_SERVICE_UNAVAILABLE,
        debug: bool = False,
        prefix: str = "/health",
        **kwargs: dict[str, Any],
    ) -> None:
        """Initialize the router."""
        kwargs["prefix"] = prefix  # type: ignore[assignment]
        kwargs["tags"] = ["Healthchecks"]  # type: ignore[assignment]
        super().__init__(**kwargs)  # type: ignore[arg-type]
        for probe in probes:
            self._add_probe_route(
                probe,
                success_handler=success_handler,
                failure_handler=failure_handler,
                success_status=success_status,
                failure_status=failure_status,
                debug=debug,
            )

    def _add_probe_route(  # noqa: PLR0913
        self,
        probe: Probe,
        *,
        success_handler: HandlerType = default_handler,
        failure_handler: HandlerType = default_handler,
        success_status: int = status.HTTP_204_NO_CONTENT,
        failure_status: int = status.HTTP_503_SERVICE_UNAVAILABLE,
        debug: bool = False,
    ) -> None:
        probe_handler = make_probe_asgi(
            probe,
            success_handler=success_handler,
            failure_handler=failure_handler,
            success_status=success_status,
            failure_status=failure_status,
            debug=debug,
        )

        async def handle_request() -> Response:
            content, headers, status_code = await probe_handler()
            return Response(content=content, status_code=status_code, headers=headers)

        self.add_api_route(
            path=f"/{probe.name}",
            endpoint=handle_request,
            status_code=success_status,
            summary=probe.endpoint_summary,
            include_in_schema=debug,
        )

__init__(*probes, success_handler=default_handler, failure_handler=default_handler, success_status=status.HTTP_204_NO_CONTENT, failure_status=status.HTTP_503_SERVICE_UNAVAILABLE, debug=False, prefix='/health', **kwargs)

Initialize the router.

Source code in fast_healthchecks/integrations/fastapi.py

def __init__(  # noqa: PLR0913
    self,
    *probes: Probe,
    success_handler: HandlerType = default_handler,
    failure_handler: HandlerType = default_handler,
    success_status: int = status.HTTP_204_NO_CONTENT,
    failure_status: int = status.HTTP_503_SERVICE_UNAVAILABLE,
    debug: bool = False,
    prefix: str = "/health",
    **kwargs: dict[str, Any],
) -> None:
    """Initialize the router."""
    kwargs["prefix"] = prefix  # type: ignore[assignment]
    kwargs["tags"] = ["Healthchecks"]  # type: ignore[assignment]
    super().__init__(**kwargs)  # type: ignore[arg-type]
    for probe in probes:
        self._add_probe_route(
            probe,
            success_handler=success_handler,
            failure_handler=failure_handler,
            success_status=success_status,
            failure_status=failure_status,
            debug=debug,
        )

FastStream integration for health checks.

health(*probes, success_handler=default_handler, failure_handler=default_handler, success_status=HTTPStatus.NO_CONTENT, failure_status=HTTPStatus.SERVICE_UNAVAILABLE, debug=False, prefix='/health')

Make list of routes for healthchecks.

Source code in fast_healthchecks/integrations/faststream.py

def health(  # noqa: PLR0913
    *probes: Probe,
    success_handler: HandlerType = default_handler,
    failure_handler: HandlerType = default_handler,
    success_status: int = HTTPStatus.NO_CONTENT,
    failure_status: int = HTTPStatus.SERVICE_UNAVAILABLE,
    debug: bool = False,
    prefix: str = "/health",
) -> Iterable[tuple[str, "ASGIApp"]]:
    """Make list of routes for healthchecks."""
    return [
        _add_probe_route(
            probe,
            success_handler=success_handler,
            failure_handler=failure_handler,
            success_status=success_status,
            failure_status=failure_status,
            debug=debug,
            prefix=prefix,
        )
        for probe in probes
    ]

FastAPI integration for health checks.

health(*probes, success_handler=default_handler, failure_handler=default_handler, success_status=HTTPStatus.NO_CONTENT, failure_status=HTTPStatus.SERVICE_UNAVAILABLE, debug=False, prefix='/health')

Make list of routes for healthchecks.

Source code in fast_healthchecks/integrations/litestar.py

def health(  # noqa: PLR0913
    *probes: Probe,
    success_handler: HandlerType = default_handler,
    failure_handler: HandlerType = default_handler,
    success_status: int = HTTPStatus.NO_CONTENT,
    failure_status: int = HTTPStatus.SERVICE_UNAVAILABLE,
    debug: bool = False,
    prefix: str = "/health",
) -> Iterable[HTTPRouteHandler]:
    """Make list of routes for healthchecks."""
    return [
        _add_probe_route(
            probe,
            success_handler=success_handler,
            failure_handler=failure_handler,
            success_status=success_status,
            failure_status=failure_status,
            debug=debug,
            prefix=prefix,
        )
        for probe in probes
    ]