flask-vitals 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Clara Vanacker
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,150 @@
1
+ Metadata-Version: 2.4
2
+ Name: flask-vitals
3
+ Version: 0.1.0
4
+ Summary: Drop-in Flask health blueprint: /healthz + /readyz, ready for Huginn / UptimeRobot-style monitoring.
5
+ Keywords: flask,health,healthcheck,readiness,liveness,monitoring
6
+ Author: Clara Vanacker
7
+ Author-email: Clara Vanacker <claravanacker27@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Framework :: Flask
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
17
+ Classifier: Topic :: System :: Monitoring
18
+ Classifier: Typing :: Typed
19
+ Requires-Dist: flask>=3.1.0
20
+ Requires-Python: >=3.14
21
+ Project-URL: Homepage, https://github.com/ClaraVnk/flask-vitals
22
+ Project-URL: Repository, https://github.com/ClaraVnk/flask-vitals
23
+ Project-URL: Issues, https://github.com/ClaraVnk/flask-vitals/issues
24
+ Description-Content-Type: text/markdown
25
+
26
+ <div align="center">
27
+
28
+ # 🩺 flask-vitals
29
+
30
+ **A drop-in Flask health blueprint β€” `/healthz` (liveness) + `/readyz` (readiness) in two lines.**
31
+
32
+ [![CI](https://github.com/ClaraVnk/flask-vitals/actions/workflows/ci.yml/badge.svg)](https://github.com/ClaraVnk/flask-vitals/actions/workflows/ci.yml)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
34
+ [![Python 3.14+](https://img.shields.io/badge/python-3.14+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
35
+ [![Flask](https://img.shields.io/badge/Flask-3.x-000000.svg?logo=flask&logoColor=white)](https://flask.palletsprojects.com/)
36
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
37
+ [![Checked with mypy](https://img.shields.io/badge/mypy-strict-2A6DB2.svg)](https://mypy-lang.org/)
38
+ [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-contributing)
39
+
40
+ </div>
41
+
42
+ ---
43
+
44
+ Every service needs the same two endpoints β€” *"are you alive?"* and *"can you serve?"* β€”
45
+ yet everyone re-writes them, slightly differently, in every app. **flask-vitals** is
46
+ the boring, correct version you register once:
47
+
48
+ ```python
49
+ from flask_vitals import vitals
50
+
51
+ app.register_blueprint(vitals())
52
+ ```
53
+
54
+ …and now `GET /healthz` and `GET /readyz` answer exactly the way orchestrators
55
+ (Kubernetes), load balancers, and external monitors
56
+ ([Huginn](https://github.com/ClaraVnk/huginn), UptimeRobot, Uptime Kuma) expect.
57
+
58
+ ## ✨ Features
59
+
60
+ - **Liveness vs. readiness, done right** β€” `/healthz` says the process is up;
61
+ `/readyz` says it can actually serve (its dependencies are reachable).
62
+ - **Injected checks** β€” readiness probes your DB / cache / queue via callables
63
+ *you* provide; the library never reaches into your stack.
64
+ - **Honest status codes** β€” `/readyz` returns **`503`** with a per-check
65
+ breakdown when something is down, so "up but broken" is caught.
66
+ - **Zero config to start, fully tunable** β€” custom paths, an optional version
67
+ string, any number of named checks.
68
+ - **Tiny & typed** β€” one module, no dependency beyond Flask, `mypy --strict`,
69
+ 100 % tested. MIT-licensed.
70
+
71
+ ## πŸ“¦ Install
72
+
73
+ ```bash
74
+ uv add "git+https://github.com/ClaraVnk/flask-vitals"
75
+ # or
76
+ pip install "git+https://github.com/ClaraVnk/flask-vitals"
77
+ ```
78
+
79
+ ## πŸš€ Quickstart
80
+
81
+ ```python
82
+ from flask import Flask
83
+ from sqlalchemy import text
84
+ from flask_vitals import vitals
85
+
86
+ app = Flask(__name__)
87
+
88
+ def db_ok() -> None:
89
+ db.session.execute(text("SELECT 1")) # raises β†’ not ready
90
+
91
+ app.register_blueprint(vitals(checks={"db": db_ok}, version="1.4.2"))
92
+ ```
93
+
94
+ | Request | Response | Code |
95
+ | -------------- | -------------------------------------------------------------- | ---- |
96
+ | `GET /healthz` | `{"status": "ok", "version": "1.4.2"}` | `200` |
97
+ | `GET /readyz` | `{"ready": true, "checks": {"db": true}}` | `200` |
98
+ | `GET /readyz` | `{"ready": false, "checks": {"db": false}}` *(db unreachable)* | `503` |
99
+
100
+ A check **passes** unless it returns `False` or raises β€” so a one-liner like
101
+ `lambda: cache.ping()` is a valid check.
102
+
103
+ ### Options
104
+
105
+ | Argument | Default | Purpose |
106
+ | ---------------- | ------------ | ----------------------------------------- |
107
+ | `checks` | `{}` | `{name: callable}` readiness probes |
108
+ | `version` | `None` | echoed by `/healthz` when set |
109
+ | `liveness_path` | `/healthz` | liveness route |
110
+ | `readiness_path` | `/readyz` | readiness route |
111
+ | `name` | `"vitals"` | blueprint name (change if registered twice)|
112
+
113
+ ## πŸ“‘ Monitoring it (e.g. with Huginn)
114
+
115
+ Point an uptime monitor at each app:
116
+
117
+ - an **HTTP** monitor on `…/healthz` β€” expected status `200` β†’ *is it alive?*
118
+ - a **keyword** monitor on `…/readyz` containing `"ready": true` β†’ *is it serving?*
119
+
120
+ That's the UptimeRobot/Uptime-Kuma experience for any Flask app, with no bespoke
121
+ health code per service.
122
+
123
+ ## πŸ› οΈ Develop
124
+
125
+ ```bash
126
+ uv sync
127
+ uv run ruff format --check .
128
+ uv run ruff check .
129
+ uv run mypy
130
+ uv run pytest
131
+ ```
132
+
133
+ ## 🧱 Architecture
134
+
135
+ One module, `flask_vitals.blueprint`, exposing `vitals(...) -> flask.Blueprint`.
136
+ No global state, no dependency beyond Flask; readiness checks are injected by the
137
+ host app, so the library stays decoupled from your stack and trivially testable.
138
+
139
+ ## 🀝 Contributing
140
+
141
+ Issues and PRs are welcome! Keep it small and tested:
142
+
143
+ 1. `uv sync`
144
+ 2. Make your change with a test.
145
+ 3. `uv run ruff format . && uv run ruff check . && uv run mypy && uv run pytest`
146
+ 4. Open a PR.
147
+
148
+ ## πŸ“„ License
149
+
150
+ [MIT](LICENSE) Β© Clara Vanacker
@@ -0,0 +1,125 @@
1
+ <div align="center">
2
+
3
+ # 🩺 flask-vitals
4
+
5
+ **A drop-in Flask health blueprint β€” `/healthz` (liveness) + `/readyz` (readiness) in two lines.**
6
+
7
+ [![CI](https://github.com/ClaraVnk/flask-vitals/actions/workflows/ci.yml/badge.svg)](https://github.com/ClaraVnk/flask-vitals/actions/workflows/ci.yml)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
+ [![Python 3.14+](https://img.shields.io/badge/python-3.14+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
10
+ [![Flask](https://img.shields.io/badge/Flask-3.x-000000.svg?logo=flask&logoColor=white)](https://flask.palletsprojects.com/)
11
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
12
+ [![Checked with mypy](https://img.shields.io/badge/mypy-strict-2A6DB2.svg)](https://mypy-lang.org/)
13
+ [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-contributing)
14
+
15
+ </div>
16
+
17
+ ---
18
+
19
+ Every service needs the same two endpoints β€” *"are you alive?"* and *"can you serve?"* β€”
20
+ yet everyone re-writes them, slightly differently, in every app. **flask-vitals** is
21
+ the boring, correct version you register once:
22
+
23
+ ```python
24
+ from flask_vitals import vitals
25
+
26
+ app.register_blueprint(vitals())
27
+ ```
28
+
29
+ …and now `GET /healthz` and `GET /readyz` answer exactly the way orchestrators
30
+ (Kubernetes), load balancers, and external monitors
31
+ ([Huginn](https://github.com/ClaraVnk/huginn), UptimeRobot, Uptime Kuma) expect.
32
+
33
+ ## ✨ Features
34
+
35
+ - **Liveness vs. readiness, done right** β€” `/healthz` says the process is up;
36
+ `/readyz` says it can actually serve (its dependencies are reachable).
37
+ - **Injected checks** β€” readiness probes your DB / cache / queue via callables
38
+ *you* provide; the library never reaches into your stack.
39
+ - **Honest status codes** β€” `/readyz` returns **`503`** with a per-check
40
+ breakdown when something is down, so "up but broken" is caught.
41
+ - **Zero config to start, fully tunable** β€” custom paths, an optional version
42
+ string, any number of named checks.
43
+ - **Tiny & typed** β€” one module, no dependency beyond Flask, `mypy --strict`,
44
+ 100 % tested. MIT-licensed.
45
+
46
+ ## πŸ“¦ Install
47
+
48
+ ```bash
49
+ uv add "git+https://github.com/ClaraVnk/flask-vitals"
50
+ # or
51
+ pip install "git+https://github.com/ClaraVnk/flask-vitals"
52
+ ```
53
+
54
+ ## πŸš€ Quickstart
55
+
56
+ ```python
57
+ from flask import Flask
58
+ from sqlalchemy import text
59
+ from flask_vitals import vitals
60
+
61
+ app = Flask(__name__)
62
+
63
+ def db_ok() -> None:
64
+ db.session.execute(text("SELECT 1")) # raises β†’ not ready
65
+
66
+ app.register_blueprint(vitals(checks={"db": db_ok}, version="1.4.2"))
67
+ ```
68
+
69
+ | Request | Response | Code |
70
+ | -------------- | -------------------------------------------------------------- | ---- |
71
+ | `GET /healthz` | `{"status": "ok", "version": "1.4.2"}` | `200` |
72
+ | `GET /readyz` | `{"ready": true, "checks": {"db": true}}` | `200` |
73
+ | `GET /readyz` | `{"ready": false, "checks": {"db": false}}` *(db unreachable)* | `503` |
74
+
75
+ A check **passes** unless it returns `False` or raises β€” so a one-liner like
76
+ `lambda: cache.ping()` is a valid check.
77
+
78
+ ### Options
79
+
80
+ | Argument | Default | Purpose |
81
+ | ---------------- | ------------ | ----------------------------------------- |
82
+ | `checks` | `{}` | `{name: callable}` readiness probes |
83
+ | `version` | `None` | echoed by `/healthz` when set |
84
+ | `liveness_path` | `/healthz` | liveness route |
85
+ | `readiness_path` | `/readyz` | readiness route |
86
+ | `name` | `"vitals"` | blueprint name (change if registered twice)|
87
+
88
+ ## πŸ“‘ Monitoring it (e.g. with Huginn)
89
+
90
+ Point an uptime monitor at each app:
91
+
92
+ - an **HTTP** monitor on `…/healthz` β€” expected status `200` β†’ *is it alive?*
93
+ - a **keyword** monitor on `…/readyz` containing `"ready": true` β†’ *is it serving?*
94
+
95
+ That's the UptimeRobot/Uptime-Kuma experience for any Flask app, with no bespoke
96
+ health code per service.
97
+
98
+ ## πŸ› οΈ Develop
99
+
100
+ ```bash
101
+ uv sync
102
+ uv run ruff format --check .
103
+ uv run ruff check .
104
+ uv run mypy
105
+ uv run pytest
106
+ ```
107
+
108
+ ## 🧱 Architecture
109
+
110
+ One module, `flask_vitals.blueprint`, exposing `vitals(...) -> flask.Blueprint`.
111
+ No global state, no dependency beyond Flask; readiness checks are injected by the
112
+ host app, so the library stays decoupled from your stack and trivially testable.
113
+
114
+ ## 🀝 Contributing
115
+
116
+ Issues and PRs are welcome! Keep it small and tested:
117
+
118
+ 1. `uv sync`
119
+ 2. Make your change with a test.
120
+ 3. `uv run ruff format . && uv run ruff check . && uv run mypy && uv run pytest`
121
+ 4. Open a PR.
122
+
123
+ ## πŸ“„ License
124
+
125
+ [MIT](LICENSE) Β© Clara Vanacker
@@ -0,0 +1,60 @@
1
+ [project]
2
+ name = "flask-vitals"
3
+ version = "0.1.0"
4
+ description = "Drop-in Flask health blueprint: /healthz + /readyz, ready for Huginn / UptimeRobot-style monitoring."
5
+ readme = "README.md"
6
+ authors = [{ name = "Clara Vanacker", email = "claravanacker27@gmail.com" }]
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ requires-python = ">=3.14"
10
+ keywords = ["flask", "health", "healthcheck", "readiness", "liveness", "monitoring"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Framework :: Flask",
14
+ "Intended Audience :: Developers",
15
+ "Operating System :: OS Independent",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.14",
18
+ "Topic :: Software Development :: Libraries :: Application Frameworks",
19
+ "Topic :: System :: Monitoring",
20
+ "Typing :: Typed",
21
+ ]
22
+ dependencies = ["flask>=3.1.0"]
23
+
24
+ [project.urls]
25
+ Homepage = "https://github.com/ClaraVnk/flask-vitals"
26
+ Repository = "https://github.com/ClaraVnk/flask-vitals"
27
+ Issues = "https://github.com/ClaraVnk/flask-vitals/issues"
28
+
29
+ [build-system]
30
+ requires = ["uv_build>=0.11.8,<0.12.0"]
31
+ build-backend = "uv_build"
32
+
33
+ [dependency-groups]
34
+ dev = [
35
+ "mypy>=2.1.0",
36
+ "pytest>=9.1.1",
37
+ "ruff>=0.15.20",
38
+ ]
39
+
40
+ [tool.ruff]
41
+ line-length = 100
42
+ target-version = "py314"
43
+ src = ["src", "tests"]
44
+
45
+ [tool.ruff.lint]
46
+ select = ["E", "F", "I", "UP", "B", "S", "RUF", "ANN", "BLE"]
47
+ ignore = ["ANN401"]
48
+
49
+ [tool.ruff.lint.per-file-ignores]
50
+ "tests/**" = ["S101", "ANN", "S106"]
51
+
52
+ [tool.mypy]
53
+ python_version = "3.14"
54
+ strict = true
55
+ mypy_path = "src"
56
+ packages = ["flask_vitals"]
57
+
58
+ [tool.pytest.ini_options]
59
+ testpaths = ["tests"]
60
+ addopts = "-q"
@@ -0,0 +1,8 @@
1
+ """flask-vitals β€” a drop-in Flask health blueprint (/healthz + /readyz)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from flask_vitals.blueprint import Check, vitals
6
+
7
+ __all__ = ["Check", "vitals"]
8
+ __version__ = "0.1.0"
@@ -0,0 +1,62 @@
1
+ """A drop-in Flask health blueprint: ``/healthz`` (liveness) and ``/readyz``
2
+ (readiness).
3
+
4
+ Mirrors the liveness/readiness split that orchestrators and external monitors
5
+ (Huginn, UptimeRobot, Kubernetes…) expect:
6
+
7
+ * ``/healthz`` β€” the process is up. No dependencies probed. Always ``200``.
8
+ * ``/readyz`` β€” the app can serve: every registered check passes. ``200`` when
9
+ all pass, ``503`` otherwise, with a per-check breakdown.
10
+
11
+ A check is any zero-arg callable. It passes unless it returns ``False`` or
12
+ raises β€” so ``lambda: db.session.execute(text("SELECT 1"))`` is a valid check.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Callable, Mapping
18
+ from typing import TYPE_CHECKING
19
+
20
+ from flask import Blueprint, jsonify
21
+
22
+ if TYPE_CHECKING:
23
+ from flask.typing import ResponseReturnValue
24
+
25
+ # A readiness check: a zero-arg callable. Healthy unless it returns False or
26
+ # raises (a None/truthy return passes).
27
+ type Check = Callable[[], object]
28
+
29
+
30
+ def vitals(
31
+ *,
32
+ checks: Mapping[str, Check] | None = None,
33
+ version: str | None = None,
34
+ liveness_path: str = "/healthz",
35
+ readiness_path: str = "/readyz",
36
+ name: str = "vitals",
37
+ ) -> Blueprint:
38
+ """Build a health blueprint. Register it: ``app.register_blueprint(vitals(...))``."""
39
+ bp = Blueprint(name, __name__)
40
+ registered = dict(checks or {})
41
+
42
+ @bp.get(liveness_path)
43
+ def liveness() -> ResponseReturnValue:
44
+ body: dict[str, str] = {"status": "ok"}
45
+ if version is not None:
46
+ body["version"] = version
47
+ return jsonify(body), 200
48
+
49
+ @bp.get(readiness_path)
50
+ def readiness() -> ResponseReturnValue:
51
+ results: dict[str, bool] = {}
52
+ all_ok = True
53
+ for check_name, check in registered.items():
54
+ try:
55
+ passed = check() is not False # None/truthy β†’ pass
56
+ except Exception: # noqa: BLE001 - readiness must never raise
57
+ passed = False
58
+ results[check_name] = passed
59
+ all_ok = all_ok and passed
60
+ return jsonify({"ready": all_ok, "checks": results}), (200 if all_ok else 503)
61
+
62
+ return bp
File without changes