| Name | rest-health JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Framework-agnostic REST healthcheck endpoints for Python web apps |
| upload_time | 2025-09-02 10:54:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Fabricio Entringer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
health
healthcheck
rest
api
fastapi
flask
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# rest-health
<div align="center">
<img src="./assets/rest-health-logo.png" alt="rest-health logo" width="200">
</div>
**Framework-agnostic REST healthcheck endpoints for Python web apps**
`rest-health` provides a simple, lightweight way to expose standardized REST healthcheck endpoints across different Python web frameworks. No unnecessary complexity - just clean, production-ready health monitoring.
## Features
- **Framework-agnostic**: Works with FastAPI, Flask, and any other Python web framework
- **Lightweight**: Zero external dependencies for core functionality
- **Simple API**: Register health checks as simple functions
- **Production-ready**: Proper error handling and standard HTTP status codes
- **Extensible**: Easy to add custom health checks
## Installation
```bash
pip install rest-health
```
For framework-specific integrations:
```bash
# For FastAPI
pip install rest-health[fastapi]
# For Flask
pip install rest-health[flask]
```
## Quick Start
### Basic Usage
```python
from rest_health import HealthCheck
# Create a health checker
health = HealthCheck()
# Add a simple check
def database_check():
# Your database connectivity check logic
return True # or False if unhealthy
health.add_check("database", database_check)
# Run all checks
result = health.run()
# Returns: {"status": "ok", "checks": {"database": {"status": "ok", "success": True}}}
```
### FastAPI Integration
```python
from fastapi import FastAPI
from rest_health import HealthCheck
from rest_health.adapters.fastapi import create_fastapi_healthcheck
app = FastAPI()
# Setup health checks
health = HealthCheck()
def database_check():
# Check database connectivity
return True
def cache_check():
# Check cache connectivity
return True
health.add_check("database", database_check)
health.add_check("cache", cache_check)
# Add health endpoint
health_router = create_fastapi_healthcheck(health)
app.include_router(health_router)
# Now GET /health returns health status
```
### Flask Integration
```python
from flask import Flask
from rest_health import HealthCheck
from rest_health.adapters.flask import create_flask_healthcheck
app = Flask(__name__)
# Setup health checks
health = HealthCheck()
def database_check():
# Check database connectivity
return True
health.add_check("database", database_check)
# Add health endpoint
health_blueprint = create_flask_healthcheck(health)
app.register_blueprint(health_blueprint)
# Now GET /health returns health status
```
## Advanced Usage
### Custom Health Checks
```python
from rest_health import HealthCheck
import requests
health = HealthCheck()
def external_api_check():
"""Check if external API is responsive."""
try:
response = requests.get("https://api.example.com/ping", timeout=5)
return response.status_code == 200
except:
return False
def database_check():
"""Check database connectivity."""
try:
# Your database check logic here
return True
except:
return False
health.add_check("external_api", external_api_check)
health.add_check("database", database_check)
```
### Error Handling
When a health check raises an exception, it's automatically caught and the check is marked as failed:
```python
def failing_check():
raise ValueError("Something went wrong")
health.add_check("problematic_service", failing_check)
result = health.run()
# Returns:
# {
# "status": "fail",
# "checks": {
# "problematic_service": {
# "status": "fail",
# "success": False,
# "error": "Something went wrong"
# }
# }
# }
```
### Custom Endpoint Path
```python
# FastAPI - custom path
health_router = create_fastapi_healthcheck(health, path="/api/health")
# Flask - custom path
health_blueprint = create_flask_healthcheck(health, path="/api/health")
```
## Response Format
Health check endpoints return JSON with the following structure:
```json
{
"status": "ok", // "ok" or "fail"
"checks": {
"database": {
"status": "ok", // "ok" or "fail"
"success": true
},
"cache": {
"status": "fail",
"success": false,
"error": "Connection timeout" // Only present on error
}
}
}
```
## HTTP Status Codes
- `200 OK`: All health checks passed
- `503 Service Unavailable`: One or more health checks failed
## Design Philosophy
`rest-health` follows these principles:
- **Simplicity**: No background tasks, no async complexity, no unnecessary features
- **Framework-agnostic**: Core logic works with any Python web framework
- **Lightweight**: Minimal dependencies and overhead
- **Production-ready**: Proper error handling and observability
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
For detailed technical information, development setup, coding standards, and contribution guidelines, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "rest-health",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "health, healthcheck, rest, api, fastapi, flask",
"author": null,
"author_email": "Fabricio Entringer <fabricio.entringer@example.com>",
"download_url": "https://files.pythonhosted.org/packages/45/5f/a1bad03c2331bc73b7147b577024ba7c6c0e76e59308cf54c72a7cc2f8ca/rest_health-0.1.0.tar.gz",
"platform": null,
"description": "# rest-health\n\n<div align=\"center\">\n <img src=\"./assets/rest-health-logo.png\" alt=\"rest-health logo\" width=\"200\">\n</div>\n\n**Framework-agnostic REST healthcheck endpoints for Python web apps**\n\n`rest-health` provides a simple, lightweight way to expose standardized REST healthcheck endpoints across different Python web frameworks. No unnecessary complexity - just clean, production-ready health monitoring.\n\n## Features\n\n- **Framework-agnostic**: Works with FastAPI, Flask, and any other Python web framework\n- **Lightweight**: Zero external dependencies for core functionality\n- **Simple API**: Register health checks as simple functions\n- **Production-ready**: Proper error handling and standard HTTP status codes\n- **Extensible**: Easy to add custom health checks\n\n## Installation\n\n```bash\npip install rest-health\n```\n\nFor framework-specific integrations:\n\n```bash\n# For FastAPI\npip install rest-health[fastapi]\n\n# For Flask\npip install rest-health[flask]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom rest_health import HealthCheck\n\n# Create a health checker\nhealth = HealthCheck()\n\n# Add a simple check\ndef database_check():\n # Your database connectivity check logic\n return True # or False if unhealthy\n\nhealth.add_check(\"database\", database_check)\n\n# Run all checks\nresult = health.run()\n# Returns: {\"status\": \"ok\", \"checks\": {\"database\": {\"status\": \"ok\", \"success\": True}}}\n```\n\n### FastAPI Integration\n\n```python\nfrom fastapi import FastAPI\nfrom rest_health import HealthCheck\nfrom rest_health.adapters.fastapi import create_fastapi_healthcheck\n\napp = FastAPI()\n\n# Setup health checks\nhealth = HealthCheck()\n\ndef database_check():\n # Check database connectivity\n return True\n\ndef cache_check():\n # Check cache connectivity \n return True\n\nhealth.add_check(\"database\", database_check)\nhealth.add_check(\"cache\", cache_check)\n\n# Add health endpoint\nhealth_router = create_fastapi_healthcheck(health)\napp.include_router(health_router)\n\n# Now GET /health returns health status\n```\n\n### Flask Integration\n\n```python\nfrom flask import Flask\nfrom rest_health import HealthCheck\nfrom rest_health.adapters.flask import create_flask_healthcheck\n\napp = Flask(__name__)\n\n# Setup health checks\nhealth = HealthCheck()\n\ndef database_check():\n # Check database connectivity\n return True\n\nhealth.add_check(\"database\", database_check)\n\n# Add health endpoint\nhealth_blueprint = create_flask_healthcheck(health)\napp.register_blueprint(health_blueprint)\n\n# Now GET /health returns health status\n```\n\n## Advanced Usage\n\n### Custom Health Checks\n\n```python\nfrom rest_health import HealthCheck\nimport requests\n\nhealth = HealthCheck()\n\ndef external_api_check():\n \"\"\"Check if external API is responsive.\"\"\"\n try:\n response = requests.get(\"https://api.example.com/ping\", timeout=5)\n return response.status_code == 200\n except:\n return False\n\ndef database_check():\n \"\"\"Check database connectivity.\"\"\"\n try:\n # Your database check logic here\n return True\n except:\n return False\n\nhealth.add_check(\"external_api\", external_api_check)\nhealth.add_check(\"database\", database_check)\n```\n\n### Error Handling\n\nWhen a health check raises an exception, it's automatically caught and the check is marked as failed:\n\n```python\ndef failing_check():\n raise ValueError(\"Something went wrong\")\n\nhealth.add_check(\"problematic_service\", failing_check)\n\nresult = health.run()\n# Returns:\n# {\n# \"status\": \"fail\",\n# \"checks\": {\n# \"problematic_service\": {\n# \"status\": \"fail\",\n# \"success\": False,\n# \"error\": \"Something went wrong\"\n# }\n# }\n# }\n```\n\n### Custom Endpoint Path\n\n```python\n# FastAPI - custom path\nhealth_router = create_fastapi_healthcheck(health, path=\"/api/health\")\n\n# Flask - custom path \nhealth_blueprint = create_flask_healthcheck(health, path=\"/api/health\")\n```\n\n## Response Format\n\nHealth check endpoints return JSON with the following structure:\n\n```json\n{\n \"status\": \"ok\", // \"ok\" or \"fail\"\n \"checks\": {\n \"database\": {\n \"status\": \"ok\", // \"ok\" or \"fail\"\n \"success\": true\n },\n \"cache\": {\n \"status\": \"fail\",\n \"success\": false,\n \"error\": \"Connection timeout\" // Only present on error\n }\n }\n}\n```\n\n## HTTP Status Codes\n\n- `200 OK`: All health checks passed\n- `503 Service Unavailable`: One or more health checks failed\n\n## Design Philosophy\n\n`rest-health` follows these principles:\n\n- **Simplicity**: No background tasks, no async complexity, no unnecessary features\n- **Framework-agnostic**: Core logic works with any Python web framework\n- **Lightweight**: Minimal dependencies and overhead\n- **Production-ready**: Proper error handling and observability\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nFor detailed technical information, development setup, coding standards, and contribution guidelines, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Fabricio Entringer\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Framework-agnostic REST healthcheck endpoints for Python web apps",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/fabricio-entringer/rest-health",
"Issues": "https://github.com/fabricio-entringer/rest-health/issues",
"Repository": "https://github.com/fabricio-entringer/rest-health"
},
"split_keywords": [
"health",
" healthcheck",
" rest",
" api",
" fastapi",
" flask"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8db5036da248d47f53e560f4834a2711b3429cc9e00d073a3727b9905e7c1798",
"md5": "4f54f85fcf64c15b46b981ad8277e39b",
"sha256": "11b8e7eccce699f3c0f0b01acd5811b2585e1561faaec8e2d2724d730ce08856"
},
"downloads": -1,
"filename": "rest_health-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f54f85fcf64c15b46b981ad8277e39b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8106,
"upload_time": "2025-09-02T10:54:28",
"upload_time_iso_8601": "2025-09-02T10:54:28.024968Z",
"url": "https://files.pythonhosted.org/packages/8d/b5/036da248d47f53e560f4834a2711b3429cc9e00d073a3727b9905e7c1798/rest_health-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "455fa1bad03c2331bc73b7147b577024ba7c6c0e76e59308cf54c72a7cc2f8ca",
"md5": "a16d763c519c74e3574b7f676889ddd6",
"sha256": "65c5c89b6f0cd408ef91970a0e0a7bd8927ab43c2590cc70715503a60220186e"
},
"downloads": -1,
"filename": "rest_health-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a16d763c519c74e3574b7f676889ddd6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9252,
"upload_time": "2025-09-02T10:54:29",
"upload_time_iso_8601": "2025-09-02T10:54:29.395996Z",
"url": "https://files.pythonhosted.org/packages/45/5f/a1bad03c2331bc73b7147b577024ba7c6c0e76e59308cf54c72a7cc2f8ca/rest_health-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 10:54:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fabricio-entringer",
"github_project": "rest-health",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rest-health"
}
