Quick start

Requirements

Python 3.12 or above
Django 4.2 or newer

Install

pip install maykin-config-checks

Add maykin_config_checks to the Django INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "maykin_config_checks",
    ...
]

Usage

Implementing checks

This library is based on the following components:

The HealthCheck which implements the logic of a particular configuration check.
The HealthCheckResult, which is the result of running a HealthCheck. It contains information about whether the check succeeded and additional information in case the check failed.
The run_checks(), which runs all the HealthCheck that are retrieved by a collector function and returns an iterable of HealthCheckResult.

You can see dummy implementations of all of these components below:

from collections.abc import Iterable
from dataclasses import asdict, dataclass

from maykin_config_checks import HealthCheck, HealthCheckResult, JSONValue


@dataclass
class DummyResult:
    success: bool
    identifier: str
    verbose_name: str
    message: str = ""
    extra: dict | None = None

    def to_builtins(self) -> JSONValue:
        return asdict(self)


class DummyCheck:
    identifier = "dummy"
    verbose_name = "Dummy"

    def __call__(self) -> HealthCheckResult:
        return DummyResult(
            success=True,
            verbose_name=self.verbose_name,
            identifier=self.identifier,
            message="Everything is great.",
        )


class DummyCheckFail:
    identifier = "dummy_fail"
    verbose_name = "Dummy fail"

    def __call__(self) -> HealthCheckResult:
        return DummyResult(
            success=False,
            verbose_name=self.verbose_name,
            identifier=self.identifier,
            message="Everything is sad.",
            extra={"info": "bla"},
        )


class CheckWithException:
    identifier = "check_with_exception"
    verbose_name = "Check with exception"

    def __call__(self) -> HealthCheckResult:
        raise Exception("HELLO EXCEPTION!")


def check_collector() -> Iterable[HealthCheck]:
    return [DummyCheck(), DummyCheckFail()]

View

To have an API view that returns the results of the performed health checks, add the following to the urlpatterns:

from django.contrib import admin
from django.urls import path

from maykin_config_checks.api.views import HealthChecksView
from testapp.checks import DummyCheck, DummyCheckFail

urlpatterns = [
    path("admin/", admin.site.urls),
    path(
        "health-checks",
        HealthChecksView.as_view(
            checks_collector=lambda: [DummyCheck(), DummyCheckFail()]
        ),
        name="health-checks",
    ),
]

Where the argument checks_collector is a Callable[[], Iterable[HealthCheck]]. It is used to retrieve which health checks should be performed by the view. You can also add the view multiple times to the urlpatters with different checks_collector arguments if you want to have multiple health check views that run different checks.

Management command

There is also a management command that can be used to run health checks from the CLI.

django-admin health_checks --checks-collector dotted.path.to.checks_collector_fn