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

Система проверки фреймворка — это набор статических проверок для валидации проектов 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, проверка должна выполняться на всех установленных приложениях в проекте. Аргумент **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)