django/docs/ref/applications.txt

211 lines
6.9 KiB
Plaintext
Raw Normal View History

============
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/app.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.app.RockNRollConfig'`` to
their :setting:`INSTALLED_APPS`.
The recommended convention is to put the configuration class in a submodule of
the application called ``app``. 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.verbose_name
Human-readable name for the application, e.g. "Admin".
If this isn't provided, Django uses ``label.title()``.
Read-only attributes
--------------------
.. attribute:: AppConfig.name
Full Python path to the application, e.g. ``'django.contrib.admin'``.
.. attribute:: AppConfig.label
Last component of the Python path to the application, e.g. ``'admin'``.
This value must be unique across a Django project.
.. 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
-------
2013-12-30 03:26:13 +08:00
.. 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.
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(only_with_models_module=False)
Returns an iterable of :class:`~django.apps.AppConfig` instances.
If only applications containing a models module are of interest, this method
can be called with ``only_with_models_module=True``.
.. method:: apps.get_app_config(app_label, only_with_models_module=False)
Returns an :class:`~django.apps.AppConfig` for the application with the
given ``app_label``. Raises :exc:`~exceptions.LookupError` if no such
application exists.
If only applications containing a models module are of interest, this method
can be called with ``only_with_models_module=True``.
.. method:: apps.has_app(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.