Быстрый старт

virtualenv

Virtualenv, вероятно, то, что вам нужно для разработки приложений Click.

Какую проблему решает virtualenv? Скорее всего, вы хотите использовать его для других проектов помимо вашего скрипта Click. Но чем больше проектов у вас есть, тем выше вероятность того, что вы будете работать с разными версиями самого Python или, по крайней мере, с разными версиями библиотек Python. Допустим, библиотеки часто нарушают обратную совместимость, и маловероятно, что какое-либо серьёзное приложение будет иметь нулевую зависимость. Так что же делать, если два или более ваших проектов имеют конфликтующие зависимости?

Virtualenv на помощь! Virtualenv позволяет устанавливать несколько копий Python рядом друг с другом, по одной для каждого проекта. Он фактически не устанавливает отдельные копии Python, но предоставляет умный способ изоляции различных проектных сред.

Создайте папку своего проекта, а затем virtualenv внутри неё:

$ mkdir myproject
$ cd myproject
$ python3 -m venv .venv

Теперь, когда вы захотите работать над проектом, вам нужно только активировать соответствующую среду. В операционных системах OS X и Linux сделайте следующее:

$ . .venv/bin/activate
(venv) $

Если вы пользователь Windows, следующая команда для вас:

> .venv\scripts\activate
(venv) >

В любом случае, теперь вы должны использовать ваш virtualenv (обратите внимание, как изменилась командная строка вашей оболочки, чтобы показать активную среду).

И если вы хотите прекратить использование virtualenv, используйте следующую команду:

$ deactivate

После этого командная строка вашей оболочки должна быть такой же, как и раньше.

Теперь перейдём к следующему этапу. Введите следующую команду, чтобы активировать Click в вашем virtualenv:

$ pip install click

Через несколько секунд вы будете готовы к работе.

Демонстрация и примеры

Доступен видеоролик, который демонстрирует базовый API Click и как создавать простые приложения с его помощью. Он также исследует, как создавать команды с подкомандами.

• Создание командной строки с помощью Click

Примеры приложений Click можно найти в документации, а также в репозитории GitHub вместе с файлами readme:

• inout: Ввод и вывод файлов
• naval: Порт примера docopt naval
• aliases: Пример алиасов команд
• repo: Интерфейс командной строки типа Git-/Mercurial-
• complex: Сложный пример с загрузкой плагинов
• validation: Пример пользовательской проверки параметров
• colors: Демонстрация поддержки цвета
• termui: Демонстрация функций пользовательского интерфейса терминала
• imagepipe: Демонстрация цепочки многократных команд

Основные концепции — создание команды

Click основан на объявлении команд с помощью декораторов. Внутренне существует интерфейс без декораторов для расширенных случаев использования, но он не рекомендуется для использования на высоком уровне.

Функция становится командной строкой Click, декорировав её с помощью click.command(). В самом простом случае, просто декорирование функции этим декоратором превратит её в вызываемый скрипт:

import click

@click.command()
def hello():
    click.echo('Hello World!')

Что происходит, так это то, что декоратор преобразует функцию в Command, который затем можно вызвать:

if __name__ == '__main__':
    hello()

И что это выглядит:

$ python hello.py
Hello World!

И соответствующая страница справки:

$ python hello.py --help
Usage: hello.py [OPTIONS]

Options:
  --help  Show this message and exit.

Вывод

Почему в этом примере используется echo() вместо обычной функции print()? Ответ на этот вопрос заключается в том, что Click пытается поддерживать разные среды последовательно и быть очень надёжным даже при неправильной настройке среды. Click хочет быть функциональным, по крайней мере, на базовом уровне, даже если всё полностью сломано.

Это означает, что функция echo() применяет некоторую коррекцию ошибок в случае неправильной настройки терминала вместо того, чтобы аварийно завершаться с UnicodeError.

Функция echo также поддерживает цвет и другие стили в выводе. Она автоматически удаляет стили, если выходной поток является файлом. В Windows colorama автоматически устанавливается и используется. См. ANSI цвета.

Если вам это не нужно, вы также можете использовать конструкцию/функцию print().

Вложенные команды

Команды могут быть прикреплены к другим командам типа Group. Это позволяет произвольно вкладывать скрипты. В качестве примера здесь представлен скрипт, реализующий две команды для управления базами данных:

@click.group()
def cli():
    pass

@click.command()
def initdb():
    click.echo('Initialized the database')

@click.command()
def dropdb():
    click.echo('Dropped the database')

cli.add_command(initdb)
cli.add_command(dropdb)

Как видите, декоратор group() работает так же, как декоратор command(), но создаёт объект Group, которому можно прикрепить несколько подкоманд с помощью Group.add_command().

Для простых скриптов также можно автоматически прикреплять и создавать команду, используя декоратор Group.command() вместо этого. Вышеприведённый скрипт можно вместо этого написать так:

@click.group()
def cli():
    pass

@cli.command()
def initdb():
    click.echo('Initialized the database')

@cli.command()
def dropdb():
    click.echo('Dropped the database')

Затем вы вызываете Group в ваших точках входа setuptools или других вызовах:

if __name__ == '__main__':
    cli()

Регистрация команд позже

Вместо использования декоратора @group.command(), команды могут быть декорированы обычным декоратором @click.command() и зарегистрированы в группе позже с помощью group.add_command(). Это можно использовать для разделения команд на несколько модулей Python.

@click.command()
def greet():
    click.echo("Hello, World!")

@click.group()
def group():
    pass

group.add_command(greet)

Добавление параметров

Для добавления параметров используйте декораторы option() и argument():

@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
    for x in range(count):
        click.echo(f"Hello {name}!")

Вот как это выглядит:

$ python hello.py --help
Usage: hello.py [OPTIONS] NAME

Options:
  --count INTEGER  number of greetings
  --help           Show this message and exit.

Переключение на Setuptools

В коде, который вы написали до сих пор, в конце файла есть блок, который выглядит так: if __name__ == '__main__':. Это традиционный способ представления автономного файла Python. С помощью Click вы можете продолжать делать это, но есть лучшие способы с помощью setuptools.

Для этого есть две основные (и много других) причины:

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

Вторая причина заключается в том, что скрипты setuptools работают с virtualenv в Unix без необходимости активации virtualenv. Это очень полезная концепция, позволяющая объединить ваши скрипты со всеми требованиями в virtualenv.

Click прекрасно подходит для этого, и на самом деле, остальная часть документации будет предполагать, что вы пишете приложения с помощью setuptools.

Сильно рекомендую ознакомиться с главой Интеграция с Setuptools перед прочтением остальной части, так как примеры предполагают, что вы будете использовать setuptools.