Python — отличный язык для консольных приложений, и это подчёркивает большое количество библиотек для этих задач. Но какие вообще библиотеки существуют? А какую лучше взять? В этом материале сравниваются популярные и не очень инструменты для консольного мира и дана попытка ответить на второй вопрос.

Для удобства чтения обзор разделён на два поста: в первом сравнивается шесть самых популярных библиотек, во втором — менее популярные и более специфичные, но всё же заслуживающие внимания.

В каждом из примеров будет написана на Python 3.7 консольная утилита к библиотеке todolib, с которой можно создавать, просматривать, помечать и удалять задачи. Остальное будет дописано при условии простоты реализации на том или ином фреймворке. Сами задачи хранятся в json-файле, который будет сохраняться отдельным вызовом — дополнительное условие к примерам.
Вдобавок к этому, для каждой реализации будет написан тривиальный тест. За фреймворк для тестирования взят pytest со следующими фикстурами:

@pytest.fixture(autouse=True)
def db(monkeypatch):
    """
    monkeypatch получения базы данных из файла,
    чтобы перед тестами всегда была пустая база
    """
    value = {"tasks": []}
    monkeypatch.setattr(todolib.TodoApp, "get_db", lambda _: value)
    return value

@pytest.yield_fixture(autouse=True)
def check(db):
    """ Фикстура для проверки содержимого БД """
    yield
    assert db["tasks"] and db["tasks"][0]["title"] == "test"

# вывод, который ожидается от выполнения команд
EXPECTED = "Task 'test' created with number 1.\n"

В принципе, для демонстрации библиотек всего перечисленного хватит. Полный исходный код доступен в этом репозитории.

argparse

У argparse есть неоспоримое преимущество — он есть в стандартной библиотеке и его API нетрудно выучить: есть парсер, есть аргументы, у аргументов есть type, action, dest, default и help. И есть subparser — возможность выделять часть аргументов и логики в отдельные команды.

Парсер

На первый взгляд — ничего необычного, парсер как парсер. Но — на мой взгляд — читаемость не самая лучшая, если сравнивать с другими библиотеками, т.к. аргументы к разным командам описываются в одном месте.

main

И здесь то же самое — парсер кроме парсинга аргументов больше ничего не умеет, так что логику придётся писать самостоятельно и в одном месте. С одной стороны — жить можно, с другой — можно же лучше, только пока неясно, как именно.

UPD: Как подметил foldr, на самом деле сабпарсерам можно задать функции через set_defaults(func=foo), то есть argparse позволяет укоротить main до небольших размеров. Век живи — век учись.

Тестирование

Для проверки вывода утилиты используется фикстура capsys, которая даёт доступ к тексту из stdout и stderr.

def test_argparse(capsys):
    todo_argparse.main(["add", "test"])
    out, _ = capsys.readouterr()
    assert out == EXPECTED

Итог

Из плюсов — хороший набор возможностей для парсинга, наличие модуля в стандартной библиотеке.

Минусы — argparse занимается лишь парсингом аргументов, большую часть логики в main пришлось писать самому. И неясно, как в тестах проверять exit code.

docopt

docopt — это небольшой (<600 строк, в сравнении с 2500 у argparse) парсер, that will make you smile, цитируя описание на GitHub. Основная идея docopt заключается в том, чтобы описать интерфейс буквально текстом, например, в docstring.

На том же гитхабе у docopt >6700 звёзд, он используется в минимум 22 тысячах других проектах. И это лишь у python-реализации! На странице проекта docopt есть множество вариантов под разные языки, от C и PHP до CoffeeScript и даже R. Такую кросплатформенность могу объяснить лишь компактностью и простотой кода.

Парсер

В сравнении с argparse, этот парсер — большой шаг вперёд.

"""Todo notes on docopt.

Usage:
  todo_docopt [-v | -vv ] add <task>
  todo_docopt [-v | -vv ] show --show-done
  todo_docopt [-v | -vv ] done <number>
  todo_docopt [-v | -vv ] remove <number>
  todo_docopt -h | --help
  todo_docopt --version

Options:
  -h --help     Show help.
  -v --verbose  Enable verbose mode.
"""

main

В целом всё так же, как и с argparse, однако теперь у verbose может быть несколько значений (0-2), и ещё доступ к аргументам отличается: docopt возвращает не namespace с атрибутами, а просто словарь, где выбор той или иной команды обозначается через её boolean, что видно в if:

Тестирование

Аналогично тестированию argparse:

def test_docopt(capsys):
    todo_docopt.main(["add", "test"])
    out, _ = capsys.readouterr()
    assert out == EXPECTED

Итог

Из плюсов — гораздо меньше кода для парсера, простота описания и чтения команд и аргументов, встроенный version.

Минусы, во-первых, те же, что и у argparse — много логики в main, нельзя протестировать exit code. К тому же текущая версия (0.6.2) docopt ещё не стабильна и вряд ли когда-нибудь будет — проект активно развивался с 2012 по конец 2013 года, последний коммит был в декабре 17-го. А самое неприятное на данный момент — некоторые регулярки docopt'а провоцируют DeprecationWarning'и при выполнении тестов.

Click

Click принципиально отличается от argparse и docopt количеством функционала и подходом к описанию команд и параметров через декораторы, а саму логику предлагается выделять в отдельные функции вместо большого main. Авторы утверждают, что у Click много настроек, но стандартных параметров должно хватить. Среди фич подчёркиваются вложенные команды и их ленивая подгрузка.

Проект крайне популярен: кроме того, что у него >8100 звёзд и он используется в минимум 174 тысячах (!) проектах, он до сих пор развивается: версия 7.0 вышла осенью 2018 года, а новые коммиты и merge request'ы появляются и по сей день.

Парсер

На странице документации я нашёл декоратор confirmation_option, который запрашивает подтверждения у пользователя перед выполнением команды. Для его демонстрации была добавлена команда wipe, которая очищает весь список задач.

main

И тут мы встречаемся с главным преимеществом Click — благодаря тому, что логика команд разнесена по их функциям, в main почти ничего не остаётся. Также здесь продемонстрирована возможность библиотеки получать аргументы и параметры из переменных окружения.

if __name__ == "__main__":
    cli(auto_envvar_prefix="TODO")

Тестирование

В случае с Click в перехвате sys.stdout нет нужды, так как есть модуль click.testing с раннером для таких вещей. И мало того, что CliRunner сам перехватывает вывод, он ещё и позволяет проверить exit code, что тоже круто. Всё это позволяет тестировать click-утилиты без использования pytest и обходиться стандартным модулем unittest.

import click.testing
def test_click():
    runner = click.testing.CliRunner()
    result = runner.invoke(todo_click.cli, ["add", "test"])
    assert result.exit_code == 0
    assert result.output == EXPECTED

Итог

Это лишь малая часть того, что умеет Click. Из остального API — валидация значений, интеграция с терминалом (цвета, пейджер а-ля less, прогресс-бар и т.д.), result callback, автодополнение и многое другое. Можете посмотреть их примеры здесь.

Плюсы: много инструментов на любой случай, оригинальный, но при этом удобный подход к описанию команд, простота тестирования и активная жизнь проекта.

Минусы: Какие у «клика» минусы — это сложный вопрос. Может, он чего-то не умеет из того, на что способны следующие библиотеки?

Fire

Fire — это не просто молодая (появилась в 2017-м) библиотека для консольных интерфейсов от Google, это библиотека для генерации консольных интерфейсов из, дословно цитируя, абсолютно любого объекта Python.
Среди прочего заявляется, что fire помогает в разработке и отладке кода, помогает адаптировать существующий код в CLI, облегчает переход из баша в Python и обладает своим REPL для интерактивной работы. Посмотрим?

Парсер и main

fire.Fire действительно способен принимать любой объект: модуль, инстанс класса, словарь с именами команд и соответствующими функциями, и так далее.

Что для нас важно, так это то, что Fire допускает передачу объекта класса. Таким образом, конструктор класса принимает аргументы, общие для всех команд, а его методы и атрибуты являются отдельными командами. Этим мы и воспользуемся:

Встроенные флаги

У Fire есть собственные флаги с особым синтаксисом (их надо передавать после "--"), которые позволяют заглянуть под капот парсера и приложения в целом:

Тестирование

Тестирование main-функции аналогично тестированию argparse и docopt, поэтому приводить его здесь не вижу смысла.

В то же время стоит отметить, что из-за интроспективной натуры Fire можно с тем же успехом тестировать сразу класс Commands.

Итог

Fire — инструмент, интересный не меньше, чем click. Он не требует перечисления множества опций в парсере, конфигурация минимальна, есть свои опции для отладки, а сама библиотека живёт и развивается даже активнее, чем click (60 коммитов за это лето).

Минусы: умеет ощутимо меньше, чем click и другие парсеры; нестабильный API (текущая версия — 0.2.1).

Cement

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

Парсер

Парсер в Cement выглядит необычно, но если приглядеться к параметрам, то нетрудно догадаться, что под капотом стоит знакомый argparse. Но, может, это и к лучшему — не надо учить новые параметры.

App и main

Cement, кроме всего остального, ещё оборачивает сигналы в исключения. Здесь это продемонстрировано на выходе с нулевым кодом при SIGINT/SIGTERM.


Если вчитаться в main, то можно заметить, что загрузку и сохранение todolib.TodoApp можно провести и в переопределённых __enter__/__exit__, но эти фазы в итоге были выделены в отдельные методы для того, чтобы продемонстрировать хуки Cement.

Тестирование

Для тестирования можно использовать тот же класс приложения:

def test_cement(capsys):
    with todo_cement.TodoApp(argv=["add", "test"]) as app:
        app.run()
        out, _ = capsys.readouterr()
        assert out == EXPECTED
        # для ассерта вывода от jinja, которые в нашем примере не используются
        assert app.last_rendered is None

Итоги

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

Минусы: Местами пустая документация; небольшие скрипты на основе Cement могут показаться несколько сложноватыми.

Cleo

Cleo далеко не такой популярный фреймворк, как другие перечисленные здесь (всего около 400 звёзд на GitHub), и всё же мне удалось познакомиться с ним, когда я изучал, каким образом Poetry осуществляет форматирование вывода.

Так вот, Cleo — это один из проектов автора уже упомянутого Poetry, инструмента для управления зависимостями, virtualenv'ами и сборками приложений. Про Poetry на хабре уже не раз писали, а про его консольную часть — нет.

Парсер

Cleo, как и Cement, построен на объектных принципах, т.е. определение команд происходит через класс Command и его docstring, доступ к параметрам осуществляется через метод option(), и так далее. Кроме того, метод line(), который используется для вывода текста, поддерживает стили (т.е. цвета) и фильтрацию вывода на основании количества verbose-флагов из коробки. А ещё у cleo есть вывод таблиц. А ещё прогресс-бары. А ещё… В общем, смотрите:

main

Всё, что надо, это создать объект cleo.Application и потом передать ему команды в add_commands. Чтобы не повторяться при тестировании, всё это было перенесено из main в конструктор:

from cleo import Application as BaseApplication


class TodoApp(BaseApplication):
    def __init__(self):
        super().__init__(name="ToDo app - cleo version", version=todolib.__version__)
        self.add_commands(AddCommand(), ShowCommand(), DoneCommand(), RemoveCommand())


def main(args=None):
    TodoApp().run(args=args)

Тестирование

Для тестирования команд в Cleo есть CommandTester, который, как и все взрослые дяди фреймворки, перехватывает I/O и exit code:

def test_cleo():
    app = todo_cleo.TodoApp()
    command = app.find("add")
    tester = cleo.CommandTester(command)
    tester.execute("test")
    assert tester.status_code == 0
    assert tester.io.fetch_output() == "Task test created with number 0.\n"

Итог

Плюсы: объектная структура с наличием type hints, что упрощает разработку (т.к. многие IDE и редакторы имеют хорошую поддержку ООП-кода и модуля typing); хороший объём функционала по работе не только с аргументами, но и I/O.

Плюс-минус: свой параметр verbosity, который совместим только с I/O Cleo/CliKit. И хотя можно написать кастомный handler для модуля logging, его может быть сложно поддерживать вместе с развитием cleo.

Минусы: явно — личное мнение — молодое API: фреймворку не хватает другого «крупного» пользователя, кроме Poetry, а так Cleo развивается параллельно с развитием и под нужды его одного; местами документация устаревшая (например, уровни логирования теперь лежат не в модуле clikit, а в clikit.api.io.flags), да и в целом она скудна и не отражает всего API.

Cleo, в сравнении с Cement, больше сфокусирован на CLI, и он единственный, кто задумался о форматировании (скрытии стектрейса по умолчанию) исключений в выводе по умолчанию. Но он — снова личное мнение — проигрывает Cement'у в своей юности и стабильности API.

В заключение

К этому моменту у всех уже есть своё мнение, что лучше, но заключение должно быть: мне больше всего понравился Click, за то, что в нём много чего есть и при этом с ним достаточно просто разрабатывать и тестировать приложения. Если вы стараетесь писать код по минимуму — начните с Fire. Вашему скрипту нужен доступ в Memcached, форматирование с jinja и расширяемость — берите Cement и не пожалеете. У вас пет-проджект или хотите попробовать что-то иное — посмотрите на cleo.