Django contains a registry of installed applications that stores configuration\nand provides introspection. It also maintains a list of available models.
\nThis registry is called apps and it’s available in\ndjango.apps:
>>> from django.apps import apps\n>>> apps.get_app_config('admin').verbose_name\n'Administration'\nThe term project describes a Django web application. The project Python\npackage is defined primarily by a settings module, but it usually contains\nother things. For example, when you run django-admin startproject mysite\nyou’ll get a mysite project directory that contains a mysite Python\npackage with settings.py, urls.py, asgi.py and wsgi.py. The\nproject package is often extended to include things like fixtures, CSS, and\ntemplates which aren’t tied to a particular application.
A project’s root directory (the one that contains manage.py) is usually\nthe container for all of a project’s applications which aren’t installed\nseparately.
The term application describes a Python package that provides some set of\nfeatures. Applications may be reused in various\nprojects.
\nApplications include some combination of models, views, templates, template\ntags, static files, URLs, middleware, etc. They’re generally wired into\nprojects with the INSTALLED_APPS setting and optionally with other\nmechanisms such as URLconfs, the MIDDLEWARE setting, or template\ninheritance.
It is important to understand that a Django application is a set of code\nthat interacts with various parts of the framework. There’s no such thing as\nan Application object. However, there’s a few places where Django needs to\ninteract with installed applications, mainly for configuration and also for\nintrospection. That’s why the application registry maintains metadata in an\nAppConfig instance for each installed application.
There’s no restriction that a project package can’t also be considered an\napplication and have models, etc. (which would require adding it to\nINSTALLED_APPS).
To configure an application, create an apps.py module inside the\napplication, then define a subclass of AppConfig there.
When INSTALLED_APPS contains the dotted path to an application\nmodule, by default, if Django finds exactly one AppConfig subclass in\nthe apps.py submodule, it uses that configuration for the application. This\nbehavior may be disabled by setting AppConfig.default to False.
If the apps.py module contains more than one AppConfig subclass,\nDjango will look for a single one where AppConfig.default is True.
If no AppConfig subclass is found, the base AppConfig class\nwill be used.
Alternatively, INSTALLED_APPS may contain the dotted path to a\nconfiguration class to specify it explicitly:
INSTALLED_APPS = [\n ...\n 'polls.apps.PollsAppConfig',\n ...\n]\nIf you’re using “Rock ’n’ roll” in a project called anthology, but you\nwant it to show up as “Jazz Manouche” instead, you can provide your own\nconfiguration:
# anthology/apps.py\n\nfrom rock_n_roll.apps import RockNRollConfig\n\nclass JazzManoucheConfig(RockNRollConfig):\n verbose_name = "Jazz Manouche"\n\n# anthology/settings.py\n\nINSTALLED_APPS = [\n 'anthology.apps.JazzManoucheConfig',\n # ...\n]\nThis example shows project-specific configuration classes located in a\nsubmodule called apps.py. This is a convention, not a requirement.\nAppConfig subclasses may be defined anywhere.
In this situation, INSTALLED_APPS must contain the dotted path to\nthe configuration class because it lives outside of an application and thus\ncannot be automatically detected.
Application configuration objects store metadata for an application. Some\nattributes can be configured in AppConfig\nsubclasses. Others are set by Django and read-only.
Full Python path to the application, e.g. 'django.contrib.admin'.
This attribute defines which application the configuration applies to. It\nmust be set in all AppConfig subclasses.
It must be unique across a Django project.
\nShort name for the application, e.g. 'admin'
This attribute allows relabeling an application when two applications\nhave conflicting labels. It defaults to the last component of name.\nIt should be a valid Python identifier.
It must be unique across a Django project.
\nHuman-readable name for the application, e.g. “Administration”.
\nThis attribute defaults to label.title().
Filesystem path to the application directory, e.g.\n'/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'.
In most cases, Django can automatically detect and set this, but you can\nalso provide an explicit override as a class attribute on your\nAppConfig subclass. In a few situations this is\nrequired; for instance if the app package is a namespace package with\nmultiple paths.
Set this attribute to False to prevent Django from selecting a\nconfiguration class automatically. This is useful when apps.py defines\nonly one AppConfig subclass but you don’t want Django to use it by\ndefault.
Set this attribute to True to tell Django to select a configuration\nclass automatically. This is useful when apps.py defines more than one\nAppConfig subclass and you want Django to use one of them by\ndefault.
By default, this attribute isn’t set.
\nThe implicit primary key type to add to models within this app. You can\nuse this to keep AutoField as the primary key\ntype for third party applications.
By default, this is the value of DEFAULT_AUTO_FIELD.
Root module for the application, e.g. <module 'django.contrib.admin' from\n'django/contrib/admin/__init__.py'>.
Module containing the models, e.g. <module 'django.contrib.admin.models'\nfrom 'django/contrib/admin/models.py'>.
It may be None if the application doesn’t contain a models module.\nNote that the database related signals such as\npre_migrate and\npost_migrate\nare only emitted for applications that have a models module.
Returns an iterable of Model classes for this\napplication.
Requires the app registry to be fully populated.
\nReturns the Model with the given\nmodel_name. model_name is case-insensitive.
Raises LookupError if no such model exists in this application.
Requires the app registry to be fully populated unless the\nrequire_ready argument is set to False. require_ready behaves\nexactly as in apps.get_model().
Subclasses can override this method to perform initialization tasks such\nas registering signals. It is called as soon as the registry is fully\npopulated.
\nAlthough you can’t import models at the module-level where\nAppConfig classes are defined, you can import them in\nready(), using either an import statement or\nget_model().
If you’re registering model signals, you\ncan refer to the sender by its string label instead of using the model\nclass itself.
Example:
\nfrom django.apps import AppConfig\nfrom django.db.models.signals import pre_save\n\n\nclass RockNRollConfig(AppConfig):\n # ...\n\n def ready(self):\n # importing model classes\n from .models import MyModel # or...\n MyModel = self.get_model('MyModel')\n\n # registering signals with the model's string label\n pre_save.connect(receiver, sender='app_label.MyModel')\nPython packages without an __init__.py file are known as “namespace\npackages” and may be spread across multiple directories at different locations\non sys.path (see PEP 420).
Django applications require a single base filesystem path where Django\n(depending on configuration) will search for templates, static assets,\netc. Thus, namespace packages may only be Django applications if one of the\nfollowing is true:
\nThe namespace package actually has only a single location (i.e. is not\nspread across more than one directory.)
The AppConfig class used to configure the application\nhas a path class attribute, which is the\nabsolute directory path Django will use as the single base path for the\napplication.
If neither of these conditions is met, Django will raise\nImproperlyConfigured.
The application registry provides the following public API. Methods that\naren’t listed below are considered private and may change without notice.
\nBoolean attribute that is set to True after the registry is fully\npopulated and all AppConfig.ready() methods are called.
Returns an iterable of AppConfig instances.
Returns an AppConfig for the application with the\ngiven app_label. Raises LookupError if no such application\nexists.
Checks whether an application with the given name exists in the registry.\napp_name is the full name of the app, e.g. 'django.contrib.admin'.
Returns the Model with the given app_label\nand model_name. As a shortcut, this method also accepts a single\nargument in the form app_label.model_name. model_name is\ncase-insensitive.
Raises LookupError if no such application or model exists. Raises\nValueError when called with a single argument that doesn’t contain\nexactly one dot.
Requires the app registry to be fully populated unless the\nrequire_ready argument is set to False.
Setting require_ready to False allows looking up models\nwhile the app registry is being populated,\nspecifically during the second phase where it imports models. Then\nget_model() has the same effect as importing the model. The main use\ncase is to configure model classes with settings, such as\nAUTH_USER_MODEL.
When require_ready is False, get_model() returns a model class\nthat may not be fully functional (reverse accessors may be missing, for\nexample) until the app registry is fully populated. For this reason, it’s\nbest to leave require_ready to the default value of True whenever\npossible.
When Django starts, django.setup() is responsible for populating the\napplication registry.
Configures Django by:
\nLoading the settings.
Setting up logging.
If set_prefix is True, setting the URL resolver script prefix to\nFORCE_SCRIPT_NAME if defined, or / otherwise.
Initializing the application registry.
This function is called automatically:
\nWhen 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\nscripts.
\nThe application registry is initialized in three stages. At each stage, Django\nprocesses all applications in the order of INSTALLED_APPS.
First Django imports each item in INSTALLED_APPS.
If it’s an application configuration class, Django imports the root package\nof the application, defined by its name attribute. If\nit’s a Python package, Django looks for an application configuration in an\napps.py submodule, or else creates a default application configuration.
At this stage, your code shouldn’t import any models!
\nIn other words, your applications’ root packages and the modules that\ndefine your application configuration classes shouldn’t import any models,\neven indirectly.
\nStrictly speaking, Django allows importing models once their application\nconfiguration is loaded. However, in order to avoid needless constraints on\nthe order of INSTALLED_APPS, it’s strongly recommended not\nimport any models at this stage.
Once this stage completes, APIs that operate on application configurations\nsuch as get_app_config() become usable.
Then Django attempts to import the models submodule of each application,\nif there is one.
You must define or import all models in your application’s models.py or\nmodels/__init__.py. Otherwise, the application registry may not be fully\npopulated at this point, which could cause the ORM to malfunction.
Once this stage completes, APIs that operate on models such as\nget_model() become usable.
Finally Django runs the ready() method of each application\nconfiguration.
Here are some common problems that you may encounter during initialization:
\nAppRegistryNotReady: This happens when\nimporting an application configuration or a models module triggers code that\ndepends on the app registry.
For example, gettext() uses the app\nregistry to look up translation catalogs in applications. To translate at\nimport time, you need gettext_lazy()\ninstead. (Using gettext() would be a bug,\nbecause the translation would happen at import time, rather than at each\nrequest depending on the active language.)
Executing database queries with the ORM at import time in models modules\nwill also trigger this exception. The ORM cannot function properly until all\nmodels are available.
\nThis exception also happens if you forget to call django.setup() in\na standalone Python script.
ImportError: cannot import name ... This happens if the import sequence\nends up in a loop.
To eliminate such problems, you should minimize dependencies between your\nmodels modules and do as little work as possible at import time. To avoid\nexecuting code at import time, you can move it into a function and cache its\nresults. The code will be executed when you first need its results. This\nconcept is known as “lazy evaluation”.
\ndjango.contrib.admin automatically performs autodiscovery of admin\nmodules in installed applications. To prevent it, change your\nINSTALLED_APPS to contain\n'django.contrib.admin.apps.SimpleAdminConfig' instead of\n'django.contrib.admin'.