fastapi-ht 0.1.0__tar.gz

fastapi_ht-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync project dependencies
+        run: uv sync --dev
+
+      - name: Run test suite
+        run: uv run pytest

fastapi_ht-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_ht-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.py[cod]

fastapi_ht-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fastapi_ht-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+<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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-ht"
+version = "0.1.0"
+description = "Health check utilities for FastAPI applications."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.135.3",
+    "pydantic>=2.11.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/PinnLabs/fastapi-health-check"
+Repository = "https://github.com/PinnLabs/fastapi-health-check"
+Issues = "https://github.com/PinnLabs/fastapi-health-check/issues"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "mypy>=1.20.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.9",
+    "uvicorn>=0.44.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_health_check"]

fastapi_ht-0.1.0/src/examples/basic_app.py

@@ -0,0 +1,19 @@
+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)

fastapi_ht-0.1.0/src/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_ht-0.1.0/src/fastapi_health_check/assets/__init__.py

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

fastapi_ht-0.1.0/src/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_ht-0.1.0/src/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_ht-0.1.0/src/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_ht-0.1.0/src/fastapi_health_check/integration/__init__.py

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