بناء أداة CLI

بناء أداة CLI — Building a CLI Tool

أحد أقوى استخدامات Python هو بناء أدوات سطر الأوامر — برامج تشغّلها من الطرفية وتمرر لها معاملات مباشرةً. هذه الأدوات تُبنى بلغة Python في ثوانٍ وتعمل على كل نظام تشغيل. ستتعلم في هذا الدرس كيف تصنع أداة CLI احترافية خطوة بخطوة.

ملاحظة عن البيئة التفاعلية: الأمثلة التفاعلية هنا تعمل داخل المتصفح عبر Pyodide. لأن sys.argv في المتصفح لا يحمل معاملات حقيقية، نمرر المعاملات مباشرةً عبر parse_args([...]). هذا النمط مطابق تماماً لما يحدث على جهازك الحقيقي — الفرق الوحيد هو مصدر المعاملات.

sys.argv — المعاملات البسيطة

حين تشغّل برنامج Python من الطرفية، تصلك المعاملات عبر sys.argv — وهي قائمة (list) فيها اسم البرنامج أولاً ثم المعاملات التي مررتها:

python converter.py celsius 100

ما يصل إلى البرنامج:

sys.argv = ["converter.py", "celsius", "100"]
#            [0]              [1]         [2]

sys.argv[0] هو اسم البرنامج دائماً. المعاملات تبدأ من sys.argv[1].

جرّب هذا المثال التفاعلي — يُحاكي قراءة sys.argv ومعالجتها:

main.go

import sys

# محاكاة sys.argv — Simulating sys.argv
# في الجهاز الحقيقي: sys.argv = ["converter.py", "celsius", "100"]
args = ["converter.py", "celsius", "100"]

print("اسم البرنامج:", args[0])  # Program name
print("عدد المعاملات:", len(args) - 1)  # Number of args

if len(args) > 1:
    print("المعاملات:", args[1:])  # Arguments
    for i, arg in enumerate(args[1:], start=1):
        # طباعة كل معامل — Print each argument
        print(f"  معامل {i}: {arg}")
else:
    print("لم تُمرر أي معاملات!")
    print("الاستخدام: python script.py <وحدة> <قيمة>")

Output:

المشكلة مع sys.argv المباشر أنك تحتاج لمعالجة كل شيء يدوياً: التحقق من وجود المعاملات، تحويل الأنواع، طباعة رسالة المساعدة. لهذا أنشأت Python مكتبة argparse.

argparse — المعاملات الاحترافية

argparse مكتبة مدمجة في Python تمنحك:

معاملات موضعية (positional arguments): مطلوبة دائماً، بترتيب محدد
خيارات (optional arguments): تبدأ بـ -- أو -، لها قيم افتراضية
أعلام (flags): خيارات boolean مثل --verbose
رسالة مساعدة تلقائية: --help تُولَّد تلقائياً

بنية argparse الأساسية:

import argparse

# 1. أنشئ الـ parser — Create parser
parser = argparse.ArgumentParser(description="وصف الأداة")

# 2. عرّف المعاملات — Define arguments
parser.add_argument("name")                    # موضعي — positional
parser.add_argument("--age", type=int)         # خيار — optional
parser.add_argument("--verbose", action="store_true")  # علم — flag

# 3. حلّل المعاملات — Parse arguments
args = parser.parse_args(["أحمد", "--age", "25", "--verbose"])

# 4. استخدم النتائج — Use results
print(args.name)    # "أحمد"
print(args.age)     # 25  (تحوّل تلقائياً لـ int)
print(args.verbose) # True

جرّب مثالاً كاملاً:

main.go

import argparse

# إنشاء الـ parser — Create the parser
parser = argparse.ArgumentParser(
    prog="greeter",
    description="أداة للتحية — A greeting tool"
)

# معامل موضعي — Positional argument (required)
parser.add_argument(
    "name",
    help="اسم الشخص للتحية"
)

# خيار اختياري — Optional argument with default
parser.add_argument(
    "--greeting", "-g",
    default="مرحباً",
    help="رسالة التحية (الافتراضي: مرحباً)"
)

# خيار رقمي — Numeric option
parser.add_argument(
    "--times", "-t",
    type=int,
    default=1,
    help="عدد مرات التحية (الافتراضي: 1)"
)

# علم boolean — Boolean flag
parser.add_argument(
    "--formal",
    action="store_true",
    help="استخدم أسلوباً رسمياً"
)

# تحليل المعاملات مباشرةً — Parse args directly (in-browser simulation)
args = parser.parse_args(["عزيز", "--greeting", "السلام عليكم", "--times", "2", "--formal"])

# استخدام النتائج — Use the results
for i in range(args.times):
    if args.formal:
        print(f"{args.greeting}، الأستاذ {args.name}.")
    else:
        print(f"{args.greeting} يا {args.name}!")

Output:

أنواع وخيارات متقدمة

argparse يدعم أنواعاً وقيوداً متعددة:

الخاصية	الاستخدام	المعنى
`type=int`	`--count 5`	تحويل تلقائي لـ int
`type=float`	`--rate 3.14`	تحويل لـ float
`default=X`	غير موجود	استخدام X إذا لم يُمرر
`required=True`	—	إجباري حتى لو يبدأ بـ `--`
`choices=[...]`	`--unit km`	قبول قيم محددة فقط
`action="store_true"`	`--verbose`	True إذا وجد، False إذا غاب
`nargs="+"`	`--files a b c`	قبول قائمة من القيم

مثال على choices وtype:

main.go

import argparse

parser = argparse.ArgumentParser(description="محوّل العملات — Currency info")

# choices يقبل قيم محددة فقط — choices restricts accepted values
parser.add_argument(
    "--currency",
    choices=["SAR", "USD", "EUR", "GBP"],
    default="SAR",
    help="العملة"
)

# type=float للتحويل التلقائي — auto-convert to float
parser.add_argument(
    "--amount",
    type=float,
    required=True,
    help="المبلغ"
)

# flag للتفاصيل — verbose flag
parser.add_argument("--verbose", action="store_true")

args = parser.parse_args(["--currency", "USD", "--amount", "100.5", "--verbose"])

print(f"المبلغ: {args.amount:.2f} {args.currency}")

if args.verbose:
    rates = {"SAR": 3.75, "USD": 1.0, "EUR": 0.92, "GBP": 0.79}
    rate = rates[args.currency]
    in_usd = args.amount / rate
    print(f"بالدولار: {in_usd:.2f} USD")
    print(f"سعر الصرف: 1 USD = {rate} {args.currency}")

Output:

مشروع: محوّل الوحدات — Unit Converter

لنبني أداة CLI كاملة تحوّل بين وحدات الحرارة والمسافة. هذا المشروع يجمع كل ما تعلمناه: معاملات موضعية، خيارات، choices، type=float.

منطق التحويل:

درجات حرارة: °C → °F: (C × 9/5) + 32 | °F → °C: (F - 32) × 5/9
مسافة: كيلومتر → ميل: km × 0.621371 | ميل → كيلومتر: miles × 1.60934

main.go

import argparse

def celsius_to_fahrenheit(c):
    # تحويل سيلسيوس لفهرنهايت — Celsius to Fahrenheit
    return (c * 9 / 5) + 32

def fahrenheit_to_celsius(f):
    # تحويل فهرنهايت لسيلسيوس — Fahrenheit to Celsius
    return (f - 32) * 5 / 9

def km_to_miles(km):
    # تحويل كيلومتر لميل — Kilometers to miles
    return km * 0.621371

def miles_to_km(miles):
    # تحويل ميل لكيلومتر — Miles to kilometers
    return miles * 1.60934

# إنشاء الـ parser — Create parser
parser = argparse.ArgumentParser(
    prog="converter",
    description="محوّل الوحدات — Unit Converter"
)

parser.add_argument("--from-unit", "-f",
    choices=["C", "F", "km", "mi"],
    required=True,
    help="الوحدة الأصلية (C/F/km/mi)"
)

parser.add_argument("--to-unit", "-t",
    choices=["C", "F", "km", "mi"],
    required=True,
    help="الوحدة الهدف (C/F/km/mi)"
)

parser.add_argument("--value", "-v",
    type=float,
    required=True,
    help="القيمة المراد تحويلها"
)

# محاكاة تشغيل: converter --from-unit C --to-unit F --value 100
args = parser.parse_args(["--from-unit", "C", "--to-unit", "F", "--value", "100"])

# منطق التحويل — Conversion logic
conversions = {
    ("C", "F"): celsius_to_fahrenheit,
    ("F", "C"): fahrenheit_to_celsius,
    ("km", "mi"): km_to_miles,
    ("mi", "km"): miles_to_km,
}

key = (args.from_unit, args.to_unit)

if key not in conversions:
    print(f"خطأ: لا يمكن التحويل من {args.from_unit} إلى {args.to_unit}")
else:
    result = conversions[key](args.value)
    print(f"{args.value:.2f} {args.from_unit} = {result:.2f} {args.to_unit}")

Output:

لاحظ أن argparse يحوّل --from-unit تلقائياً إلى args.from_unit (يستبدل - بـ _). هذا سلوك مقصود في المكتبة.

تشغيل الأداة على جهازك الحقيقي

احفظ الكود في ملف converter.py وشغّله:

# تحويل درجات الحرارة — Temperature conversion
python converter.py --from-unit C --to-unit F --value 100
# النتيجة: 100.00 C = 212.00 F

# تحويل المسافة — Distance conversion
python converter.py --from-unit km --to-unit mi --value 10
# النتيجة: 10.00 km = 6.21 mi

# طباعة المساعدة — Print help
python converter.py --help

argparse يولّد رسالة --help تلقائياً من الأوصاف التي كتبتها — هذا ما يجعل أدوات CLI الاحترافية واضحة وقابلة للاستخدام.

التحديات — Challenges

تحدي 1: معامل واحد

اكتب برنامجاً يقبل معاملاً موضعياً واحداً اسمه city ويطبع مرحباً من: <city>. مرر ["الرياض"] إلى parse_args.

تحدي — Challenge

import argparse

parser = argparse.ArgumentParser()

# أضف معامل موضعي اسمه city — Add positional argument 'city'
# اكتب الكود هنا

args = parser.parse_args(["الرياض"])
print(f"مرحباً من: {args.city}")

تحدي 2: إضافة علم

أضف علماً اسمه --uppercase إلى برنامج التحية. إذا كان موجوداً، اطبع النص بأحرف كبيرة. مرر ["python", "--uppercase"] إلى parse_args. المتوقع: PYTHON.

تحدي — Challenge

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("text", help="النص المراد طباعته")

# أضف علم --uppercase — Add --uppercase flag
# اكتب الكود هنا

args = parser.parse_args(["python", "--uppercase"])

# طبع النص بأحرف كبيرة إذا كان العلم موجوداً — Print uppercase if flag set
# اكتب الكود هنا

تحدي 3: تحويل درجة الحرارة

اكتب برنامجاً يقبل درجة حرارة بالسيلسيوس (type=float) ويطبع مكافئها بالفهرنهايت. مرر ["--celsius", "0"] إلى parse_args. المتوقع: 32.0.

تحدي — Challenge

import argparse

parser = argparse.ArgumentParser()

# أضف خيار --celsius بنوع float — Add --celsius option with type=float
# اكتب الكود هنا

args = parser.parse_args(["--celsius", "0"])

# احسب الفهرنهايت وأطبع النتيجة — Calculate Fahrenheit and print
# اكتب الكود هنا

تحدي 4: محوّل المسافة الكامل

اكتب محوّلاً يقبل --km (float) ويطبع المسافة بالأميال. 1 km = 0.621371 miles. مرر ["--km", "10"] إلى parse_args. المتوقع: 6.21.

تحدي — Challenge

import argparse

parser = argparse.ArgumentParser()

# أضف خيار --km — Add --km option
# اكتب الكود هنا

args = parser.parse_args(["--km", "10"])

# احسب الأميال وأطبع النتيجة — Calculate miles and print
# اكتب الكود هنا