Система проверки системы

Система проверки системы — это набор статических проверок для валидации проектов Django. Она обнаруживает распространённые проблемы и предоставляет подсказки по их исправлению. Система расширяема, поэтому вы можете легко добавить свои собственные проверки.

Проверки могут быть вызваны явно с помощью команды check. Проверки вызываются неявно перед большинством команд, включая runserver и migrate. По соображениям производительности проверки не выполняются как часть стека WSGI, используемого при развертывании. Если вам нужно выполнить проверки системы на сервере развертывания, вызовите их явно с помощью check.

Серьёзные ошибки помешают запуску команд Django (таких как runserver) вообще. Незначительные проблемы сообщаются в консоль. Если вы проверили причину предупреждения и можете его игнорировать, вы можете скрыть определённые предупреждения, используя настройку SILENCED_SYSTEM_CHECKS в файле настроек проекта.

Полный список всех проверок, которые могут быть подняты Django, можно найти в Справочнике по проверке системы.

Создание собственных проверок

Система гибкая и позволяет вам создавать функции, которые выполняют любой другой тип проверки, который вам может потребоваться. Ниже приведён пример функции-заглушки проверки:

from django.core.checks import Error, register


@register()
def example_check(app_configs, **kwargs):
    errors = []
    # ... your check logic here
    if check_failed:
        errors.append(
            Error(
                "an error",
                hint="A hint.",
                obj=checked_object,
                id="myapp.E001",
            )
        )
    return errors

Функция проверки должна принимать аргумент app_configs; этот аргумент — список приложений, которые следует проверить. Если None, проверка должна выполняться на всех установленных приложениях в проекте.

Проверка получит ключевой аргумент databases. Это список псевдонимов баз данных, соединения с которыми можно использовать для проверки конфигурации на уровне базы данных. Если databases равно None, проверка не должна использовать соединения с базами данных.

Аргумент **kwargs необходим для дальнейшего расширения.

Сообщения

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

Предупреждения и ошибки, поднятые методом проверки, должны быть экземплярами 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)