mirror of
https://github.com/django/django.git
synced 2024-11-18 07:26:04 +00:00
2ff93e027c
Thanks Russell for the report, Marc for the initial patch, Carl for the final review, and everyone who contributed to the design discussion.
248 lines
8.2 KiB
Plaintext
248 lines
8.2 KiB
Plaintext
============
|
||
Applications
|
||
============
|
||
|
||
.. module:: django.apps
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
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
|
||
'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.
|
||
|
||
.. note::
|
||
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 :setting:`INSTALLED_APPS` setting and optionally with other
|
||
mechanisms such as URLconfs, the :setting:`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
|
||
:class:`~django.apps.AppConfig` instance for each installed application.
|
||
|
||
Configuring applications
|
||
========================
|
||
|
||
To configure an application, subclass :class:`~django.apps.AppConfig` and put
|
||
the dotted path to that subclass in :setting:`INSTALLED_APPS`.
|
||
|
||
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.
|
||
|
||
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::
|
||
|
||
# rock_n_roll/apps.py
|
||
|
||
from django.apps import AppConfig
|
||
|
||
class RockNRollConfig(AppConfig):
|
||
name = 'rock_n_roll'
|
||
verbose_name = "Rock ’n’ roll"
|
||
|
||
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
|
||
update their :setting:`INSTALLED_APPS` setting.
|
||
|
||
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.
|
||
|
||
The recommended convention is to put the configuration class in a submodule of
|
||
the application called ``apps``. However, this isn't enforced by Django.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Application configuration
|
||
=========================
|
||
|
||
.. class:: AppConfig
|
||
|
||
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
|
||
-----------------------
|
||
|
||
.. attribute:: AppConfig.name
|
||
|
||
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 :class:`~django.apps.AppConfig` subclasses.
|
||
|
||
It must be unique across a Django project.
|
||
|
||
.. attribute:: AppConfig.label
|
||
|
||
Short name for the application, e.g. ``'admin'``
|
||
|
||
This attribute allows relabelling 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.
|
||
|
||
.. attribute:: AppConfig.verbose_name
|
||
|
||
Human-readable name for the application, e.g. "Admin".
|
||
|
||
This attribute defaults to ``label.title()``.
|
||
|
||
Read-only attributes
|
||
--------------------
|
||
|
||
.. attribute:: AppConfig.path
|
||
|
||
Filesystem path to the application directory, e.g.
|
||
``'/usr/lib/python2.7/dist-packages/django/contrib/admin'``.
|
||
|
||
It may be ``None`` if the application isn't stored in a directory, for
|
||
instance if it's loaded from an egg.
|
||
|
||
.. attribute:: AppConfig.module
|
||
|
||
Root module for the application, e.g. ``<module 'django.contrib.admin' from
|
||
'django/contrib/admin/__init__.pyc'>``.
|
||
|
||
.. attribute:: AppConfig.models_module
|
||
|
||
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.
|
||
|
||
Methods
|
||
-------
|
||
|
||
.. method:: AppConfig.get_models()
|
||
|
||
Returns an iterable of :class:`~django.db.models.Model` classes.
|
||
|
||
.. method:: AppConfig.get_model(model_name)
|
||
|
||
Returns the :class:`~django.db.models.Model` with the given
|
||
``model_name``. Raises :exc:`~exceptions.LookupError` if no such model
|
||
exists. ``model_name`` is case-insensitive.
|
||
|
||
.. method:: AppConfig.ready()
|
||
|
||
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 :meth:`get_model` to access a model class by
|
||
name, like this::
|
||
|
||
def ready(self):
|
||
MyModel = self.get_model('MyModel')
|
||
|
||
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.
|
||
|
||
.. method:: apps.ready()
|
||
|
||
Returns ``True`` if the registry is fully populated.
|
||
|
||
.. method:: apps.get_app_configs()
|
||
|
||
Returns an iterable of :class:`~django.apps.AppConfig` instances.
|
||
|
||
.. method:: apps.get_app_config(app_label)
|
||
|
||
Returns an :class:`~django.apps.AppConfig` for the application with the
|
||
given ``app_label``. Raises :exc:`~exceptions.LookupError` if no such
|
||
application exists.
|
||
|
||
.. method:: apps.is_installed(app_name)
|
||
|
||
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 :meth:`~django.apps.apps.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.
|
||
|
||
.. method:: apps.get_model(app_label, model_name)
|
||
|
||
Returns the :class:`~django.db.models.Model` with the given ``app_label``
|
||
and ``model_name``. Raises :exc:`~exceptions.LookupError` if no such
|
||
application or model exists. ``model_name`` is case-insensitive.
|