fastapi-ht 0.1.0__py3-none-any.whl

fastapi_health_check/__init__.py

@@ -0,0 +1,17 @@
+from fastapi_health_check.checks import AppAliveCheck, FunctionHealthCheck, HealthCheck, health_check
+from fastapi_health_check.integration.fastapi import install_health_check
+from fastapi_health_check.models import HealthCheckResult, HealthReport
+from fastapi_health_check.registry import HealthRegistry
+from fastapi_health_check.ui import render_health_report_page
+
+__all__ = [
+    "AppAliveCheck",
+    "FunctionHealthCheck",
+    "HealthCheck",
+    "HealthCheckResult",
+    "HealthRegistry",
+    "HealthReport",
+    "health_check",
+    "install_health_check",
+    "render_health_report_page",
+]

fastapi_health_check/assets/__init__.py

@@ -0,0 +1 @@
+"""Static assets for the health check UI."""

fastapi_health_check/assets/health-report.css

@@ -0,0 +1,178 @@
+:root {
+  color-scheme: light;
+  --bg: #f4f8fb;
+  --panel: #ffffff;
+  --panel-border: #d7e4e9;
+  --text: #1d2733;
+  --muted: #5b6975;
+  --ok: #009688;
+  --ok-soft: #d8f2ee;
+  --fail: #e15656;
+  --fail-soft: #ffe2e2;
+  --accent: #0b7fab;
+  --accent-soft: rgba(11, 127, 171, 0.14);
+  --shadow: 0 22px 50px rgba(15, 23, 42, 0.08);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  color: var(--text);
+  background:
+    radial-gradient(circle at top left, var(--accent-soft), transparent 30%),
+    linear-gradient(180deg, #ffffff 0%, var(--bg) 100%);
+}
+
+.page {
+  width: min(960px, calc(100% - 32px));
+  margin: 0 auto;
+  padding: 56px 0 72px;
+}
+
+.hero {
+  display: grid;
+  gap: 18px;
+  margin-bottom: 28px;
+}
+
+.eyebrow {
+  margin: 0;
+  color: var(--accent);
+  font-size: 0.9rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+h1 {
+  margin: 0;
+  font-size: clamp(2rem, 4vw, 3.35rem);
+  line-height: 1.02;
+}
+
+.subtitle {
+  margin: 0;
+  max-width: 42rem;
+  color: var(--muted);
+  font-size: 1rem;
+  line-height: 1.6;
+}
+
+.summary {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.summary-card,
+.check-card {
+  background: var(--panel);
+  border: 1px solid var(--panel-border);
+  border-radius: 20px;
+  box-shadow: var(--shadow);
+}
+
+.summary-card {
+  padding: 22px;
+}
+
+.summary-label {
+  margin: 0 0 10px;
+  color: var(--muted);
+  font-size: 0.9rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.summary-value {
+  margin: 0;
+  font-size: 1.8rem;
+  font-weight: 700;
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  width: fit-content;
+  padding: 8px 12px;
+  border-radius: 999px;
+  font-weight: 700;
+}
+
+.badge.ok {
+  color: var(--ok);
+  background: var(--ok-soft);
+}
+
+.badge.fail {
+  color: var(--fail);
+  background: var(--fail-soft);
+}
+
+.checks {
+  display: grid;
+  gap: 16px;
+}
+
+.check-card {
+  padding: 20px 22px;
+}
+
+.check-header {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+.check-name {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.check-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+}
+
+.duration {
+  color: var(--muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.message {
+  margin: 0;
+  color: var(--muted);
+  line-height: 1.6;
+}
+
+.empty {
+  padding: 28px;
+  text-align: center;
+  color: var(--muted);
+  background: rgba(255, 255, 255, 0.72);
+  border: 1px dashed var(--panel-border);
+  border-radius: 20px;
+}
+
+@media (max-width: 640px) {
+  .page {
+    width: min(100% - 24px, 960px);
+    padding-top: 32px;
+  }
+
+  .summary-card,
+  .check-card {
+    border-radius: 16px;
+  }
+}

fastapi_health_check/assets/health-report.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{ title }}</title>
+    <style>
+{{ styles }}
+    </style>
+  </head>
+  <body>
+    <main class="page">
+      <section class="hero">
+        <p class="eyebrow">FastAPI Health Check</p>
+        <h1>{{ title }}</h1>
+        <p class="subtitle">A compact operational view of backend dependencies, designed for quick status inspection.</p>
+      </section>
+      <section class="summary">
+        <article class="summary-card">
+          <p class="summary-label">Overall status</p>
+          <div class="badge {{ summary_class }}">{{ summary_label }}</div>
+        </article>
+        <article class="summary-card">
+          <p class="summary-label">Checks</p>
+          <p class="summary-value">{{ checks_count }}</p>
+        </article>
+      </section>
+      <section class="checks">
+{{ checks_markup }}
+      </section>
+    </main>
+  </body>
+</html>

fastapi_health_check/checks.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from inspect import isawaitable
+from abc import ABC, abstractmethod
+from time import perf_counter
+
+from fastapi_health_check.models import HealthCheckResult
+
+CheckHandler = Callable[[], str | None | Awaitable[str | None]]
+
+
+class HealthCheck(ABC):
+    default_name = ""
+
+    def __init__(self, name: str | None = None) -> None:
+        resolved_name = name or self.default_name or self.__class__.__name__.removesuffix("Check").lower()
+        if not resolved_name:
+            msg = "health checks must define a name"
+            raise ValueError(msg)
+
+        self.name = resolved_name
+
+    async def run(self) -> HealthCheckResult:
+        started_at = perf_counter()
+
+        try:
+            message = await self.check()
+        except Exception as exc:
+            return HealthCheckResult(
+                name=self.name,
+                status="fail",
+                message=str(exc),
+                duration_ms=round((perf_counter() - started_at) * 1000, 3),
+            )
+
+        return HealthCheckResult(
+            name=self.name,
+            status="ok",
+            message=message,
+            duration_ms=round((perf_counter() - started_at) * 1000, 3),
+        )
+
+    @abstractmethod
+    async def check(self) -> str | None:
+        """Execute the health check and return an optional success message."""
+
+
+class AppAliveCheck(HealthCheck):
+    default_name = "app_alive"
+
+    async def check(self) -> str | None:
+        return None
+
+
+class FunctionHealthCheck(HealthCheck):
+    def __init__(self, name: str, handler: CheckHandler) -> None:
+        super().__init__(name=name)
+        self._handler = handler
+
+    async def check(self) -> str | None:
+        result = self._handler()
+        if isawaitable(result):
+            return await result
+
+        return result
+
+
+def health_check(name: str, handler: CheckHandler) -> FunctionHealthCheck:
+    return FunctionHealthCheck(name=name, handler=handler)

fastapi_health_check/integration/__init__.py

@@ -0,0 +1,3 @@
+from fastapi_health_check.integration.fastapi import install_health_check
+
+__all__ = ["install_health_check"]

fastapi_health_check/integration/fastapi.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, JSONResponse, Response
+
+from fastapi_health_check.registry import HealthRegistry
+from fastapi_health_check.ui import render_health_report_page
+
+
+def install_health_check(
+    app: FastAPI,
+    registry: HealthRegistry,
+    *,
+    path: str = "/ht",
+    ui_title: str = "System Health",
+    include_in_schema: bool = False,
+) -> None:
+    async def health_endpoint(request: Request) -> Response:
+        report = await registry.run_checks()
+        status_code = 200 if report.is_healthy else 503
+        accept = request.headers.get("accept", "")
+        prefers_json = "application/json" in accept and "text/html" not in accept
+
+        if prefers_json:
+            return JSONResponse(status_code=status_code, content=report.model_dump(mode="json"))
+
+        content = render_health_report_page(report, title=ui_title)
+        return HTMLResponse(status_code=status_code, content=content)
+
+    app.add_api_route(
+        path,
+        health_endpoint,
+        methods=["GET"],
+        include_in_schema=include_in_schema,
+        name="health_check",
+    )

fastapi_health_check/models.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+HealthStatus = Literal["ok", "fail"]
+
+
+class HealthCheckResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(min_length=1)
+    status: HealthStatus
+    message: str | None = None
+    duration_ms: float = Field(ge=0)
+
+
+class HealthReport(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    status: HealthStatus
+    checks: list[HealthCheckResult]
+
+    @classmethod
+    def from_checks(cls, checks: list[HealthCheckResult]) -> "HealthReport":
+        status: HealthStatus = "fail" if any(check.status == "fail" for check in checks) else "ok"
+        return cls(status=status, checks=checks)
+
+    @property
+    def is_healthy(self) -> bool:
+        return self.status == "ok"

fastapi_health_check/registry.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from fastapi_health_check.checks import HealthCheck
+from fastapi_health_check.models import HealthReport
+
+
+class HealthRegistry:
+    def __init__(self, checks: Iterable[HealthCheck] | None = None) -> None:
+        self._checks: list[HealthCheck] = []
+
+        if checks is not None:
+            for check in checks:
+                self.register(check)
+
+    @property
+    def checks(self) -> tuple[HealthCheck, ...]:
+        return tuple(self._checks)
+
+    def register(self, check: HealthCheck) -> HealthCheck:
+        if any(existing.name == check.name for existing in self._checks):
+            msg = f"health check with name '{check.name}' is already registered"
+            raise ValueError(msg)
+
+        self._checks.append(check)
+        return check
+
+    async def run_checks(self) -> HealthReport:
+        results = [await check.run() for check in self._checks]
+        return HealthReport.from_checks(results)

fastapi_health_check/ui.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from html import escape
+from importlib.resources import files
+
+from fastapi_health_check.models import HealthCheckResult, HealthReport
+
+_ASSETS = files("fastapi_health_check.assets")
+_HTML_TEMPLATE = (_ASSETS / "health-report.html").read_text(encoding="utf-8")
+_CSS_STYLES = (_ASSETS / "health-report.css").read_text(encoding="utf-8")
+
+
+def render_health_report_page(report: HealthReport, *, title: str = "FastAPI Health Check") -> str:
+    summary_label = "Healthy" if report.is_healthy else "Issues detected"
+    summary_class = "ok" if report.is_healthy else "fail"
+    checks_markup = "\n".join(_render_check_card(check) for check in report.checks) or _render_empty_state()
+
+    replacements = {
+        "{{ title }}": escape(title),
+        "{{ styles }}": _CSS_STYLES,
+        "{{ summary_class }}": summary_class,
+        "{{ summary_label }}": escape(summary_label),
+        "{{ checks_count }}": str(len(report.checks)),
+        "{{ checks_markup }}": checks_markup,
+    }
+
+    html = _HTML_TEMPLATE
+    for marker, value in replacements.items():
+        html = html.replace(marker, value)
+
+    return html
+
+
+def _render_check_card(check: HealthCheckResult) -> str:
+    message = escape(check.message) if check.message else "No additional details."
+    return f"""        <article class="check-card">
+          <div class="check-header">
+            <h2 class="check-name">{escape(check.name)}</h2>
+            <div class="check-meta">
+              <div class="badge {check.status}">{escape(check.status.upper())}</div>
+              <span class="duration">{check.duration_ms:.3f} ms</span>
+            </div>
+          </div>
+          <p class="message">{message}</p>
+        </article>"""
+
+
+def _render_empty_state() -> str:
+    return '        <div class="empty">No health checks are currently registered.</div>'

fastapi_ht-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: fastapi-ht
+Version: 0.1.0
+Summary: Health check utilities for FastAPI applications.
+Project-URL: Homepage, https://github.com/PinnLabs/fastapi-health-check
+Project-URL: Repository, https://github.com/PinnLabs/fastapi-health-check
+Project-URL: Issues, https://github.com/PinnLabs/fastapi-health-check/issues
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.135.3
+Requires-Dist: pydantic>=2.11.7
+Description-Content-Type: text/markdown
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/PinnLabs/fastapi-health-check/main/public/logo.png" alt="fastapi-health-check logo" width="520" style="display: block; margin:
+    0 auto;" />
+</p>
+
+# fastapi-health-check
+
+FastAPI health checks with a small public API, a visual status page, and JSON responses from the same endpoint.
+
+### Example interface
+
+![fastapi-health-check example interface](https://raw.githubusercontent.com/PinnLabs/fastapi-health-check/main/public/example_use.png)
+
+## What the library provides
+
+- A base contract for advanced checks
+- A lightweight registry for collecting and running checks
+- A single `/ht` endpoint with HTML by default
+- JSON responses when the client sends `Accept: application/json`
+- A simple way to monitor any custom area of your system
+
+## Important note
+
+The library does not ship with a database check by default.
+
+The only built-in check today is `AppAliveCheck`, which reports that the application is up. Database, Redis, queues, external APIs, or any other monitored area are meant to be registered by the user.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+
+from fastapi_health_check import AppAliveCheck, HealthRegistry, health_check, install_health_check
+
+
+app = FastAPI()
+registry = HealthRegistry(
+    [
+        AppAliveCheck(),
+        health_check("database", lambda: "connection ok"),
+        health_check("redis", lambda: "cache reachable"),
+    ]
+)
+
+install_health_check(app, registry)
+```
+
+This exposes `GET /ht`.
+
+- In a browser, the route renders an HTML health page
+- For automated integrations, the same route returns JSON when the client sends `Accept: application/json`
+
+## Monitoring custom areas
+
+If you want to monitor anything beyond the built-in app liveness check, the easiest option is the `health_check()` factory.
+
+You can use it for:
+
+- databases
+- Redis or cache layers
+- background queues
+- external APIs
+- storage services
+- internal domain-specific dependencies
+
+### Synchronous checks
+
+```python
+from fastapi_health_check import health_check
+
+database_check = health_check("database", lambda: "connection ok")
+redis_check = health_check("redis", lambda: "cache reachable")
+```
+
+### Asynchronous checks
+
+```python
+from fastapi_health_check import health_check
+
+
+async def payments_api_check() -> str | None:
+    return "payments API available"
+
+
+payments_check = health_check("payments_api", payments_api_check)
+```
+
+### Class-based checks for advanced cases
+
+```python
+from fastapi_health_check import HealthCheck
+
+
+class QueueCheck(HealthCheck):
+    default_name = "queue"
+
+    async def check(self) -> str | None:
+        return "queue connected"
+```
+
+Use class-based checks when you want:
+
+- dependency injection through `__init__`
+- reusable state
+- more structured custom behavior
+
+## Local manual testing
+
+The repository includes a local example application at `src/examples/basic_app.py`.
+
+Run it with:
+
+```bash
+uv run uvicorn src.examples.basic_app:app --reload
+```
+
+Then open:
+
+- `http://127.0.0.1:8000/ht` for the HTML page
+- `curl -H "Accept: application/json" http://127.0.0.1:8000/ht` for JSON

fastapi_ht-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+fastapi_health_check/__init__.py,sha256=yI61LWfPHqWWFfdwstj9WqlLJSINvcNGm2CVRcDeIx0,597
+fastapi_health_check/checks.py,sha256=S8Wjs8KFBJHgZJ3mmIXZtBNYOz7HyzTQ-djlMSDQl1g,2010
+fastapi_health_check/models.py,sha256=Klv2gFP0wEzgiP9Ahcw-nt8txTmBnT8d2vHbf63Z-7Y,828
+fastapi_health_check/registry.py,sha256=eCFw-rn75RmHiBLxf3yI14uShTYgFtZxMGMGtF_Yn40,994
+fastapi_health_check/ui.py,sha256=MimjOnjxJx5-CAdxPFknxc6VFIFskxeKucil7JYbEGk,1863
+fastapi_health_check/assets/__init__.py,sha256=jVgFKZWCvqBvs82qYebKU1Ju1MGHJtA6n5bFynTMxqU,45
+fastapi_health_check/assets/health-report.css,sha256=I_l6w0jc4Hbt1_GDhjg9BBgC1BeM2NBF6KBNVepESvM,2815
+fastapi_health_check/assets/health-report.html,sha256=Yn6vDaAimwiSN7ZEvSFoyTiuTruoyUPglSe_9lzHm08,1003
+fastapi_health_check/integration/__init__.py,sha256=ybFTWgVTbcaFxgSJZ6r9aCZeG_4eKl16s5WtBGwuykY,110
+fastapi_health_check/integration/fastapi.py,sha256=Nb3yCf9ZrwH_0M-mu1AbHGwGtOsxVlOQbQpdjaO9q5I,1176
+fastapi_ht-0.1.0.dist-info/METADATA,sha256=RiDhlM8I964qsCKEkAB7jq3G2sHPfZSTCzpH5yuHCTE,3590
+fastapi_ht-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fastapi_ht-0.1.0.dist-info/RECORD,,

fastapi_ht-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any