Registry / web-framework / py-healthcheck

py-healthcheck

library1.10.1pypypi✓ verified 87d ago

py-healthcheck is a Python library that simplifies adding healthcheck and environment dump endpoints to Flask or Tornado web applications. It allows developers to define custom check functions to monitor application dependencies and internal state, exposing their status via a configurable HTTP route. The latest stable version is 1.10.1, though its release cadence appears irregular based on PyPI and GitHub history, with the most recent update in June 2022.

web-framework observability devops

pip install py-healthcheck

github ↗package ↗

INSTALL

IMPORT

SIG · PY-HEALTHCHECK

py-healthcheck

web-frameworkpythonv1.10.1

Install

1.6s avg

Import

50ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.10.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.052s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.048s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HealthCheck

✓ from healthcheck import HealthCheck

EnvironmentDump

✓ from healthcheck import EnvironmentDump

TornadoHandler

✓ from healthcheck import TornadoHandler

This Flask quickstart demonstrates setting up `/healthcheck` and `/environment` endpoints. Custom functions (`redis_available`, `database_check`) are added to the health check. The `EnvironmentDump` also includes custom application data. Run with `python your_app.py` or `flask run` and access `/healthcheck` and `/environment` in your browser. Set `MOCK_REDIS_FAILURE=true` or `MOCK_DB_FAILURE=true` environment variables to see failure states.

from flask import Flask from healthcheck import HealthCheck, EnvironmentDump import os app = Flask(__name__) health = HealthCheck(app, '/healthcheck') envdump = EnvironmentDump(app, '/environment') def redis_available(): # Simulate a Redis check # In a real app, you'd connect to Redis here if os.environ.get('MOCK_REDIS_FAILURE') == 'true': return False, "Redis connection failed (mocked)" return True, "redis ok" def database_check(): # Simulate a database check # In a real app, you'd check DB connection/query if os.environ.get('MOCK_DB_FAILURE') == 'true': return False, "Database connection failed (mocked)" return True, "database ok" health.add_check(redis_available) health.add_check(database_check) def application_data(): return { "maintainer": "Your Name", "git_repo": "https://github.com/your/repo", "version": "1.0.0" } envdump.add_section("application", application_data) # To run the Flask app (for demonstration, use 'flask run' in production) if __name__ == '__main__': # Example usage: http://127.0.0.1:5000/healthcheck # Example usage: http://127.0.0.1:5000/environment app.run(debug=True)

Debug

Known issues

gotchaHealth check results are cached by default (27 seconds for success, 9 seconds for failure). This can obscure immediate service degradation. To perform real-time checks, initialize `HealthCheck` with `success_ttl=None` and `failed_ttl=None`.

fix

Initialize `HealthCheck(success_ttl=None, failed_ttl=None)` or tune `success_ttl` and `failed_ttl` parameters as needed.

affects: >=1.0.0

gotchaAll custom health checker functions must strictly return a tuple of `(bool, str)`. The boolean indicates success/failure, and the string provides a message. Exceptions within a checker function are caught and reported as failures.

fix

Ensure all functions passed to `health.add_check()` adhere to the `(bool, str)` return signature. For example: `return True, "Service is up"` or `return False, "Service is down: error details"`.

affects: >=1.0.0

gotchaStarting with version 1.6.0, the library added support for timeouts on execution checkers. If your custom checks perform long-running operations, consider implementing explicit timeouts within your checker functions or exploring configuration options for the `HealthCheck` instance to prevent health checks from blocking.

fix

Review documentation for `HealthCheck` or `add_check` for specific timeout parameters. Alternatively, implement timeouts using Python's `concurrent.futures` or `asyncio.wait_for` within your custom checker functions. The release notes suggest this is an added capability.

affects: >=1.6.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'healthcheck'

The `py-healthcheck` library has not been installed or is not accessible in the current Python environment.

fix

Run `pip install py-healthcheck` to install the library.

HTTP 404 Not Found when accessing /healthcheck or /environment

The health check or environment dump endpoints have not been correctly registered with your Flask or Tornado application.

fix

For Flask, ensure `HealthCheck(app, '/healthcheck')` and `EnvironmentDump(app, '/environment')` are correctly instantiated with your `app` object and desired paths. For Tornado, ensure `TornadoHandler` is correctly added to `app.add_handlers` or `tornado.web.Application` routes.

TypeError: 'bool' object is not iterable

A custom health checker function returned only a boolean or another non-iterable type, instead of the required `(bool, str)` tuple.

fix

Modify your checker function to return a tuple, e.g., `return True, "All good"`.

Upgrade

Version history

1.10.1latest on PyPI · released Jun 11, 2022

Audit

Dependencies

FlaskoptionalRequired for Flask application integration.

TornadooptionalRequired for Tornado application integration.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ateliedocodigo/py-healthcheck ↗

packagehttps://pypi.org/project/py-healthcheck/ ↗