アプリケーションLink to this heading#

For application authorsLink to this heading#

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 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 INSTALLED_APPS just contains 'rock_n_roll'. This allows you to make use of AppConfig features without requiring your users to update their INSTALLED_APPS setting. Besides this use case, it's best to avoid using default_app_config and instead specify the app config class in INSTALLED_APPS as described next.

Of course, you can also tell your users to put 'rock_n_roll.apps.RockNRollConfig' in their INSTALLED_APPS setting. You can even provide several different AppConfig subclasses with different behaviors and allow your users to choose one via their 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 name attribute for Django to determine which application this configuration applies to. You can define any attributes documented in the AppConfig API reference.

アプリケーションユーザー向けLink to this heading#

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.

Configurable attributesLink to this heading#

AppConfig.nameLink to this definition#

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.

Djangoプロジェクト全体の中で固有である必要があります。

AppConfig.labelLink to this definition#

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.

Djangoプロジェクト全体の中で固有である必要があります。

AppConfig.verbose_nameLink to this definition#

Human-readable name for the application, e.g. "Administration".

This attribute defaults to label.title().

AppConfig.pathLink to this definition#

Filesystem path to the application directory, e.g. '/usr/lib/python3.4/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.

読み取り専用属性Link to this heading#

AppConfig.moduleLink to this definition#

Root module for the application, e.g. <module 'django.contrib.admin' from 'django/contrib/admin/__init__.pyc'>.

AppConfig.models_moduleLink to this definition#

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.

メソッドLink to this heading#

AppConfig.get_models()Link to this definition#

Returns an iterable of Model classes for this application.

Requires the app registry to be fully populated.

AppConfig.get_model(model_name, require_ready=True)Link to this definition#

Returns the Model with the given model_name. model_name is case-insensitive.

Raises 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 apps.get_model().

AppConfig.ready()Link to this definition#

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 AppConfig classes are defined, you can import them in ready(), using either an import statement or get_model().

If you're registering model signals, you can refer to the sender by its string label instead of using the model class itself.

実装例:

Code

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')

Namespace packages as apps (Python 3.3+)Link to this heading#

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:

1. The namespace package actually has only a single location (i.e. is not spread across more than one directory.)

2. 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.

How applications are loadedLink to this heading#

When Django starts, django.setup() is responsible for populating the application registry.

setup(set_prefix=True)Link to this definition#

Configures Django by:

• Loading the settings.

• Setting up logging.

• If set_prefix is True, setting the URL resolver script prefix to 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.

The application registry is initialized in three stages. At each stage, Django processes all applications in the order of INSTALLED_APPS.

1. First Django imports each item in INSTALLED_APPS.

   If it's an application configuration class, Django imports the root package of the application, defined by its 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 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 get_app_config() become usable.

2. 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 get_model() become usable.

3. Finally Django runs the ready() method of each application configuration.

トラブルシューティングLink to this heading#

Here are some common problems that you may encounter during initialization:

• AppRegistryNotReady: This happens when importing an application configuration or a models module triggers code that depends on the app registry.

  For example, ugettext() uses the app registry to look up translation catalogs in applications. To translate at import time, you need ugettext_lazy() instead. (Using ugettext() 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 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 INSTALLED_APPS to contain 'django.contrib.admin.apps.SimpleAdminConfig' instead of 'django.contrib.admin'.