Стиль кода ¶
При написании кода, предназначенного для использования в составе 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 пробелами. Добавьте последнюю запятую после последнего импорта и поместите закрывающую скобку в отдельной строке.
Поместите одну пустую строку между последним импортом и любым кодом уровня модуля и поместите две пустые строки над первой функцией или классом.
Например (комментарии носят информационный характер):
# 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 .