Рубрики
Без рубрики

Генерация интерфейсов командной строки (CLI) с помощью Fire в Python

В этом уроке мы рассмотрим, как создать приложение интерфейса командной строки с помощью Python Fire.

Автор оригинала: Tapan Pandey.

Вступление

Интерфейс командной строки (CLI) – это способ взаимодействия с компьютерами с помощью текстовых команд.

Многие инструменты, которые не требуют графических интерфейсов, написаны как CLI-инструменты/утилиты. Хотя Python имеет встроенный модуль argparse , существуют и другие библиотеки с аналогичной функциональностью.

Эти библиотеки могут помочь нам в написании сценариев CLI, предоставляя такие услуги, как синтаксический анализ параметров и флагов для гораздо более продвинутых функций CLI.

В этой статье рассматривается библиотека Python Fire , написанная компанией Google Inc., полезный инструмент для создания CLI с минимальным кодом.

Общая форма приложений CLI

Прежде чем мы начнем с библиотеки Fire , давайте попробуем разобраться в основах программ интерфейса командной строки в целом. В зависимости от программы и команды общий шаблон CLI можно суммировать следующим образом:

prompt command parameter1 parameter2 ... parameterN
  • prompt – это последовательность символов, которая побуждает пользователя ввести команду
  • команда – это имя программы, которую выполняет пользователь (например, ls )
  • параметры – это необязательные токены, которые дополняют или изменяют вывод команды

Программа CLI выполняется путем ввода имени программы после появления prompt , в данном случае символа $ .

Здесь мы используем команду ls , которая возвращает список имен файлов в каталоге, причем по умолчанию используется текущий каталог:

$ ls
README.md
python

Вы можете изменить поведение или вывод программы командной строки, предоставив ей список маркеров или параметров, более известных как flags . Давайте попробуем использовать флаг команды 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 short, мы просто набираем -all
  2. Короткие варианты обозначаются одним символом, в то время как длинные варианты имеют полное имя, разделенное дефисом, и не могут быть объединены вместе.

Флаг --time-style работает с флагом -l и управляет форматом отображения времени для списка каталогов.

CLI предоставляет пользователю простой способ настройки и запуска приложения из командной строки. Библиотека Google Python Fire позволяет легко добавить компонент обработки CLI к любому существующему скрипту Python.

Давайте посмотрим, как сделать приложение командной строки с помощью Python Fire .

Установка

Давайте продолжим и установим библиотеку с помощью pip :

$ pip install fire

Python Fire работает с любым объектом Python-функциями, классами, словарями, списками и т. Д. Давайте попробуем понять использование библиотеки Python Fire на нескольких примерах.

Генерация CLI-приложения с помощью Python Fire

Давайте сделаем сценарий, скажем, fire_cli.py и поместить в него функцию:

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

При запуске этой программы в оболочке Python вывод будет следующим:

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

Мы можем легко превратить этот скрипт в CLI приложение с помощью Python Fire:

import fire

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

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

Огонь.Fire() вызывает поворот модуля, т. е. fire_cli.py в приложение Fire CLI. Более того, он автоматически выставил функцию great_manchind() в качестве команды.

Теперь мы можем сохранить и запустить приведенный выше скрипт как CLI следующим образом:

$ python fire_greet_mk_cli.py greet_mankind
Hello World

В качестве освежения, давайте разберем вызов:

  • $ – это подсказка
  • python – это интерпретатор команд
  • fire_cli.py – это модуль, содержащий команду CLI
  • greet_manchind – это команда

Передача аргументов команде

Давайте сделаем еще одно приложение 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 flags для проверки описания команды, сгенерированного из Python docs:

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() на командную строку и установить ее в качестве точки входа по умолчанию:

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

Разбор аргументов

Библиотека огня также работает с классами. Давайте определим класс Custom Sequence , который генерирует и возвращает список чисел между 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)

Вот как мы генерируем последовательность с помощью этой утилиты командной строки:

$ 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 

DESCRIPTION
    Class that generates a sequence of numbers

FLAGS
    --offset=OFFSET

Огненные флаги

Fire Clips поставляется со многими встроенными флагами. Мы уже видели --help , хотя другим полезным флагом является --interactive . Использование этого флага переводит нас в режим Python 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 должны быть отделены от других параметров двумя дефисами ( -- ), поэтому, если мы хотим использовать в команде оба флага --help и --interactive , это будет выглядеть примерно так:

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

Вывод

Библиотека Python Fire от Google-это быстрый и простой способ создания интерфейсов командной строки (CLI) практически для любого объекта Python.

В этой статье мы рассмотрели, как установить Python Fire, а также создать простые интерфейсы командной строки.