Приложения

Для авторов приложений

Если вы создаете подключаемое приложение под названием «Rock ’n’ roll», вот как можно задать подходящее название для административного интерфейса:

# rock_n_roll/apps.py

from django.apps import AppConfig


class RockNRollConfig(AppConfig):
    name = "rock_n_roll"
    verbose_name = "Rock ’n’ roll"

RockNRollConfig будет загружен автоматически, если INSTALLED_APPS содержит 'rock_n_roll'. Чтобы предотвратить это, установите default в значение False в определении класса.

Можно предоставить несколько подклассов AppConfig с различным поведением. Чтобы указать Django, какой из них использовать по умолчанию, установите default в значение True в его определении. Если пользователи захотят выбрать конфигурацию не по умолчанию, им потребуется заменить 'rock_n_roll' путем к конкретному классу в формате с точками в настройке INSTALLED_APPS.

Атрибут AppConfig.name указывает Django, к какому приложению относится эта конфигурация. Можно определить любые другие атрибуты, описанные в справочнике API AppConfig.

Подклассы AppConfig можно определять где угодно. Соглашение об использовании apps.py лишь позволяет Django загружать их автоматически, когда INSTALLED_APPS содержит путь к модулю приложения, а не путь к классу конфигурации.

from django.apps import apps as django_apps

Для пользователей приложений

Если вы используете «Rock ’n’ roll» в проекте под названием anthology, но хотите, чтобы приложение отображалось под названием «Jazz Manouche», вы можете предоставить собственную конфигурацию:

# anthology/apps.py

from rock_n_roll.apps import RockNRollConfig


class JazzManoucheConfig(RockNRollConfig):
    verbose_name = "Jazz Manouche"


# anthology/settings.py

INSTALLED_APPS = [
    "anthology.apps.JazzManoucheConfig",
    # ...
]

В этом примере показаны специфичные для проекта классы конфигурации, расположенные в подмодуле с именем apps.py. Это соглашение, а не требование. Подклассы AppConfig можно определять где угодно.

В этом случае INSTALLED_APPS должен содержать путь к классу конфигурации в формате с точками, поскольку он находится вне приложения и поэтому не может быть обнаружен автоматически.

Настраиваемые атрибуты

AppConfig.name

Полный путь к приложению на Python, например 'django.contrib.admin'.

Этот атрибут определяет, к какому приложению относится конфигурация. Он должен быть задан во всех подклассах AppConfig.

Его значение должно быть уникальным в пределах проекта Django.

AppConfig.label

Краткое имя приложения, например 'admin'

Этот атрибут позволяет переименовать приложение, если метки двух приложений конфликтуют. По умолчанию ему присваивается последний компонент name. Значение должно быть допустимым идентификатором Python.

Его значение должно быть уникальным в пределах проекта Django.

Предупреждение

Изменение этого атрибута после применения миграций приложения приведет к нарушению совместимости проекта или, в случае повторно используемого приложения, всех существующих установок этого приложения. Это связано с тем, что AppConfig.label используется в таблицах базы данных и файлах миграций при указании приложения в списке зависимостей.

AppConfig.verbose_name

Понятное человеку имя приложения, например «Администрирование».

По умолчанию этому атрибуту присваивается значение label.title().

AppConfig.path

Путь к каталогу приложения в файловой системе, например '/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'.

В большинстве случаев Django может определить и установить его автоматически, но также можно явно переопределить его атрибутом класса подкласса AppConfig. В некоторых случаях это необходимо; например, если пакет приложения является пакетом пространства имен с несколькими путями.

AppConfig.default

Установите для этого атрибута значение False, чтобы Django не выбирал класс конфигурации автоматически. Это полезно, если в apps.py определен только один подкласс AppConfig, но вы не хотите, чтобы Django использовал его по умолчанию.

Установите для этого атрибута значение True, чтобы Django автоматически выбирал класс конфигурации. Это полезно, если в apps.py определено несколько подклассов AppConfig и вы хотите, чтобы Django использовал один из них по умолчанию.

По умолчанию этот атрибут не задан.

AppConfig.default_auto_field [исходный код]

Тип первичного ключа, который неявно добавляется к моделям в этом приложении. Можно использовать этот атрибут, чтобы сохранить AutoField в качестве типа первичного ключа для сторонних приложений.

По умолчанию используется значение DEFAULT_AUTO_FIELD.

Атрибуты только для чтения

AppConfig.module

Корневой модуль приложения, например <module 'django.contrib.admin' from 'django/contrib/admin/__init__.py'>.

AppConfig.models_module

Модуль, содержащий модели, например <module 'django.contrib.admin.models' from 'django/contrib/admin/models.py'>.

Его значение может быть None, если приложение не содержит модуль models. Обратите внимание, что сигналы, связанные с базой данных, такие как pre_migrate и post_migrate, отправляются только для приложений, содержащих модуль models.

Методы

AppConfig.get_models(include_auto_created=False, include_swapped=False) [исходный код]

Возвращает итерируемый объект с классами Model для этого приложения.

Требует полного заполнения реестра приложений.

AppConfig.get_model(model_name, require_ready=True) [исходный код]

Возвращает Model с указанным model_name. Сравнение model_name не учитывает регистр.

Вызывает LookupError, если в этом приложении нет такой модели.

Требует полного заполнения реестра приложений, если только аргумент require_ready не установлен в значение False. require_ready работает точно так же, как в apps.get_model().

AppConfig.ready() [исходный код]

Подклассы могут переопределить этот метод для выполнения задач инициализации, например регистрации сигналов. Он вызывается сразу после полного заполнения реестра.

Хотя импортировать модели на уровне модуля, где определены классы AppConfig, нельзя, это можно сделать в ready() с помощью инструкции import или метода get_model().

При регистрации model signals в качестве отправителя можно указать строковую метку вместо самого класса модели.

Пример:

from django.apps import AppConfig
from django.db.models.signals import pre_save


class RockNRollConfig(AppConfig):
    # ...

    def ready(self):
        # importing model classes
        from .models import MyModel  # or...

        MyModel = self.get_model("MyModel")

        # registering signals with the model's string label
        pre_save.connect(receiver, sender="app_label.MyModel")

Предупреждение

Хотя к классам моделей можно обращаться описанным выше способом, избегайте взаимодействия с базой данных в реализации ready(). Это касается методов моделей, выполняющих запросы (save(), delete(), методы менеджеров и т. д.), а также прямых SQL-запросов через django.db.connection. Метод ready() будет выполняться при запуске каждой команды управления. Например, несмотря на то что настройки тестовой базы данных отличаются от рабочих настроек, manage.py test все равно выполнит некоторые запросы к вашей рабочей базе данных!

Примечание

В обычном процессе инициализации Django вызывает метод ready только один раз. Однако в некоторых особых случаях, особенно при тестировании с изменением списка установленных приложений, ready может вызываться несколько раз. В таком случае либо пишите идемпотентные методы, либо добавьте в классы AppConfig флаг, который предотвратит повторное выполнение кода, предназначенного для однократного запуска.

Пакеты пространства имен в качестве приложений

Пакеты Python без файла __init__.py называются «пакетами пространства имен» и могут располагаться в нескольких каталогах в разных местах sys.path (см. PEP 420).

Для приложений Django требуется единый базовый путь в файловой системе, по которому Django (в зависимости от конфигурации) будет искать шаблоны, статические ресурсы и т. д. Поэтому пакеты пространства имен могут быть приложениями Django только при выполнении одного из следующих условий:

1. Пакет пространства имен фактически имеет только одно расположение (то есть не распределен по нескольким каталогам).
2. Класс AppConfig, используемый для настройки приложения, имеет атрибут класса path, содержащий абсолютный путь к каталогу, который Django будет использовать в качестве единого базового пути приложения.

Если не выполнено ни одно из этих условий, Django вызовет исключение ImproperlyConfigured.

Как загружаются приложения

При запуске Django за заполнение реестра приложений отвечает django.setup().

setup(set_prefix=True) [источник]

Настраивает Django:

• Загружает настройки.
• Настраивает ведение журнала.
• Если set_prefix имеет значение True, задаёт префикс скрипта для резолвера URL: FORCE_SCRIPT_NAME, если он определён, или / в противном случае.
• Инициализирует реестр приложений.

Эта функция вызывается автоматически:

• При запуске HTTP-сервера с использованием поддержки ASGI или WSGI в Django.
• При вызове команды управления.

В других случаях, например в обычных скриптах Python, её необходимо вызывать явно.

Реестр приложений инициализируется в три этапа. На каждом этапе Django обрабатывает все приложения в порядке, заданном в INSTALLED_APPS.

1. Сначала Django импортирует каждый элемент из INSTALLED_APPS.

   Если это класс конфигурации приложения, Django импортирует корневой пакет приложения, заданный его атрибутом name. Если это пакет Python, Django ищет конфигурацию приложения в подмодуле apps.py, а если не находит — создаёт конфигурацию приложения по умолчанию.

   На этом этапе ваш код не должен импортировать никакие модели!

   Иными словами, корневые пакеты ваших приложений и модули, в которых определены классы конфигурации приложений, не должны импортировать модели, даже косвенно.

   Строго говоря, Django разрешает импортировать модели после загрузки конфигурации приложения. Однако, чтобы избежать ненужных ограничений на порядок элементов в INSTALLED_APPS, настоятельно рекомендуется не импортировать модели на этом этапе.

   После завершения этого этапа становятся доступны API для работы с конфигурациями приложений, например get_app_config().

2. Затем Django пытается импортировать подмодуль models каждого приложения, если он существует.

   Вы должны определить или импортировать все модели приложения в его models.py или models/__init__.py. Иначе реестр приложений к этому моменту может оказаться заполнен не полностью, что может привести к сбоям в работе ORM.

   После завершения этого этапа становятся доступны API для работы с моделями, например get_model().

3. Наконец, Django вызывает метод ready() каждой конфигурации приложения.

Устранение неполадок

Ниже перечислены распространённые проблемы, с которыми можно столкнуться во время инициализации:

• AppRegistryNotReady: эта ошибка возникает, когда при импорте конфигурации приложения или модуля моделей выполняется код, зависящий от реестра приложений.

  Например, gettext() использует реестр приложений для поиска каталогов переводов в приложениях. Для перевода во время импорта необходимо использовать gettext_lazy(). (Использование gettext() было бы ошибкой, поскольку перевод выполнялся бы во время импорта, а не при каждом запросе с учётом активного языка.)

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

  Это исключение также возникает, если вы забыли вызвать django.setup() в автономном скрипте Python.

• ImportError: cannot import name ... Это происходит, если последовательность импорта приводит к циклической зависимости.

  Чтобы избежать подобных проблем, следует свести к минимуму зависимости между модулями моделей и выполнять как можно меньше действий во время импорта. Чтобы не выполнять код во время импорта, можно перенести его в функцию и кэшировать результаты. Код будет выполнен при первой необходимости в его результатах. Эта концепция называется «ленивым вычислением».

• django.contrib.admin автоматически выполняет поиск модулей admin в установленных приложениях. Чтобы отключить это, измените INSTALLED_APPS: укажите в нём 'django.contrib.admin.apps.SimpleAdminConfig' вместо 'django.contrib.admin'.

• RuntimeWarning: Accessing the database during app initialization is discouraged. Это предупреждение возникает при выполнении запросов к базе данных до готовности приложений, например во время импорта модулей или в методе AppConfig.ready(). Такие преждевременные запросы к базе данных не рекомендуются: они выполняются при запуске каждой команды управления, замедляют запуск проекта, могут кэшировать устаревшие данные и даже завершиться с ошибкой, если ожидают выполнения миграции.

  Например, распространённая ошибка — запрос к базе данных для заполнения вариантов поля формы:

  class LocationForm(forms.Form):
      country = forms.ChoiceField(choices=[c.name for c in Country.objects.all()])
  

  В приведённом выше примере запрос из Country.objects.all() выполняется во время импорта модуля, поскольку выполняется итерация по QuerySet. Чтобы избежать предупреждения, вместо этого в форме можно использовать ModelChoiceField:

  class LocationForm(forms.Form):
      country = forms.ModelChoiceField(queryset=Country.objects.all())
  

  Чтобы упростить поиск кода, вызвавшего это предупреждение, можно настроить Python так, чтобы он считал предупреждения ошибками и показывал трассировку стека, например с помощью python -Werror manage.py shell.