ایجاد رابط های خط فرمان (CLI) با Fire در پایتون

معرفی

آ رابط خط فرمان (CLI) روشی برای تعامل با رایانه با استفاده از دستورات متنی است.

بسیاری از ابزارهایی که نیازی به رابط کاربری گرافیکی ندارند به عنوان ابزار / ابزارهای CLI نوشته می شوند. اگرچه پایتون دارای داخلی است argparse ماژول، کتابخانه های دیگری با عملکرد مشابه وجود دارد.

این کتابخانه‌ها می‌توانند در نوشتن اسکریپت‌های CLI، ارائه خدماتی مانند تجزیه گزینه‌ها و پرچم‌ها برای عملکرد بسیار پیشرفته‌تر CLI به ما کمک کنند.

این مقاله در مورد Python Fire کتابخانه، نوشته شده توسط Google Inc.، ابزاری مفید برای ایجاد CLI با حداقل کد.

فرم عمومی برنامه های کاربردی CLI

قبل از شروع با Fire کتابخانه بیایید سعی کنیم اصول آن را درک کنیم command-line برنامه های رابط به طور کلی بسته به روی برنامه و دستور، الگوی کلی یک CLI را می توان به صورت زیر خلاصه کرد:

prompt command parameter1 parameter2 ... parameterN

• سریع دنباله ای از شخصیت هایی است که درخواست می کند کاربر برای وارد کردن یک دستور
• فرمان نام برنامه ای است که کاربر در حال اجرای آن است (مثلاً ls)
• مولفه های توکن های اختیاری هستند که خروجی فرمان را تقویت یا تغییر می دهند

یک برنامه CLI با تایپ نام برنامه بعد از عبارت اجرا می شود prompt ظاهر می شود، در این مورد $ سمبل.

در اینجا ما از ls دستوری که فهرستی از نام فایل‌ها را در یک فهرست برمی‌گرداند، دایرکتوری فعلی پیش‌فرض است:

$ ls
README.md
python

شما می توانید رفتار یا خروجی a را تغییر دهید command-line برنامه با ارائه لیستی از نشانه ها یا پارامترهایی که بیشتر به عنوان شناخته می شوند پرچم ها. بیایید پرچمی را امتحان کنیم ls دستور:

$ ls -l
-rwxrwxrwx 1 pandeytapan pandeytapan  10 Sep 23 18:29 README.md
drwxrwxrwx 1 pandeytapan pandeytapan 512 Sep 23 18:29 python

همانطور که می بینید، پس از عبور از -l پرچم، ما اطلاعات اضافی برای هر ورودی مانند مالک، گروه و اندازه فایل دریافت می کنیم.

پرچم هایی که یک خط فاصله دارند (-) گزینه های کوتاه نامیده می شوند، در حالی که آنهایی که دو خط فاصله دارند (--) گزینه های طولانی نامیده می شوند. هر دو نوع را می توان با هم در یک دستور استفاده کرد، مانند مثال زیر:

$ ls -l --time-style=full-iso
-rwxrwxrwx 1 pandeytapan pandeytapan  10 2020-09-23 18:29:25.501149000 +0530 README.md
drwxrwxrwx 1 pandeytapan pandeytapan 512 2020-09-23 18:29:25.506148600 +0530 python

تفاوت بین گزینه های کوتاه و بلند:

1. گزینه های کوتاه را می توان با زنجیر به هم متصل کرد
   • اگر بخواهیم از هر دو استفاده کنیم -l و -a گزینه های کوتاه ما فقط تایپ می کنیم -al
2. گزینه های کوتاه با یک کاراکتر مشخص می شوند در حالی که گزینه های طولانی یک نام کامل با خط فاصله دارند و نمی توان آنها را به هم متصل کرد.

این --time-style پرچم با -l پرچم گذاری کنید و فرمت زمان نمایش فهرست دایرکتوری را کنترل می کند.

یک CLI راه آسانی را برای کاربر فراهم می کند تا برنامه را از خط فرمان پیکربندی و اجرا کند. گوگل Python Fire کتابخانه اضافه کردن یک جزء پردازشی CLI را به هر اسکریپت موجود پایتون آسان می کند.

بیایید ببینیم چگونه با استفاده از یک برنامه خط فرمان بسازیم Python Fire.

نصب و راه اندازی

بیایید پیش برویم و کتابخانه را با استفاده از آن نصب کنیم pip:

$ pip install fire

Python Fire آثار روی هر شی پایتون مانند توابع، کلاس ها، دیکشنری ها، لیست ها و غیره. بیایید سعی کنیم کاربرد Python Fire کتابخانه از طریق چند مثال

ایجاد برنامه CLI با Python Fire

بیایید یک فیلمنامه بسازیم، بگوییم، fire_cli.py و یک تابع در آن قرار دهید:

def greet_mankind():
    """Greets you with Hello World"""
    return 'Hello World'

در اجرای این برنامه روی پوسته پایتون خروجی این است:

>>> from fire_cli import greet_mankind
>>> greet_mankind()
'Hello World'
>>>

ما به راحتی می توانیم این اسکریپت را با استفاده از Python Fire به یک برنامه CLI تبدیل کنیم:

import fire

def greet_mankind():
    """
    Returns a textual message
    """
    return 'Hello World'

if __name__ == '__main__':
    fire.Fire()

این fire.Fire() تماس ماژول را تبدیل می کند fire_cli.py به یک برنامه Fire CLI. علاوه بر این، آن را در معرض دید قرار داده است greet_mankind() به صورت خودکار عمل می کند.

اکنون می توانیم اسکریپت فوق را به صورت CLI به صورت زیر ذخیره و اجرا کنیم:

$ python fire_greet_mk_cli.py greet_mankind
Hello World

به عنوان تجدید، اجازه دهید تماس را تجزیه کنیم:

• $ سریع است
• python مفسر دستور است
• fire_cli.py ماژولی است که حاوی دستور CLI است
• greet_mankind فرمان است

انتقال استدلال به یک فرمان

اجازه دهید یک برنامه CLI دیگر بسازیم که یک نام را به عنوان پارامتر می گیرد و یک پیام تبریک سفارشی نمایش می دهد:

import fire

def greetings(name):
    '''
    Returns a greeting message
    Parameters
    ----------
    name : string
        String that represents the addresses name 

    Returns
    -------
    string
        greeting message concatenated with name
    '''
    return 'Hello %s' % name

if __name__ == '__main__':
    fire.Fire()

در اینجا، ما اکنون تابعی داریم که یک رشته را می پذیرد – name. Python Fire به طور خودکار این را انتخاب می کند و اگر آرگومان را بعد از آن ارائه کنیم greetings تماس بگیرید، آن ورودی را به name پارامتر. ما همچنین یک نظر به عنوان نوعی سند برای آن اضافه کرده‌ایم --help فرمان

در اینجا روش اجرای این دستور از خط فرمان آمده است:

$ python fire_greet_cli.py greetings Robin
Hello Robin

یک برنامه Fire CLI می تواند استفاده کند --help برای بررسی توضیحات فرمان ایجاد شده از اسناد پایتون پرچم گذاری کنید:

python fire_greet_cli.py greetings --help
NAME
    fire_greet_cli.py greetings - Returns a greeting message

SYNOPSIS
    fire_greet_cli.py greetings NAME

DESCRIPTION
    Returns a greetings message

POSITIONAL ARGUMENTS
    NAME
        String that represents the addresses name

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

تنظیم یک تابع به عنوان نقطه ورودی

با کمی تغییر می توانیم نوردهی را کنترل کنیم greetings() تابع به command-line و آن را به عنوان نقطه ورودی پیش فرض قرار دهید:

import fire

def greetings(name):
    '''
    Returns a greeting message 
    :param name: string argument
    :return: greeting message appended with name
    '''
    return 'Hello %s' % name

if __name__ == '__main__':
    fire.Fire(greetings)

اکنون دستور را به این صورت اجرا می کنیم:

$ python fire_greet_cli.py Robin
Hello Robin

بنابراین این بار دیگر نیازی نیست دستور را همانطور که تعریف کرده ایم فراخوانی کنیم greetings به طور ضمنی به عنوان یک نقطه ورودی با استفاده از Fire(). نکته ای که در اینجا قابل ذکر است این است که با این نسخه، ما فقط می توانیم یک آرگومان واحد را پاس کنیم :

$ python fire_greet_cli.py Robin Hood
ERROR: Could not consume arg: Hood
...
$ python fire_greet_cli.py Robin
Hello Robin

تجزیه آرگومان ها

کتابخانه Fire همچنین با کلاس ها کار می کند. بیایید یک کلاس تعریف کنیم CustomSequence که لیستی از اعداد بین را تولید و برمی گرداند start و end:

import fire

class CustomSequence:
    '''Class that generates a sequence of numbers'''
    def __init__(self, offset=1):
        '''
         Parameters
        ----------
        offset : int, optional
            Number controlling the difference between two generated values
        '''
        self.offset = offset

    def generate(self, start, stop):
        '''
        Generates the sequence of numbers

        Parameters
        ----------
        start : int
            Number that represents the elements lower bound
        stop : int
            Number that represents the elements upper bound

        Returns
        -------
        string
            a string that represents the generated sequence
        '''
        return ' '.join(str(item) for item in range(start, stop, self.offset))

if __name__ == '__main__':
    fire.Fire(CustomSequence)

به این صورت است که با استفاده از این یک دنباله تولید می کنیم command-line سودمندی:

$ python fire_gen_cli.py generate 1 10
1 2 3 4 5 6 7 8 9

ما از یک کلاس به جای یک تابع استفاده کردیم، زیرا برخلاف توابع، اگر بخواهیم آرگومان را به سازنده منتقل کنیم، همیشه باید به عنوان یک پرچم خط فرمان با خط فاصله دو نشان داده شود (مثلاً --offset=2).

بنابراین، برنامه CLI ما از یک آرگومان اختیاری پشتیبانی می کند --offset که تصویب خواهد شد روی به سازنده کلاس این خروجی را با کنترل تفاوت بین دو مقدار تولید شده متوالی تغییر می دهد:

در اینجا خروجی با مقدار افست 2 است:

$ python fire_gen_cli.py generate 1 10 --offset=2
1 3 5 7 9

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

$ python fire_gen_cli.py generate --start=10 --stop=20
10 11 12 13 14 15 16 17 18 19
$ python fire_gen_cli.py generate 10 20
10 11 12 13 14 15 16 17 18 19
$ python fire_gen_cli.py generate --start=10 --stop=20 --offset=2
10 12 14 16 18

ما می توانیم استفاده ازgenerate دستور با استفاده از --help پرچم. این اطلاعات استفاده برای CLI را ارائه می دهد:

$ python fire_gen_cli.py generate --help
INFO: Showing help with the command 'fire_gen_cli.py generate -- --help'.

NAME
    fire_gen_cli.py generate - Generates the sequence of numbers

SYNOPSIS
    fire_gen_cli.py generate START STOP

DESCRIPTION
    Generates the sequence of numbers

POSITIONAL ARGUMENTS
    START
        Number that represents the first value for the sequence
    STOP
        Number that represents the ending value for the sequence

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

استفاده کردن --help با ماژول اطلاعات استفاده خود را به ما می دهد:

$ python fire_gen_cli.py  --help
INFO: Showing help with the command 'fire_gen_cli.py -- --help'.

NAME
    fire_gen_cli.py - Class that generates a sequence of numbers

SYNOPSIS
    fire_gen_cli.py <flags>

DESCRIPTION
    Class that generates a sequence of numbers

FLAGS
    --offset=OFFSET

آتش پرچم ها

Fire CLI با پرچم‌های داخلی بسیاری عرضه می‌شود. قبلا دیده ایم --helpبا این حال، یک پرچم مفید دیگر است --interactive. استفاده از این پرچم ما را در حالت REPL پایتون قرار می دهد، در حالی که ماژول از قبل تعریف شده است.

این برای آزمایش دستورات بسیار مفید است:

$ python fire_greet_cli.py -- --interactive
Fire is starting a Python REPL with the following objects:
Modules: fire
Objects: component, fire_greet_cli.py, greetings, result, trace

Python 3.7.8 (tags/v3.7.8:4b47a5b6ba, Jun 28 2020, 08:53:46) (MSC v.1916 64 bit (AMD64))
Type 'copyright', 'credits' or 'license' for more information
IPython 7.16.1 -- An enhanced Interactive Python. Type '?' for help.


In (1): greetings("Robin")
Out(1): 'Hello Robin'

توجه داشته باشید که Fire flags باید با دو خط فاصله از گزینه های دیگر جدا شود (--) پس اگر بخواهیم از هر دو استفاده کنیم --help و --interactive پرچم در یک دستور، چیزی شبیه به این خواهد بود:

$ python fire_greet_cli.py -- --help --interactive

نتیجه

کتابخانه Python Fire گوگل یک راه سریع و آسان برای ایجاد رابط های خط فرمان (CLIs) برای تقریباً هر شی پایتون است.

در این مقاله، روش نصب Python Fire و همچنین تولید ساده را بررسی کردیم command-line رابط ها