# Dokumentasi Django 5.2.8

# Bagaimana membuat perintah `django-admin` yang disesuaikan

Aplikasi dapat mendaftarkan tindakan mereka sendiri dengan `manage.py`. Sebagai contoh, anda mungkin ingin menambahkan sebuah tindakan `manage.py` untuk sebuah aplikasi Django yang anda sedang sebarkan. Dalam dokumen ini, kami akan membangun sebuah penyesuaian perintah `closepoll` untuk aplikasi `polls` dari tutorial.

Untuk melakukan ini, tambah direktori `management/commands` pada aplikasi. Django akan mendaftarkan perintah `manage.py` untuk setiap modul Python di direktori dyang namanya tidak dimulai dengan garis bawah. Sebagai contoh:

    polls/
        __init__.py
        models.py
        management/
            __init__.py
            commands/
                __init__.py
                _private.py
                closepoll.py
        tests.py
        views.py

Dalam contoh ini, perintah `closepoll` akan dibuat tersedia pada setiap proyek yang menyertakan aplikasi `polls` dalam `INSTALLED_APPS`.

Modul `_private.py` tidak akan tersedia sebagai perintah pengelolaan.

Modul `closepoll.py` mempunyai hanya satu persyaratan -- itu harus ditentukan sebuah kelas `Command` yang memperpanjang `BaseCommand` atau satu dari subclasses nya.

Tulisan berdiri sendiri

Penyesuaian pengelolaan perintah adalah khususnya berguna untuk menjalankan tulisan berdiri sendiri atau untuk tulisan yang secara berkala dijalankan dari panel kendali UNIX crontab atau Windows scheduled tasks.

Untuk menerapkan perintah, sunting `polls/management/commands/closepoll.py` untuk kelihatan seperti ini:

    from django.core.management.base import BaseCommand, CommandError
    from polls.models import Question as Poll

    class Command(BaseCommand):
        help = "Closes the specified poll for voting"

        def add_arguments(self, parser):
            parser.add_argument("poll_ids", nargs="+", type=int)

        def handle(self, *args, **options):
            for poll_id in options["poll_ids"]:
                try:
                    poll = Poll.objects.get(pk=poll_id)
                except Poll.DoesNotExist:
                    raise CommandError('Poll "%s" does not exist' % poll_id)

                poll.opened = False
                poll.save()

                self.stdout.write(
                    self.style.SUCCESS('Successfully closed poll "%s"' % poll_id)
                )

Catatan

Ketika anda menggunakan pengelolaan perintah dan berharap untuk menyediakan keluaran tempat tuts, anda harus menulis ke `self.stdout` dan `self.stderr`, daripada mencetak ke `stdout` and `stderr` secara langsung. Dengan menggunakan proxi ini, dia menjadi lebih mudah untuk mencoba penyesuaian perintah anda. Catat juga bahwa anda tidak butuh mengakhiri pesan dengan karakter baris baru, dia akan ditambahkan otomatis, meskipun anda menentukan parameter `ending`:

    self.stdout.write("Unterminated line", ending="")

Perintah baru penyesuaian dapat dipanggil menggunakan `python manage.py closepoll <poll_ids>`.

Metode `handle()` mengambil satu atau lebih `poll_ids` dan mensetel `poll.opened` menjadi `False` untuk masing-masing. Jika pengguna mereferensikan jajak pendapat yang tidak ada, sebuah `CommandError` dimunculkan. Atribut `poll.opened` tidak ada dalam tutorial dan telah ditambahkan pada `polls.models.Question` untuk contoh ini.

## Menerima argumen pilihan

`closepoll` yang sama dapat dengan mudah dirubah untuk menghapus jejak pendapat yang diberikan daripada menutupnya dengan menerima tambahan pilihan baris perintah. Penyesuaian pilihan ini dapat ditambahkan dalam cara `add_arguments()` seperti ini:

    class Command(BaseCommand):
        def add_arguments(self, parser):
            # Positional arguments
            parser.add_argument("poll_ids", nargs="+", type=int)

            # Named (optional) arguments
            parser.add_argument(
                "--delete",
                action="store_true",
                help="Delete poll instead of closing it",
            )

        def handle(self, *args, **options):
            # ...
            if options["delete"]:
                poll.delete()
            # ...

The option (`delete` in our example) is available in the options dict parameter of the handle method. See the `argparse` Python documentation for more about `add_argument` usage.

Dalam tambahan untuk dapat menambahkan penyesuaian pilihan baris perintah, semua management commands dapat menerima beberapa pilihan awal seperti `--verbosity` dan `--traceback`.

## Pengelolaan perintah dan lokal

Secara awalan, perintah pengelolaan dijalankan dengan lokal aktif saat ini.

Jika, untuk beberapa alasan, perintah pengelolaan penyesuaian anda harus berjalan tanpa lokal aktif (sebagai contoh, untuk menghindari isi diterjemahkan dari menjadi dimasukkan kedalam basisdata), non aktifkan terjemahan menggunakan decorator `@no_translations` pada metode `handle()` anda:

    from django.core.management.base import BaseCommand, no_translations

    class Command(BaseCommand):
        ...

        @no_translations
        def handle(self, *args, **options): ...

Sejak penonaktifan terjemahan membutuhkan akses untuk mengkonfigurasi pengaturan, decorator tidak dapat digunakan untuk perintah yang bekerja tanpa pengaturan yang dikonfigurasikan.

## Pengujian

Informasi pada bagaimana untuk mencoba penyesuaian pengelolaan perintah dapat ditemukan dalam dokumen percobaan.

## Menimpa perintah

Django mendaftarkan perintah siap-pakai dan kemudian mencari untuk perintah dalam `INSTALLED_APPS` secara memutar. Selama pencarian, jika sebuah nama perintah menggandakan sebuah perintah sudah terdaftar, perintah baru yang ditemukan ditimpa dahulu.

Dengan kata lain, untuk menimpa sebuah perintah, perintah baru harus memiliki nama sama dan aplikasinya harus sebelum menimpa aplikasi perintah dalam `INSTALLED_APPS`.

Perintah pengelolaan dari aplikasi pihak-ketiga yang telah tidak sengaja ditimpa dapat dibuat tersedia dibawah sebuah nama baru dengan membuat perintah baru di satu dari aplikasi proyek anda (diurutkan sebelum aplikasi pihak-ketiga dalam `INSTALLED_APPS`) yang mengimpor `Command` dari perintah ditimpa.

## Obyek perintah

class BaseCommand

Kelas dasar dari mana semua pengelolaan perintah akhirnya berasal.

Gunakan kelas ini jika anda ingin mengakses semua mekanisme yang mengurai argumen baris perintah dan bekerja kode apa untuk dipanggil dalam tanggapan; jika anda tidak butuh merubah kebiasaan apapun, pertimbangkan menggunakan satu dari subclasses nya.

Mensubkelaskan kelas `BaseCommand` membutuhkan bahwa anda menerapkan cara `handle()`.

### Atribut

Semua atribut dapat di setel dalam kelas turunan anda dan dapat digunakan dalam subclasses `BaseCommand`.

BaseCommand.help

  Deskripsi singkat dari perintah, dimana akan ditampilkan di pesan bantuan ketika pengguna eksekusi perintah `python manage.py help <command>`.

BaseCommand.missing_args_message

  If your command defines mandatory positional arguments, you can customize the message error returned in the case of missing arguments. The default is output by `argparse` ("too few arguments").

BaseCommand.output_transaction

  Sebuah boolean menunjukkan apakah perintah keluaran pernyataan SQL; jika `True`, keluaran akan otomatis dibungkus dengan `BEGIN;` dan `COMMIT;`. Nilai awal adalah `False`.

BaseCommand.requires_migrations_checks

  Sebuah boolean; jika `True`, memerintahkan mencetak sebuah peringatan jika pengaturan perpindahan pada cakram tidak cocok dengan perpindahan di basisdata. Sebuah peringatan tidak mencegah perintah dari penjalanan. Nilai awal adalah `False`.

BaseCommand.requires_system_checks

  Sebuah etiket list atau tuple, misalnya `[Tags.staticfiles, Tags.models]`. Pemeriksaan sistem registered in the chosen tags akan diperiksa untuk kesalahan sebelum menjalankan perintah. Nilai `'__all__'``dapat digunakan untuk menentukan bahwa semua pemeriksaan sustem harus dilakukan. Nilai awalan adalah ``'__all__'`.

BaseCommand.style

  Sebuah atribut instance yang membantu membuat keluaran bewarna ketika menulis ke `stdout` atau `stderr`. Sebagai contoh:

      self.stdout.write(self.style.SUCCESS("..."))

  Lihat Pewarnaan sintaksis untuk mempelajari bagaimana merubah papan warna dan melihat gaya tersedia (gunakan versi huruf besar dari "roles" yang digambarkan dalam bagian itu).

  Jika anda melewati pilihan `--no-color` ketika menjalankan perintah anda, semua pemanggilan `self.style()` akan mengembalikan deretan karakter asli tidak bewarna.

BaseCommand.suppressed_base_arguments

  Pilihan perintah awalan untuk menekan keluaran bantuan. Ini harus berupa kumpulan dari nama-nama pilihan (misalnya `'--verbosity'`). Nilai awalan untuk pilihan yang ditekankan masih bisa dilewati.

### Cara

`BaseCommand` mempunyai beberapa cara yang dapat dikesampingkan tetapi hanya cara `handle()` harus diterapkan.

Menerapkan constructor dalam subkelas

Jika anda menerapkan `__init__` dalam subkelas anda dari `BaseCommand`, anda harus memanggil `__init__` dari :class:`BaseCommand:

    class Command(BaseCommand):
        def __init__(self, *args, **kwargs):
            super().__init__(*args, **kwargs)
            # ...

BaseCommand.create_parser(prog_name, subcommand, **kwargs)

  Mengembalikan instance `CommandParser`, yaitu sebuah subkelas `ArgumentParser` dengan sedikit penyesuaian untuk Django.

  Anda dapat menyesuaikan instance dengan menimpa metode ini dan memanggil `super()` dengan `kwargs` dari parameter `ArgumentParser`.

BaseCommand.add_arguments(parser)

  Titik masukan untuk menambahkan pengurai argumen untuk menangani argumen baris perintah dilewati ke perintah. Penyesuaian perintah harus menimpa metode ini untuk menambah kedua argumen penempatan dan pilihan yang diterima oleh perintah. Memanggil `super()` tidak dibutuhkan ketika pengsubkelasan secara langsung `BaseCommand`.

BaseCommand.get_version()

  Mengembalikan versi Django, yang seharusnya benar untuk semua perintah Django siap pakai. Perintah pasokan-pengguna dapat menimpa metode ini untuk mengembalikan versi mereka sendiri.

BaseCommand.execute(*args, **options)

  Mencoba menjalankan perintaj ini, melakukan pemeriksaan sistem jika diperlukan (seperti yang dikendalikan oleh atribut `requires_system_checks`). Jika perintah memunculkan `CommandError`, itu dicegat dan dicetak ke `stderr`.

Memanggil perintah pengelolaan di kode anda

`execute()` jangan dipanggil secara langsung dari kode anda untuk menjalankan sebuah perintah. Lebih baik gunakan `call_command()`.

BaseCommand.handle(*args, **options)

  Logika sebenarnya dari perintah. Subkelas harus menerapkan cara ini.

  Itu mungkin mengembalikan sebuah string yang akan dicetak pada `stdout` (dibungkus oleh `BEGIN;` dan `COMMIT;` jika `output_transaction` adalah `True`).

BaseCommand.check(app_configs=None, tags=None, display_num_errors=False, include_deployment_checks=False, fail_level=checks.ERROR, databases=None)

  Menggunakan kerangka kerja pemeriksaan sistem untuk memeriksa keseluruhan proyek Django untuk potensi masalah. Masalah serius dimunculkan sebagai `CommandError`; peringatan adalah keluaran `stderr`; pemberitahuan kecil adalah keluaran `stdout`.

  Jika `app_configs` dan `tags` keduanya `None`, semua pemeriksaan sistem dilakukan kecuali pemeriksaan terkait penyebaran dan basisdata deployment. `tags` dapat didaftar dari etiket pemeriksaan, seperti `compatibility` atau `models`.

  Anda dapat melewati `include_deployment_checks=True` untuk juga melakukan pemeriksaan penyebaran, dan daftar dari nama lain basisdata dalam `databases` untuk menjalankan basisdata pemeriksaan terkait terhadap mereka.

BaseCommand.get_check_kwargs(options)
  New in Django 5.2.

  Dukungan kwargs untuk panggilan pada `check()`, termasuk merubah nilai `requires_system_checks` pada kwarg `tag`.

  Timpa metode ini untuk merubah nilai-nilai disediakan pada `check()`. Sebagai contoh, untuk ikut serta pemeriksaan terkait basisdata anda dapat menimpa `get_check_kwargs()` sebagai berikut:

      def get_check_kwargs(self, options):
          kwargs = super().get_check_kwargs(options)
          return {**kwargs, "databases": [options["database"]]}

### Subkelas `BaseCommand`

class AppCommand

Sebuah pengelolaan perintah yang mengambil satu atau lebih label aplikasi terpasang sebagai argumen, dan melakukan sesuatu dengan masing-masing dari mereka.

Daripada menerapkan `handle()`, subkelas harus menerapkan `handle_app_config()`, yang akan dipanggil sekali untuk setiap aplikasi.

AppCommand.handle_app_config(app_config, **options)

  Melakukan tindakan perintah untuk `app_config`, yang akan menjadi sebuah instance `AppConfig` terhubung ke sebuah label aplikasi yang diberikan pada baris perintah.

class LabelCommand

Sebuah pengelolaan perintah yang mengambil satu atau lebih argumen (label) yang berubah-ubah pada baris perintah, dan melakukan sesuatu dengan masing-masing dari mereka.

Daripada menerapkan `handle()`, subkelas harus menerapkan `handle_label()`, yang akan dipanggil sekali untuk setiap label.

LabelCommand.label

  Sebuah string menggambarkan argumenberubah-ubah dilewatkan ke perintah. String digunakan dalam penggunaan teks dan pesan kesalahan dari perintah. Awalan pada `'label'`.

LabelCommand.handle_label(label, **options)

  Melakukan tindakan perintah untuk `label`, yang akan menjadi deretan karakter seperti yang diberikan pada baris perintah.

### Perintah pengecualian

exception CommandError(returncode=1)

Kelas pengecualian mengindikasikan sebuah masalah selama menjalankan perintah pengelolaan.

Jika pengecualian ini muncul selama menjalankan perintah pengelolaan dari konsol baris perintah, itu akan ditangkap dan dirubah menjadi pesan kesalahan tercetak-bagus untuk menyesuaikan aliran keluaran (yaitu, `stderr`); sebagai hasilnya, memunculkan pengecualian ini (dengan deskripsi kesalahan yang masuk akal) adalah cara yang dipilih untuk mengunjukkan bahwa sesuatu telah salah dalam penjalanan program. Itu menerima argumen pilihan `returncode` untuk menyesuaikan keadaan keluar untuk perintah pengelolaan untuk keluar, menggunakan `sys.exit()`.

Jika sebuah pengelolaan perintah dipanggil dari kode melalui `call_command()`, itu terserah kamu untuk menangkap pengecualian ketika dibutuhkan.