Руководство по программированию на Python

PEP8

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