Стиль кода

При написании кода, предназначенного для использования в составе Django, придерживайтесь этих стандартов кодирования.

Стиль Python

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

  • За особыми исключениями соблюдайте рекомендации PEP 8 .

    Используйте flake8 для обнаружения подобных проблем. Обратите внимание, что наш файл setup.cfg содержит исключение определенных файлов (устаревшие модули, которые не нужно было бы исправлять, и некоторый код внешнего происхождения, который включает Django), а также исключение определенных проверок ошибок, которые мы не считаем серьезные нарушения. Помни этоPEP 8 - это только руководство, основная цель - соблюдение стиля окружающего кода.

    Исключение из PEP 8 - это наши правила в отношении длины строк. Не ограничивайте строки кода 79 символами, если это означает, что код выглядит значительно уродливее или его труднее читать. Мы допускаем до 119 символов, так как это ширина обзора кода GitHub; все, что длиннее, требует горизонтальной прокрутки, что затрудняет просмотр. Эта проверка включается при запускеflake8 . Документация, комментарии и строки документации должны быть заключены в 79 символов, даже если PEP 8 предлагает 72.

  • Используйте 4 пробела для отступа.

  • Используйте четыре отступа для подвешивания вместо вертикального выравнивания:

    raise AttributeError(
        'Here is a multiline error message '
        'shortened for clarity.'
    )
    

    Вместо того :

    raise AttributeError('Here is a multiline error message '
                         'shortened for clarity.')
    

    Это улучшает использование пространства и позволяет избежать необходимости изменять выравнивание строк при изменении длины первой строки.

  • Используйте одинарные кавычки для строк или двойные кавычки, если сама строка содержит одинарные кавычки. Не тратьте время на преобразование существующего кода, не связанного с текущим изменением, в соответствии с этим стилем.

  • Избегайте использования «мы» в комментариях, например. «Зацикливаемся», а не «Зацикливаемся».

  • Используйте символы подчеркивания, а не camelCase, для имен переменных, функций и методов (т. Е. poll.get_unique_voters() Не poll.getUniqueVoters() ).

  • Используйте InitialCaps для имен классов (или для заводских функций, возвращающих классы).

  • В строках документации следуйте стилю существующих строк документации и PEP 257 .

  • В тестах используйте assertRaisesMessage() и assertWarnsMessage() вместо assertRaises() и, assertWarns() чтобы вы могли проверить сообщение об исключении или предупреждении. Используйте assertRaisesRegex() и assertWarnsRegex() только в том случае, если вам нужно сопоставление регулярных выражений.

    Используйте для проверки логических значений, а не и , чтобы вы могли проверить фактическое логическое значение, а не истинность выражения.assertIs(…, True/False) assertTrue() assertFalse()

  • В тестовых строках документации укажите ожидаемое поведение, которое демонстрирует каждый тест. Не включайте такие преамбулы, как «Проверяет, что» или «Обеспечивает это».

    Зарезервируйте ссылки на билеты для неясных проблем, когда в билетах есть дополнительные сведения, которые сложно описать в строках документации или комментариях. Включите номер билета в конце такого предложения:

    def test_foo():
        """
        A test docstring looks like this (#123456).
        """
        ...
    

Импорт

  • Используйте isort для автоматизации сортировки импорта, следуя приведенным ниже инструкциям.

    Чтобы быть быстрым:

    $ python -m pip install isort
    $ isort -rc .
    
    ...\> py -m pip install isort
    ...\> isort -rc .
    

    Это выполняется isort рекурсивно из текущего каталога, изменяя любые файлы, которые не соответствуют директивам. Если необходимо иметь несортированный импорт (например, чтобы избежать циклического импорта), используйте такой комментарий

    import module  # isort:skip
    
  • Поместите импорты в эти группы: future, стандартная библиотека, сторонние библиотеки, другие компоненты Django, локальный компонент Django, инструкции try / except. Отсортируйте строки каждой группы в алфавитном порядке в соответствии с полным названием модуля. В каждом разделе помещайте все операторы перед операторами типа . Используйте абсолютный импорт для других компонентов Django и относительный импорт для локальных компонентов.import module from module import objects

  • В каждой строке отсортируйте элементы в алфавитном порядке, сгруппировав имена в верхнем регистре перед именами в нижнем регистре.

  • Разделите длинные строки круглыми скобками и сделайте отступ для строк продолжения 4 пробелами. Добавьте последнюю запятую после последнего импорта и поместите закрывающую скобку в отдельной строке.

    Поместите одну пустую строку между последним импортом и любым кодом уровня модуля и поместите две пустые строки над первой функцией или классом.

    Например (комментарии носят информационный характер):

    django / contrib / admin / example.py
    # future
    from __future__ import unicode_literals
    
    # standard library
    import json
    from itertools import chain
    
    # third-party
    import bcrypt
    
    # Django
    from django.http import Http404
    from django.http.response import (
        Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse,
        cookie,
    )
    
    # local Django
    from .models import LogEntry
    
    # try/except
    try:
        import yaml
    except ImportError:
        yaml = None
    
    CONSTANT = 'foo'
    
    
    class Example:
        # ...
    
  • Если возможно, используйте самый прямой импорт

    from django.views import View
    

    вместо того

    from django.views.generic.base import View
    

Стиль шаблонов

  • В коде шаблонов Django поместите один и только один пробел между фигурными скобками и содержимым тегов.

    Делать:

    {{ foo }}
    

    Не делай :

    {{foo}}
    

Стиль просмотра

  • В представлениях Django должен вызываться первый параметр представления функции request .

    Делать

    def my_view(request, foo):
        # ...
    

    Не делай :

    def my_view(req, foo):
        # ...
    

Стиль моделей

  • Имена полей должны быть в нижнем регистре с использованием подчеркивания вместо CamelStyle.

    Делать

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    

    Не делай :

    class Person(models.Model):
        FirstName = models.CharField(max_length=20)
        Last_Name = models.CharField(max_length=40)
    
  • Знак должен появиться после определений полей, с одной пустой строкой, разделяющей поля определения класса.class Meta

    Делать

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    
        class Meta:
            verbose_name_plural = 'people'
    

    Не делай :

    class Person(models.Model):
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
        class Meta:
            verbose_name_plural = 'people'
    

    Не делайте этого тоже:

    class Person(models.Model):
        class Meta:
            verbose_name_plural = 'people'
    
        first_name = models.CharField(max_length=20)
        last_name = models.CharField(max_length=40)
    
  • Порядок внутренних классов моделей и стандартных методов должен быть следующим (обратите внимание, что не все из них являются обязательными):

    • Все поля в базе
    • Настраиваемые атрибуты менеджера
    • class Meta
    • def __str__()
    • def save()
    • def get_absolute_url()
    • Любой другой индивидуальный метод
  • Если choices определено для поля шаблона, определите каждый вариант как список кортежей с именем, написанным только в верхнем регистре, в качестве атрибута класса шаблона. пример

    class MyModel(models.Model):
        DIRECTION_UP = 'U'
        DIRECTION_DOWN = 'D'
        DIRECTION_CHOICES = [
            (DIRECTION_UP, 'Up'),
            (DIRECTION_DOWN, 'Down'),
        ]
    

Используя django.conf.settings

Модули обычно не должны использовать настройки, хранящиеся на django.conf.settings их первом уровне (то есть оцениваемые при импорте модуля). Вот почему:

Ручная настройка параметров (т.е. не полагаясь на DJANGO_SETTINGS_MODULE переменная окружения) допускается и возможно следующим образом:

from django.conf import settings

settings.configure({}, SOME_SETTING='foo')

Однако, если параметр доступен до линии settings.configure , это не будет работать (внутренне, settings это один , LazyObject который настраивается автоматически , когда доступ к настройкам , если это не было сделано ранее).

Итак, если модуль содержит такой код

from django.conf import settings
from django.urls import get_callable

default_foo_view = get_callable(settings.FOO_VIEW)

… Затем импорт этого модуля приведет к настройке объекта settings . Это означает, что возможность импорта модуля на первом уровне из внешнего кода несовместима с возможностью вручную настраивать объект settings или делает это очень трудным при определенных обстоятельствах.

Вместо приведенного выше кода следует добавить уровень различия или косвенного обращения, например django.utils.functional.LazyObject , django.utils.functional.lazy() или lambda .

Разное

  • Отметьте все строки для перевода; см. документацию i18n для более подробной информации.
  • Удалите операторы import , которые больше не используются, при редактировании кода. flake8 может идентифицировать этот импорт для вас. Если неиспользуемый импорт необходимо оставить для совместимости, поместите комментарий в конце строки, чтобы вы не промолчали.# NOQA flake8
  • Всегда удаляйте все пустые места в конце строки в коде, потому что они добавляют символы без необходимости, создают визуальный беспорядок в исправлениях, а также могут иногда вызывать ненужные конфликты слияния. Некоторые среды разработки могут быть настроены на их автоматическое удаление, а большинство инструментов управления версиями можно настроить так, чтобы они выделялись на дисплеях различий.
  • Не пишите свое имя в генерируемом вами коде. Наша политика заключается в том, чтобы помещать имена участников в файл, AUTHORS распространяемый с Django, вместо того, чтобы распространять их по всему коду. Возьмите на себя смелость включить свое имя в этот файл AUTHORS в свой патч, если вы делаете больше, чем просто тривиальное редактирование.

Стиль JavaScript

Дополнительные сведения о стиле кода JavaScript, используемом Django, см . В разделе JavaScript .

Copyright ©2020 All rights reserved