Фреймворк системных проверок

Сообщения

Функция должна возвращать список сообщений. Если проверка не обнаружила проблем, функция проверки должна возвращать пустой список.

Предупреждения и ошибки, выдаваемые методом проверки, должны быть экземплярами CheckMessage. Экземпляр CheckMessage содержит одно сообщение об ошибке или предупреждении. Он также предоставляет контекст и рекомендации, относящиеся к сообщению, а также уникальный идентификатор, используемый для фильтрации.

Эта концепция очень похожа на сообщения из фреймворка сообщений или фреймворка журналирования. Сообщения помечаются level, указывающим на их уровень важности.

Также существуют сокращённые варианты, упрощающие создание сообщений с распространёнными уровнями важности. При использовании этих классов аргумент level можно опустить, поскольку его значение определяется именем класса.

• Debug
• Info
• Warning
• Error
• Critical

Регистрация проверок и присвоение им меток

Наконец, функцию проверки необходимо явно зарегистрировать в реестре системных проверок. Проверки следует регистрировать в файле, который загружается вместе с приложением; например, в методе AppConfig.ready().

register(*tags)(function)

Вы можете передать register любое количество меток, чтобы пометить проверку. Метки полезны, поскольку позволяют запускать только определённую группу проверок. Например, чтобы зарегистрировать проверку совместимости, выполните следующий вызов:

from django.core.checks import register, Tags


@register(Tags.compatibility)
def my_check(app_configs, **kwargs):
    # ... perform compatibility checks and collect errors
    return errors

Можно зарегистрировать «проверки развертывания», актуальные только для файла настроек производственной среды, следующим образом:

@register(Tags.security, deploy=True)
def my_check(app_configs, **kwargs): ...

Эти проверки будут выполняться, только если используется параметр check --deploy.

Вместо декоратора можно использовать register как функцию, передав вызываемый объект (обычно функцию) первым аргументом в register.

Приведённый ниже код эквивалентен коду выше:

def my_check(app_configs, **kwargs): ...


register(my_check, Tags.security, deploy=True)

Проверки полей, ограничений, моделей, менеджеров, шаблонизаторов, задач и баз данных

В некоторых случаях регистрировать функцию проверки не нужно — можно воспользоваться уже существующей регистрацией.

Поля, ограничения, модели, менеджеры моделей, шаблонизаторы, бэкенды задач и бэкенды баз данных реализуют метод check(), уже зарегистрированный во фреймворке проверок. Чтобы добавить дополнительные проверки, расширьте реализацию в базовом классе, выполните все необходимые дополнительные проверки и добавьте полученные сообщения к сообщениям, сформированным базовым классом. Рекомендуется выносить каждую проверку в отдельный метод.

Рассмотрим пример реализации пользовательского поля с именем RangedIntegerField. Это поле добавляет аргументы min и max в конструктор IntegerField. Возможно, вы захотите добавить проверку, гарантирующую, что пользователи указывают минимальное значение, меньшее или равное максимальному. Следующий фрагмент кода показывает, как реализовать эту проверку:

from django.core import checks
from django.db import models


class RangedIntegerField(models.IntegerField):
    def __init__(self, min=None, max=None, **kwargs):
        super().__init__(**kwargs)
        self.min = min
        self.max = max

    def check(self, **kwargs):
        # Call the superclass
        errors = super().check(**kwargs)

        # Do some custom checks and add messages to `errors`:
        errors.extend(self._check_min_max_values(**kwargs))

        # Return all errors and warnings
        return errors

    def _check_min_max_values(self, **kwargs):
        if self.min is not None and self.max is not None and self.min > self.max:
            return [
                checks.Error(
                    "min greater than max.",
                    hint="Decrease min or increase max.",
                    obj=self,
                    id="myapp.E001",
                )
            ]
        # When no error, return an empty list
        return []

Чтобы добавить проверки для менеджера модели, выполните те же действия в подклассе Manager.

Чтобы добавить проверку для класса модели, подход почти тот же: единственное отличие в том, что проверка является методом класса, а не методом экземпляра:

class MyModel(models.Model):
    @classmethod
    def check(cls, **kwargs):
        errors = super().check(**kwargs)
        # ... your own checks ...
        return errors

Написание тестов

Объекты сообщений можно сравнивать. Это позволяет легко писать тесты:

from django.core.checks import Error

errors = checked_object.check()
expected_errors = [
    Error(
        "an error",
        hint="A hint.",
        obj=checked_object,
        id="myapp.E001",
    )
]
self.assertEqual(errors, expected_errors)

from django.core.management import call_command
from django.core.management.base import SystemCheckError
from django.test import SimpleTestCase, modify_settings, override_settings


class SystemCheckIntegrationTest(SimpleTestCase):
    @override_settings(SITE_ID="non_integer")
    @modify_settings(INSTALLED_APPS={"prepend": "django.contrib.sites"})
    def test_non_integer_site_id(self):
        message = "(sites.E101) The SITE_ID setting must be an integer."
        with self.assertRaisesMessage(SystemCheckError, message):
            call_command("check")

from django.conf import settings
from django.core.checks import Warning, register


@register("myapp", deploy=True)
def check_enable_analytics_is_true_on_deploy(app_configs, **kwargs):
    errors = []
    if getattr(settings, "ENABLE_ANALYTICS", None) is not True:
        errors.append(
            Warning(
                "The ENABLE_ANALYTICS setting should be set to True in deployment.",
                id="myapp.W001",
            )
        )
    return errors

from io import StringIO

from django.core.management import call_command
from django.test import SimpleTestCase, override_settings


class EnableAnalyticsDeploymentCheckTest(SimpleTestCase):
    @override_settings(ENABLE_ANALYTICS=None)
    def test_when_set_to_none(self):
        stderr = StringIO()
        call_command("check", "-t", "myapp", "--deploy", stderr=stderr)
        message = (
            "(myapp.W001) The ENABLE_ANALYTICS setting should be set "
            "to True in deployment."
        )
        self.assertIn(message, stderr.getvalue())