streamlit_healthcheck

 1# -*- coding: utf-8 -*-
 2"""
 3Streamlit Healthcheck provides lightweight, extensible utilities to run automated
 4health checks, expose health endpoints, and collect basic metrics for Streamlit
 5applications. It is designed to be CI/CD-friendly and to support reliable,
 6observable delivery pipelines.
 7
 8Key features
 9- Run synchronous or async health checks with timeouts and recovery hints
10- Register custom checks (liveness, readiness, dependency checks)
11- Expose HTTP/Streamlit endpoints for machine-readable and human-readable status
12- Emit structured metrics/events suitable for scraping or CI validation
13- Simple integration helpers for common backends (Redis, Postgres, external APIs)
14
15Quickstart
16----------
17
181) Install:
19
20```bash
21pip install streamlit_healthcheck
22```
23
242) Basic usage:
25
26>>> from streamlit_healthcheck import healthcheck
27>>> report = healthcheck.run_all(timeout=5)
28>>> if not report.ok:
29>>>      # handle degraded state (log, alert, fail pipeline)
30>>>      print(report.summary)
31
32API (common surface)
33-------------------
34
35- healthcheck.run_all(timeout: float = 5) -> HealthReport
36  Runs all registered checks and returns a HealthReport object with:
37     - ok: bool
38     - summary: str
39     - details: dict
40     - duration: float
41
42- healthcheck.register(name: str, fn: Callable, *, critical: bool = False)
43  Register a custom check function. Critical checks mark the whole service unhealthy.
44
45- healthcheck.serve(endpoint: str = "/health", host: str = "0.0.0.0", port: int = 8000)
46  Expose a simple HTTP endpoint (or embed in Streamlit) that returns JSON health status.
47
48DevOps alignment
49----------------
50
51- Reliable: Designed to reduce deployment failures and improve service uptime.
52- Automatable: Designed to be executed in CI/CD pipelines (pre-deploy checks, post-deploy smoke tests).
53- Observable: Emits structured outputs and metrics for dashboards and alerting.
54- Lean: Small, focused checks to enable frequent, low-risk deployments.
55- Measurable: Integrates with monitoring to improve MTTR and change failure rate.
56- Shareable: Clear APIs, runbooks examples, and integration docs for teams.
57
58Integration tips
59-----------------
60
61- Use canary deployments or blue-green deployments to minimize impact during rollouts.
62- Use feature flags or conditional checks to avoid noisy alerts during rollouts.
63- Run healthcheck.run_all in CI as a gating step for deployments.
64- Expose metrics to Prometheus or your metrics backend for SLA tracking.
65
66Configuration
67-----------------
68
69- Supports environment variables and optional YAML/JSON config for check registration.
70- Default timeouts and thresholds are overridable per-check.
71
72Contributing
73-----------------
74
75- Tests, type hints, and small, focused PRs welcome.
76- Follow the repository's CONTRIBUTING.md and code-of-conduct.
77- Add unit tests for new checks and integrations; CI runs linting and tests.
78- Use GitHub issues for bugs, feature requests, and discussions.
79
80License
81-----------------
82
83GNU GENERAL PUBLIC LICENSE v3
84
85"""
86# Version
87from importlib.metadata import version, PackageNotFoundError
88
89try:
90    __version__ = version("streamlit_healthcheck")
91except PackageNotFoundError:
92    # package is not installed
93    pass