2013-12-24 14:40:12 +00:00
|
|
|
|
============
|
|
|
|
|
Applications
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
.. module:: django.apps
|
|
|
|
|
|
|
|
|
|
Django contains a registry of installed applications that stores configuration
|
|
|
|
|
and provides introspection. It also maintains a list of available :doc:`models
|
|
|
|
|
</topics/db/models>`.
|
|
|
|
|
|
|
|
|
|
This registry is simply called :attr:`~django.apps.apps` and it's available in
|
|
|
|
|
:mod:`django.apps`::
|
|
|
|
|
|
|
|
|
|
>>> from django.apps import apps
|
|
|
|
|
>>> apps.get_app_config('admin').verbose_name
|
2019-08-23 06:48:27 +00:00
|
|
|
|
'Administration'
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Projects and applications
|
|
|
|
|
=========================
|
|
|
|
|
|
2015-12-24 14:47:45 +00:00
|
|
|
|
The term **project** describes a Django web application. The project Python
|
|
|
|
|
package is defined primarily by a settings module, but it usually contains
|
|
|
|
|
other things. For example, when you run ``django-admin startproject mysite``
|
|
|
|
|
you'll get a ``mysite`` project directory that contains a ``mysite`` Python
|
|
|
|
|
package with ``settings.py``, ``urls.py``, and ``wsgi.py``. The project package
|
|
|
|
|
is often extended to include things like fixtures, CSS, and templates which
|
|
|
|
|
aren't tied to a particular application.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2016-01-04 15:52:20 +00:00
|
|
|
|
A **project's root directory** (the one that contains ``manage.py``) is usually
|
|
|
|
|
the container for all of a project's applications which aren't installed
|
|
|
|
|
separately.
|
|
|
|
|
|
2013-12-24 14:40:12 +00:00
|
|
|
|
The term **application** describes a Python package that provides some set of
|
2015-12-24 14:47:45 +00:00
|
|
|
|
features. Applications :doc:`may be reused </intro/reusable-apps/>` in various
|
2016-01-04 15:52:20 +00:00
|
|
|
|
projects.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Applications include some combination of models, views, templates, template
|
|
|
|
|
tags, static files, URLs, middleware, etc. They're generally wired into
|
|
|
|
|
projects with the :setting:`INSTALLED_APPS` setting and optionally with other
|
2015-11-07 15:12:37 +00:00
|
|
|
|
mechanisms such as URLconfs, the :setting:`MIDDLEWARE` setting, or template
|
|
|
|
|
inheritance.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
It is important to understand that a Django application is just a set of code
|
|
|
|
|
that interacts with various parts of the framework. There's no such thing as
|
|
|
|
|
an ``Application`` object. However, there's a few places where Django needs to
|
|
|
|
|
interact with installed applications, mainly for configuration and also for
|
|
|
|
|
introspection. That's why the application registry maintains metadata in an
|
|
|
|
|
:class:`~django.apps.AppConfig` instance for each installed application.
|
|
|
|
|
|
2015-12-24 14:47:45 +00:00
|
|
|
|
There's no restriction that a project package can't also be considered an
|
|
|
|
|
application and have models, etc. (which would require adding it to
|
|
|
|
|
:setting:`INSTALLED_APPS`).
|
|
|
|
|
|
2015-11-17 15:50:00 +00:00
|
|
|
|
.. _configuring-applications-ref:
|
|
|
|
|
|
2013-12-24 14:40:12 +00:00
|
|
|
|
Configuring applications
|
|
|
|
|
========================
|
|
|
|
|
|
|
|
|
|
To configure an application, subclass :class:`~django.apps.AppConfig` and put
|
|
|
|
|
the dotted path to that subclass in :setting:`INSTALLED_APPS`.
|
|
|
|
|
|
2014-01-24 21:43:00 +00:00
|
|
|
|
When :setting:`INSTALLED_APPS` simply contains the dotted path to an
|
|
|
|
|
application module, Django checks for a ``default_app_config`` variable in
|
|
|
|
|
that module.
|
|
|
|
|
|
|
|
|
|
If it's defined, it's the dotted path to the :class:`~django.apps.AppConfig`
|
|
|
|
|
subclass for that application.
|
|
|
|
|
|
|
|
|
|
If there is no ``default_app_config``, Django uses the base
|
|
|
|
|
:class:`~django.apps.AppConfig` class.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2015-09-21 20:42:35 +00:00
|
|
|
|
``default_app_config`` allows applications that predate Django 1.7 such as
|
|
|
|
|
``django.contrib.admin`` to opt-in to :class:`~django.apps.AppConfig` features
|
|
|
|
|
without requiring users to update their :setting:`INSTALLED_APPS`.
|
|
|
|
|
|
|
|
|
|
New applications should avoid ``default_app_config``. Instead they should
|
|
|
|
|
require the dotted path to the appropriate :class:`~django.apps.AppConfig`
|
|
|
|
|
subclass to be configured explicitly in :setting:`INSTALLED_APPS`.
|
|
|
|
|
|
2013-12-24 14:40:12 +00:00
|
|
|
|
For application authors
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
If you're creating a pluggable app called "Rock ’n’ roll", here's how you
|
|
|
|
|
would provide a proper name for the admin::
|
|
|
|
|
|
2014-01-02 22:06:25 +00:00
|
|
|
|
# rock_n_roll/apps.py
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
from django.apps import AppConfig
|
|
|
|
|
|
|
|
|
|
class RockNRollConfig(AppConfig):
|
|
|
|
|
name = 'rock_n_roll'
|
|
|
|
|
verbose_name = "Rock ’n’ roll"
|
|
|
|
|
|
2014-01-24 21:43:00 +00:00
|
|
|
|
You can make your application load this :class:`~django.apps.AppConfig`
|
|
|
|
|
subclass by default as follows::
|
|
|
|
|
|
|
|
|
|
# rock_n_roll/__init__.py
|
|
|
|
|
|
|
|
|
|
default_app_config = 'rock_n_roll.apps.RockNRollConfig'
|
|
|
|
|
|
|
|
|
|
That will cause ``RockNRollConfig`` to be used when :setting:`INSTALLED_APPS`
|
|
|
|
|
just contains ``'rock_n_roll'``. This allows you to make use of
|
|
|
|
|
:class:`~django.apps.AppConfig` features without requiring your users to
|
2015-09-07 13:28:15 +00:00
|
|
|
|
update their :setting:`INSTALLED_APPS` setting. Besides this use case, it's
|
|
|
|
|
best to avoid using ``default_app_config`` and instead specify the app config
|
|
|
|
|
class in :setting:`INSTALLED_APPS` as described next.
|
2014-01-24 21:43:00 +00:00
|
|
|
|
|
|
|
|
|
Of course, you can also tell your users to put
|
|
|
|
|
``'rock_n_roll.apps.RockNRollConfig'`` in their :setting:`INSTALLED_APPS`
|
|
|
|
|
setting. You can even provide several different
|
|
|
|
|
:class:`~django.apps.AppConfig` subclasses with different behaviors and allow
|
|
|
|
|
your users to choose one via their :setting:`INSTALLED_APPS` setting.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
The recommended convention is to put the configuration class in a submodule of
|
2014-01-02 22:06:25 +00:00
|
|
|
|
the application called ``apps``. However, this isn't enforced by Django.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
You must include the :attr:`~django.apps.AppConfig.name` attribute for Django
|
|
|
|
|
to determine which application this configuration applies to. You can define
|
|
|
|
|
any attributes documented in the :class:`~django.apps.AppConfig` API
|
|
|
|
|
reference.
|
|
|
|
|
|
2014-02-02 14:31:34 +00:00
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
If your code imports the application registry in an application's
|
|
|
|
|
``__init__.py``, the name ``apps`` will clash with the ``apps`` submodule.
|
|
|
|
|
The best practice is to move that code to a submodule and import it. A
|
|
|
|
|
workaround is to import the registry under a different name::
|
|
|
|
|
|
|
|
|
|
from django.apps import apps as django_apps
|
|
|
|
|
|
2013-12-24 14:40:12 +00:00
|
|
|
|
For application users
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
If you're using "Rock ’n’ roll" in a project called ``anthology``, but you
|
2016-02-03 10:42:48 +00:00
|
|
|
|
want it to show up as "Jazz Manouche" instead, you can provide your own
|
2013-12-24 14:40:12 +00:00
|
|
|
|
configuration::
|
|
|
|
|
|
|
|
|
|
# anthology/apps.py
|
|
|
|
|
|
2014-01-24 21:43:00 +00:00
|
|
|
|
from rock_n_roll.apps import RockNRollConfig
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2016-02-03 10:42:48 +00:00
|
|
|
|
class JazzManoucheConfig(RockNRollConfig):
|
|
|
|
|
verbose_name = "Jazz Manouche"
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
# anthology/settings.py
|
|
|
|
|
|
|
|
|
|
INSTALLED_APPS = [
|
2016-02-03 10:42:48 +00:00
|
|
|
|
'anthology.apps.JazzManoucheConfig',
|
2013-12-24 14:40:12 +00:00
|
|
|
|
# ...
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
Again, defining project-specific configuration classes in a submodule called
|
|
|
|
|
``apps`` is a convention, not a requirement.
|
|
|
|
|
|
|
|
|
|
Application configuration
|
|
|
|
|
=========================
|
|
|
|
|
|
2013-12-25 20:57:52 +00:00
|
|
|
|
.. class:: AppConfig
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Application configuration objects store metadata for an application. Some
|
|
|
|
|
attributes can be configured in :class:`~django.apps.AppConfig`
|
|
|
|
|
subclasses. Others are set by Django and read-only.
|
|
|
|
|
|
|
|
|
|
Configurable attributes
|
|
|
|
|
-----------------------
|
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
.. attribute:: AppConfig.name
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
Full Python path to the application, e.g. ``'django.contrib.admin'``.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
This attribute defines which application the configuration applies to. It
|
|
|
|
|
must be set in all :class:`~django.apps.AppConfig` subclasses.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
It must be unique across a Django project.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
.. attribute:: AppConfig.label
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-31 15:23:42 +00:00
|
|
|
|
Short name for the application, e.g. ``'admin'``
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2014-03-01 02:03:46 +00:00
|
|
|
|
This attribute allows relabeling an application when two applications
|
2013-12-31 15:23:42 +00:00
|
|
|
|
have conflicting labels. It defaults to the last component of ``name``.
|
|
|
|
|
It should be a valid Python identifier.
|
|
|
|
|
|
|
|
|
|
It must be unique across a Django project.
|
|
|
|
|
|
|
|
|
|
.. attribute:: AppConfig.verbose_name
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2014-03-09 20:20:34 +00:00
|
|
|
|
Human-readable name for the application, e.g. "Administration".
|
2013-12-31 15:23:42 +00:00
|
|
|
|
|
|
|
|
|
This attribute defaults to ``label.title()``.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-25 20:57:52 +00:00
|
|
|
|
.. attribute:: AppConfig.path
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Filesystem path to the application directory, e.g.
|
2017-02-18 00:45:34 +00:00
|
|
|
|
``'/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'``.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2014-01-26 02:37:05 +00:00
|
|
|
|
In most cases, Django can automatically detect and set this, but you can
|
|
|
|
|
also provide an explicit override as a class attribute on your
|
|
|
|
|
:class:`~django.apps.AppConfig` subclass. In a few situations this is
|
|
|
|
|
required; for instance if the app package is a `namespace package`_ with
|
|
|
|
|
multiple paths.
|
|
|
|
|
|
|
|
|
|
Read-only attributes
|
|
|
|
|
--------------------
|
|
|
|
|
|
2013-12-26 17:40:28 +00:00
|
|
|
|
.. attribute:: AppConfig.module
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Root module for the application, e.g. ``<module 'django.contrib.admin' from
|
2017-01-22 01:02:00 +00:00
|
|
|
|
'django/contrib/admin/__init__.py'>``.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
2013-12-25 20:57:52 +00:00
|
|
|
|
.. attribute:: AppConfig.models_module
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
Module containing the models, e.g. ``<module 'django.contrib.admin.models'
|
2017-01-22 01:02:00 +00:00
|
|
|
|
from 'django/contrib/admin/models.py'>``.
|
2013-12-24 14:40:12 +00:00
|
|
|
|
|
|
|
|
|
It may be ``None`` if the application doesn't contain a ``models`` module.
|
2014-02-28 14:22:33 +00:00
|
|
|
|
Note that the database related signals such as
|
|
|
|
|
:data:`~django.db.models.signals.pre_migrate` and
|
|
|
|
|
:data:`~django.db.models.signals.post_migrate`
|
|
|
|
|
are only emitted for applications that have a ``models`` module.
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
2013-12-28 13:41:11 +00:00
|
|
|
|
Methods
|
|
|
|
|
-------
|
|
|
|
|
|
2013-12-29 19:26:13 +00:00
|
|
|
|
.. method:: AppConfig.get_models()
|
|
|
|
|
|
2015-09-11 18:07:12 +00:00
|
|
|
|
Returns an iterable of :class:`~django.db.models.Model` classes for this
|
|
|
|
|
application.
|
2013-12-29 19:26:13 +00:00
|
|
|
|
|
2016-09-30 19:08:35 +00:00
|
|
|
|
Requires the app registry to be fully populated.
|
|
|
|
|
|
2016-05-03 10:21:54 +00:00
|
|
|
|
.. method:: AppConfig.get_model(model_name, require_ready=True)
|
2013-12-28 13:41:11 +00:00
|
|
|
|
|
|
|
|
|
Returns the :class:`~django.db.models.Model` with the given
|
2016-09-30 19:08:35 +00:00
|
|
|
|
``model_name``. ``model_name`` is case-insensitive.
|
|
|
|
|
|
|
|
|
|
Raises :exc:`LookupError` if no such model exists in this application.
|
|
|
|
|
|
2016-05-03 10:21:54 +00:00
|
|
|
|
Requires the app registry to be fully populated unless the
|
|
|
|
|
``require_ready`` argument is set to ``False``. ``require_ready`` behaves
|
|
|
|
|
exactly as in :meth:`apps.get_model()`.
|
|
|
|
|
|
2013-12-31 16:55:12 +00:00
|
|
|
|
.. method:: AppConfig.ready()
|
2013-12-30 11:49:53 +00:00
|
|
|
|
|
2013-12-31 16:55:12 +00:00
|
|
|
|
Subclasses can override this method to perform initialization tasks such
|
|
|
|
|
as registering signals. It is called as soon as the registry is fully
|
2013-12-30 11:49:53 +00:00
|
|
|
|
populated.
|
|
|
|
|
|
2016-08-11 08:59:19 +00:00
|
|
|
|
Although you can't import models at the module-level where
|
|
|
|
|
:class:`~django.apps.AppConfig` classes are defined, you can import them in
|
|
|
|
|
``ready()``, using either an ``import`` statement or
|
|
|
|
|
:meth:`~AppConfig.get_model`.
|
|
|
|
|
|
|
|
|
|
If you're registering :mod:`model signals <django.db.models.signals>`, you
|
|
|
|
|
can refer to the sender by its string label instead of using the model
|
|
|
|
|
class itself.
|
|
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
|
|
from django.db.models.signals import pre_save
|
2014-01-10 22:06:19 +00:00
|
|
|
|
|
|
|
|
|
def ready(self):
|
2016-08-11 08:59:19 +00:00
|
|
|
|
# importing model classes
|
|
|
|
|
from .models import MyModel # or...
|
2014-01-10 22:06:19 +00:00
|
|
|
|
MyModel = self.get_model('MyModel')
|
|
|
|
|
|
2016-08-11 08:59:19 +00:00
|
|
|
|
# registering signals with the model's string label
|
|
|
|
|
pre_save.connect(receiver, sender='app_label.MyModel')
|
|
|
|
|
|
2014-02-15 16:27:12 +00:00
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
|
|
Although you can access model classes as described above, avoid
|
|
|
|
|
interacting with the database in your :meth:`ready()` implementation.
|
|
|
|
|
This includes model methods that execute queries
|
|
|
|
|
(:meth:`~django.db.models.Model.save()`,
|
|
|
|
|
:meth:`~django.db.models.Model.delete()`, manager methods etc.), and
|
|
|
|
|
also raw SQL queries via ``django.db.connection``. Your
|
|
|
|
|
:meth:`ready()` method will run during startup of every management
|
|
|
|
|
command. For example, even though the test database configuration is
|
|
|
|
|
separate from the production settings, ``manage.py test`` would still
|
|
|
|
|
execute some queries against your **production** database!
|
|
|
|
|
|
2014-05-24 13:57:04 +00:00
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
In the usual initialization process, the ``ready`` method is only called
|
|
|
|
|
once by Django. But in some corner cases, particularly in tests which
|
|
|
|
|
are fiddling with installed applications, ``ready`` might be called more
|
2015-03-07 16:34:33 +00:00
|
|
|
|
than once. In that case, either write idempotent methods, or put a flag
|
2014-05-24 13:57:04 +00:00
|
|
|
|
on your ``AppConfig`` classes to prevent re-running code which should
|
|
|
|
|
be executed exactly one time.
|
|
|
|
|
|
2014-01-26 02:37:05 +00:00
|
|
|
|
.. _namespace package:
|
|
|
|
|
|
2017-01-18 16:51:29 +00:00
|
|
|
|
Namespace packages as apps
|
|
|
|
|
--------------------------
|
2014-01-26 02:37:05 +00:00
|
|
|
|
|
2017-01-18 16:51:29 +00:00
|
|
|
|
Python packages without an ``__init__.py`` file are known as "namespace
|
|
|
|
|
packages" and may be spread across multiple directories at different locations
|
|
|
|
|
on ``sys.path`` (see :pep:`420`).
|
2014-01-26 02:37:05 +00:00
|
|
|
|
|
|
|
|
|
Django applications require a single base filesystem path where Django
|
|
|
|
|
(depending on configuration) will search for templates, static assets,
|
|
|
|
|
etc. Thus, namespace packages may only be Django applications if one of the
|
|
|
|
|
following is true:
|
|
|
|
|
|
2018-11-15 18:54:28 +00:00
|
|
|
|
#. The namespace package actually has only a single location (i.e. is not
|
2014-01-26 02:37:05 +00:00
|
|
|
|
spread across more than one directory.)
|
|
|
|
|
|
2018-11-15 18:54:28 +00:00
|
|
|
|
#. The :class:`~django.apps.AppConfig` class used to configure the application
|
2014-01-26 02:37:05 +00:00
|
|
|
|
has a :attr:`~django.apps.AppConfig.path` class attribute, which is the
|
|
|
|
|
absolute directory path Django will use as the single base path for the
|
|
|
|
|
application.
|
|
|
|
|
|
|
|
|
|
If neither of these conditions is met, Django will raise
|
|
|
|
|
:exc:`~django.core.exceptions.ImproperlyConfigured`.
|
|
|
|
|
|
2013-12-25 20:57:52 +00:00
|
|
|
|
Application registry
|
|
|
|
|
====================
|
|
|
|
|
|
|
|
|
|
.. data:: apps
|
|
|
|
|
|
|
|
|
|
The application registry provides the following public API. Methods that
|
|
|
|
|
aren't listed below are considered private and may change without notice.
|
|
|
|
|
|
2014-02-14 01:50:27 +00:00
|
|
|
|
.. attribute:: apps.ready
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
2016-02-25 13:55:10 +00:00
|
|
|
|
Boolean attribute that is set to ``True`` after the registry is fully
|
|
|
|
|
populated and all :meth:`AppConfig.ready` methods are called.
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
2013-12-30 22:53:54 +00:00
|
|
|
|
.. method:: apps.get_app_configs()
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
|
|
|
|
Returns an iterable of :class:`~django.apps.AppConfig` instances.
|
|
|
|
|
|
2013-12-30 22:53:54 +00:00
|
|
|
|
.. method:: apps.get_app_config(app_label)
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
|
|
|
|
Returns an :class:`~django.apps.AppConfig` for the application with the
|
2014-04-26 14:00:15 +00:00
|
|
|
|
given ``app_label``. Raises :exc:`LookupError` if no such application
|
|
|
|
|
exists.
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
2014-01-06 21:48:41 +00:00
|
|
|
|
.. method:: apps.is_installed(app_name)
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
|
|
|
|
Checks whether an application with the given name exists in the registry.
|
2014-01-24 21:43:00 +00:00
|
|
|
|
``app_name`` is the full name of the app, e.g. ``'django.contrib.admin'``.
|
2013-12-25 20:57:52 +00:00
|
|
|
|
|
2016-05-03 10:21:54 +00:00
|
|
|
|
.. method:: apps.get_model(app_label, model_name, require_ready=True)
|
2013-12-28 13:41:11 +00:00
|
|
|
|
|
|
|
|
|
Returns the :class:`~django.db.models.Model` with the given ``app_label``
|
2014-01-26 11:46:28 +00:00
|
|
|
|
and ``model_name``. As a shortcut, this method also accepts a single
|
2016-10-06 15:00:36 +00:00
|
|
|
|
argument in the form ``app_label.model_name``. ``model_name`` is
|
|
|
|
|
case-insensitive.
|
2014-01-26 11:46:28 +00:00
|
|
|
|
|
2014-04-26 14:00:15 +00:00
|
|
|
|
Raises :exc:`LookupError` if no such application or model exists. Raises
|
|
|
|
|
:exc:`ValueError` when called with a single argument that doesn't contain
|
|
|
|
|
exactly one dot.
|
2014-04-13 15:18:02 +00:00
|
|
|
|
|
2016-05-03 10:21:54 +00:00
|
|
|
|
Requires the app registry to be fully populated unless the
|
|
|
|
|
``require_ready`` argument is set to ``False``.
|
|
|
|
|
|
|
|
|
|
Setting ``require_ready`` to ``False`` allows looking up models
|
|
|
|
|
:ref:`while the app registry is being populated <app-loading-process>`,
|
|
|
|
|
specifically during the second phase where it imports models. Then
|
|
|
|
|
``get_model()`` has the same effect as importing the model. The main use
|
|
|
|
|
case is to configure model classes with settings, such as
|
|
|
|
|
:setting:`AUTH_USER_MODEL`.
|
|
|
|
|
|
|
|
|
|
When ``require_ready`` is ``False``, ``get_model()`` returns a model class
|
|
|
|
|
that may not be fully functional (reverse accessors may be missing, for
|
|
|
|
|
example) until the app registry is fully populated. For this reason, it's
|
|
|
|
|
best to leave ``require_ready`` to the default value of ``True`` whenever
|
|
|
|
|
possible.
|
|
|
|
|
|
2016-10-06 14:20:22 +00:00
|
|
|
|
.. _app-loading-process:
|
|
|
|
|
|
2014-04-26 16:32:17 +00:00
|
|
|
|
Initialization process
|
|
|
|
|
======================
|
|
|
|
|
|
|
|
|
|
How applications are loaded
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
When Django starts, :func:`django.setup()` is responsible for populating the
|
|
|
|
|
application registry.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django
|
|
|
|
|
|
2016-08-11 11:01:55 +00:00
|
|
|
|
.. function:: setup(set_prefix=True)
|
2014-04-26 16:32:17 +00:00
|
|
|
|
|
|
|
|
|
Configures Django by:
|
|
|
|
|
|
|
|
|
|
* Loading the settings.
|
|
|
|
|
* Setting up logging.
|
2016-08-11 11:01:55 +00:00
|
|
|
|
* If ``set_prefix`` is True, setting the URL resolver script prefix to
|
2015-10-23 19:02:34 +00:00
|
|
|
|
:setting:`FORCE_SCRIPT_NAME` if defined, or ``/`` otherwise.
|
2014-04-26 16:32:17 +00:00
|
|
|
|
* Initializing the application registry.
|
|
|
|
|
|
|
|
|
|
This function is called automatically:
|
|
|
|
|
|
|
|
|
|
* When running an HTTP server via Django's WSGI support.
|
|
|
|
|
* When invoking a management command.
|
|
|
|
|
|
|
|
|
|
It must be called explicitly in other cases, for instance in plain Python
|
|
|
|
|
scripts.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django.apps
|
|
|
|
|
|
|
|
|
|
The application registry is initialized in three stages. At each stage, Django
|
|
|
|
|
processes all applications in the order of :setting:`INSTALLED_APPS`.
|
|
|
|
|
|
|
|
|
|
#. First Django imports each item in :setting:`INSTALLED_APPS`.
|
|
|
|
|
|
|
|
|
|
If it's an application configuration class, Django imports the root package
|
|
|
|
|
of the application, defined by its :attr:`~AppConfig.name` attribute. If
|
|
|
|
|
it's a Python package, Django creates a default application configuration.
|
|
|
|
|
|
|
|
|
|
*At this stage, your code shouldn't import any models!*
|
|
|
|
|
|
|
|
|
|
In other words, your applications' root packages and the modules that
|
|
|
|
|
define your application configuration classes shouldn't import any models,
|
|
|
|
|
even indirectly.
|
|
|
|
|
|
|
|
|
|
Strictly speaking, Django allows importing models once their application
|
|
|
|
|
configuration is loaded. However, in order to avoid needless constraints on
|
|
|
|
|
the order of :setting:`INSTALLED_APPS`, it's strongly recommended not
|
|
|
|
|
import any models at this stage.
|
|
|
|
|
|
2014-12-06 12:56:43 +00:00
|
|
|
|
Once this stage completes, APIs that operate on application configurations
|
2014-07-12 13:33:21 +00:00
|
|
|
|
such as :meth:`~apps.get_app_config()` become usable.
|
|
|
|
|
|
2014-04-26 16:32:17 +00:00
|
|
|
|
#. Then Django attempts to import the ``models`` submodule of each application,
|
|
|
|
|
if there is one.
|
|
|
|
|
|
|
|
|
|
You must define or import all models in your application's ``models.py`` or
|
|
|
|
|
``models/__init__.py``. Otherwise, the application registry may not be fully
|
|
|
|
|
populated at this point, which could cause the ORM to malfunction.
|
|
|
|
|
|
2014-07-12 13:33:21 +00:00
|
|
|
|
Once this stage completes, APIs that operate on models such as
|
|
|
|
|
:meth:`~apps.get_model()` become usable.
|
|
|
|
|
|
2014-04-26 16:32:17 +00:00
|
|
|
|
#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application
|
|
|
|
|
configuration.
|
|
|
|
|
|
2014-04-25 15:39:49 +00:00
|
|
|
|
.. _applications-troubleshooting:
|
2014-04-13 15:18:02 +00:00
|
|
|
|
|
2014-04-25 15:39:49 +00:00
|
|
|
|
Troubleshooting
|
2014-04-26 16:32:17 +00:00
|
|
|
|
---------------
|
2014-04-13 15:18:02 +00:00
|
|
|
|
|
2014-04-26 16:32:17 +00:00
|
|
|
|
Here are some common problems that you may encounter during initialization:
|
2014-04-13 15:18:02 +00:00
|
|
|
|
|
2016-10-06 14:20:22 +00:00
|
|
|
|
* :class:`~django.core.exceptions.AppRegistryNotReady`: This happens when
|
|
|
|
|
importing an application configuration or a models module triggers code that
|
|
|
|
|
depends on the app registry.
|
2014-04-13 15:18:02 +00:00
|
|
|
|
|
2017-01-26 19:58:33 +00:00
|
|
|
|
For example, :func:`~django.utils.translation.gettext()` uses the app
|
2014-04-13 15:18:02 +00:00
|
|
|
|
registry to look up translation catalogs in applications. To translate at
|
2017-01-26 19:58:33 +00:00
|
|
|
|
import time, you need :func:`~django.utils.translation.gettext_lazy()`
|
|
|
|
|
instead. (Using :func:`~django.utils.translation.gettext()` would be a bug,
|
2014-04-13 15:18:02 +00:00
|
|
|
|
because the translation would happen at import time, rather than at each
|
|
|
|
|
request depending on the active language.)
|
|
|
|
|
|
|
|
|
|
Executing database queries with the ORM at import time in models modules
|
|
|
|
|
will also trigger this exception. The ORM cannot function properly until all
|
|
|
|
|
models are available.
|
|
|
|
|
|
2014-04-26 16:32:17 +00:00
|
|
|
|
This exception also happens if you forget to call :func:`django.setup()` in
|
|
|
|
|
a standalone Python script.
|
|
|
|
|
|
2014-04-13 15:18:02 +00:00
|
|
|
|
* ``ImportError: cannot import name ...`` This happens if the import sequence
|
|
|
|
|
ends up in a loop.
|
|
|
|
|
|
|
|
|
|
To eliminate such problems, you should minimize dependencies between your
|
|
|
|
|
models modules and do as little work as possible at import time. To avoid
|
|
|
|
|
executing code at import time, you can move it into a function and cache its
|
|
|
|
|
results. The code will be executed when you first need its results. This
|
|
|
|
|
concept is known as "lazy evaluation".
|
|
|
|
|
|
2014-04-25 15:39:49 +00:00
|
|
|
|
* ``django.contrib.admin`` automatically performs autodiscovery of ``admin``
|
|
|
|
|
modules in installed applications. To prevent it, change your
|
2014-04-13 15:18:02 +00:00
|
|
|
|
:setting:`INSTALLED_APPS` to contain
|
|
|
|
|
``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of
|
|
|
|
|
``'django.contrib.admin'``.
|