Рекомендации по написанию кода на Python

PEP8

Мы просим, чтобы все вклады в Python соответствовали руководству стилей PEP8, за исключением ограничения длины строки (E501) и некоторых незначительных проблем, связанных с документацией. Список нарушений PEP8, которые можно игнорировать, находится в файле setup.cfg в заголовке [flake8]. Возможно, вам потребуется настроить линтер flake8 в вашем редакторе/IDE для использования конфигурации в этом файле.

Кроме того, строки импорта должны быть отсортированы в соответствии с правилами isort 5.6.4. Если вы установили зависимости для тестирования Wagtail (pip install -e .[testing]), вы можете проверить свой код, выполнив make lint.

Совместимость с Django

Wagtail разработан для совместимости с несколькими версиями Django. Иногда это требует выполнения одного фрагмента кода для последних версий Django и другого фрагмента кода для более старых версий Django. В этих случаях всегда проверяйте, какая версия Django используется, просматривая django.VERSION:

import django

if django.VERSION >= (1, 9):
    # Use new attribute
    related_field = field.rel
else:
    # Use old, deprecated attribute
    related_field = field.related

Всегда сравнивайте с версией, используя оператор больше или равно (>=), чтобы код для более новых версий Django обрабатывался в первую очередь.

Не используйте try ... except при проверке, имеет ли объект атрибут или метод, введённый в более новых версиях Django, так как это не ясно выражает, почему используется try ... except. Явная проверка версии Django делает намерение кода очень ясным.

# Do not do this
try:
    related_field = field.rel
except AttributeError:
    related_field = field.related

Если код должен использовать что-то, что менялось во многих версиях Django, подумайте о создании функции, которая будет оборачивать проверку:

import django

def related_field(field):
    if django.VERSION >= (1, 9):
        return field.rel
    else:
        return field.related

Если Django ввёл новую функцию, которая, по вашему мнению, была бы очень полезна для Wagtail, но она недоступна в более старых версиях Django, поддерживаемых Wagtail, эту функцию можно скопировать в Wagtail. Если пользователь использует новую версию Django, которая имеет эту функцию, функцию следует импортировать из Django. В противном случае следует использовать версию, включённую в Wagtail. Должен быть включён ссылка на исходный код Django, откуда была взята эта функция:

import django

if django.VERSION >= (1, 9):
    from django.core.validators import validate_unicode_slug
else:
    # Taken from https://github.com/django/django/blob/1.9/django/core/validators.py#L230
    def validate_unicode_slug(value):
        # Code left as an exercise to the reader
        pass

Тесты

Wagtail имеет набор тестов, которые мы стремимся улучшать и расширять. См. Тестирование.

Мы выполняем непрерывную интеграцию, чтобы убедиться, что ни один коммит или запрос на вытягивание не приводит к сбоям тестов. Если ваши изменения добавляют функциональность в Wagtail, включите дополнительные тесты для её проверки; если ваши изменения изменяют существующую функциональность, соответствующим образом обновите соответствующие тесты.