# Django 6.0.7 문서

# 애플리케이션

Django는 설치된 어플리케이션에 대한 설정과 인트로스펙션을 저장하는 레지스트리를 가지고 있습니다. 이는 또한 사용 가능한 :doc:`모델</topics/db/models>`의 리스트를 관리합니다.

이 레지스트리는 `apps`::로 접근 가능합니다.

    >>> from django.apps import apps
    >>> apps.get_app_config("admin").verbose_name
    'Administration'

## 프로젝트와 어플리케이션

프로젝트는 장고 웹 애플리케이션을 지칭합니다. 파이썬 표준 모듈은 settings에 대부분 정의되어 있지만, 비표준 모듈들도 포함되어 있습니다. 예를 들어 “django-admin startproject mysite”를 실행한다면 “mysite” 디렉터리가 생성될 것이며 “mysite” 디렉터리 안에는 “settings.py”, “urls.py”, “asgi.py”, “wsgi.py”가 파이썬 패키지와 함께 설치되어 있을 것입니다. 때로는 프로젝트 패키지가 CSS, 템플릿이 특정 애플리케이션에 종속되지 않도록 확장되기도 합니다.

프로젝트의 최상위 디렉토리 (``manage.py``를 포함하고 있는 디렉토리)는 보통 따로 설치되지 않은 프로젝트의 어플리케이션을 포함하는 컨테이너 역할을 합니다.

애플리케이션이라는 용어는 몇 가지 파이썬 패키지의 모음이라고 설명할 수 있습니다. :doc:애플리케이션은</intro/reusable-apps/> 다양한 프로젝트에서 재사용 될 수 있습니다.

애플리케이션은 모델, 뷰, 템플릿, 템플릿 태그, 정적 파일, URLs, 미들웨어 등의 조합을 포함합니다. 일반적으로 `INSTALLED_APPS` 설정으로 프로젝트에 묶여있고 선택적으로 URLconfs, `MIDDLEWARE` 설정, 또는 템플릿 상속과 같은 메커니즘으로 묶입니다.

Django 애플리케이션은 프레임워크의 다양한 부분과 상호 작용하는 코드 집합이라는 점을 이해하는 것이 중요합니다. `Application` 객체와 같은 것은 없습니다. 그러나 Django가 주로 구성 및 검사를 위해 설치된 응용 프로그램과 상호 작용해야 하는 곳이 몇 군데 있습니다. 이것이 애플리케이션 레지스트리가 설치된 각 애플리케이션에 대한 메타데이터를 `AppConfig` 인스턴스에 유지하는 이유입니다.

프로젝트 패키지가 애플리케이션으로 고려되거나 모델을 가질 수 없다는 제한이 없습니다. (물론 설정에있는 `INSTALLED_APPS`에 값을 추가해야 합니다).

## 애플리케이션 설정하기

애플리케이션을 생성하려면, 애플리케이션 안에 “apps,py”모듈을 생성하고, 그곳에서 :class:`AppConfig`의 서브클래스를 정의하십시오.

`INSTALLED_APPS`에 애플리케이션 모듈에 대한 점선 경로가 포함되어 있을 때, 기본적으로 Django가 ``apps.py`` 하위 모듈에서 정확히 하나의 `AppConfig` 하위 클래스를 찾으면, 해당 구성을 애플리케이션에 사용합니다. 이 동작은 attr:`AppConfig.default`를 ``False``로 설정하여 비활성화할 수 있습니다.

`apps.py` 모듈이 하나 이상의 `AppConfig` 하위 클래스를 포함하는 경우 Django는 :attr:`AppConfig.default`가 ``True``인 단일 하위 클래스를 찾습니다.

`AppConfig` 하위 클래스가 없으면 기본 `AppConfig` 클래스가 사용됩니다.

또는, :setting:`INSTALLED_APPS`에 구성 클래스에 대한 점선 경로를 포함하여 명시적으로 지정할 수 있습니다.

    INSTALLED_APPS = [
        ...,
        "polls.apps.PollsAppConfig",
        ...,
    ]

### 애플리케이션 제작자의 경우

“Rock ‘n’ roll”이라는 플러그형 앱을 만드는 경우, 관리자에게 적절한 이름을 제공하는 방법은 다음과 같습니다:

    # rock_n_roll/apps.py

    from django.apps import AppConfig

    class RockNRollConfig(AppConfig):
        name = "rock_n_roll"
        verbose_name = "Rock ’n’ roll"

``RockNRollConfig``는 `INSTALLED_APPS`에 ``’rock_n_roll’``이 포함되어 있을 때 자동으로 로드됩니다. 이를 방지하려면, 클래스 정의에서 :attr:`~AppConfig.default`를 ``False``로 설정하십시오.

동작이 다른 여러 가지 `AppConfig` 하위 클래스를 사용할 수 있습니다. 기본값으로 사용할 것이 어떤 것인지를 Django에 알리려면, `사용자가 기본이 아닌 구성을 선택하려는 경우, :setting:`INSTALLED_APPS` 설정에서 ``’rock_n_roll’``을 해당 특정 클래스에 대한 점선 경로로 바꿔야 합니다.

`AppConfig.name` 속성은 이 구성이 적용되는 애플리케이션을 Django에 알려줍니다. `AppConfig` API 참조에 문서화된 다른 속성을 정의할 수 있습니다.

`AppConfig` 하위 클래스는 어디에서나 정의할 수 있습니다. `apps.py` 규칙은 설정 클래스에 대한 경로가 아닌 애플리케이션 모듈에 대한 경로를 포함할 때 Django가 자동으로 로드하도록 허용할 뿐입니다.

참고

코드가 애플리케이션의 `__init__.py``에서 애플리케이션 레지스트리를 가져오면, ``apps``라는 이름이 ``apps` 하위 모듈과 충돌합니다. 가장 좋은 방법은 해당 코드를 하위 모듈로 이동하고 가져오는 것입니다. 다른 해결 방법은 다른 이름으로 레지스트리를 가져오는 것입니다:

    from django.apps import apps as django_apps

### 애플리케이션 사용자의 경우

``anthology``라는 프로젝트에서 “Rock ‘n’ roll”을 사용하고 있지만 대신 “Jazz Manouche”로 표시하고 싶다면, 다음과 같이 고유한 구성을 제공할 수 있습니다:

    # 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",
        # ...
    ]

이 예제는 ``apps.py``라는 하위 모듈에 있는 프로젝트별 구성 클래스를 보여줍니다. 이것은 규칙이지 요구 사항이 아닙니다. `AppConfig` 하위 클래스는 어디에서나 정의할 수 있습니다.

이 상황에서, :setting:`INSTALLED_APPS`는 구성 클래스에 점선 경로를 포함해야 합니다. 왜냐하면 애플리케이션 외부에 있으므로 자동으로 감지할 수 없기 때문입니다.

## 애플리케이션 설정

class AppConfig

  애플리케이션 구성 개체는 애플리케이션에 대한 메타데이터를 저장합니다. 일부 속성은 `AppConfig` 하위 클래스에서 구성할 수 있습니다. 다른 것들은 Django에 의해 설정되고 읽기 전용입니다.

### 구성 가능한 속성들

AppConfig.name

  애플리케이션에 대한 전체 Python 경로, 예: `'django.contrib.admin'`.

  이 속성은 구성이 적용되는 애플리케이션을 정의합니다. 모든 `AppConfig` 하위 클래스에서 설정해야 합니다.

  Django 프로젝트 전체에서 고유한 값이어야 합니다.

AppConfig.label

  애플리케이션을 위한 짧은 이름, 예를 들어 “admin”

  이 속성을 사용하면, 두 애플리케이션의 레이블이 충돌하는 경우 애플리케이션의 레이블을 다시 지정할 수 있습니다. 기본값은 ``name``의 마지막 구성 요소이며, 이는 유효한 파이썬 식별자여야 합니다.

  Django 프로젝트 전체에서 고유한 값이어야 합니다.

  경고

  마이그레이션이 적용된 후 이 속성을 변경하면 프로젝트에 호환성 문제가 발생할 수 있으며, 재사용 가능한 앱의 경우 기존에 설치된 앱에서도 문제가 생길 수 있습니다. 이는 ``AppConfig.label``이 의존성 목록에서 앱을 참조할 때 데이터베이스 테이블과 마이그레이션 파일에 사용되기 때문입니다.

AppConfig.verbose_name

  사람이 읽을 수 있는 애플리케이션의 이름, 예를 들어 “Administration”

  이 속성의 디폴트 값은 `label.title()` 입니다.

AppConfig.path

  애플리케이션 디렉토리에 대한 파일 시스템 경로, 예: `'/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'`.

  대부분의 경우, Django는 이를 자동으로 감지하고 설정할 수 있지만, ~django.apps.AppConfig` 하위 클래스의 클래스 속성으로 명시적 재정의를 제공할 수도 있습니다. 몇 가지 상황에서 이것이 필요합니다. 예를 들어 앱 패키지가 여러 경로를 포함하는 `네임스페이스 패키지`_인 경우입니다.

AppConfig.default

  이 속성을 ``False``로 설정하여 Django가 구성 클래스를 자동으로 선택하지 않도록 합니다. 이는 ``apps.py``가 하나의 `AppConfig` 하위 클래스만 정의하지만, Django 기본값을 원하지 않을 때 유용합니다.

  이 속성을 ``True``로 설정하여 Django가 구성 클래스를 자동으로 선택하도록 합니다. 이는 ``apps.py``가 하나 이상의 `AppConfig` 하위 클래스를 정의하고 Django가 기본값으로 그 중 하나를 사용하기를 원할 때 유용합니다.

  기본적으로, 이 속성은 설정되지 않습니다.

AppConfig.default_auto_field

  이 앱의 모델에 자동으로 추가되는 기본 키 유형입니다.

  모델을 정의하는 재사용 가능한 애플리케이션은 애플리케이션에 포함된 마이그레이션이 모델과 일치하도록 반드시 이 속성을 설정해야 합니다. 그렇지 않으면 사용자가 :setting:`DEFAULT_AUTO_FIELD`를 다르게 설정한 상태에서 :djadmin:`makemigrations`를 실행할 때 해당 애플리케이션에 대한 마이그레이션이 생성될 수 있으며, 이는 애플리케이션에서 이후 제공하는 마이그레이션과 충돌할 수 있습니다.

  예를 들어 `AutoField` 클래스를 계속 사용하려면:

      default_auto_field = "django.db.models.AutoField"

  기본적으로 이는 :setting:`DEFAULT_AUTO_FIELD`의 값입니다.

### 읽기 전용 속성

AppConfig.module

  응용 프로그램의 루트 모듈, 예: `<module 'django.contrib.admin' from 'django/contrib/admin/__init__.py'>`.

AppConfig.models_module

  모델을 포함하는 모듈, 예. `<module 'django.contrib.admin.models' from 'django/contrib/admin/models.py'>`.

  애플리케이션에 `models` 모듈이 포함되어 있지 않으면 `None` 일 수 있습니다. `pre_migrate` 및 `post_migrate`와 같은 데이터베이스 관련 신호는 ``models`` 모듈이 있는 응용 프로그램에 대해서만 방출됩니다.

### 메소드

AppConfig.get_models(include_auto_created=False, include_swapped=False)

  이 애플리케이션에 대한 클래스:~django.db.models.Model 클래스의 이터러블을 반환합니다.

  앱 레지스트리가 완전히 채워져야 합니다.

AppConfig.get_model(model_name, require_ready=True)

  주어진 ``model_name``과 함께 :class:`~django.db.models.Model`을 반환합니다. ``model_name``은 대소문자를 구분하지 않습니다.

  이 애플리케이션에 해당 모델이 없으면 :exc:`LookupError`가 발생합니다.

  `require_ready` 인자가 ``False``로 설정되지 않은 한, 앱 레지스트리가 완전히 로드되어 있어야 합니다. ``require_ready``는 :meth:`apps.get_model`에서와 동일하게 동작합니다.

AppConfig.ready()

  서브클래스는 시그널 등록과 같은 초기화 작업을 수행하기 위해 이 메서드를 재정의할 수 있습니다. 이 메서드는 레지스트리가 완전히 채워지는 즉시 호출됩니다.

  `AppConfig` 클래스가 정의된 모듈 수준의 모델을 import 할 수는 없지만, `ready()``에서 ``import` 문 또는 :meth:`~AppConfig.get_model`을 사용해 import 할 수 있습니다.

  :mod:`모델 신호 <django.db.models.signals>`를 등록하는 경우, 모델 클래스 자체를 사용하는 대신 문자열 레이블로 발신자를 참조할 수 있습니다.

  예제:

      from django.apps import AppConfig
      from django.db.models.signals import pre_save

      class RockNRollConfig(AppConfig):
          # ...

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

  경고

  위에서 설명한 대로 모델 클래스에 접근할 수 있지만, `ready()` 구현에서는 데이터베이스와 상호 작용하지 마십시오. 여기에는 쿼리를 실행하는 모델 메서드(`save()`, `delete()`, 매니저 메소드 등)와 ``django.db.connection``을 통한 원시 SQL 쿼리도 포함됩니다. `ready()` 메서드는 모든 관리 명령이 시작될 때마다 실행됩니다. 예를 들어, 테스트 데이터베이스 구성이 프로덕션 설정과 분리되어 있더라도 ``manage.py test``는 여전히 프로덕션 데이터베이스에 대해 일부 쿼리를 실행합니다!

  참고

  일반적인 초기화 과정에서, `ready` 메서드는 Django에 의해 한 번만 호출됩니다. 그러나 일부 특수한 경우, 특히 설치된 응용 프로그램을 만지작거리는 테스트에서는 `ready``가 두 번 이상 호출될 수 있습니다. 이 경우 idempotent 메서드를 작성하거나 ``AppConfig` 클래스에 플래그를 지정하여 정확히 한 번만 실행되어야 하는 코드를 다시 실행하지 않도록 합니다.

### 앱으로서의 네임스페이스 패키지

`__init__.py` 파일이 없는 파이썬 패키지는 “네임스페이스 패키지”로 알려져 있으며 ``sys.path``의 여러 위치에 있는 여러 디렉토리에 분산될 수 있습니다(PEP 420 참조).

Django 애플리케이션에는 Django(구성에 따라 다름)가 템플릿, 정적 자산 등을 검색하는 단일 기본 파일 시스템 경로가 필요합니다. 따라서 네임스페이스 패키지는 다음 중 하나가 참인 경우에만 Django 애플리케이션일 수 있습니다.

1. 네임스페이스 패키지는 실제로 단일 위치만 갖습니다(즉, 둘 이상의 디렉토리에 분산되지 않음).

2. 애플리케이션을 구성하는 데 사용되는 `AppConfig` 클래스에는 Django가 어플리케이션을 위한 단일 기본 경로로 사용할 절대 디렉토리 경로인 `path` 클래스 속성이 있습니다.

이러한 조건 중 어느 것도 충족되지 않으면, Django는 :exc:`~django.core.exceptions.ImproperlyConfigured`를 발생시킵니다.

## 애플리케이션 레지스트리

apps

  애플리케이션 레지스트리는 다음 공용 API를 제공합니다. 아래에 나열되지 않은 메서드는 비공개로 간주되며 예고 없이 변경될 수 있습니다.

apps.ready

  레지스트리가 완전히 채워지고 모든 AppConfig.ready 메서드가 호출된 후 ``True``로 설정되는 Boolean 속성입니다.

apps.get_app_configs()

  `AppConfig` 인스턴스의 이터러블을 반환합니다.

apps.get_app_config(app_label)

  주어진 ``app_label``이 있는 애플리케이션에 대해 :class:`~django.apps.AppConfig`를 반환합니다. 그러한 애플리케이션이 존재하지 않으면 :exc:`LookupError`를 발생시킵니다.

apps.is_installed(app_name)

  지정된 이름의 애플리케이션이 레지스트리에 있는지 확인합니다. `app_name``은 앱의 전체 이름입니다, 예를 들어`’django.contrib.admin’``.

apps.get_model(app_label, model_name, require_ready=True)

  주어진 `app_label` 및 `model_name``으로 :class:`~django.db.models.Model`을 반환합니다. 바로 가기로 이 메서드는 ``app_label.model_name` 형식의 단일 인수도 허용합니다. ``model_name``은 대소문자를 구분하지 않습니다.

  그러한 애플리케이션이나 모델이 존재하지 않으면 :exc:`LookupError`를 발생시킵니다. 정확히 하나의 점을 포함하지 않는 단일 인수로 호출하면 :exc:`ValueError`가 발생합니다.

  `require_ready` 인수가 ``False``로 설정되지 않은 한 앱 레지스트리가 완전히 채워져야 합니다.

  ``require_ready``를 ``False``로 설정하면 앱 레지스트리가 채워지는 동안, 특히 모델을 가져오는 두 번째 단계에서 모델을 조회할 수 있습니다. 그러면 ``get_model()``은 모델을 가져오는 것과 같은 효과가 있습니다. 주요 사용 사례는 :setting:`AUTH_USER_MODEL`과 같은 설정으로 모델 클래스를 구성하는 것입니다.

  ``require_ready``가 ``False``인 경우, ``get_model()``은 앱 레지스트리가 완전히 채워질 때까지 부분적으로만 작동할 수 있는(예: 역 접근자가 누락될 수 있음) 모델 클래스를 반환합니다. 이러한 이유로, 가능하면 ``require_ready``를 기본값인 ``True``로 두는 것이 가장 좋습니다.

## 초기화 프로세스

### 애플리케이션이 로드되는 방식

Django가 시작될 때 :func:`django.setup`이 애플리케이션 레지스트리를 채우는 역할을 합니다.

setup(set_prefix=True)

  다음을 통해 Django를 구성합니다:

  - 설정들을 로딩중

  - 로깅 설정.

  - ``set_prefix``가 True인 경우, URL 해석기 스크립트 접두어를 `FORCE_SCRIPT_NAME`(정의된 경우) 또는 ``/``로 설정합니다.

  - 애플리케이션 레지스트리 초기화 중

  이 함수는 자동으로 호출 됩니다:

  - Django의 ASGI 또는 WSGI 지원을 통해 서버를 실행하는 경우.

  - 관리 명령어를 실행할 때

  다른 경우(예를 들어 일반 Python 스크립트)에는, 명시적으로 호출해야 합니다.

애플리케이션 레지스트리는 3단계로 초기화됩니다. 각 단계에서 Django는 설정:`INSTALLED_APPS`의 순서로 모든 애플리케이션을 처리합니다.

1. 먼저 Django는 :setting:`INSTALLED_APPS`에서 각 항목을 가져옵니다.

   애플리케이션 구성 클래스인 경우, Django는 `name` 속성으로 정의된 애플리케이션의 루트 패키지를 가져옵니다. Python 패키지인 경우 Django는 `apps.py` 하위 모듈에서 애플리케이션 구성을 찾거나 기본값 애플리케이션 구성을 만듭니다.

   이 단계에서, 코드는 어떤 모델도 가져오지 않아야 합니다!

   즉, 애플리케이션의 루트 패키지와 애플리케이션 구성 클래스를 정의하는 모듈은 모델을 간접적으로라도 가져오면 안 됩니다.

   엄밀히 말하면, Django는 애플리케이션 구성이 로드되면 모델을 가져올 수 있습니다. 그러나 :setting:’INSTALLED_APPS’ 순서에 대한 불필요한 제약을 피하기 위해 이 단계에서 모델을 가져오지 않는 것이 좋습니다.

   이 단계가 완료되면 :meth:`~apps.get_app_config`와 같은 애플리케이션 구성을 대상으로 동작하는 API를 사용할 수 있습니다.

2. 그런 다음 Django는 각 애플리케이션의 `models` 하위 모듈(있는 경우)을 가져오려고 시도합니다.

   애플리케이션의 `models.py` 또는 ``models/__init__.py``에서 모든 모델을 정의하거나 가져와야 합니다. 그렇지 않으면 이 시점에서 응용 프로그램 레지스트리가 완전히 채워지지 않아 ORM이 오작동할 수 있습니다.

   이 단계가 완료되면 :meth:`~apps.get_model`과 같이 모델을 대상으로 동작하는 API를 사용할 수 있습니다.

3. 마지막으로 Django는 각 애플리케이션 구성의 `ready()` 메서드를 실행합니다.

### 문제해결

다음은 초기화 중에 발생할 수 있는 몇 가지 일반적인 문제입니다:

- `AppRegistryNotReady`: 애플리케이션 구성을 가져오거나 모델 모듈이 앱 레지스트리에 의존하는 코드를 트리거할 때 발생합니다.

  예를 들어 :func:`~django.utils.translation.gettext`는 앱 레지스트리를 사용하여 애플리케이션에서 번역 카탈로그를 조회합니다. 임포트 시점에 번역하려면 대신 :func:`~django.utils.translation.gettext_lazy`를 사용해야 합니다. (:func:`~django.utils.translation.gettext`사용하면 버그입니다. 활성화된 언어에 따라 각 요청 시점이 아닌 임포트 시점에 번역이 수행되기 때문입니다.)

  모델 모듈에서 가져올 때 ORM으로 데이터베이스 쿼리를 실행하면 이 예외가 트리거됩니다. ORM은 모든 모델을 사용할 수 있을 때까지 제대로 작동하지 않습니다.

  독립적으로 실행하는 Python 스크립트에서는 :func:`django.setup`을 호출하지 않으면 이 예외가 발생할 수 있습니다.

- `ImportError: can import name ...` 가져오기 시퀀스가 루프에서 끝나는 경우에 발생합니다.

  이러한 문제를 제거하려면, 모델 모듈 간의 종속성을 최소화하고 가져올 때 가능한 한 적은 작업을 수행해야 합니다. 가져올 때 코드를 실행하지 않으려면, 코드를 함수로 이동하고 결과를 캐시할 수 있습니다. 결과가 처음 필요할 때 코드가 실행됩니다. 이 개념을 “게으른 평가”라고 합니다.

- `django.contrib.admin``은 설치된 애플리케이션에서 ``admin` 모듈의 자동 검색을 자동으로 수행합니다. 이를 방지하려면 `'django.contrib.admin'` 대신 ``’django.contrib.admin.apps.SimpleAdminConfig’``를 포함하도록 :setting:`INSTALLED_APPS`를 변경하십시오.

- `RuntimeWarning: Accessing the database during app initialization is discouraged.` 이 경고는 앱이 준비되기 전에 실행되는 데이터베이스 쿼리에서 발생합니다. 예를 들어 모듈 임포트 중이나 `AppConfig.ready()` 메서드에서 실행되는 경우입니다. 이러한 조기 데이터베이스 쿼리는 권장되지 않습니다. 이는 모든 관리 명령이 시작될 때마다 실행되어 프로젝트 시작 속도를 저하시킬 수 있고, 오래된 데이터를 캐시할 수 있으며, 마이그레이션이 대기 중인 경우 오류가 발생할 수도 있기 때문입니다.

  예를 들어, 가장 흔한 실수는 폼 필드의 선택 항목을 얻기 위해 데이터베이스 쿼리를 만드는 일입니다.

      class LocationForm(forms.Form):
          country = forms.ChoiceField(choices=[c.name for c in Country.objects.all()])

  위 예시에서 `Country.objects.all()` 쿼리는 ``QuerySet``이 반복되기 때문에 모듈 임포트 중에 실행됩니다. 이 경고를 피하려면 폼에서 :class:`~django.forms.ModelChoiceField`를 사용하는 것이 좋습니다:

      class LocationForm(forms.Form):
          country = forms.ModelChoiceField(queryset=Country.objects.all())

  이 경고를 유발한 코드를 더 쉽게 찾으려면 Python에서 :ref:`경고를 오류로 처리하도록 설정 <python:warning-filter>`하여 스택 트레이스를 확인할 수 있습니다. 예를 들어 ``python -Werror manage.py shell``을 실행할 수 있습니다.