# Dokumentasi Django 5.2.8

# Aplikasi

Django mengandung sebuah registrar dari aplikasi terpasang yang menyimpan konfigurasi dan menyediakan introspeksi. Dia juga merawat daftar dari ketersediaan models.

Registri memanggil `apps` dan tersedia dalam `django.apps`:

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

## Proyek dan aplikasi

Istilah proyek menggambarkan sebuah aplikasi jaringan Django. Proyek paket Python ditentukan terutama dengan mengatur modul, tetapi biasanya mengandung hal lain. Sebagai contoh, ketika anda menjalankan `django-admin startproject mysite` anda akan mendapatkan sebuah direktori proyek `mysite` yang mengandung sebuah paket Python `mysite` dengan `settings.py`, `urls.py`, dan `wsgi.py`. Paket proyek sering diperluas untuk disertakan untuk menyertakan hal-hal seperti perbaikan, CSS, dan cetakan yang tidak diikat ke aplikasi tertentu.

Sebuah direktori akar proyek (satu yang mengandung `manage.py`) biasanya mengandung semua aplikasi proyek yang tidak dipasang secara terpisah.

Istilah aplikasi menggambarkan paket Python yang menyediakan beberapa kumpulan fitur. Aplikasi may be reused di beragam proyek.

Aplikasi menyertakan beberapa kombinasi model, tampilan, cetakan, etiket cetakan, berkas tetap, URL, middleware, dll. Mereka umumnya diikat kedalam proyek dengan pengaturan `INSTALLED_APPS` dan secara pilihan dengan mekanisme lain seperti URLconf, pengaturan `MIDDLEWARE`, atau warisan cetakan.

Sangat penting untuk dimengerti bahwa aplikasi Django hanyalah kumpulan kode yang saling mempengaruhi dengan beragam bagian dari kerangka. Tidak ada sesuatu seperti obyek `Aplikasi`. Bagaimanapun, terdapat sedikit tempat dimana Django butuh saling mempengaruhi dengan aplikasi terpasang, terutama untuk konfigurasi dan juga untuk introspeksi. Itu mengapa registrar aplikasi merawat metadata dalam sebuah instance `AppConfig` untuk setiap aplikasi terpasang.

Tidak ada batasan bahwa sebuah paket proyek tidak dapat dianggap sebuah aplikasi dan mempunyai model, dll. (yang akan butuh menambahkannya ke `INSTALLED_APPS`).

## Konfigurasi aplikasi

Untuk mengkonfigurasikan sebuah aplikasi, buat sebuah modul `apps.py` di dalam aplikasi, kemudian tentukan sub kelas dari `AppConfig` disana.

Ketika `INSTALLED_APPS` mengandung jalur bertitik pada modul aplikasi, secara awalan, jika Django menemukan tepatnya satu subkelas `AppConfig` dalam submodul `apps.py`, dia menggunakan konfigurasi itu untuk aplikasi. Perilaku ini mungkin ditiadakan dengan menyetel `AppConfig.default` menjadi `False`.

Jika modul `apps.py` mengandung lebih dari satu subkelas `AppConfig`, Django akan mencari yang tunggal dimana `AppConfig.default` adalah `True`.

Jika tidak ada subkelas `AppConfig` ditemukan, kelas dasar `AppConfig` akan digunakan.

Cara lain, `INSTALLED_APPS` mungkin mengandung jalur bertitik pada kelas konfigurasi untuk menentukan itu dengan jelas:

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

### Untuk pengarang aplikasi

Jika anda membuat sebuah aplikasi dapat dipasang dipanggil "Rock ’n’ roll", ini adalah bagaimana anda akan menyediakan sebuah nama pantas untuk admin:

    # rock_n_roll/apps.py

    from django.apps import AppConfig

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

`RockNRollConfig` akan dimuiat secara otomatis ketika `INSTALLED_APPS` mengandung `'rock_n_roll'`. Jika anda ingin mencegah ini, setel `default` menjadi `False` dalam pendefinisian kelas.

Anda dapat menyediakan beberapa subkelas `AppConfig` dengan perilaku berbeda. Untuk memberitahu Django yang mana akan digunakan secara awalan, setel `default` menjadi `True` dalam pendefinisiannya. Jika pengguna anda ingin mengambil konfigurasi bukan-awalan, mereka harus mengganti `'rock_n_roll'` dengan jalur bertitik ke kelas spesifik dalam pengaturan `INSTALLED_APPS` mereka.

Atribut `AppConfig.name` memberitahu Django aplikasi mana konfigurasi ini diberlakukan. Anda dapat menentukan atribut lain apapun terdokumentasi dalam acuan API `AppConfig`.

Subkelas `AppConfig` dapat ditentukan dimanapun. `apps.py` konvensi semata mengizinkan Django memuat mereka otomatis ketika `INSTALLED_APPS` mengandung jalur pada modul aplikasi daripada jalur pada kelas konfigurasi.

Catatan

Jika kode mengimpor registrar aplikasi di `__init__.py` aplikasi, nama `apps` akan bentrok dengan submodul `apps`. Praktik terbaik adalah memindahkan kode tersebut ke submodul dan mengimpornya. Sebuah solusi adalah mengimpor registrar dibawah nama berbeda:

    from django.apps import apps as django_apps

### Untuk pengguna aplikasi

Jika anda menggunakan "Rock ’n’ roll" dalam proyek disebut `anthology`, tetapi anda ingin menampilkan "Jazz Manouche", anda dapat menyediakan konfigurasi anda sendiri:

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

Contoh ini menunjukkan kelas-kelas konfigurasi proyek-khusus bertempat dalam submodul disebut `apps.py`. Konvensi ini, bukan sebuah persyaratan. Subkelas `AppConfig` mungkin ditentukan dimanasaja.

Dalam situasi ini, `INSTALLED_APPS` harus mengandung jalur bertitik pada kelas konfigurasi karena itu berada diluar dari aplikasi dan dengan demikian tidak dapat otomatis dikenali.

## Konfigurasi aplikasi

class AppConfig

  Konfigurasi aplikasi obyek menyimpan metadata untuk sebuah aplikasi. Beberapa atribut dapat dikonfigurasikan di subkelas `AppConfig`. Lainnya disetel oleh Django dan hanya-baca.

### Atribut dapat dikonfigurasi

AppConfig.name

  Jalur Phyton penuh ke aplikasi, misalnya `'django.contrib.admin'`.

  Atribut ini menentukan konfigurasi aplikasi mana yang berlaku. DIa harus disetel di semua subkelas `AppConfig`.

  Dia harus unik terhadap proyek Django.

AppConfig.label

  Nama pendek untuk aplikasi, misalnya `'admin'`

  Atribut ini mengizinkan melabel kembali sebuah aplikasi ketika dua aplikasi mempunyai label bertentangan. Awal dia ke komponen terakhir dari `name`. Dia harus penciri Python yang sah.

  Dia harus unik terhadap proyek Django.

  Peringatan

  Changing this attribute after migrations have been applied for an application will result in breaking changes to a project or, in the case of a reusable app, any existing installs of that app. This is because `AppConfig.label` is used in database tables and migration files when referencing an app in the dependencies list.

AppConfig.verbose_name

  Nama dapat dibaca manusia untuk aplikasi, misalnya "Administrasi".

  Atribut awal ke `label.title()`.

AppConfig.path

  Jalur sistem berkas pada direktori aplikasi, misalnya `'/usr/lib/pythonX.Y/dist-packages/django/contrib/admin'`.

  Dalam banyak kasus, Django dapat otomatis mengenali dan mengatur ini, tetapi anda dapat juga menyediakan menimpa eksplisit sebagai atribut kelas di subkelas `AppConfig` anda. Dalam beberapa situasi ini diwajibkan; sebagai contoh jika paket aplikasi adalah namespace package dengan banyak jalur.

AppConfig.default

  Setel atribut ini menjadi `False` untuk mencegah Django dari memilih kelas konfigurasi secara otomatis. Ini berguna ketika `apps.py` menentukan satu subkelas `AppConfig` tetapi anda tidak ingin Django menggunakannya secara awalan.

  Setel atribut ini menjadi `True` untuk memberitahu Django untuk memilih kelas konfigurasi secara otomatis. Ini berguna ketika `apps.py` menentukan lebih dari satu subkelas `AppConfig` dan anda ingin Django menggunakan satu dari mereka secara awalan.

  Secara awalan, atribut ini tidak disetel.

AppConfig.default_auto_field

  Jenis primary key tersirat untuk menambah pada model dalam aplikasi ini. Anda dapat menggunakan ini untuk menjaga `AutoField` sebagai jenis the primary key untuk aplikasi pihak ketiga.

  Secara awalan, ini adalah nilai dari `DEFAULT_AUTO_FIELD`.

### Atribut hanya-baca

AppConfig.module

  modul utama/akar untuk aplikasi, misalnya "<module 'django.contrib.admin' from 'django/contrib/admin/__init__.py'>".

AppConfig.models_module

  Modul yang berisi model, misalnya "<module 'django.contrib.admin.models' from 'django/contrib/admin/models.py'>".

  Itu mungkin `None` jika aplikasi tidak mengandung sebuah modul `models`. Catat bahwa basisdata terkait sinyal seperti `pre_migrate` dan `post_migrate` hanya dimunculkan untuk aplikasi yang mempunyai sebuah modul `models`

### Cara

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

  Mengembalikan kelas `Model` berulang untuk aplikasi ini.

  Membutuhkan aplikasi registrar untuk sepenuhnya dikumpulkan.

AppConfig.get_model(model_name, require_ready=True)

  Mengembalikan `Model` dengan `model_name` diberikan. `model_name` adalah tidak sensitif.

  Memunculkan `LookupError` jika tidak ada model yang ada dalam aplikasi ini.

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

  Subkelas dapat menimpa metode ini untuk melakukan tugas inisialisasi seperti mendaftarkan sinyal. Dia dipanggil segera ketika registrar dikumpulkan penuh.

  Meskipun anda tidak dapat mengimpor pada tingkat-modul dimana kelas-kelas `AppConfig` ditentukan, anda dapat mengimpor `ready()`, menggunakan antara pernyataan `import` atau `get_model()`.

  Jika anda sedang mendaftarkan `model signals`, anda dapat mengacu pada pengirim berdasarkan label deretan karakter nya daripada menggunakan kelas model itu sendiri.

  Contoh:

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

  Peringatan

  Although you can access model classes as described above, avoid interacting with the database in your `ready()` implementation. This includes model methods that execute queries (`save()`, `delete()`, manager methods etc.), and also raw SQL queries via `django.db.connection`. Your `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!

  Catatan

  Di proses inisialisasi biasanya, metode `ready` hanya dipanggil sekali oleh Django. Tetapi dalam kasus tertentu, khususnya dalam percobaan yang remeh dengan aplikasi terpasang, `ready` mungkin dipanggil lebih dari satu. Dalam kasus tersebut, baik menulis metode idempoten, atau menaruh bendera pada kelas `AppConfig` anda untuk mencegah menjalankan kembali kode yang harus dijalankan setidaknya satu kali.

### Paket namespace sebagai aplikasi

Paket-paket Python tanpa berkas `__init__.py` dikenal sebagai "namespace packages" dan mungkin tersebar di banyak direktori pada tempat berbeda di `sys.path` (see PEP 420).

Aplikasi Django membutuhkan sebuah jalus sistem berkas berbasis tunggal dimana Django (tergantung pada konfigurasi) akan mencari cetakan, aset tetap, dll. Hingga, paket namespace mungkin hanya aplikasi Django jika satu dari hal berikut adalah benar:

1. Paket namespace sebenarnya mempunyai hanya tempat tunggal (yaitu tidak tersebar terhadap lebih dari satu direktori.)

2. Kelas `AppConfig` digunakan untuk mengkonfigurasikan aplikasi yang mempunyai atribut kelas `path`, yang merupakan jalur direktori mutlak Django akan digunakan sebagai jalur dasar tunggal untuk aplikasi.

Jika tidak satupun dari kondisi ini bertemu, Django akan memunculkan `ImproperlyConfigured`.

## Registrar aplikasi

apps

  Registrar aplikasi menyediakan API umum berikut. Cara yang tidak ada di daftar dibawah ini dianggap pribadi dan mungkin berubah tanpa pemberitahuan.

apps.ready

  Atribut Boolean yang disetel ke `True` setelah registrar sepenuhnya dikumpulkan dan semua cara `AppConfig.ready()` dipanggil.

apps.get_app_configs()

  Mengembalikan instance berulang dari `AppConfig`.

apps.get_app_config(app_label)

  Mengembalikan sebuah `AppConfig` untuk aplikasi dengan `app_label`. yang diberikan. Memunculkan `LookupError` jika tidak ada aplikasi.

apps.is_installed(app_name)

  Memeriksa apakah aplikasi dengan nama diberikan anda di registrar. `app_name` adalah nama penuh dari aplikasi, misalnya `'django.contrib.admin'`.

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

  Mengembalikan `Model` dengan `app_label` yang diberikan dan `model_name`. Sebagai sebuah jalan pintas, metode ini juga menerima argumen tunggal dalam bentuk `app_label.model_name`. `model_name` kasus-tidak peka.

  Memunculkan `LookupError` jika tidak seperti aplikasi atau model ada. Memunculkan `ValueError` ketika dipanggil dengan argumen tunggal yang tidak mengandung satu titik.

  Membutuhkan aplikasi regristrar untuk sepenuhnya dikumpulkan meskipun argumen `require_ready` disetel menjadi `False`.

  Mengatur `require_ready` menjadi `False` mengizinkan pencarian model while the app registry is being populated, khususnya selama tahap kedua dimana itu mengimpor model. Kemudian `get_model()` mempunyai pengaruh sama ketika mengimpor model. Kasus penggunaan utama adalah mengkonfigurasi kelas-kelas model dengan pengaturan, seperti `AUTH_USER_MODEL`.

  Ketika `require_ready` adalah `False`, `get_model()` mengembalikan sebuah kelas model yang mungkin tidak sepenuhnya berfungsi (accessor balikan mungkin hilang, sebagai contoh) sampai aplikasi regristrar sepenuhnya dikumpulkan. Untuk alasan ini, itu adalah terbaik untuk membiarkan `require_ready` ke nilai awalan dari `True` kapanpun memungkinkan.

## Inisialisasi pengolahan

### Bagaimana aplikasi dimuat

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

setup(set_prefix=True)

  Konfigurasi Django oleh:

  - Memuat pengaturan.

  - Mengatur pencatatan.

  - Jika `set_prefix` adalah True, pengaturan awalan tulisan penyelesai URL ke `FORCE_SCRIPT_NAME` jika ditentukan, atau jika tidak `/`.

  - Memulai registrar aplikasi

  Fungsi ini dipanggil otomatis:

  - Ketika menjalankan peladen HTTP melalui dukungan ASGI atau WSGI Django.

  - Ketika meminta perintah pengelolaan.

  Dia harus dipanggil secara tersirat di kasus lain, sebagai contoh di tulisan Phyton.

Registrar aplikasi dimulai dalam tiga tingkatan, Pada setiap tingkatan, Django mengolah semua aplikasi berdasarkan dari `INSTALLED_APPS`.

1. Django pertama mengimpor setiap barang di `INSTALLED_APPS`.

   Jika ini adalah kelas konfigurasi aplikasi, Django impor paket akar dari aplikasi, ditentukan dengan atribut `name` nya. Jika itu adalah paket Python, Django mencari untuk konfigurasi aplikasi dalam sebuah submodul `apps.py`, atau lainnya membuat konfigurasi aplikasi awalan.

   Pada tingkatan ini, kode anda jangan mengimpor model apapun!

   Dengan kata lain, paket akar aplikasi anda dan modul yang menentukan kelas-kelas konfigurasi aplikasi anda jangan impor model apapun, bahkan secara tidak langsung.

   Sesungguhnya, Django mengizinkan mengimpor model sekali konfigurasi aplikasi mereka dimuat. Bagaimanapun, agar menghindari kendala yang tidak perlu pada urutan `INSTALLED_APPS`, sangat dianjurkan tidak mengimpor model apapun pada tingkatan ini.

   Once this stage completes, APIs that operate on application configurations such as `get_app_config()` become usable.

2. Kemudian Django berusaha mengimpor submodul `model` dari setiap aplikasi, jika memang ada.

   Anda harus menentukan atau mengimpor semua model di aplikasi `models.py` anda atau `models/__init__.py`. Sebaliknya, registri aplikasi mungkin tidak dikumpulkan penuh pada titik ini, yang dapat menyebabkan ORM tidak berfungsi.

   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.

### Menyelesaikan masalah

Disini beberapa masalah umum yang mungkin muncul selama inisialisasi:

- `AppRegistryNotReady`: Ini terjadi ketika mengimpor sebuah konfigurasi aplikasi atau sebuah kode pemicu modul model yang bergantung di registri aplikasi.

  For example, `gettext()` uses the app registry to look up translation catalogs in applications. To translate at import time, you need `gettext_lazy()` instead. (Using `gettext()` would be a bug, because the translation would happen at import time, rather than at each request depending on the active language.)

  Menjalankan permintaan basisdata dengan ORM pada waktu impor dalam modul model juga akan memicu pengecualian ini. ORM tidak dapat berfungsi dengan benar sampai semua model tersedia.

  This exception also happens if you forget to call `django.setup()` in a standalone Python script.

- `ImportError: tidak dapat impor nama ...` Ini terjadi jika urutan impor berakhir dalam perulangan.

  Untuk mengurangi permasalahan tersebut, anda harus mengecilkan ketergantungan diantara model anda dan melakukan sedikit pekerjaan sebisa mungkin pada waktu impor. Untuk menghindari penjalanan kode pada waktu impor, anda dapat memindahkannya dan menembolok hasilnya. Kode akan dikerjakan ketika anda pertama butuh hasilnya. Konsep ini dikenal sebagai "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'`.

- `RuntimeWarning: Accessing the database during app initialization is discouraged.` This warning is triggered for database queries executed before apps are ready, such as during module imports or in the `AppConfig.ready()` method. Such premature database queries are discouraged because they will run during the startup of every management command, which will slow down your project startup, potentially cache stale data, and can even fail if migrations are pending.

  For example, a common mistake is making a database query to populate form field choices:

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

  In the example above, the query from `Country.objects.all()` is executed during module import, because the `QuerySet` is iterated over. To avoid the warning, the form could use a `ModelChoiceField` instead:

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

  To make it easier to find the code that triggered this warning, you can make Python treat warnings as errors to reveal the stack trace, for example with `python -Werror manage.py shell`.