typer

Typer، قم ببناء CLIs رائعة. من السهل الترميز. بناءً على تلميحات نوع بايثون.

---

التوثيق : https://typer.tiangolo.com

كود المصدر : https://github.com/fastapi/typer

---

Typer عبارة عن مكتبة لإنشاء تطبيقات CLI التي سيحب المستخدمون استخدامها وسيحب المطورون إنشاؤها . بناءً على تلميحات نوع بايثون.

إنها أيضًا أداة سطر أوامر لتشغيل البرامج النصية، وتحويلها تلقائيًا إلى تطبيقات CLI.

الميزات الرئيسية هي:

• بديهية في الكتابة : دعم محرر رائع. الانتهاء في كل مكان. وقت أقل في التصحيح. مصممة لتكون سهلة الاستخدام والتعلم. وقت أقل في قراءة المستندات.
• سهل الاستخدام : إنه سهل الاستخدام للمستخدمين النهائيين. المساعدة التلقائية، والإكمال التلقائي لجميع الأصداف.
• باختصار : تقليل تكرار التعليمات البرمجية. ميزات متعددة من كل إعلان المعلمة. أخطاء أقل.
• ابدأ ببساطة : يضيف المثال الأبسط سطرين فقط من التعليمات البرمجية إلى تطبيقك: استيراد واحد واستدعاء دالة واحد .
• النمو بشكل كبير : يمكنك زيادة التعقيد بقدر ما تريد، وإنشاء أشجار معقدة عشوائيًا من الأوامر ومجموعات من الأوامر الفرعية، مع الخيارات والوسائط.
• تشغيل البرامج النصية : يتضمن Typer أمر/برنامج من typer يمكنك استخدامه لتشغيل البرامج النصية، وتحويلها تلقائيًا إلى CLIs، حتى لو لم يستخدموا Typer داخليًا.

FastAPI من CLIs

Typer هو الأخ الأصغر لـ FastAPI، وهو FastAPI لـ CLIs.

تثبيت

قم بإنشاء وتنشيط بيئة افتراضية ثم قم بتثبيت Typer :

$ pip install typer
---> 100%
Successfully installed typer rich shellingham 

مثال

الحد الأدنى المطلق

• قم بإنشاء ملف main.py باستخدام:

 def main ( name : str ):
    print ( f"Hello { name } " )

لا يستخدم هذا البرنامج النصي Typer داخليًا. ولكن يمكنك استخدام أمر typer لتشغيله كتطبيق CLI.

تشغيله

قم بتشغيل التطبيق الخاص بك باستخدام أمر typer :

 // Run your application
$ typer main.py run

// You get a nice error, you are missing NAME
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ typer main.py run --help

Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME

Run the provided Typer app.

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// Now pass the NAME argument
$ typer main.py run Camila

Hello Camila

// It works! ?

هذه هي أبسط حالة استخدام، ولا حتى استخدام Typer داخليًا، ولكنها قد تكون مفيدة جدًا بالفعل للنصوص البرمجية البسيطة.

ملاحظة : يعمل الإكمال التلقائي عند إنشاء حزمة Python وتشغيلها باستخدام --install-completion أو عند استخدام أمر typer .

استخدم Typer في التعليمات البرمجية الخاصة بك

لنبدأ الآن في استخدام Typer في التعليمات البرمجية الخاصة بك، وقم بتحديث main.py باستخدام:

 import typer


def main ( name : str ):
    print ( f"Hello { name } " )


if __name__ == "__main__" :
    typer . run ( main )

يمكنك الآن تشغيله باستخدام Python مباشرةً:

 // Run your application
$ python main.py

// You get a nice error, you are missing NAME
Usage: main.py [OPTIONS] NAME
Try 'main.py --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ python main.py --help

Usage: main.py [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// Now pass the NAME argument
$ python main.py Camila

Hello Camila

// It works! ?

ملاحظة : يمكنك أيضًا استدعاء نفس البرنامج النصي باستخدام أمر typer ، لكنك لا تحتاج إلى ذلك.

ترقية المثال

وكان هذا أبسط مثال ممكن.

الآن دعونا نرى واحدًا أكثر تعقيدًا بعض الشيء.

مثال مع أمرين فرعيين

قم بتعديل الملف main.py .

قم بإنشاء تطبيق typer.Typer() ، وقم بإنشاء أمرين فرعيين مع المعلمات الخاصة بهما.

 import typer

app = typer . Typer ()


@ app . command ()
def hello ( name : str ):
    print ( f"Hello { name } " )


@ app . command ()
def goodbye ( name : str , formal : bool = False ):
    if formal :
        print ( f"Goodbye Ms. { name } . Have a good day." )
    else :
        print ( f"Bye { name } !" )


if __name__ == "__main__" :
    app ()

وهذا سوف:

• قم بإنشاء تطبيق typer.Typer بشكل صريح.
  • في الواقع، يقوم typer.run السابق بإنشاء واحد ضمنيًا لك.
• أضف أمرين فرعيين باستخدام @app.command() .
• قم بتنفيذ app() نفسه، كما لو كان وظيفة (بدلاً من typer.run ).

قم بتشغيل المثال الذي تمت ترقيته

تحقق من المساعدة الجديدة:

$ python main.py --help

 Usage: main.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ─────────────────────────────────────────╮
│ --install-completion          Install completion  │
│                               for the current     │
│                               shell.              │
│ --show-completion             Show completion for │
│                               the current shell,  │
│                               to copy it or       │
│                               customize the       │
│                               installation.       │
│ --help                        Show this message   │
│                               and exit.           │
╰───────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────╮
│ goodbye                                           │
│ hello                                             │
╰───────────────────────────────────────────────────╯

// When you create a package you get  auto-completion  for free, installed with --install-completion

// You have 2 subcommands (the 2 functions): goodbye and hello

تحقق الآن من المساعدة الخاصة بالأمر hello :

$ python main.py hello --help

 Usage: main.py hello [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

والآن تحقق من المساعدة الخاصة بأمر goodbye :

$ python main.py goodbye --help

 Usage: main.py goodbye [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --formal    --no-formal      [default: no-formal] │
│ --help                       Show this message    │
│                              and exit.            │
╰───────────────────────────────────────────────────╯

// Automatic --formal and --no-formal for the bool option ?

يمكنك الآن تجربة تطبيق سطر الأوامر الجديد:

 // Use it with the hello command

$ python main.py hello Camila

Hello Camila

// And with the goodbye command

$ python main.py goodbye Camila

Bye Camila!

// And with --formal

$ python main.py goodbye --formal Camila

Goodbye Ms. Camila. Have a good day.

خلاصة

باختصار، يمكنك الإعلان مرة واحدة عن أنواع المعلمات ( وسائط CLI وخيارات CLI ) كمعلمات دالة.

يمكنك القيام بذلك باستخدام أنواع Python الحديثة القياسية.

ليس عليك أن تتعلم بناء جملة جديدًا، أو أساليب أو فئات مكتبة معينة، وما إلى ذلك.

فقط بيثون القياسية.

على سبيل المثال، بالنسبة إلى int :

 total : int

أو لعلامة bool :

 force : bool

وبالمثل بالنسبة للملفات والمسارات والتعدادات (الاختيارات) وما إلى ذلك. وهناك أدوات لإنشاء مجموعات من الأوامر الفرعية وإضافة البيانات الوصفية والتحقق الإضافي وما إلى ذلك.

تحصل على : دعم محرر رائع، بما في ذلك عمليات التحقق من الإكمال والنوع في كل مكان.

يحصل المستخدمون لديك على : --help تلقائية، وإكمال تلقائي في أجهزتهم الطرفية (Bash، وZsh، وFish، وPowerShell) عندما يقومون بتثبيت الحزمة الخاصة بك أو عند استخدام أمر typer .

للحصول على مثال أكثر اكتمالا يتضمن المزيد من الميزات، راجع البرنامج التعليمي - دليل المستخدم.

التبعيات

يقف تايبر على أكتاف عملاق. التبعية الداخلية الوحيدة المطلوبة هي النقر.

افتراضيًا، يأتي أيضًا مع تبعيات قياسية إضافية:

• rich : لإظهار الأخطاء المنسقة بشكل جيد تلقائيًا.
• shellingham : لاكتشاف الصدفة الحالية تلقائيًا عند اكتمال التثبيت.
  • مع shellingham يمكنك فقط استخدام --install-completion .
  • بدون shellingham ، يجب عليك تمرير اسم الصدفة لتثبيت الإكمال لها، على سبيل المثال --install-completion bash .

typer-slim

إذا كنت لا تريد التبعيات الاختيارية القياسية الإضافية، فقم بتثبيت typer-slim بدلاً من ذلك.

عند التثبيت باستخدام:

pip install typer

... يتضمن نفس الكود والتبعيات مثل:

pip install " typer-slim[standard] "

التبعيات الإضافية standard rich و shellingham .

ملاحظة : يتم تضمين أمر typer فقط في حزمة typer .

رخصة

هذا المشروع مرخص بموجب شروط ترخيص MIT.