Рекомендации по программированию на Python

PEP8

Мы просим, чтобы все contributions на Python соответствовали руководству по стилю PEP8. Все файлы должны быть отформатированы с помощью автоформатера black. Это будет запущено pre-commit при соответствующей настройке.

• В репозитории проекта есть файл .editorconfig. Рекомендуется использовать текстовый редактор с поддержкой EditorConfig, чтобы избежать проблем с отступами и пробелами. Python и HTML-файлы используют 4 пробела для отступов.

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

Вы можете запустить форматирование всего Python с помощью make format. Подобно линтеру, вы можете отформатировать только python/template файлы, запустив make format-server.

Совместимость с 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, пожалуйста, включите дополнительные тесты для её покрытия; если ваши изменения изменяют существующую функциональность, пожалуйста, обновите соответствующие тесты.