227 lines
7.3 KiB
Plaintext
227 lines
7.3 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`.
|
||
|
||
Django uses the default :class:`~django.apps.AppConfig` class when
|
||
:setting:`INSTALLED_APPS` simply contains the dotted path to an application
|
||
module.
|
||
|
||
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 would then tell your users to add ``'rock_n_roll.apps.RockNRollConfig'``
|
||
to their :setting:`INSTALLED_APPS`.
|
||
|
||
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.app 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.
|