الأداة التي تعمل من سطر الأوامر يمكن أن توفر وقتًا كبيرًا إذا كانت تحل مهمة متكررة. لكن CLI سيئة قد تكون أصعب من المهمة نفسها. مكتبة argparse الرسمية تنظم positional arguments والخيارات وتولّد رسالة help للمستخدم [1]. سنستخدمها لبناء أداة تعرض حجم ملفات مجلد وتصدر تقريرًا JSON.
ابدأ بعقد استخدام واضح
قبل الكود، اكتب شكل الأمر: python report.py ./assets --json report.json --min-size 100. يجب أن يعرف المستخدم المسار المطلوب، وما الذي يفعله الخيار، وما القيمة الافتراضية. لا تجعل كل شيء اختياريًا ثم تخمن النية.
import argparse
from pathlib import Path
import json
def parse_args():
parser = argparse.ArgumentParser(description='إنشاء تقرير عن ملفات مجلد')
parser.add_argument('folder', type=Path, help='المجلد الذي تريد فحصه')
parser.add_argument('--json', dest='output', type=Path, help='ملف JSON اختياري')
parser.add_argument('--min-size', type=int, default=0, help='أقل حجم بالبايت')
return parser.parse_args()تحقق من المدخلات مبكرًا
التحقق المبكر يجعل الخطأ قابلًا للفهم. افحص أن المسار موجود وأنه مجلد، وأن الحجم ليس سالبًا. لا تلتقط كل الاستثناءات وتطبع “حدث خطأ” فقط؛ أعط المستخدم ما يمكنه إصلاحه.
def build_report(folder, minimum):
if not folder.exists():
raise FileNotFoundError(f'المجلد غير موجود: {folder}')
if not folder.is_dir():
raise NotADirectoryError(f'ليس مجلدًا: {folder}')
rows=[]
for path in folder.rglob('*'):
if path.is_file() and path.stat().st_size >= minimum:
rows.append({'name': str(path.relative_to(folder)), 'bytes': path.stat().st_size})
return sorted(rows, key=lambda row: row['bytes'], reverse=True)النتيجة والـexit code
اطبع ملخصًا للإنسان، واكتب JSON إذا طلب المستخدم ذلك. عند الفشل ارجع exit code غير صفري؛ هذا مهم عندما تستدعي الأداة من GitHub Actions أو سكربت آخر. جرّب help، مجلدًا فارغًا، مسارًا خاطئًا، وخيارًا بقيمة غير صالحة.
اجعل الأداة قابلة للتوزيع
ضع الكود في package صغيرة، أضف README وأمثلة، وثبّت نسخة Python. إذا احتجت dependencies، استخدم ملفًا واضحًا مثل pyproject.toml ولا تجعل التثبيت يعتمد على جهازك فقط. الأداة الجيدة تشرح نفسها من خلال --help.
مراجع رسمية
هذه الروابط الرسمية هي نقطة الرجوع عند اختلاف إصدار الأداة أو تغيّر سلوك المتصفح.