Membuat CLI dengan argparse

Program yang berperilaku persis sama setiap kali dijalankan hanya cocok untuk demo. Begitu sebuah program perlu menyapa nama yang berbeda, memproses berkas tertentu, atau menyalakan mode debug, program tersebut membutuhkan cara menerima instruksi dari pengguna pada saat dijalankan dari terminal. Pada Chapter ini kita membangun command line interface (CLI) pertama dengan module argparse dari standard library Python.

Argumen Mentah dengan sys.argv #

Semua kata yang diketik pengguna setelah nama program tersedia melalui list sys.argv. Interpreter Python mengisi sys.argv[0] dengan nama berkas program, lalu mengisi elemen berikutnya dengan setiap kata argumen. Simpan skrip berikut sebagai argv_demo.py:

import sys

print("nama program :", sys.argv[0])
print("argumen     :", sys.argv[1:])

Jalankan dengan python3 argv_demo.py Budi Siti. Output yang Dihasilkan:

nama program : argv_demo.py
argumen     : ['Budi', 'Siti']

Membaca argumen langsung dari sys.argv memaksa kita menangani sendiri semua detail: nilai default, opsi --help, pesan galat yang jelas, sampai validasi jumlah argumen. Module argparse mengambil alih seluruh pekerjaan tersebut.

Parser Pertama dengan argparse #

Pola kerja argparse terdiri dari tiga langkah: buat object ArgumentParser, daftarkan setiap argumen dengan method add_argument(), lalu panggil parse_args() untuk mengubah kata-kata di terminal menjadi object Namespace. Berkas salam.py berikut menyapa satu nama dengan sapaan yang bisa diganti:

import argparse

parser = argparse.ArgumentParser(description="Menyapa seseorang dari terminal.")
parser.add_argument("nama", help="nama yang akan disapa")
parser.add_argument("--sapaan", default="Halo", help="kata sapaan pembuka")

args = parser.parse_args()
print(f"{args.sapaan}, {args.nama}!")

Mari kita bedah baris-baris pentingnya:

1. Baris 3 (parser = argparse.ArgumentParser(description=): membuat object parser sekaligus menetapkan deskripsi program yang tampil pada bantuan --help.
2. Baris 4 (parser.add_argument("nama", help="nama yang akan disapa")): nama tanpa awalan berarti argumen posisional, sehingga wajib diisi pengguna.
3. Baris 5 (parser.add_argument("--sapaan", default="Halo",): nama berawalan -- berarti opsional; parameter default menetapkan nilai saat opsi tidak dipakai.
4. Baris 7 (args = parser.parse_args()): membaca sys.argv, memvalidasi isinya, lalu mengembalikan object Namespace berisi args.nama dan args.sapaan.

Jalankan dua variasi pemakaian:

python3 salam.py Budi
python3 salam.py Siti --sapaan "Selamat pagi"

Output yang Dihasilkan:

Halo, Budi!
Selamat pagi, Siti!

Bantuan bawaan dapat dilihat dengan python3 salam.py --help:

usage: salam.py [-h] [--sapaan SAPAAN] nama

Menyapa seseorang dari terminal.

positional arguments:
  nama             nama yang akan disapa

options:
  -h, --help       show this help message and exit
  --sapaan SAPAAN  kata sapaan pembuka

Seluruh blok bantuan di atas dihasilkan otomatis dari teks help dan struktur argumen; lebar kolomnya mengikuti lebar terminal. Jika argumen wajib tidak diisi, parser mencetak pesan galat ke stderr dan mengakhiri program dengan exit code 2:

usage: salam.py [-h] [--sapaan SAPAAN] nama
salam.py: error: the following arguments are required: nama

Argumen Posisional vs Opsional #

Perbedaan dua jenis argumen tersebut dirangkum pada tabel berikut:

Gunakan argumen posisional untuk data inti program dan argumen opsional untuk pengaturan yang punya nilai masuk akal secara default.

Pola main() dan Exit Code #

CLI yang mudah diuji memisahkan parsing dari eksekusi lewat fungsi main(argv=None), seperti pada pola_main.py:

import argparse
import sys


def buat_parser():
    parser = argparse.ArgumentParser(description="Menyapa seseorang dari terminal.")
    parser.add_argument("nama", help="nama yang akan disapa")
    parser.add_argument("--sapaan", default="Halo", help="kata sapaan pembuka")
    return parser


def main(argv=None):
    args = buat_parser().parse_args(argv)
    print(f"{args.sapaan}, {args.nama}!")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Pola ini memberi dua keuntungan. Pertama, fungsi main() bisa dipanggil dari test dengan list argumen, misalnya pola_main.main(["Budi"]), tanpa perlu terminal. Kedua, nilai kembalian main() menjadi exit code proses berkat sys.exit(). Kode keluar yang lazim:

Contoh exit code 1 dari cek-stok.py:

import sys

stok = {"jeruk": 12, "pisang": 7}

if min(stok.values()) < 10:
    print("stok kritis")
    sys.exit(1)

python3 cek-stok.py
echo $?

Output yang Dihasilkan:

stok kritis
1

Subperintah dengan add_subparsers #

Program seperti git bekerja lewat subperintah: git commit, git push, dan seterusnya. Method add_subparsers() menyediakan pola yang sama, seperti pada tugas.py:

import argparse

parser = argparse.ArgumentParser(description="Manajemen tugas sederhana.")
subparser = parser.add_subparsers(dest="perintah", required=True)

parser_tambah = subparser.add_parser("tambah", help="menambah tugas baru")
parser_tambah.add_argument("judul", help="judul tugas")

parser_daftar = subparser.add_parser("daftar", help="menampilkan daftar tugas")

args = parser.parse_args()

if args.perintah == "tambah":
    print(f"tugas ditambahkan: {args.judul}")
elif args.perintah == "daftar":
    print("belum ada tugas")

Method add_parser() membuat parser mandiri untuk tiap subperintah, lengkap dengan argumen dan --help masing-masing. Kata pertama di terminal menentukan parser mana yang dipakai:

python3 tugas.py tambah "Belajar Python"
python3 tugas.py daftar

Output yang Dihasilkan:

tugas ditambahkan: Belajar Python
belum ada tugas

Dengan parser, nilai default, exit code, dan subperintah, kita sudah memiliki kerangka CLI yang layak. Chapter Command-Line Options memperdalam tipe argumen, flag, dan desain bantuan --help.