Menulis perintah django-admin
penyesuaian¶
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, tambahkan direktori management/commands
ke aplikasi. Django akan mendaftarkan sebuah perintah manage.py
untuk setiap modul Python dalam direktori tersebut yang namanya tidak dimulai dengan garis bawah. Sebagai contoh:
polls/
__init__.py
models.py
management/
commands/
_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='')
The new custom command can be called using python manage.py closepoll
<poll_ids>
.
The handle()
method takes one or more poll_ids
and sets poll.opened
to False
for each one. If the user referenced any nonexistent polls, a
CommandError
is raised. The poll.opened
attribute does not exist in
the tutorial and was added to
polls.models.Question
for this example.
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()
# ...
Pilihan (delete
dalam contoh kami) tersedia dalam pilihan parameter perintah dari cara penanganan. Lihat dokumentasi Python argparse
untuk lebih tentang penggunaan add_argument
.
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.
Decorator @no_translations
adalah baru. Dalam versi terlama, terjemahan dinonaktifkan sebelum menjalankan sebuah perintah meskipun atribut perintah leave_locale_alone
(sekarang dipindahkan) disetel menjadi True
.
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¶
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
¶ Jika perintah anda menentukan argumen penempatan wajib, anda dapat menyesuaikan pesan kesalahan yang dikembalikan dalam kasus argumen yang hilang. Awalnya adalah keluaran oleh
argparse
("terlalu sedikit argumen").
-
BaseCommand.
output_transaction
¶ Sebuah boolean menunjukkan apakah perintah keluaran pernyataan SQL; jika
True
, keluaran akan otomatis dibungkus denganBEGIN;
danCOMMIT;
. Nilai awal adalahFalse
.
-
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 adalahFalse
.
-
BaseCommand.
requires_system_checks
¶ Sebuah boolean; jika
True
, seluruh proyek Django akan diperiksa untuk masalah potensial sebelum menjalankan perintah. Nilai awal adalahTrue
.
-
BaseCommand.
style
¶ Sebuah atribut instance yang membantu membuat keluaran bewarna ketika menulis ke
stdout
ataustderr
. 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 pemanggilanself.style()
akan mengembalikan deretan karakter asli tidak bewarna.
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)[sumber]¶ Returns a
CommandParser
instance, which is anArgumentParser
subclass with a few customizations for Django.You can customize the instance by overriding this method and calling
super()
withkwargs
ofArgumentParser
parameters.Changed in Django 2.2:kwargs
was added.
-
BaseCommand.
add_arguments
(parser)[sumber]¶ 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 langsungBaseCommand
.
-
BaseCommand.
get_version
()[sumber]¶ 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)[sumber]¶ Coba untuk menjalankan perintah ini, melakukan pemeriksaan sistem jika dibutuhkan (sebagai pengendalian oleh
requires_system_checks
attribute). Jika perintah muncul sebuahCommandError
, Dia 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)[sumber]¶ Logika sebenarnya dari perintah. Subkelas harus menerapkan cara ini.
Itu mungkin mengembalikan sebuah string yang akan dicetak pada
stdout
(dibungkus olehBEGIN;
danCOMMIT;
jikaoutput_transaction
adalahTrue
).
-
BaseCommand.
check
(app_configs=None, tags=None, display_num_errors=False)[sumber]¶ Gunakan kerangka sistem pemeriksaan untuk memeriksa keseluruhan proyek Django untuk masalah potensial. Masalah serius muncul seperti sebuah
CommandError
; peringatan dikeluarkan ke stderr; pemberitahuan kecil dikeluarkan pada stdout.Jika
app_configs
dantags
keduanyaNone
, semua pemeriksaan sistem dilakukan.tags
dapat menjadi daftar dari etiket pemeriksaan, seperticompatibility
ataumodels
.
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 instanceAppConfig
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¶
Kelas pengecualian mengindikasikan sebuah masalah selama menjalankan perintah pengelolaan.
Jika pengecualian ini muncul selama peerjalanan dari pengelolaan perintah dari sebuah perintah baris tempat tuts, dia akan ditangkap dan dirubah menjadi pesan kesalahan tercetak yang bagus ke aliran keluaran yang sesuai (yaitu, stderr); sebagai sebuah hasil, memunculkan pengecualian ini (dengan sebuah gambaran yang mudah dimengerti dari kesalahan) adalah jalan yang dipilih untuk menunjukkan bahwa sesuatu telah salah dalam menjalankan sebuah perintah.
Jika sebuah pengelolaan perintah dipanggil dari kode melalui call_command()
, itu terserah kamu untuk menangkap pengecualian ketika dibutuhkan.