- Documentation version: development
Django contains a registry of installed applications that stores configuration and provides introspection. It also maintains a list of available models.
>>> from django.apps import apps >>> apps.get_app_config('admin').verbose_name 'Admin'
Projects and applications¶
Django has historically used the term project to describe an installation of Django. A project is defined primarily by a settings module.
The term application describes a Python package that provides some set of features. Applications may be reused in various projects.
This terminology is somewhat confusing these days as it became common to use the phrase “web app” to describe what equates to a Django project.
Applications include some combination of models, views, templates, template tags, static files, URLs, middleware, etc. They’re generally wired into projects with the INSTALLED_APPS setting and optionally with other mechanisms such as URLconfs, the MIDDLEWARE_CLASSES setting, or template inheritance.
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 AppConfig instance for each installed application.
When 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 AppConfig subclass for that application.
If there is no default_app_config, Django uses the base AppConfig class.
For application users¶
If you’re using “Rock ’n’ roll” in a project called anthology, but you want it to show up as “Gypsy jazz” instead, you can provide your own configuration:
# anthology/apps.py from rock_n_roll.apps import RockNRollConfig class GypsyJazzConfig(RockNRollConfig): verbose_name = "Gypsy jazz" # anthology/settings.py INSTALLED_APPS = [ 'anthology.apps.GypsyJazzConfig', # ... ]
Again, defining project-specific configuration classes in a submodule called apps is a convention, not a requirement.
- class AppConfig¶
Application configuration objects store metadata for an application. Some attributes can be configured in AppConfig subclasses. 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 must be set in all AppConfig subclasses.
It must be unique across a Django project.
Short name for the application, e.g. 'admin'
This attribute allows relabeling an application when two applications 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.
Human-readable name for the application, e.g. “Admin”.
This attribute defaults to label.title().
Filesystem path to the application directory, e.g. '/usr/lib/python2.7/dist-packages/django/contrib/admin'.
In most cases, Django can automatically detect and set this, but you can also provide an explicit override as a class attribute on your AppConfig subclass. In a few situations this is required; for instance if the app package is a namespace package with multiple paths.
Root module for the application, e.g. <module 'django.contrib.admin' from 'django/contrib/admin/__init__.pyc'>.
Module containing the models, e.g. <module 'django.contrib.admin.models' from 'django/contrib/admin/models.pyc'>.
It may be None if the application doesn’t contain a models module. Note that the database related signals such as pre_migrate and post_migrate are only emitted for applications that have a models module.
Subclasses can override this method to perform initialization tasks such as registering signals. It is called as soon as the registry is fully populated.
You cannot import models in modules that define application configuration classes, but you can use get_model() to access a model class by name, like this:
def ready(self): MyModel = self.get_model('MyModel')
Although you can access model classes as described above, avoid interacting with the database in your ready() implementation. This includes model methods that execute queries (save(), delete(), manager methods etc.), and also raw SQL queries via django.db.connection. Your 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!
Namespace packages as apps (Python 3.3+)¶
Python versions 3.3 and later support Python packages without an __init__.py file. These packages are known as “namespace packages” and may be spread across multiple directories at different locations on sys.path (see PEP 420).
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:
- The namespace package actually has only a single location (i.e. is not spread across more than one directory.)
- The AppConfig class used to configure the application has a 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 ImproperlyConfigured.
The application registry provides the following public API. Methods that aren’t listed below are considered private and may change without notice.
Boolean attribute that is set to True when the registry is fully populated.
Checks whether an application with the given name exists in the registry. app_name is the full name of the app, e.g. 'django.contrib.admin'.
Unlike get_app_config(), this method can be called safely at import time. If the registry is still being populated, it may return False, even though the app will become available later.
- apps.get_model(app_label, model_name)¶
Returns the Model with the given app_label and model_name. As a shortcut, this method also accepts a single argument in the form app_label.model_name. model_name is case- insensitive.
Having trouble? We'd like to help!
- Try the FAQ — it's got answers to many common questions.
- Search for information in the archives of the django-users mailing list, or post a question.
- Ask a question in the #django IRC channel, or search the IRC logs to see if it has been asked before.
- If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, use the resources above.