كيف تعرض أمر CLI من حزمة Python؟

الإجابة المختصرة

عرّف console script في [project.scripts] داخل pyproject.toml يشير إلى دالة main، فينشئ التثبيت ملفًا تنفيذيًا بهذا الاسم في bin الخاص بالبيئة.

الشرح

يفصل الـ entry point اسم الأمر عن المسار الداخلي للكود، ويعمل على كل الأنظمة دون كتابة shebang أو ملفات ‎.bat. اجعل main تعيد exit code وتستخدم argparse أو مكتبة مثل Typer أو Click، ولا تنفذ أي منطق عند الاستيراد. ويمكن أيضًا دعم python -m my_tool بإضافة __main__.py.

مثال بالكود

# pyproject.toml
[project.scripts]
invoice = "billing.cli:main"

# src/billing/cli.py
import argparse

def main() -> int:
    parser = argparse.ArgumentParser(prog="invoice")
    parser.add_argument("order_id", type=int)
    args = parser.parse_args()
    print(f"creating invoice for {args.order_id}")
    return 0

أخطاء شائعة

• تنفيذ منطق CLI في المستوى الأعلى للموديول فيعمل عند أي import.
• طلب تشغيل python path/to/script.py من المستخدمين بدل تعريف entry point.

أسئلة متابعة

• لماذا نستخدم if __name__ == "__main__"؟
• ما دور ملف pyproject.toml؟

المصادر

• Python Packaging User Guide — Creating command line tools