Стиль кодирования

Пожалуйста, следуйте этим стандартам кодирования при написании кода для включения в 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 modulefrom 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):
    # ...

Стиль модели

  • Имена полей должны быть в нижнем регистре с использованием подчеркивания вместо 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 .

СОДЕРЖАНИЕ

Просматривать

Вы здесь:

Django Docs

Copyright ©2021 All rights reserved