Metadata-Version: 2.4
Name: healthkit
Version: 0.1.0
Summary: Professional health checks for FastAPI — DB, Redis, disk, memory in one endpoint
Project-URL: Homepage, https://github.com/shahabRDZ/healthkit
Project-URL: Repository, https://github.com/shahabRDZ/healthkit
Project-URL: Issues, https://github.com/shahabRDZ/healthkit/issues
Author-email: Shahab Rashidian Dezfuly <mm4heidary@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: fastapi,health-check,kubernetes,microservice,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: all
Requires-Dist: asyncpg>=0.28.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.28.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Description-Content-Type: text/markdown

# healthkit

[![PyPI version](https://img.shields.io/pypi/v/healthkit.svg)](https://pypi.org/project/healthkit/)
[![Python](https://img.shields.io/pypi/pyversions/healthkit.svg)](https://pypi.org/project/healthkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Professional health checks for FastAPI -- DB, Redis, disk, memory in one endpoint.

## Install

```bash
pip install healthkit

# With database drivers
pip install healthkit[postgres]
pip install healthkit[redis]
pip install healthkit[all]
```

## Quick Start

One line to add production-grade health checks:

```python
from fastapi import FastAPI
from healthkit import setup_health

app = FastAPI()

setup_health(
    app,
    postgres_url="postgresql://user:pass@localhost/mydb",
    redis_url="redis://localhost:6379/0",
)
```

That's it. Your app now has `/health` and `/health/ready` endpoints.

## Endpoints

| Endpoint         | Purpose              | Response                                |
|------------------|----------------------|-----------------------------------------|
| `GET /health`    | Full health report   | Overall status + details for each check |
| `GET /health/ready` | Readiness probe  | Overall status only (for k8s)           |

Both return **200** when healthy and **503** when any check fails.

### Example Response

```json
{
  "status": "healthy",
  "checks": [
    {"name": "postgres", "status": "healthy", "latency_ms": 1.23},
    {"name": "redis", "status": "healthy", "latency_ms": 0.45},
    {"name": "disk", "status": "healthy", "usage_percent": 42.1, "free_gb": 58.32},
    {"name": "memory", "status": "healthy", "usage_percent": 61.3, "available_gb": 6.12}
  ]
}
```

## Advanced Usage

For more control, use the `HealthCheck` class directly:

```python
from fastapi import FastAPI
from healthkit import HealthCheck, check_postgres, check_disk, check_memory

app = FastAPI()

health = HealthCheck()
health.add(check_postgres, url="postgresql://user:pass@localhost/mydb")
health.add(check_disk, threshold_percent=85)
health.add(check_memory, threshold_percent=80)
health.mount(app)
```

### Custom Checks

Add your own check functions -- sync or async:

```python
async def check_external_api() -> dict:
    # your logic here
    return {"name": "external-api", "status": "healthy", "latency_ms": 52.1}

health.add(check_external_api)
```

## Available Checks

| Check            | What it does                        | Extra dependency |
|------------------|-------------------------------------|------------------|
| `check_postgres` | Connects and runs `SELECT 1`        | `asyncpg`        |
| `check_redis`    | Connects and sends `PING`           | `redis`          |
| `check_disk`     | Reports usage %, fails if above threshold | --          |
| `check_memory`   | Reports usage %, fails if above threshold | --          |

## Configuration

| Parameter            | Default | Description                          |
|----------------------|---------|--------------------------------------|
| `postgres_url`       | --      | PostgreSQL connection string         |
| `redis_url`          | --      | Redis connection string              |
| `disk_threshold`     | `90`    | Disk usage % to trigger unhealthy    |
| `memory_threshold`   | `90`    | Memory usage % to trigger unhealthy  |

## Kubernetes Integration

```yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8000
  initialDelaySeconds: 3
  periodSeconds: 5
```

## License

MIT
