Приложения

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

Если вы создаёте подключаемое приложение под названием «Рок-н-ролл», вот как вы бы предоставили правильное имя для админки:

# 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

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

Если вы используете «Рок-н-ролл» в проекте под названием anthology, но хотите, чтобы он отображался как «Джаз Мануш», вы можете предоставить собственную конфигурацию:

# 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 [source]

Неявный тип первичного ключа, который нужно добавить к моделям в этом приложении. Вы можете использовать это для сохранения 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) [source]

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

Требует, чтобы реестр приложений был полностью заполнен.

AppConfig.get_model(model_name, require_ready=True) [source]

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

Возбуждает LookupError, если такая модель не существует в этом приложении.

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

AppConfig.ready() [source]

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

Хотя вы не можете импортировать модели на уровне модуля, где определены классы 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(), методы менеджера и т.д.), а также запросы с использованием django.db.connection. Ваш метод ready() будет выполняться во время запуска каждого командного интерфейса управления. Например, даже если конфигурация тестовой базы данных отличается от конфигурации рабочей базы данных, manage.py test всё равно будет выполнять некоторые запросы к вашей рабочей базе данных!

Примечание

В обычном процессе инициализации метод ready вызывается Django только один раз. Но в некоторых особых случаях, особенно в тестах, которые изменяют установленные приложения, 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) [source]

Настраивает 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.