mirror of
https://github.com/django/django.git
synced 2024-12-23 17:46:27 +00:00
4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
479 lines
18 KiB
Plaintext
479 lines
18 KiB
Plaintext
============
|
||
Applications
|
||
============
|
||
|
||
.. module:: django.apps
|
||
|
||
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 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
|
||
'Administration'
|
||
|
||
Projects and applications
|
||
=========================
|
||
|
||
The term **project** describes a Django web application. The project Python
|
||
package is defined primarily by a settings module, but it usually contains
|
||
other things. For example, when you run ``django-admin startproject mysite``
|
||
you'll get a ``mysite`` project directory that contains a ``mysite`` Python
|
||
package with ``settings.py``, ``urls.py``, and ``wsgi.py``. The project package
|
||
is often extended to include things like fixtures, CSS, and templates which
|
||
aren't tied to a particular application.
|
||
|
||
A **project's root directory** (the one that contains ``manage.py``) is usually
|
||
the container for all of a project's applications which aren't installed
|
||
separately.
|
||
|
||
The term **application** describes a Python package that provides some set of
|
||
features. Applications :doc:`may be reused </intro/reusable-apps/>` in various
|
||
projects.
|
||
|
||
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` setting, or template
|
||
inheritance.
|
||
|
||
It is important to understand that a Django application is 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.
|
||
|
||
There's no restriction that a project package can't also be considered an
|
||
application and have models, etc. (which would require adding it to
|
||
:setting:`INSTALLED_APPS`).
|
||
|
||
.. _configuring-applications-ref:
|
||
|
||
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` 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.
|
||
|
||
``default_app_config`` allows applications that predate Django 1.7 such as
|
||
``django.contrib.admin`` to opt-in to :class:`~django.apps.AppConfig` features
|
||
without requiring users to update their :setting:`INSTALLED_APPS`.
|
||
|
||
New applications should avoid ``default_app_config``. Instead they should
|
||
require the dotted path to the appropriate :class:`~django.apps.AppConfig`
|
||
subclass to be configured explicitly in :setting:`INSTALLED_APPS`.
|
||
|
||
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`
|
||
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. Besides this use case, it's best to
|
||
avoid using ``default_app_config`` and instead specify the app config class in
|
||
:setting:`INSTALLED_APPS` as described next.
|
||
|
||
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.
|
||
|
||
.. note::
|
||
|
||
If your code imports the application registry in an application's
|
||
``__init__.py``, the name ``apps`` will clash with the ``apps`` submodule.
|
||
The best practice is to move that code to a submodule and import it. A
|
||
workaround is to import the registry under a different name::
|
||
|
||
from django.apps import apps as django_apps
|
||
|
||
For application users
|
||
---------------------
|
||
|
||
If you're using "Rock ’n’ roll" in a project called ``anthology``, but you
|
||
want it to show up as "Jazz Manouche" instead, you can provide your own
|
||
configuration::
|
||
|
||
# anthology/apps.py
|
||
|
||
from rock_n_roll.apps import RockNRollConfig
|
||
|
||
class JazzManoucheConfig(RockNRollConfig):
|
||
verbose_name = "Jazz Manouche"
|
||
|
||
# anthology/settings.py
|
||
|
||
INSTALLED_APPS = [
|
||
'anthology.apps.JazzManoucheConfig',
|
||
# ...
|
||
]
|
||
|
||
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 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.
|
||
|
||
.. attribute:: AppConfig.verbose_name
|
||
|
||
Human-readable name for the application, e.g. "Administration".
|
||
|
||
This attribute defaults to ``label.title()``.
|
||
|
||
.. attribute:: AppConfig.path
|
||
|
||
Filesystem path to the application directory, e.g.
|
||
``'/usr/lib/pythonX.Y/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
|
||
:class:`~django.apps.AppConfig` subclass. In a few situations this is
|
||
required; for instance if the app package is a `namespace package`_ with
|
||
multiple paths.
|
||
|
||
Read-only attributes
|
||
--------------------
|
||
|
||
.. attribute:: AppConfig.module
|
||
|
||
Root module for the application, e.g. ``<module 'django.contrib.admin' from
|
||
'django/contrib/admin/__init__.py'>``.
|
||
|
||
.. attribute:: AppConfig.models_module
|
||
|
||
Module containing the models, e.g. ``<module 'django.contrib.admin.models'
|
||
from 'django/contrib/admin/models.py'>``.
|
||
|
||
It may be ``None`` if the application doesn't contain a ``models`` module.
|
||
Note that the database related signals such as
|
||
:data:`~django.db.models.signals.pre_migrate` and
|
||
:data:`~django.db.models.signals.post_migrate`
|
||
are only emitted for applications that have a ``models`` module.
|
||
|
||
Methods
|
||
-------
|
||
|
||
.. method:: AppConfig.get_models()
|
||
|
||
Returns an iterable of :class:`~django.db.models.Model` classes for this
|
||
application.
|
||
|
||
Requires the app registry to be fully populated.
|
||
|
||
.. method:: AppConfig.get_model(model_name, require_ready=True)
|
||
|
||
Returns the :class:`~django.db.models.Model` with the given
|
||
``model_name``. ``model_name`` is case-insensitive.
|
||
|
||
Raises :exc:`LookupError` if no such model exists in this application.
|
||
|
||
Requires the app registry to be fully populated unless the
|
||
``require_ready`` argument is set to ``False``. ``require_ready`` behaves
|
||
exactly as in :meth:`apps.get_model()`.
|
||
|
||
.. 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.
|
||
|
||
Although you can't import models at the module-level where
|
||
:class:`~django.apps.AppConfig` classes are defined, you can import them in
|
||
``ready()``, using either an ``import`` statement or
|
||
:meth:`~AppConfig.get_model`.
|
||
|
||
If you're registering :mod:`model signals <django.db.models.signals>`, you
|
||
can refer to the sender by its string label instead of using the model
|
||
class itself.
|
||
|
||
Example::
|
||
|
||
from django.db.models.signals import pre_save
|
||
|
||
def ready(self):
|
||
# importing model classes
|
||
from .models import MyModel # or...
|
||
MyModel = self.get_model('MyModel')
|
||
|
||
# registering signals with the model's string label
|
||
pre_save.connect(receiver, sender='app_label.MyModel')
|
||
|
||
.. warning::
|
||
|
||
Although you can access model classes as described above, avoid
|
||
interacting with the database in your :meth:`ready()` implementation.
|
||
This includes model methods that execute queries
|
||
(:meth:`~django.db.models.Model.save()`,
|
||
:meth:`~django.db.models.Model.delete()`, manager methods etc.), and
|
||
also raw SQL queries via ``django.db.connection``. Your
|
||
:meth:`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!
|
||
|
||
.. note::
|
||
|
||
In the usual initialization process, the ``ready`` method is only called
|
||
once by Django. But in some corner cases, particularly in tests which
|
||
are fiddling with installed applications, ``ready`` might be called more
|
||
than once. In that case, either write idempotent methods, or put a flag
|
||
on your ``AppConfig`` classes to prevent re-running code which should
|
||
be executed exactly one time.
|
||
|
||
.. _namespace package:
|
||
|
||
Namespace packages as apps
|
||
--------------------------
|
||
|
||
Python packages without an ``__init__.py`` file 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 :class:`~django.apps.AppConfig` class used to configure the application
|
||
has a :attr:`~django.apps.AppConfig.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
|
||
:exc:`~django.core.exceptions.ImproperlyConfigured`.
|
||
|
||
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.
|
||
|
||
.. attribute:: apps.ready
|
||
|
||
Boolean attribute that is set to ``True`` after the registry is fully
|
||
populated and all :meth:`AppConfig.ready` methods are called.
|
||
|
||
.. 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:`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'``.
|
||
|
||
.. method:: apps.get_model(app_label, model_name, require_ready=True)
|
||
|
||
Returns the :class:`~django.db.models.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.
|
||
|
||
Raises :exc:`LookupError` if no such application or model exists. Raises
|
||
:exc:`ValueError` when called with a single argument that doesn't contain
|
||
exactly one dot.
|
||
|
||
Requires the app registry to be fully populated unless the
|
||
``require_ready`` argument is set to ``False``.
|
||
|
||
Setting ``require_ready`` to ``False`` allows looking up models
|
||
:ref:`while the app registry is being populated <app-loading-process>`,
|
||
specifically during the second phase where it imports models. Then
|
||
``get_model()`` has the same effect as importing the model. The main use
|
||
case is to configure model classes with settings, such as
|
||
:setting:`AUTH_USER_MODEL`.
|
||
|
||
When ``require_ready`` is ``False``, ``get_model()`` returns a model class
|
||
that may not be fully functional (reverse accessors may be missing, for
|
||
example) until the app registry is fully populated. For this reason, it's
|
||
best to leave ``require_ready`` to the default value of ``True`` whenever
|
||
possible.
|
||
|
||
.. _app-loading-process:
|
||
|
||
Initialization process
|
||
======================
|
||
|
||
How applications are loaded
|
||
---------------------------
|
||
|
||
When Django starts, :func:`django.setup()` is responsible for populating the
|
||
application registry.
|
||
|
||
.. currentmodule:: django
|
||
|
||
.. function:: setup(set_prefix=True)
|
||
|
||
Configures Django by:
|
||
|
||
* Loading the settings.
|
||
* Setting up logging.
|
||
* If ``set_prefix`` is True, setting the URL resolver script prefix to
|
||
:setting:`FORCE_SCRIPT_NAME` if defined, or ``/`` otherwise.
|
||
* Initializing the application registry.
|
||
|
||
This function is called automatically:
|
||
|
||
* When 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
|
||
scripts.
|
||
|
||
.. currentmodule:: django.apps
|
||
|
||
The application registry is initialized in three stages. At each stage, Django
|
||
processes all applications in the order of :setting:`INSTALLED_APPS`.
|
||
|
||
#. First Django imports each item in :setting:`INSTALLED_APPS`.
|
||
|
||
If it's an application configuration class, Django imports the root package
|
||
of the application, defined by its :attr:`~AppConfig.name` attribute. If
|
||
it's a Python package, Django creates a default application configuration.
|
||
|
||
*At this stage, your code shouldn't import any models!*
|
||
|
||
In other words, your applications' root packages and the modules that
|
||
define your application configuration classes shouldn't import any models,
|
||
even indirectly.
|
||
|
||
Strictly speaking, Django allows importing models once their application
|
||
configuration is loaded. However, in order to avoid needless constraints on
|
||
the order of :setting:`INSTALLED_APPS`, it's strongly recommended not
|
||
import any models at this stage.
|
||
|
||
Once this stage completes, APIs that operate on application configurations
|
||
such as :meth:`~apps.get_app_config()` become usable.
|
||
|
||
#. Then Django attempts to import the ``models`` submodule of each application,
|
||
if there is one.
|
||
|
||
You must define or import all models in your application's ``models.py`` or
|
||
``models/__init__.py``. Otherwise, the application registry may not be fully
|
||
populated at this point, which could cause the ORM to malfunction.
|
||
|
||
Once this stage completes, APIs that operate on models such as
|
||
:meth:`~apps.get_model()` become usable.
|
||
|
||
#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application
|
||
configuration.
|
||
|
||
.. _applications-troubleshooting:
|
||
|
||
Troubleshooting
|
||
---------------
|
||
|
||
Here are some common problems that you may encounter during initialization:
|
||
|
||
* :class:`~django.core.exceptions.AppRegistryNotReady`: This happens when
|
||
importing an application configuration or a models module triggers code that
|
||
depends on the app registry.
|
||
|
||
For example, :func:`~django.utils.translation.gettext()` uses the app
|
||
registry to look up translation catalogs in applications. To translate at
|
||
import time, you need :func:`~django.utils.translation.gettext_lazy()`
|
||
instead. (Using :func:`~django.utils.translation.gettext()` would be a bug,
|
||
because the translation would happen at import time, rather than at each
|
||
request depending on the active language.)
|
||
|
||
Executing database queries with the ORM at import time in models modules
|
||
will also trigger this exception. The ORM cannot function properly until all
|
||
models are available.
|
||
|
||
This exception also happens if you forget to call :func:`django.setup()` in
|
||
a standalone Python script.
|
||
|
||
* ``ImportError: cannot import name ...`` This happens if the import sequence
|
||
ends up in a loop.
|
||
|
||
To eliminate such problems, you should minimize dependencies between your
|
||
models modules and do as little work as possible at import time. To avoid
|
||
executing code at import time, you can move it into a function and cache its
|
||
results. The code will be executed when you first need its results. This
|
||
concept is known as "lazy evaluation".
|
||
|
||
* ``django.contrib.admin`` automatically performs autodiscovery of ``admin``
|
||
modules in installed applications. To prevent it, change your
|
||
:setting:`INSTALLED_APPS` to contain
|
||
``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of
|
||
``'django.contrib.admin'``.
|