Стиль кодирования ¶
Пожалуйста, следуйте этим стандартам кодирования при написании кода для включения в Django.
Проверки перед фиксацией ¶
pre-commit - это структура для управления обработчиками pre-commit. Эти хуки помогают выявить простые проблемы, прежде чем передавать код на проверку. Проверка этих проблем перед проверкой кода позволяет рецензенту сосредоточиться на самом изменении, а также может помочь уменьшить количество запусков CI.
Чтобы использовать инструмент, сначала установите, pre-commit
а затем перехватчики git:
$ python -m pip install pre-commit
$ pre-commit install
... \> py -m pip install pre-commit
... \> pre-commit install
При первом коммите pre-commit
будут установлены хуки, они устанавливаются в их собственных средах, и их установка займет некоторое время при первом запуске. Последующие проверки будут проходить значительно быстрее. Если ошибка обнаружена, отобразится соответствующее сообщение об ошибке. Если ошибка isort
возникла, инструмент исправит их за вас. Просмотрите изменения и выполните повторную фиксацию, если они вас устраивают.
Стиль 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.Используйте четыре пробела для отступа.
Используйте четыре отступа для подвешивания вместо вертикального выравнивания:
raise AttributeError( 'Here is a multiline error message ' 'shortened for clarity.' )
Вместо:
raise AttributeError('Here is a multiline error message ' 'shortened for clarity.')
Это позволяет лучше использовать пространство и позволяет избежать повторного выравнивания строк при изменении длины первой строки.
Используйте одинарные кавычки для строк или двойные кавычки, если строка содержит одинарные кавычки. Не тратьте время на несвязанный рефакторинг существующего кода, чтобы он соответствовал этому стилю.
Интерполяция строковых переменных может использовать % -форматирование , f-строки или,
str.format()
при необходимости, с целью максимальной читабельности кода.Окончательное решение о удобочитаемости остается на усмотрение Слияния. В качестве руководства, f-строки должны использовать только простой доступ к переменным и свойствам с предварительным назначением локальной переменной для более сложных случаев:
# Allowed f'hello {user}' f'hello {user.name}' f'hello {self.user.name}' # Disallowed f'hello {get_user()}' f'you are {user.age * 365.25} days old' # Allowed with local variable assignment user = get_user() f'hello {user}' user_days_old = user.age * 365.25 f'you are {user_days_old} days old'
f-строки не должны использоваться для каких-либо строк, которые могут потребовать перевода, включая сообщения об ошибках и журнальные сообщения. В целом
format()
более подробный, поэтому предпочтительны другие методы форматирования.Не тратьте время на несвязанный рефакторинг существующего кода для корректировки метода форматирования.
Избегайте использования «мы» в комментариях, например «Зацикливаемся», а не «Зацикливаемся».
Используйте символы подчеркивания, а не 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 >= 5.1.0 $ isort -rc .
... \> py -m pip install isort > = 5.1.0 ... \> isort -rc.
Это выполняется
isort
рекурсивно из вашего текущего каталога, изменяя любые файлы, которые не соответствуют рекомендациям. Если вам нужно, чтобы импорт был неупорядоченным (например, чтобы избежать циклического импорта), используйте следующий комментарий:import module # isort:skip
Поместите импорт в эти группы: future, стандартная библиотека, сторонние библиотеки, другие компоненты Django, локальный компонент Django, try / excepts. Отсортируйте строки в каждой группе в алфавитном порядке по полному имени модуля. Поместите все утверждения перед в каждом разделе. Используйте абсолютный импорт для других компонентов 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): # ...
Стиль модели ¶
Имена полей должны быть в нижнем регистре с использованием подчеркивания вместо camelCase.
Сделай это:
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)
… Затем импорт этого модуля приведет к настройке объекта настроек. Это означает, что возможность импортировать модуль на верхнем уровне третьими сторонами несовместима с возможностью настройки объекта настроек вручную или в некоторых случаях делает ее очень сложной.
Вместо приведенного выше кода необходимо использовать уровень лени или косвенного обращения, например django.utils.functional.LazyObject
,
django.utils.functional.lazy()
или lambda
.
Разное ¶
- Отметить все строки для интернационализации; подробности см. в документации i18n .
- Удалите
import
операторы, которые больше не используются, при изменении кода. flake8 определит этот импорт для вас. Если неиспользуемый импорт должен остаться для обратной совместимости, отметьте конец с помощью, чтобы отключить предупреждение flake8.# NOQA
- Систематически удаляйте все конечные пробелы из вашего кода, поскольку они добавляют ненужные байты, добавляют визуальный беспорядок к исправлениям, а также могут иногда вызывать ненужные конфликты слияния. Некоторые IDE можно настроить так, чтобы они автоматически удалялись, а большинство инструментов VCS можно настроить так, чтобы выделять их в выходных данных diff.
- Пожалуйста, не указывайте свое имя в коде, который вы размещаете. Наша политика заключается в том, чтобы имена участников оставались в
AUTHORS
файле, распространяемом с Django, а не разбросаны по всей кодовой базе. Не стесняйтесь включать изменениеAUTHORS
файла в свой патч, если вы вносите более одного тривиального изменения.
Стиль JavaScript ¶
Подробнее о стиле кода JavaScript, используемом Django, см . В разделе JavaScript .