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

Система проверки фреймворка — это набор статических проверок для валидации проектов 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)