nilva-django-logger 0.1.4__tar.gz

nilva_django_logger-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nilva
+
+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.

nilva_django_logger-0.1.4/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: nilva-django-logger
+Version: 0.1.4
+Summary: Nilva house logging for Django and Python services — structured JSON logs, colourful console, secret masking, request logging, health probes
+Author-email: Nilva <dev@nilva.ai>
+License-Expression: MIT
+Project-URL: homepage, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-logger
+Project-URL: repository, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-logger
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: django
+Requires-Dist: django>=6.0; extra == "django"
+Provides-Extra: jalali
+Requires-Dist: jdatetime>=4.1; extra == "jalali"
+Dynamic: license-file
+
+# nilva-django-logger
+
+The Nilva house logging toolkit — structured one-JSON-object-per-line logs
+(shipped by Filebeat), a colourful self-contained console formatter, secret
+masking, request/response logging middleware, Kubernetes health probes and
+probe-noise filtering.
+
+It consolidates the logging stack that grew across Nilva backends —
+`shahab-backend` (`shahab/log_formatter.py`, `settings/logging.py`,
+`settings/log_filter.py`, `health.py`, `banner.py`), `mymci-bubble-backend`
+(`core/log_formatter.py`, `core/middlewares/logger_middleware.py`) and the
+legacy `autoutils-log` / `django-autoutils` libraries — into one installable,
+tested package with **zero required dependencies**. Django and `jdatetime`
+are optional extras; the core works in any Python service.
+
+## Install
+
+```bash
+uv add nilva-django-logger[django,jalali]          # Django project
+uv add nilva-django-logger                         # plain-Python service
+```
+
+Or straight from GitLab while unpublished:
+
+```bash
+uv add "nilva-django-logger[django,jalali] @ git+ssh://git@gitlab.nilva.ai:2220/nilva/dev-assets/django/nilva-django-logger.git@develop"
+```
+
+## Quickstart (Django)
+
+```python
+# settings.py
+from nilva_django_logger import setup_logging
+
+LOGGING_CONFIG = None  # we configure logging ourselves
+setup_logging(
+    app_name="myapp",
+    log_dir=BASE_DIR / "log",   # /app/log in the container → tailed by Filebeat
+    log_name="myapp",
+)
+
+MIDDLEWARE = [
+    # ...
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "nilva_django_logger.middleware.RequestLoggerMiddleware",
+    # ...
+]
+```
+
+```python
+# urls.py
+from nilva_django_logger.health import health_urlpatterns
+
+urlpatterns = [
+    # ...
+    *health_urlpatterns(),   # /livez/ /readyz/ /startupz/
+]
+```
+
+No `INSTALLED_APPS` entry is needed — the package has no models, templates or
+signals.
+
+What you get:
+
+- **Console** — tidy coloured lines with Jalali timestamps (when `jdatetime`
+  is installed): `<dim ts> ● LEVEL <dim logger file:line> message`.
+- **`log/myapp.log`** — rotating (10 MB × 10) house-format JSON, one complete
+  object per line, `ensure_ascii=False` so Persian stays readable:
+
+  ```json
+  {"app_name": "myapp", "short_message": "...", "logger_data": {...}, "additional_data": {...}}
+  ```
+
+- **Request logging** — one structured line per request (method, path, status,
+  response time, user, client IP, view name, correlation id); on 4xx/5xx the
+  capped request/response bodies are attached for debugging. Health probes are
+  skipped entirely.
+- **Secret masking everywhere** — `Bearer`/`Basic` credentials,
+  `password=...` / `"token": "..."` pairs and `<password>` XML tags are
+  redacted in messages *and* inside `extra={...}` payloads before any handler
+  writes them.
+- **Quiet defaults** — `django.server` at WARNING (+ probe filter),
+  `PIL`/`urllib3`/`elasticsearch`/`kafka` tamed.
+
+### Enriching request logs from views
+
+```python
+from nilva_django_logger import set_log_data, set_log_message
+
+def play(request):
+    ...
+    set_log_message(request, "Play daily game")   # replaces the generic summary line
+    set_log_data(request, score=score)            # extra structured fields
+```
+
+### Dedicated flat request-log file (Fluentd/Grafana style)
+
+The Bubble backend ships a flat JSON document per API call (`panel.log`) for
+dashboards. Enable the same with:
+
+```python
+setup_logging(..., request_file=True)             # → log/myapp_request.log
+setup_logging(..., request_file="panel.log")      # custom name
+```
+
+### Kubernetes stdout mode
+
+When the platform scrapes container stdout instead of files (as Bubble does),
+ship JSON on the console and skip files entirely:
+
+```python
+setup_logging(app_name="myapp", console_json=True)
+```
+
+## Settings
+
+Everything can also be configured centrally via a `NILVA_LOGGER` dict in
+Django settings (the `nilva-django-auth` pattern; `@override_settings`
+reloads it in tests). Keyword arguments to `setup_logging()` /
+`build_logging_config()` win over `NILVA_LOGGER`, which wins over defaults.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `APP_NAME` | `None` | stamped on every JSON document |
+| `HOST_NAME` | `None` | `"auto"` → `socket.gethostname()` |
+| `LOG_DIR` | `None` | file logging directory (`None` = console only) |
+| `LOG_NAME` | `"app"` | `<LOG_NAME>.log` file name |
+| `MAX_BYTES` / `BACKUP_COUNT` | 10 MB / 10 | rotation (~110 MB ceiling per process) |
+| `ROOT_LEVEL` / `CONSOLE_LEVEL` / `FILE_LEVEL` | DEBUG / INFO / INFO | levels |
+| `REQUEST_LOGGER_NAME` | `"nilva_request"` | logger the middleware emits on (doesn't propagate to root) |
+| `MAX_BODY_LOG` | 4096 | cap on logged request/response bodies |
+| `LOG_BODIES_ON_ERROR` | `True` | attach bodies on 4xx/5xx |
+| `BASE_URL_PREFIX` | `""` | strip before ADMIN/API/OTHER classification |
+| `HEALTH_PROBE_PATHS` | `/livez/ /readyz/ /startupz/ /healthz` | skipped by request logging + `HealthProbeFilter` |
+| `MASK` | `"*****"` | replacement text |
+| `SENSITIVE_KEYS` | built-in set | extra-payload key names masked wholesale |
+| `EXTRA_MASK_PATTERNS` | `()` | additional regexes (group 1 = kept prefix) |
+| `MASK_EXTRAS` | `True` | also mask inside `extra={...}` values |
+| `JALALI_CONSOLE` | `True` | Jalali console timestamps when `jdatetime` present |
+
+**Config-time vs. runtime.** `NILVA_LOGGER` values are read live and honored
+once Django settings are configured. If you call `setup_logging()` at the
+bottom of `settings.py` (the usual place), Django is still mid-configuration at
+that moment, so handler/formatter options baked in right then — `APP_NAME`,
+`LOG_DIR`, levels, `MASK` — should be passed as `setup_logging()` **keyword
+arguments**. Middleware and request-time options (`HEALTH_PROBE_PATHS`,
+`BASE_URL_PREFIX`, `LOG_BODIES_ON_ERROR`, `MAX_BODY_LOG`) are read per request
+and honor `NILVA_LOGGER` directly.
+
+## Masking coverage
+
+`MaskSensitiveDataFilter` redacts secrets in the message text (`Bearer`/`Basic`
+credentials, `key=value` pairs and quoted `key: value` pairs in either quote
+style — including mixed quoting like `"password": 'x'` — and `<key>` XML tags;
+quoted values containing spaces are masked in full) **and** recursively
+inside `extra={...}` payloads (values under a sensitive key name are replaced
+wholesale; deeper-than-8 or cyclic structures fail closed to the mask). Because
+regexing serialized text is best-effort, **prefer structured `extra={...}`** for
+anything sensitive — that path masks by key and never depends on quoting.
+
+## Plain-Python (no Django)
+
+The formatters, filters and config builder are stdlib-only:
+
+```python
+import logging
+from nilva_django_logger import setup_logging
+
+setup_logging(app_name="worker", log_dir="/app/log", log_name="worker")
+logging.getLogger("worker").info("processed", extra={"job_id": 42})
+```
+
+Or hand-wire single pieces into an existing config:
+
+```python
+from nilva_django_logger import JsonFormatter, MaskSensitiveDataFilter
+```
+
+## Startup banner
+
+```python
+# gunicorn.conf.py
+def on_starting(server):
+    from nilva_django_logger import print_banner
+    print_banner(MYAPP_FIGLET, subtitle=f"gunicorn · {bind} · {workers} workers")
+```
+
+Generate the art once with `figlet -f "ANSI Shadow" MYAPP`.
+
+## Deployment conventions (Filebeat flow)
+
+- In the container the app lives at `/app`, so logs land in **`/app/log/*.log`**
+  where the Filebeat sidecar tails them. Pre-create the directory in the
+  Dockerfile **owned by the non-root runtime user**; `setup_logging` also
+  creates it on the fly for local runs and falls back to console-only if the
+  directory is unwritable (an unwritable log dir must never take the app down).
+- Add `log/` to `.gitignore` **and** `.dockerignore`.
+- Wire the probes into your Deployment (`livez` never touches the DB — a DB
+  outage must not restart pods; `readyz`/`startupz` check the DB).
+
+## Design notes
+
+- The house JSON shape (`short_message` / `logger_data` / `additional_data`)
+  comes from `autoutils-log`'s `BaseLogHandler`; `app_name`/`host_name` from
+  its handler kwargs and Bubble; the `exception` key, `ensure_ascii=False`
+  and the writable-dir fallback from Shahab.
+- Filebeat/ECS fields (`log`, `docker`, `host`, `container`, `ecs`, `agent`,
+  `stream`, `input`) are never re-emitted as `additional_data` (a Bubble
+  lesson — re-ingested lines double-enrich).
+- `autoutils-log`'s `LogstashHandler`/`KafkaHandler` (blocking network sends
+  per record) were deliberately **not** ported: the house flow is rotating
+  files + Filebeat. `ColorfulStreamHandler`'s `termcolor`/`pytz`/
+  `persiantools` dependencies are gone — ANSI codes and `jdatetime` (optional)
+  suffice.
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh            # pytest
+./run_tests.sh -c         # with coverage
+uv run ruff check .
+```

nilva_django_logger-0.1.4/README.md

@@ -0,0 +1,223 @@
+# nilva-django-logger
+
+The Nilva house logging toolkit — structured one-JSON-object-per-line logs
+(shipped by Filebeat), a colourful self-contained console formatter, secret
+masking, request/response logging middleware, Kubernetes health probes and
+probe-noise filtering.
+
+It consolidates the logging stack that grew across Nilva backends —
+`shahab-backend` (`shahab/log_formatter.py`, `settings/logging.py`,
+`settings/log_filter.py`, `health.py`, `banner.py`), `mymci-bubble-backend`
+(`core/log_formatter.py`, `core/middlewares/logger_middleware.py`) and the
+legacy `autoutils-log` / `django-autoutils` libraries — into one installable,
+tested package with **zero required dependencies**. Django and `jdatetime`
+are optional extras; the core works in any Python service.
+
+## Install
+
+```bash
+uv add nilva-django-logger[django,jalali]          # Django project
+uv add nilva-django-logger                         # plain-Python service
+```
+
+Or straight from GitLab while unpublished:
+
+```bash
+uv add "nilva-django-logger[django,jalali] @ git+ssh://git@gitlab.nilva.ai:2220/nilva/dev-assets/django/nilva-django-logger.git@develop"
+```
+
+## Quickstart (Django)
+
+```python
+# settings.py
+from nilva_django_logger import setup_logging
+
+LOGGING_CONFIG = None  # we configure logging ourselves
+setup_logging(
+    app_name="myapp",
+    log_dir=BASE_DIR / "log",   # /app/log in the container → tailed by Filebeat
+    log_name="myapp",
+)
+
+MIDDLEWARE = [
+    # ...
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "nilva_django_logger.middleware.RequestLoggerMiddleware",
+    # ...
+]
+```
+
+```python
+# urls.py
+from nilva_django_logger.health import health_urlpatterns
+
+urlpatterns = [
+    # ...
+    *health_urlpatterns(),   # /livez/ /readyz/ /startupz/
+]
+```
+
+No `INSTALLED_APPS` entry is needed — the package has no models, templates or
+signals.
+
+What you get:
+
+- **Console** — tidy coloured lines with Jalali timestamps (when `jdatetime`
+  is installed): `<dim ts> ● LEVEL <dim logger file:line> message`.
+- **`log/myapp.log`** — rotating (10 MB × 10) house-format JSON, one complete
+  object per line, `ensure_ascii=False` so Persian stays readable:
+
+  ```json
+  {"app_name": "myapp", "short_message": "...", "logger_data": {...}, "additional_data": {...}}
+  ```
+
+- **Request logging** — one structured line per request (method, path, status,
+  response time, user, client IP, view name, correlation id); on 4xx/5xx the
+  capped request/response bodies are attached for debugging. Health probes are
+  skipped entirely.
+- **Secret masking everywhere** — `Bearer`/`Basic` credentials,
+  `password=...` / `"token": "..."` pairs and `<password>` XML tags are
+  redacted in messages *and* inside `extra={...}` payloads before any handler
+  writes them.
+- **Quiet defaults** — `django.server` at WARNING (+ probe filter),
+  `PIL`/`urllib3`/`elasticsearch`/`kafka` tamed.
+
+### Enriching request logs from views
+
+```python
+from nilva_django_logger import set_log_data, set_log_message
+
+def play(request):
+    ...
+    set_log_message(request, "Play daily game")   # replaces the generic summary line
+    set_log_data(request, score=score)            # extra structured fields
+```
+
+### Dedicated flat request-log file (Fluentd/Grafana style)
+
+The Bubble backend ships a flat JSON document per API call (`panel.log`) for
+dashboards. Enable the same with:
+
+```python
+setup_logging(..., request_file=True)             # → log/myapp_request.log
+setup_logging(..., request_file="panel.log")      # custom name
+```
+
+### Kubernetes stdout mode
+
+When the platform scrapes container stdout instead of files (as Bubble does),
+ship JSON on the console and skip files entirely:
+
+```python
+setup_logging(app_name="myapp", console_json=True)
+```
+
+## Settings
+
+Everything can also be configured centrally via a `NILVA_LOGGER` dict in
+Django settings (the `nilva-django-auth` pattern; `@override_settings`
+reloads it in tests). Keyword arguments to `setup_logging()` /
+`build_logging_config()` win over `NILVA_LOGGER`, which wins over defaults.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `APP_NAME` | `None` | stamped on every JSON document |
+| `HOST_NAME` | `None` | `"auto"` → `socket.gethostname()` |
+| `LOG_DIR` | `None` | file logging directory (`None` = console only) |
+| `LOG_NAME` | `"app"` | `<LOG_NAME>.log` file name |
+| `MAX_BYTES` / `BACKUP_COUNT` | 10 MB / 10 | rotation (~110 MB ceiling per process) |
+| `ROOT_LEVEL` / `CONSOLE_LEVEL` / `FILE_LEVEL` | DEBUG / INFO / INFO | levels |
+| `REQUEST_LOGGER_NAME` | `"nilva_request"` | logger the middleware emits on (doesn't propagate to root) |
+| `MAX_BODY_LOG` | 4096 | cap on logged request/response bodies |
+| `LOG_BODIES_ON_ERROR` | `True` | attach bodies on 4xx/5xx |
+| `BASE_URL_PREFIX` | `""` | strip before ADMIN/API/OTHER classification |
+| `HEALTH_PROBE_PATHS` | `/livez/ /readyz/ /startupz/ /healthz` | skipped by request logging + `HealthProbeFilter` |
+| `MASK` | `"*****"` | replacement text |
+| `SENSITIVE_KEYS` | built-in set | extra-payload key names masked wholesale |
+| `EXTRA_MASK_PATTERNS` | `()` | additional regexes (group 1 = kept prefix) |
+| `MASK_EXTRAS` | `True` | also mask inside `extra={...}` values |
+| `JALALI_CONSOLE` | `True` | Jalali console timestamps when `jdatetime` present |
+
+**Config-time vs. runtime.** `NILVA_LOGGER` values are read live and honored
+once Django settings are configured. If you call `setup_logging()` at the
+bottom of `settings.py` (the usual place), Django is still mid-configuration at
+that moment, so handler/formatter options baked in right then — `APP_NAME`,
+`LOG_DIR`, levels, `MASK` — should be passed as `setup_logging()` **keyword
+arguments**. Middleware and request-time options (`HEALTH_PROBE_PATHS`,
+`BASE_URL_PREFIX`, `LOG_BODIES_ON_ERROR`, `MAX_BODY_LOG`) are read per request
+and honor `NILVA_LOGGER` directly.
+
+## Masking coverage
+
+`MaskSensitiveDataFilter` redacts secrets in the message text (`Bearer`/`Basic`
+credentials, `key=value` pairs and quoted `key: value` pairs in either quote
+style — including mixed quoting like `"password": 'x'` — and `<key>` XML tags;
+quoted values containing spaces are masked in full) **and** recursively
+inside `extra={...}` payloads (values under a sensitive key name are replaced
+wholesale; deeper-than-8 or cyclic structures fail closed to the mask). Because
+regexing serialized text is best-effort, **prefer structured `extra={...}`** for
+anything sensitive — that path masks by key and never depends on quoting.
+
+## Plain-Python (no Django)
+
+The formatters, filters and config builder are stdlib-only:
+
+```python
+import logging
+from nilva_django_logger import setup_logging
+
+setup_logging(app_name="worker", log_dir="/app/log", log_name="worker")
+logging.getLogger("worker").info("processed", extra={"job_id": 42})
+```
+
+Or hand-wire single pieces into an existing config:
+
+```python
+from nilva_django_logger import JsonFormatter, MaskSensitiveDataFilter
+```
+
+## Startup banner
+
+```python
+# gunicorn.conf.py
+def on_starting(server):
+    from nilva_django_logger import print_banner
+    print_banner(MYAPP_FIGLET, subtitle=f"gunicorn · {bind} · {workers} workers")
+```
+
+Generate the art once with `figlet -f "ANSI Shadow" MYAPP`.
+
+## Deployment conventions (Filebeat flow)
+
+- In the container the app lives at `/app`, so logs land in **`/app/log/*.log`**
+  where the Filebeat sidecar tails them. Pre-create the directory in the
+  Dockerfile **owned by the non-root runtime user**; `setup_logging` also
+  creates it on the fly for local runs and falls back to console-only if the
+  directory is unwritable (an unwritable log dir must never take the app down).
+- Add `log/` to `.gitignore` **and** `.dockerignore`.
+- Wire the probes into your Deployment (`livez` never touches the DB — a DB
+  outage must not restart pods; `readyz`/`startupz` check the DB).
+
+## Design notes
+
+- The house JSON shape (`short_message` / `logger_data` / `additional_data`)
+  comes from `autoutils-log`'s `BaseLogHandler`; `app_name`/`host_name` from
+  its handler kwargs and Bubble; the `exception` key, `ensure_ascii=False`
+  and the writable-dir fallback from Shahab.
+- Filebeat/ECS fields (`log`, `docker`, `host`, `container`, `ecs`, `agent`,
+  `stream`, `input`) are never re-emitted as `additional_data` (a Bubble
+  lesson — re-ingested lines double-enrich).
+- `autoutils-log`'s `LogstashHandler`/`KafkaHandler` (blocking network sends
+  per record) were deliberately **not** ported: the house flow is rotating
+  files + Filebeat. `ColorfulStreamHandler`'s `termcolor`/`pytz`/
+  `persiantools` dependencies are gone — ANSI codes and `jdatetime` (optional)
+  suffice.
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh            # pytest
+./run_tests.sh -c         # with coverage
+uv run ruff check .
+```

nilva_django_logger-0.1.4/nilva_django_logger/__init__.py

@@ -0,0 +1,59 @@
+"""Nilva Django Logger — the Nilva house logging toolkit.
+
+Structured one-JSON-object-per-line logs (shipped by Filebeat), a colourful
+self-contained console formatter, secret masking, request/response logging
+middleware, Kubernetes health probes and probe-noise filtering.
+
+The core (formatters, filters, config builder, banner) is pure standard
+library and works in any Python service; the Django pieces (middleware,
+health views, ``NILVA_LOGGER`` settings) load lazily so importing this
+package never requires Django.
+"""
+
+__version__ = "0.1.4"
+
+from .banner import print_banner, render_banner
+from .config import build_logging_config, setup_logging
+from .filters import HealthProbeFilter, MaskSensitiveDataFilter
+from .formatters import ColorfulFormatter, JsonFormatter, RequestJsonFormatter
+from .settings import logger_settings
+
+#: Django-only exports, resolved lazily so ``import nilva_django_logger``
+#: works in plain-Python services without Django installed.
+_DJANGO_EXPORTS = {
+    "RequestLoggerMiddleware": "middleware",
+    "set_log_message": "middleware",
+    "set_log_data": "middleware",
+    "get_client_ip": "middleware",
+    "livez": "health",
+    "readyz": "health",
+    "startupz": "health",
+    "health_urlpatterns": "health",
+}
+
+__all__ = [
+    "__version__",
+    "JsonFormatter",
+    "ColorfulFormatter",
+    "RequestJsonFormatter",
+    "MaskSensitiveDataFilter",
+    "HealthProbeFilter",
+    "build_logging_config",
+    "setup_logging",
+    "render_banner",
+    "print_banner",
+    "logger_settings",
+    *_DJANGO_EXPORTS,
+]
+
+
+def __getattr__(name):
+    module_name = _DJANGO_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    module = import_module(f".{module_name}", __name__)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

nilva_django_logger-0.1.4/nilva_django_logger/banner.py

@@ -0,0 +1,58 @@
+"""Startup banner — print big ASCII art to the terminal when the server boots.
+
+Give it your project's figlet (``figlet -f "ANSI Shadow" MYAPP``) and wire it
+into gunicorn's ``on_starting`` hook (``gunicorn.conf.py``) so it shows once,
+in the terminal / container logs, right as the project comes up::
+
+    # gunicorn.conf.py
+    def on_starting(server):
+        from myapp.art import ART  # the figlet string
+        from nilva_django_logger import print_banner
+
+        print_banner(ART, subtitle=f"gunicorn · {bind} · {workers} workers")
+"""
+
+from __future__ import annotations
+
+import sys
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+
+_COLORS = {
+    "cyan": "\033[36m",
+    "magenta": "\033[35m",
+    "yellow": "\033[33m",
+    "green": "\033[32m",
+    "blue": "\033[34m",
+    "red": "\033[31m",
+    "white": "\033[37m",
+}
+
+
+def render_banner(
+    art: str,
+    subtitle: str | None = None,
+    *,
+    color: str = "cyan",
+    use_colors: bool = True,
+) -> str:
+    """Return the coloured banner (+ optional dimmed subtitle line)."""
+    art = art.strip("\n")
+    lines = []
+    if use_colors:
+        lines.append(f"{_BOLD}{_COLORS.get(color, _COLORS['cyan'])}{art}{_RESET}")
+        if subtitle:
+            lines.append(f"{_DIM}  {subtitle}{_RESET}")
+    else:
+        lines.append(art)
+        if subtitle:
+            lines.append(f"  {subtitle}")
+    return "\n".join(lines)
+
+
+def print_banner(art: str, subtitle: str | None = None, **kwargs) -> None:
+    """Print the banner to stdout (the terminal / container log)."""
+    sys.stdout.write("\n" + render_banner(art, subtitle, **kwargs) + "\n\n")
+    sys.stdout.flush()