آموزش استفاده از argparse برای نوشتن برنامه‌های خط فرمان در پایتون

مقدمه‌ای بر argparse در پایتون برای ساخت رابط خط فرمان

ماژول استاندارد argparse در پایتون ابزاری است که به شما کمک می‌کند رابط‌های خط فرمان (CLI) برای کد پایتون خود بسازید. ممکن است با CLIها آشنا باشید: برنامه‌هایی مثل git، ls، grep و find همه رابط‌های خط فرمانی ارائه می‌دهند که به شما اجازه می‌دهد برنامه را با ورودی‌ها و گزینه‌های مشخص اجرا کنید. argparse به شما امکان می‌دهد کد پایتون خود را با آرگومان‌های خط فرمانی مشابه صدا بزنید، مشابه نحوه استفاده از ابزارهایی مثل git، ls، grep، یا find. این ابزار برای مواقعی که می‌خواهید دیگر توسعه‌دهندگان بتوانند کد شما را از طریق خط فرمان اجرا کنند بسیار مفید است.

در این آموزش، از ابزارهای ارائه شده توسط ماژول argparse استفاده خواهید کرد تا رابط خط فرمانی بسازید که آرگومان‌های موقعیتی و اختیاری را دریافت می‌کند و رفتار برنامه را کنترل می‌کند. همچنین با استفاده از متن راهنما، رابط کاربری خود مستندسازی خواهید کرد تا دیگر توسعه‌دهندگان بتوانند به راحتی از آن استفاده کنند.

برای این آموزش، رابط خط فرمان برنامه‌ای را خواهید نوشت که ماهی‌ها را در یک آکواریوم داستانی مدیریت می‌کند.

نوشتن CLI با آرگومان موقعیتی

می‌توانید از ماژول argparse برای نوشتن یک رابط خط فرمان استفاده کنید که یک آرگومان موقعیتی دریافت می‌کند. آرگومان‌های موقعیتی معمولا ورودی‌های اجباری به برنامه شما هستند.

به عنوان مثال، یک CLI که ماهی‌های داخل یک تانک آکواریوم را چاپ می‌کند که نام تانک به عنوان آرگومان موقعیتی دریافت می‌شود.

یک فایل به نام aquarium.py باز کنید و کد زیر را وارد کنید:

import argparse

tank_to_fish = {
    "tank_a": "clownfish, tang, and butterfly fish",
    "tank_b": "surgeonfish, butterfly fish, and tang"
}

parser = argparse.ArgumentParser(description="List fish in an aquarium")
parser.add_argument("tank", type=str, help="Tank to print fish from.")
args = parser.parse_args()

print(tank_to_fish[args.tank])

اگر دستور زیر را اجرا کنید، ماهی‌های داخل tank_a چاپ می‌شوند:

python3 aquarium.py tank_a

خروجی مشابه زیر خواهید داشت:

clownfish, tang, and butterfly fish

همچنین، اجرای دستور زیر ماهی‌های داخل tank_b را چاپ می‌کند:

python3 aquarium.py tank_b

خروجی مشابه زیر خواهد بود:

surgeonfish, butterfly fish, and tang

توضیح کد

ابتدا ماژول argparse را وارد می‌کنید. سپس یک دیکشنری به نام tank_to_fish تعریف می‌کنید که نام تانک‌ها را به رشته‌ای از ماهی‌های داخل آنها نگاشت می‌کند.

یک نمونه از کلاس ArgumentParser ساخته و به متغیر parser نسبت می‌دهید. parser نقطه اصلی برای تنظیم رابط خط فرمان شما است. توضیحی که به آرگومان description می‌دهید به طور خودکار در متن راهنما نمایش داده می‌شود.

با فراخوانی add_argument، یک آرگومان به CLI اضافه می‌کنید که در اینجا یک آرگومان موقعیتی به نام tank است و نوع آن رشته است. فراخوانی parser.parse_args() باعث می‌شود ورودی خط فرمان پردازش و اعتبارسنجی شود. سپس مقدار آرگومان ورودی را می‌توانید از طریق args.tank دریافت کنید و ماهی‌های آن تانک را چاپ کنید.

استفاده از متن راهنما

argparse به طور خودکار یک گزینه -h یا --help اضافه می‌کند که متن راهنمای CLI را نمایش می‌دهد.

اگر aquarium.py را با آرگومان‌های نادرست اجرا کنید مثلاً بدون وارد کردن tank، خروجی خطا و پیام دستور استفاده را خواهید دید:

python3 aquarium.py
usage: aquarium.py [-h] tank
aquarium.py: error: the following arguments are required: tank

با اجرای دستور زیر، متن راهنما را دریافت می‌کنید:

python3 aquarium.py -h

خروجی مانند زیر خواهد بود:

usage: aquarium.py [-h] tank

List fish in an aquarium

positional arguments:
  tank        Tank to print fish from.

optional arguments:
  -h, --help  show this help message and exit

اضافه کردن آرگومان اختیاری

گاه بهتر است آرگومان‌های اختیاری هم داشته باشید. این گزینه‌ها معمولا با دو خط فاصله شروع می‌شوند، مثلا --some-option. بیایید کد aquarium.py را بازنویسی کنیم تا گزینه --upper-case را اضافه کنیم:

import argparse

tank_to_fish = {
    "tank_a": "clownfish, tang, and butterfly fish",
    "tank_b": "surgeonfish, butterfly fish, and tang"
}

parser = argparse.ArgumentParser(description="List fish in an aquarium")
parser.add_argument("tank", type=str, help="Tank to print fish from.")
parser.add_argument("--upper-case", default=False, action="store_true", help="Print fish in uppercase.")
args = parser.parse_args()

fish = tank_to_fish[args.tank]
if args.upper_case:
    fish = fish.upper()

print(fish)

اگر دستور زیر را اجرا کنید، خروجی به صورت حروف بزرگ چاپ می‌شود:

python3 aquarium.py tank_a --upper-case

خروجی چیزی مانند زیر خواهد بود:

CLOWNFISH, TANG, AND BUTTERFLY FISH

گزینه --upper-case با تنظیم default=False به صورت پیش‌فرض خاموش است و با تنظیم action="store_true" اگر این گزینه ارائه شود مقدارش True می‌شود.

توجه کنید که در کد برای دسترسی به این گزینه از args.upper_case استفاده شده است، چون argparse خط فاصله‌ها را به آندرلاین تبدیل می‌کند.

بهبود متن راهنما با نمایش مقدار پیش‌فرض

با استفاده از آرگومان formatter_class=argparse.ArgumentDefaultsHelpFormatter هنگام ساخت ArgumentParser می‌توانید مقدار پیش‌فرض را در متن راهنما نمایش دهید:

parser = argparse.ArgumentParser(
    description="List fish in an aquarium",
    formatter_class=argparse.ArgumentDefaultsHelpFormatter
)

اکنون متن راهنمای CLI هنگام اجرای دستور python3 aquarium.py --help شامل مقادیر پیش‌فرض برای گزینه‌ها می‌شود.

جمع‌بندی

ماژول argparse بخشی قدرتمند از کتابخانه استاندارد پایتون است که به شما اجازه می‌دهد رابط‌های خط فرمان برای برنامه‌های خود ایجاد کنید. این آموزش شما را با مفاهیم پایه شامل آرگومان‌های موقعیتی، اختیاری و مستندسازی با متن راهنما آشنا کرد.

می‌توانید برای یادگیری امکانات بیشتر به مستندات رسمی argparse مراجعه کنید.

از همراهی شما با پارمین کلود متشکریم.