CLI yang nyata jarang berhenti pada satu argumen nama. Program meminta angka, menawarkan pilihan terbatas, menyediakan flag on/off, sampai menerima daftar nilai sekaligus. Chapter ini membahas fitur argparse yang mengubah teks mentah dari terminal menjadi nilai Python yang sudah tervalidasi: parameter type, choices, action, nargs, grup saling eksklusif, hingga selera merancang bantuan --help yang enak dibaca.

Validasi Tipe dengan type dan choices #

Secara default setiap argumen datang sebagai string. Parameter type=int meminta parser mengubah teks menjadi bilangan bulat, choices membatasi nilai yang diterima, metavar merapikan placeholder di bantuan, dan action="count" menghitung berapa kali sebuah opsi diketik. Berkas hitung.py menggabungkan semuanya:

python 
import argparse

parser = argparse.ArgumentParser(description="Mencetak pesan beberapa kali.")
parser.add_argument("pesan", help="pesan yang akan dicetak")
parser.add_argument("--ulang", type=int, default=1, choices=range(1, 4), metavar="N",
                    help="jumlah pengulangan, 1-3 (default: 1)")
parser.add_argument("-v", "--verbose", action="count", default=0,
                    help="tingkatkan detail keluaran, boleh berulang")

args = parser.parse_args()

for _ in range(args.ulang):
    print(args.pesan)
if args.verbose >= 1:
    print(f"[dicetak {args.ulang} kali, verbose={args.verbose}]")

Mari kita bedah baris-baris pentingnya:

  1. Baris 5 (type=int, default=1, choices=range(1, 4)): parser memanggil int() pada teks yang diberikan, memastikan nilainya berada di antara 1 sampai 3, dan memakai 1 saat opsi tidak diisi.
  2. Baris 5 (metavar="N"): mengubah placeholder di bantuan dari --ulang ULANG menjadi --ulang N agar lebih ringkas.
  3. Baris 7 (action="count", default=0): setiap kemunculan -v menambah nilai args.verbose, sehingga -v bernilai 1 dan -v -v bernilai 2.
  4. Baris 14-15 (if args.verbose >= 1:): mencontohkan penggunaan level verbose untuk menampilkan informasi tambahan.

Jalankan dua variasi berikut:

bash 
python3 hitung.py "Halo Dunia" --ulang 2
python3 hitung.py "Halo" --ulang 2 -v

Output yang Dihasilkan:

text 
Halo Dunia
Halo Dunia
Halo
Halo
[dicetak 2 kali, verbose=1]

Validasi bekerja bahkan sebelum program berjalan. Nilai --ulang 5 ditolak parser dengan pesan ke stderr dan exit code 2:

text 
usage: hitung.py [-h] [--ulang N] [-v] pesan
hitung.py: error: argument --ulang: invalid choice: '5' (choose from 1, 2, 3)

Nilai action yang paling sering dipakai dirangkum berikut:

Nilai actionPerilakuTipe hasilContoh
"store" (default)menyimpan satu nilaimengikuti type--ulang 2 menjadi 2
"store_true"flag tanpa nilaibool--apply menjadi True
"store_false"kebalikan store_truebool--no-warna menjadi False
"count"menghitung kemunculanint-v -v menjadi 2

Satu Opsi, Banyak Nilai dengan nargs #

Parameter nargs mengizinkan satu opsi menerima beberapa nilai. Berkas laporan.py memakai nargs="+" untuk satu atau lebih email, required=True untuk opsi yang tetap wajib, serta nargs="?" dengan const untuk opsi opsional yang boleh muncul tanpa nilai:

python 
import argparse

parser = argparse.ArgumentParser(
    description="Menyiapkan laporan untuk dikirim.",
    epilog="Contoh: laporan.py --penerima [email protected] --detail",
)
parser.add_argument("--penerima", nargs="+", required=True, metavar="EMAIL",
                    help="satu atau lebih alamat email penerima")
parser.add_argument("--format", choices=["teks", "json"], default="teks",
                    help="format laporan (default: teks)")
parser.add_argument("--judul", nargs="?", const="Laporan Harian", default=None, metavar="TEKS",
                    help="judul laporan; tanpa nilai memakai Laporan Harian")

mode = parser.add_mutually_exclusive_group()
mode.add_argument("--ringkas", action="store_true", help="keluaran ringkas")
mode.add_argument("--detail", action="store_true", help="keluaran detail")

args = parser.parse_args()

print("penerima :", ", ".join(args.penerima))
print("format   :", args.format)
print("judul    :", args.judul if args.judul else "(tanpa judul)")
print("mode     :", "ringkas" if args.ringkas else "detail" if args.detail else "normal")

Tiga perilaku nargs patut dicermati:

  1. Baris 7 (nargs="+"): args.penerima menjadi list berisi semua nilai setelah --penerima, minimal satu.
  2. Baris 11 (nargs="?", const="Laporan Harian", default=None): jika --judul tidak ditulis, nilainya None; jika ditulis tanpa nilai, nilainya "Laporan Harian"; jika ditulis dengan nilai, nilai itulah yang dipakai.
  3. Baris 7 (required=True): opsi tetap opsional secara gaya penulisan, tetapi program menolak berjalan tanpa opsi tersebut.

Jalankan dua variasi berikut:

bash 
python3 laporan.py --penerima [email protected] [email protected] --judul
python3 laporan.py --penerima [email protected] --detail

Output yang Dihasilkan:

text 
penerima : [email protected], [email protected]
format   : teks
judul    : Laporan Harian
mode     : normal
penerima : [email protected]
format   : teks
judul    : (tanpa judul)
mode     : detail

Ringkasan nilai nargs:

Nilai nargsArtiSaat tidak diisi
"+"satu atau lebih nilaigalat karena wajib
"*"nol atau lebih nilailist kosong []
"?"nol atau satu nilaidefault; const bila flag muncul tanpa nilai
N (angka)tepat N nilaigalat karena wajib

Opsi yang Saling Eksklusif #

Baris 14-16 pada laporan.py membentuk mutually exclusive group melalui add_mutually_exclusive_group(). Parser memastikan hanya salah satu dari --ringkas atau --detail yang boleh dipakai dalam satu perintah. Menggabungkan keduanya memicu penolakan:

text 
usage: laporan.py [-h] --penerima EMAIL [EMAIL ...] [--format {teks,json}]
                  [--judul [TEKS]] [--ringkas | --detail]
laporan.py: error: argument --detail: not allowed with argument --ringkas

Pesan galat seperti ini jauh lebih murah daripada membiarkan dua opsi bertentangan lolos ke logika program.

Merancang Tampilan –help #

Bantuan adalah halaman depan CLI. Parameter description menjelaskan program, epilog menambahkan catatan penutup, dan metavar menjaga placeholder tetap pendek. Tampilan python3 laporan.py --help:

text 
usage: laporan.py [-h] --penerima EMAIL [EMAIL ...] [--format {teks,json}]
                  [--judul [TEKS]] [--ringkas | --detail]

Menyiapkan laporan untuk dikirim.

options:
  -h, --help            show this help message and exit
  --penerima EMAIL [EMAIL ...]
                        satu atau lebih alamat email penerima
  --format {teks,json}  format laporan (default: teks)
  --judul [TEKS]        judul laporan; tanpa nilai memakai Laporan Harian
  --ringkas             keluaran ringkas
  --detail              keluaran detail

Contoh: laporan.py --penerima [email protected] --detail

Beberapa kebiasaan yang membuat bantuan enak dibaca: tulis help satu kalimat pendek dan mulai dengan huruf kecil, sebutkan nilai default secara eksplisit, dan pilih metavar yang bermakna seperti EMAIL atau FILE. Bila epilog berisi baris-baris contoh yang tidak boleh dibungkus, tambahkan formatter_class=argparse.RawDescriptionHelpFormatter pada ArgumentParser.

Dengan kombinasi type, choices, action, nargs, dan grup eksklusif, kontrak antara pengguna dan program menjadi tegas sejak baris perintah. Selanjutnya, kita melihat kanal konfigurasi lain yang tidak berpindah lewat terminal: environment variables.