Kursus Python / Membuat alat command line dengan argparse

argparse adalah modul standar Python untuk mendefinisikan argumen command line, mengonversi nilai, membatasi pilihan, dan menampilkan bantuan pemakaian. Modul ini juga melaporkan masukan yang tidak sesuai melalui pesan kesalahan dan status keluar. Pisahkan pembacaan argumen dari perhitungan agar perilaku program mudah digunakan kembali dan diuji.

Memahami argumen posisi dan opsi bernama

Argumen posisi dikenali dari urutannya pada perintah. Pada latihan ini, 3500 8000 2500 adalah tiga nilai untuk parameter amounts. Sebaliknya, --currency USD adalah opsi bernama dengan satu nilai. Tanda spasi memisahkan argumen; menulis "3500 8000" membuat satu argumen string, bukan dua angka.

nargs="+" mewajibkan sedikitnya satu nilai. type=nonnegative menyerahkan setiap nilai kepada fungsi konversi khusus, dan choices membatasi label mata uang. default="KRW" digunakan jika opsi mata uang tidak diberikan. Aturan ini membuat kesalahan dapat diketahui sebelum perhitungan dijalankan.

Gunakan Python 3.12 atau lebih baru dan lingkungan virtual proyek. Tidak ada paket tambahan untuk modul ini. Argumen command line dapat terlihat dalam riwayat shell dan daftar proses; jangan menggunakannya untuk menyimpan password atau token. Jika suatu alat menerima jalur yang mengandung spasi, apit jalur dengan tanda kutip agar tetap menjadi satu argumen.

Membuat perintah penjumlahan lengkap

Buat folder latihan baru, lalu simpan seluruh kode berikut sebagai sum_cli.py dengan UTF-8. Buka terminal pada folder itu, pilih interpreter proyek, dan jalankan python sum_cli.py 3500 8000 2500. Gunakan python3 sebagai pengganti jika itulah nama interpreter di lingkungan Anda.

import argparse

def nonnegative(text):
    try:
        value = int(text)
    except ValueError as error:
        raise argparse.ArgumentTypeError("expected an integer") from error
    if value < 0:
        raise argparse.ArgumentTypeError("expected a nonnegative amount")
    return value

def main():
    parser = argparse.ArgumentParser(description="Sum expense amounts")
    parser.add_argument("amounts", type=nonnegative, nargs="+")
    parser.add_argument("--currency", choices=["KRW", "USD"], default="KRW", help="Output unit label; no currency conversion")
    args = parser.parse_args()
    print(f"{sum(args.amounts):,} {args.currency}")

if __name__ == "__main__":
    main()

Hasil yang diharapkan:

14,000 KRW

Fungsi nonnegative menerima teks dari command line. Jika int(text) gagal, fungsi mengubahnya menjadi ArgumentTypeError dengan pesan tentang bilangan bulat. Jika konversi berhasil tetapi nilainya negatif, fungsi menghasilkan pesan tentang jumlah nonnegatif. argparse menggabungkan pesan tersebut dengan informasi pemakaian program.

parse_args() menghasilkan objek Namespace. Atribut args.amounts berisi daftar hasil konversi, sehingga sum menjumlahkan angka, bukan menyambung string. Bagian if __name__ == "__main__" menjalankan main saat file dipanggil sebagai program, tanpa langsung menjalankan parser ketika file diimpor.

Opsi --currency hanya memilih label keluaran. Memasukkan 14000 dengan label USD menghasilkan 14,000 USD; program tidak mengonversi 14000 won ke dolar. Semua angka harus sudah dinyatakan dalam satuan yang dipilih. Program ini juga memakai bilangan bulat, sehingga pecahan seperti 3.5 ditolak.

Memeriksa bantuan, kesalahan, dan status keluar

Jalankan kedua perintah ini secara terpisah agar hasil masing-masing mudah diperiksa:

python sum_cli.py --help
python sum_cli.py 0 500 --currency KRW

Perintah pertama menampilkan deskripsi, bentuk argumen, opsi bantuan, serta pilihan KRW dan USD. Bantuan dapat dipanggil tanpa memberikan jumlah; program selesai dengan status 0. Perintah kedua menampilkan 500 KRW, juga dengan status 0. Nama program, pemenggalan baris, atau warna bantuan dapat berbeda menurut versi dan terminal.

Periksa status tepat setelah setiap eksekusi: ketik $LASTEXITCODE pada PowerShell atau echo $? pada shell macOS/Ubuntu. Jangan menyisipkan program lain terlebih dahulu karena status dapat tergantikan. Saat dipanggil dari Python melalui subprocess.run, baca returncode, stdout, dan stderr secara terpisah. Kesalahan argumen biasa memakai status 2 dan pesan pada stderr; tidak ada total yang dicetak sebagai hasil sukses.

Kembalikan argumen ke 3500 8000 2500 setelah percobaan gagal dan pastikan hasil awal muncul lagi. Memeriksa kegagalan saja tidak cukup untuk memastikan pemakaian normal masih bekerja. Pengujian sebaiknya memeriksa nilai total, makna diagnostik, dan status, bukan menuntut seluruh teks bantuan identik pada semua versi.

Memperluas alat tanpa mencampur aturan bisnis

Jika perhitungan bertambah, pindahkan logika ke fungsi yang menerima nilai yang dibutuhkan dan mengembalikan hasil. Fungsi perhitungan tidak perlu mengetahui objek Namespace. Dengan rancangan itu, antarmuka command line, aplikasi lain, dan pengujian otomatis dapat memakai fungsi yang sama.

Untuk operasi yang berbeda seperti init, add, dan list, add_subparsers() dapat membagi antarmuka menjadi subperintah. Tetapkan masukan wajib, keluaran, dan status gagal untuk setiap operasi. Jangan menambahkan opsi yang namanya menjanjikan konversi atau validasi yang belum diimplementasikan.

Konverter latihan ini mengikuti aturan int, bukan format digit desimal yang paling ketat; misalnya tanda plus dan underscore yang sah dapat diterima. Jika aplikasi hanya mengizinkan digit ASCII tanpa tanda atau pemisah, tambahkan kebijakan format secara eksplisit sebelum konversi dan uji perubahannya. Rincian parser tersedia dalam dokumentasi argparse Python.