آموزش argparse در پایتون: ساخت ابزار خط فرمان (CLI)

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

۱. چرا argparse؟ استاندارد طلایی ساخت CLI در پایتون

پاسخ کوتاه: کتابخانه argparse به شما اجازه می‌دهد ورودی‌های کاربر را در خط فرمان دریافت، اعتبارسنجی و به انواع داده مناسب تبدیل کنید و به صورت خودکار راهنمای کاربری (Help) استاندارد بسازید. این کتابخانه به عنوان بخشی از ماژول‌های استاندارد پایتون، نیاز به هیچ نصب اضافه‌ای ندارد.

بسیاری از برنامه نویسان تازه کار از sys.argv برای خواندن ورودی‌های ترمینال استفاده می‌کنند. اما sys.argv صرفاً یک لیست ساده از رشته‌ها است؛ فاقد اعتبارسنجی است، نوع داده‌ها را تشخیص نمی‌دهد و اگر کاربر ورودی اشتباهی وارد کند، برنامه با خطای سیستمی کرش می‌کند. استفاده از ابزارهای استاندارد نظیر آنچه در اسنیپت‌های پایتون وجود دارد، به شما کمک می‌کند برنامه‌هایی پایدارتر بنویسید.

۲. مفاهیم پایه: آرگومان‌های موقعیتی در برابر اختیاری

در دنیای خط فرمان، ما به طور کلی با دو نوع آرگومان سر و کار داریم که شناخت تفاوت آن‌ها برای طراحی یک CLI اصولی حیاتی است:

• آرگومان‌های موقعیتی (Positional Arguments): ورودی‌هایی هستند که ترتیب وارد کردن آن‌ها مهم است و وجودشان برای اجرای برنامه الزامی است. مانند آدرس فایل مبدا در دستور کپی.
• آرگومان‌های اختیاری (Optional Arguments): با پیشوند - یا -- مشخص می‌شوند و برای تغییر رفتار پیش‌فرض برنامه به کار می‌روند. مانند پرچم --verbose برای نمایش جزئیات بیشتر.

۳. راهنمای گام‌به‌گام پیاده‌سازی یک پروژه واقعی

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

گام اول: ساخت پارسر پایه

ابتدا کتابخانه را وارد کرده و شیء اصلی پارسر را با یک توضیح کوتاه درباره عملکرد ابزار ایجاد می‌کنیم:

import argparse

parser = argparse.ArgumentParser(description="Word Counter Utility - A simple CLI tool to analyze text files.")

گام دوم: تعریف آرگومان‌ها

حالا ورودی‌های مورد نیاز را تعریف می‌کنیم. ما به یک آرگومان اجباری (مسیر فایل) و دو آرگومان اختیاری نیاز داریم:

# آرگومان موقعیتی و اجباری
parser.add_argument("filepath", type=str, help="Path to the text file you want to analyze")

# آرگومان اختیاری برای شمارش کاراکترها به جای کلمات
parser.add_argument("-c", "--chars", action="store_true", help="Count characters instead of words")

# آرگومان اختیاری برای ذخیره نتیجه در فایل خروجی
parser.add_argument("-o", "--output", type=str, help="Path to save the output results")

گام سوم: تحلیل ورودی‌ها و اجرای منطق برنامه

با صدا زدن متد parse_args() پایتون خط فرمان را می‌خواند. سپس کدهای مربوط به پردازش فایل را پیاده‌سازی می‌کنیم:

import os

args = parser.parse_args()

if not os.path.exists(args.filepath):
    print(f"Error: The file '{args.filepath}' does not exist.")
    exit(1)

with open(args.filepath, 'r', encoding='utf-8') as file:
    content = file.read()

if args.chars:
    result = f"Total characters: {len(content)}"
else:
    result = f"Total words: {len(content.split())}"

print(result)

if args.output:
    with open(args.output, 'w', encoding='utf-8') as out_file:
        out_file.write(result)
    print(f"Results saved to {args.output}")

۴. ویژگی‌های پیشرفته argparse برای حرفه‌ای‌ها

اگر می‌خواهید ابزارهای CLI شما درست مانند ابزارهای استاندارد لینوکس و گیت رفتار کنند، باید فراتر از اصول اولیه بروید. در ادامه ۳ قابلیت تخصصی که پروژه‌های شما را دگرگون می‌کنند بررسی می‌کنیم.

۱. محدود کردن ورودی‌ها با پارامتر choices

گاهی می‌خواهید کاربر فقط بتواند مقادیر خاصی را وارد کند. ویژگی choices جلوی ورود مقادیر غیرمجاز را در همان ابتدا می‌گیرد:

parser.add_argument(
    "--mode", 
    choices=["fast", "detailed", "silent"], 
    default="detailed",
    help="Select the execution mode (default: detailed)"
)

۲. آرگومان‌های متقابل انحصاری (Mutually Exclusive Groups)

گاهی دو گزینه نباید همزمان با هم مصرف شوند. به عنوان مثال، شما نمی‌توانید همزمان اسکریپت را در حالت “بسیار پرجزئیات (verbose)” و “کاملاً بی‌صدا (quiet)” اجرا کنید. این کار با متد زیر به راحتی قابل مدیریت است:

group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true", help="Increase output verbosity")
group.add_argument("-q", "--quiet", action="store_true", help="Suppress all outputs")

۳. پیاده‌سازی زیردستورها با Subparsers

برای ساخت ابزارهای پیشرفته‌ای که ساختار درختی دارند (مثل دستورات git clone یا docker run)، باید از قابلیت add_subparsers استفاده کنید:

subparsers = parser.add_subparsers(dest="command", help="Available sub-commands")

# دستور ایجاد دیتابیس
parser_db = subparsers.add_parser("init-db", help="Initialize the database")
parser_db.add_argument("--force", action="store_true", help="Force overwrite database if exists")

# دستور افزودن کاربر جدید
parser_user = subparsers.add_parser("create-user", help="Create a new system user")
parser_user.add_argument("username", type=str, help="Username of the new user")

۵. جدول مقایسه روش‌های پردازش ورودی در پایتون

۶. عیب‌یابی سریع خطاهای رایج

۷. پرسش‌های متداول (FAQ)