philiprehberger-health-check 0.2.0

Health check endpoint builder for web applications.

philiprehberger-health-check

Health check endpoint builder for web applications.

Installation

pip install philiprehberger-health-check

Usage

Basic Health Check

from philiprehberger_health_check import HealthCheck, checks

hc = HealthCheck()
hc.add("database", lambda: True)
hc.add(*checks.tcp("redis", "localhost", 6379))
hc.add(*checks.disk_space("disk", "/", min_free_gb=2))

result = hc.run()
print(result.status)  # "healthy" or "unhealthy"

for check in result.checks:
    print(f"{check.name}: {'OK' if check.healthy else check.message}")

Check Dependencies

hc = HealthCheck()
hc.add("database", check_db)
hc.add("migrations", check_migrations, depends_on=["database"])

result = hc.run()
# If "database" fails, "migrations" is skipped automatically

Async Execution

import asyncio

hc = HealthCheck()
hc.add("database", check_db)
hc.add("cache", check_cache)
hc.add("migrations", check_migrations, depends_on=["database"])

result = await hc.run_async()
# Independent checks run concurrently; dependencies are respected

Built-in Checks

# TCP connectivity
hc.add(*checks.tcp("postgres", "db.example.com", 5432, timeout=3))

# Disk space
hc.add(*checks.disk_space("storage", "/data", min_free_gb=5))

# Memory usage (Linux only, skipped on other platforms)
hc.add(*checks.memory("ram", max_percent=85))

# Custom check
hc.add(*checks.custom("cache", lambda: cache.ping()))

API

Name	Description
HealthCheck()	Create a health check builder
hc.add(name, fn, depends_on=None)	Register a check with optional dependencies
hc.run()	Run all checks sequentially and return HealthResult
hc.run_async()	Run checks concurrently, respecting dependency order
checks.tcp(name, host, port, timeout=2)	TCP connectivity check
checks.disk_space(name, path, min_free_gb=1)	Disk free space check
checks.memory(name, max_percent=90)	Memory usage check (Linux)
checks.custom(name, fn)	Wrap any callable as a check
CheckResult	Dataclass: name, healthy, message, duration_ms
HealthResult	Dataclass: status, checks, uptime_seconds

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this package useful, consider starring the repository.

License

MIT