{"id":26882594,"url":"https://github.com/colin-b/healthpy","last_synced_at":"2025-05-08T02:40:24.449Z","repository":{"id":56483465,"uuid":"224739043","full_name":"Colin-b/healthpy","owner":"Colin-b","description":"Health Check for HTTP APIs (RFC implementation)","archived":false,"fork":false,"pushed_at":"2020-11-04T19:34:02.000Z","size":107,"stargazers_count":15,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-05-04T15:17:02.406Z","etag":null,"topics":["api","check","consul","health","http","redis","status"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Colin-b.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-28T22:30:37.000Z","updated_at":"2025-04-09T19:31:24.000Z","dependencies_parsed_at":"2022-08-15T19:40:14.159Z","dependency_job_id":null,"html_url":"https://github.com/Colin-b/healthpy","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Colin-b%2Fhealthpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Colin-b%2Fhealthpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Colin-b%2Fhealthpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Colin-b%2Fhealthpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Colin-b","download_url":"https://codeload.github.com/Colin-b/healthpy/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252989401,"owners_count":21836658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","check","consul","health","http","redis","status"],"created_at":"2025-03-31T16:38:56.483Z","updated_at":"2025-05-08T02:40:24.433Z","avatar_url":"https://github.com/Colin-b.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003eHealth Check for HTTP APIs\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://pypi.org/project/healthpy/\"\u003e\u003cimg alt=\"pypi version\" src=\"https://img.shields.io/pypi/v/healthpy\"\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.com/Colin-b/healthpy\"\u003e\u003cimg alt=\"Build status\" src=\"https://api.travis-ci.com/Colin-b/healthpy.svg?branch=master\"\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.com/Colin-b/healthpy\"\u003e\u003cimg alt=\"Coverage\" src=\"https://img.shields.io/badge/coverage-100%25-brightgreen\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.com/Colin-b/healthpy\"\u003e\u003cimg alt=\"Number of tests\" src=\"https://img.shields.io/badge/tests-140 passed-blue\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/healthpy/\"\u003e\u003cimg alt=\"Number of downloads\" src=\"https://img.shields.io/pypi/dm/healthpy\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nCreate an health check endpoint on your REST API following [Health Check RFC](https://inadarei.github.io/rfc-healthcheck/) draft version 4.\n\n- [Perform checks](#perform-checks)\n  - [Of an external HTTP resource](#http)\n  - [Of a redis server](#redis)\n- [Return health check result](#return-result)\n  - [Aggregate multiple statuses](#compute-status-from-multiple-statuses)\n  - [Use a custom status](#using-custom-status)\n  - [HTTP response body](#http-response-body)\n  - [HTTP response status code](#http-response-status-code)\n- [Endpoint](#endpoint)\n  - [Starlette](#starlette)\n  - [Flask-RestX](#flask-restx)\n\n## Perform checks\n\nIn case you have external dependencies, you should check the health of those dependencies.\n\n### HTTP\n\nIf you have an external HTTP resource, you can check its health, as in the following sample:\n\n```python\nimport healthpy.httpx\n\nstatus, checks = healthpy.httpx.check(\"petstore\", \"https://petstore3.swagger.io/api/v3/openapi.json\")\n```\n\nNote: [httpx](https://pypi.python.org/pypi/httpx) module must be installed to perform HTTP health checks.\n\nAlternatively, you can use [requests](https://pypi.python.org/pypi/requests) to perform the exact same check:\n\n```python\nimport healthpy.requests\n\nstatus, checks = healthpy.requests.check(\"petstore\", \"https://petstore3.swagger.io/api/v3/openapi.json\")\n```\n\n### Redis\n\nIf you rely on redis, you should check its health.\n\n[redis](https://pypi.python.org/pypi/redis) module must be installed to perform Redis health checks.\n\n```python\nimport healthpy.redis\n\nstatus, checks = healthpy.redis.check(\"redis://redis_url\", \"redis_key\")\n```\n\n## Return result\n\nOnce all checks have been performed you should return the result to your client.\n\n### Compute status from multiple statuses\n\nIf you performed more than one check, you have to compute an aggregated status from all the checks.\n\n```python\nimport healthpy\n\nstatus1 = healthpy.pass_status \nstatus2 = healthpy.warn_status\nstatusN = healthpy.fail_status\n\nstatus = healthpy.status(status1, status2, statusN)\n```\n\n### Using custom status\n\nBy default pass status is \"pass\", warn status is \"warn\" and fail status is \"fail\".\n\nIt can be tweaked by setting the value of healthpy.*_status as in the following sample:\n\n```python\nimport healthpy\n\nhealthpy.pass_status = \"ok\"\nhealthpy.warn_status = \"custom\"\nhealthpy.fail_status = \"error\"\n```\n\n### HTTP response body\n\nHTTP response body can be retrieved as a dictionary to be returned as JSON.\n\n```python\nimport healthpy\n\nstatus = healthpy.pass_status  # replace with the aggregated status\nchecks = {}  # replace with the computed checks\n\nbody = healthpy.response_body(status, checks=checks)\n```\n\nChecks results are not mandatory in the response.\n\n```python\nimport healthpy\n\nstatus = healthpy.pass_status  # replace with the aggregated status\n\nbody = healthpy.response_body(status)\n```\n\n### HTTP response status code\n\nHTTP response status code can be retrieved as an integer.\n\n```python\nimport healthpy\n\nstatus = healthpy.pass_status  # replace with the aggregated status\n\nstatus_code = healthpy.response_status_code(status)\n```\n\n#### Consul\n\nHTTP response status code should be a bit different for [Consul](https://www.consul.io/docs/agent/checks.html) health checks.\n\n```python\nimport healthpy\n\nstatus = healthpy.pass_status  # replace with the aggregated status\n\nstatus_code = healthpy.consul_response_status_code(status)\n```\n\n## Endpoint\n\n### Starlette\n\nAn helper function is available to create a [starlette](https://www.starlette.io) endpoint for [Consul](https://www.consul.io/docs/agent/checks.html) health check.\n\n```python\nfrom starlette.applications import Starlette\nimport healthpy\nimport healthpy.httpx\nimport healthpy.redis\nfrom healthpy.starlette import add_consul_health_endpoint\n\n\napp = Starlette()\n\n\nasync def health_check():\n    # TODO Replace by your own checks.\n    status_1, checks_1 = healthpy.httpx.check(\"my external dependency\", \"http://url_to_check\")\n    status_2, checks_2 = healthpy.redis.check(\"redis://redis_url\", \"key_to_check\")\n    return healthpy.status(status_1, status_2), {**checks_1, **checks_2}\n\n# /health endpoint will call the health_check coroutine.\nadd_consul_health_endpoint(app, health_check)\n```\n\nNote: [starlette](https://pypi.python.org/pypi/starlette) module must be installed.\n\n### Flask-RestX\n\nAn helper function is available to create a [Flask-RestX](https://flask-restx.readthedocs.io/en/latest/) endpoint for health check.\n\n```python\nimport flask\nimport flask_restx\nimport healthpy\nimport healthpy.httpx\nimport healthpy.redis\nfrom healthpy.flask_restx import add_health_endpoint\n\n\napp = flask.Flask(__name__)\napi = flask_restx.Api(app)\n\n\nasync def health_check():\n    # TODO Replace by your own checks.\n    status_1, checks_1 = healthpy.httpx.check(\"my external dependency\", \"http://url_to_check\")\n    status_2, checks_2 = healthpy.redis.check(\"redis://redis_url\", \"key_to_check\")\n    return healthpy.status(status_1, status_2), {**checks_1, **checks_2}\n\n# /health endpoint will call the health_check coroutine.\nadd_health_endpoint(api, health_check)\n```\n\nNote: [flask-restx](https://pypi.python.org/pypi/flask-restx) module must be installed.\n\n\n#### Consul Service Health check\n\nAn helper function is available to create a [Flask-RestX](https://flask-restx.readthedocs.io/en/latest/) endpoint for [Consul](https://www.consul.io/docs/agent/checks.html) health check.\n\n```python\nimport flask\nimport flask_restx\nimport healthpy\nimport healthpy.httpx\nimport healthpy.redis\nfrom healthpy.flask_restx import add_consul_health_endpoint\n\n\napp = flask.Flask(__name__)\napi = flask_restx.Api(app)\n\n\nasync def health_check():\n    # TODO Replace by your own checks.\n    status_1, checks_1 = healthpy.httpx.check(\"my external dependency\", \"http://url_to_check\")\n    status_2, checks_2 = healthpy.redis.check(\"redis://redis_url\", \"key_to_check\")\n    return healthpy.status(status_1, status_2), {**checks_1, **checks_2}\n\n# /health endpoint will call the health_check coroutine.\nadd_consul_health_endpoint(api, health_check)\n```\n\nNote: [flask-restx](https://pypi.python.org/pypi/flask-restx) module must be installed.\n\n## Testing\n\nA `pytest` fixture can be used to mock the datetime returned in http health check.\n\n```python\nfrom healthpy.testing import mock_http_health_datetime\n\ndef test_http(mock_http_health_datetime):\n    # Time will be returned as \"2018-10-11T15:05:05.663979\"\n    pass  # Add your test calling healthpy.http.check\n```\n\n## How to install\n1. [python 3.7+](https://www.python.org/downloads/) must be installed\n2. Use pip to install module:\n```sh\npython -m pip install healthpy\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolin-b%2Fhealthpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolin-b%2Fhealthpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolin-b%2Fhealthpy/lists"}