Click и Python: Создание расширяемых и компонуемых CLI-приложений

Оглавление

Создание интерфейсов командной строки с помощью Click и Python
- Зачем использовать Click для разработки CLI
- Как установить и настроить Click: Ваше первое CLI-приложение
Добавление аргументов в приложение Click
Предоставление опций в ваших приложениях для кликов
Предоставление типов параметров для аргументов и опций
Создание подкоманд в Click
- Немедленная регистрация подкоманды
- Отсрочка регистрации подкоманды
Настройка использования и справочных сообщений в приложении Click
- Документирование команд и параметров
- Документирование аргументов
Подготовка приложения Click к установке и использованию
Заключение

Вы можете использовать библиотеку Click, чтобы быстро предоставить вашим сценариям автоматизации и инструментария Python расширяемый, компонуемый и удобный для пользователя интерфейс командной строки (CLI).. Независимо от того, являетесь ли вы разработчиком, специалистом по обработке данных, инженером DevOps или тем, кто часто использует Python для автоматизации повторяющихся задач, вы по достоинству оцените Click и его уникальные возможности.

В экосистеме Python вы найдете множество библиотек для создания CLI, в том числе argparse из стандартной библиотеки , Наборщик и несколько других. Однако Click предлагает надежное, продуманное, интуитивно понятное и многофункциональное решение.

В этом руководстве вы узнаете, как:

Создайте интерфейсы командной строки с помощью Click и Python
Добавьте аргументов, параметры и подкоманды в свои CLI-приложения
Улучшите использование и страниц справки ваших CLI-приложений, нажав
Подготовьте Click CLI-приложение для установки, используйте и распространения

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

Получите свой код: Нажмите здесь, чтобы загрузить пример кода, который вы будете использовать для создания своего CLI-приложения с помощью Click и Python.

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

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

Click - отличная альтернатива модулю argparse, который является платформой CLI по умолчанию в стандартной библиотеке Python. Далее вы узнаете, что отличает его от других.

Зачем использовать Click для разработки интерфейса командной строки

По сравнению с argparse Click предоставляет более гибкую и интуитивно понятную платформу для создания CLI-приложений с высокой степенью расширения. Она позволяет вам постепенно создавать свои приложения без ограничений и с минимальным количеством кода. Этот код будет читаем даже тогда, когда ваш интерфейс командной строки вырастет и станет более сложным.

Интерфейс прикладного программирования (API) Click очень интуитивно понятен и последователен. API использует преимущества Python декораторов, позволяя вам быстро добавлять аргументы, опции и подкоманды в ваш CLIS.

Функции являются основополагающими в CLIS, основанных на кликах. Вам нужно написать функции, которые затем можно обернуть соответствующими декораторами для создания аргументов, команд и так далее.

У Click есть несколько полезных функций, которыми вы можете воспользоваться. Например, Click apps:

Может быть легко компонуемым без ограничений
Следуйте инструкциям Unix соглашения о работе с командной строкой
Поддержка загрузки значений из переменных окружения
Поддержка пользовательских подсказок для ввода значений
Обрабатывать пути и файлы "из коробки"
Разрешить произвольное вложение команд, также известных как подкоманды

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

Когда дело доходит до обработки пользовательского ввода, Click хорошо разбирается в типах данных. Благодаря этой функции библиотека генерирует постоянные сообщения об ошибках, когда пользователь вводит неверный тип данных.

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

Как установить и настроить Click: Ваше первое CLI-приложение

В отличие от argparse, Click не входит в стандартную библиотеку Python. Это означает, что для использования библиотеки вам необходимо установить Click как зависимость вашего CLI-проекта. Вы можете установить Click from PyPI с помощью pip. Сначала вам следует создать виртуальную среду Python для работы. Все это можно выполнить с помощью следующих команд, зависящих от платформы:

PS> python -m venv venv
PS> venv\Scripts\activate
(venv) PS> python -m pip install click

$ python -m venv venv
$ source venv/bin/activate
(venv) $ python -m pip install click

С помощью первых двух команд вы создаете и активируете виртуальную среду Python с именем venv в вашем рабочем каталоге. Как только среда станет активной, вы установите Click с помощью pip.

Отлично! Вы установили Click в новой виртуальной среде. Теперь запускайте свой любимый редактор кода. Создайте новый файл hello.py и добавьте в него следующее содержимое:

# hello.py

import click

@click.command("hello")
@click.version_option("0.1.0", prog_name="hello")
def hello():
    click.echo("Hello, World!")

if __name__ == "__main__":
    hello()

В этом файле вы сначала импортируете пакет click. Затем вы создаете функцию с именем hello(). С помощью этой функции вы выводите сообщение на экран. Для этого вы используете функцию Click echo() вместо своего старого знакомого print(). Зачем тебе это делать?

Функция echo() исправляет некоторые ошибки в случае, если в терминальной программе возникают проблемы с конфигурацией. Она также поддерживает цвета и другие стили в выходных данных. Она автоматически удаляет любые стили, если выходной поток представляет собой файл, а не стандартный вывод. Итак, при работе с Click вам следует использовать echo() для обработки выходных данных приложения.

Вы используете два декоратора поверх этой функции. Тот самый @click.command декоратор объявляет hello() как команду щелчка с именем "hello". Тот самый @click.version_option декоратор устанавливает версию и название CLI-приложения. Эта информация появится, когда вы запустите приложение с помощью параметра командной строки --version.

Наконец, вы добавляете идиому name-main для вызова функции hello() при запуске файла как исполняемой программы.

Запустите приложение из командной строки:

(venv) $ python hello.py
Hello, World!

(venv) $ python hello.py --version
hello, version 0.1.0

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

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Когда вы запускаете скрипт без аргументов, на вашем экране отображается Hello, World!. Если вы используете опцию --version, то получаете информацию о названии и версии приложения. Обратите внимание, что при нажатии кнопки автоматически отображается опция --help, с помощью которой вы можете перейти на главную страницу справки приложения.

Это было круто! С помощью нескольких строк кода и возможностей Click вы создали свое первое CLI-приложение. Это приложение минималистично, но этого достаточно, чтобы понять, что вы сможете создать с помощью Click. Чтобы продолжить знакомство с CLI, вы узнаете, как заставить ваши приложения принимать входные аргументы от пользователя.

Добавление аргументов в приложение Click

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

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

Добавление основных аргументов

Вы можете использовать @click.argument декоратор, чтобы заставить ваше приложение Click принимать и анализировать аргументы, которые вы вводите непосредственно в командной строке. Click анализирует самые основные аргументы в виде строк, которые затем можно передать базовой функции.

Для иллюстрации предположим, что вы хотите создать небольшое CLI-приложение, имитирующее Unix-команду ls. В самом простом варианте эта команда принимает каталог в качестве аргумента и выводит список его содержимого. Если вы используете Linux или macOS, вы можете попробовать выполнить команду, как показано в следующем примере:

$ ls sample/
hello.txt     lorem.md      realpython.md

В этом примере предполагается, что в вашем текущем рабочем каталоге есть папка с именем sample/. Ваша папка содержит файлы hello.txt, lorem.md, и realpython.md, которые перечислены в той же строке вывода.

Примечание: Если вы используете Windows, то у вас будет команда ls, которая работает аналогично команде Unix ls. Однако в своей обычной форме команда выводит другой результат:

PS> ls .\sample\

    Directory: C:\sample

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---          07/11/2023 10:06 AM             88 hello.txt
-a---          07/11/2023 10:06 AM           2629 lorem.md
-a---          07/11/2023 10:06 AM            429 realpython.md

Команда PowerShell ls выдает таблицу, содержащую подробную информацию о каждом файле и подкаталоге в вашем целевом каталоге. Итак, в следующих версиях ls.py вы будете имитировать Unix-версию этой команды вместо версии PowerShell.

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

Как вы можете эмулировать поведение этой команды с помощью Click и Python? Вы можете сделать что-то вроде следующего:

# ls.py v1

from pathlib import Path

import click

@click.command()
@click.argument("path")
def cli(path):
    target_dir = Path(path)
    if not target_dir.exists():
        click.echo("The target directory doesn't exist")
        raise SystemExit(1)

    for entry in target_dir.iterdir():
        click.echo(f"{entry.name:{len(entry.name) + 5}}", nl=False)

    click.echo()

if __name__ == "__main__":
    cli()

Это ваша первая версия приложения-эмулятора команд ls. Вы начинаете с импорта Path класса из pathlib. Вы будете использовать этот класс для эффективного управления путями в вашем приложении. Далее вы импортируете click как обычно.

Вашему эмулятору ls требуется единственная функция для выполнения своей задачи. Вы вызываете эту функцию cli(), что является обычной практикой. В приложениях Click обычно используется команда точки входа cli(), как вы увидите в этом руководстве.

В этом примере вы используете @click.command декоратор для определения команды. Затем вы используете @click.argument декоратор со строкой "path" в качестве аргумента. Этот вызов декоратора добавляет новый аргумент командной строки с именем "path" в вашу пользовательскую команду ls.

Обратите внимание, что имя аргумента командной строки должно совпадать с именем аргумента cli(). Таким образом, вы передаете пользовательский ввод непосредственно в свой обрабатывающий код.

Внутри cli() вы создаете новый Path экземпляр, используя пользовательский ввод. Затем вы проверяете путь ввода. Если путь не существует, вы сообщаете об этом пользователю и выходите из приложения с соответствующим статусом выхода. Если путь существует, то for цикл выводит содержимое каталога, имитируя то, что делает команда Unix ls.

Вызов click.echo() в конце cli() позволяет добавить новую строку в конце вывода, чтобы соответствовать поведению ls.

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

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

(venv) $ python ls.py sample/
lorem.md     realpython.md     hello.txt

(venv) $ python ls.py non_existing/
The target directory doesn't exist

(venv) $ python ls.py
Usage: ls.py [OPTIONS] PATH
Try 'ls.py --help' for help.

Error: Missing argument 'PATH'.

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

примечание: Вы можете обнаружить, что порядок, в котором ls.py списки файлов не совпадает заказ в выходной или в оригинале ls команды выходной. Это потому, что метод .iterdir() возвращает записи каталога в произвольном порядке.

Как это выглядит даже для двадцати строк кода на Python? Отлично! Однако Click предлагает вам лучший способ сделать это. Вы можете воспользоваться возможностями Click для автоматической обработки путей к файлам в ваших приложениях.

Использование аргументов пути

Декоратор @click.argument принимает аргумент с именем type, который вы можете использовать для определения целевого типа данных для данного аргумента. В дополнение к этому, Click предоставляет богатый набор пользовательских классов, которые позволяют вам последовательно обрабатывать различные типы данных, включая пути.

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

В приведенном ниже примере вы переписываете приложение ls, используя возможности Click:

# ls.py v2

from pathlib import Path

import click

@click.command()
@click.argument(
    "path",
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(path):
    for entry in path.iterdir():
        click.echo(f"{entry.name:{len(entry.name) + 5}}", nl=False)

    click.echo()

if __name__ == "__main__":
    cli()

В этой новой версии ls.py вы передаете объект click.Path в type аргумент @click.argument. С этим дополнением Click будет обрабатывать любые входные данные как объект path.

Чтобы создать экземпляр класса click.Path() в этом примере, вы используете несколько аргументов:

exists: Если вы установите для него значение True, то щелчок мыши позволит убедиться, что путь существует.
file_okay: Если вы зададите значение False, то при нажатии кнопки будет проверяться, что введенный путь не указывает на файл.
readable: Если вы установите значение True, то при нажатии кнопки вы сможете прочитать содержимое целевого каталога.
path_type: Если вы установите для него значение pathlib.Path, то при нажатии кнопки вводимые данные будут преобразованы в объект Path.

При таких настройках ваша функция cli() будет более лаконичной. Для отображения содержимого каталога требуется только цикл for. Продолжайте и запустите следующие команды, чтобы протестировать новую версию вашего скрипта ls.py:

(venv) $ python ls.py sample/
lorem.md     realpython.md     hello.txt

(venv) $ python ls.py non_existing/
Usage: ls.py [OPTIONS] PATH
Try 'ls.py --help' for help.

Error: Invalid value for 'PATH': Directory 'non_existing/' does not exist.

И снова, когда вы запускаете приложение, указав правильный путь к каталогу, вы получаете список содержимого каталога. Если целевой каталог не существует, нажмите кнопку "Решить проблему". Вы получите приятное сообщение об использовании и сообщение об ошибке, описывающее текущую проблему. Это еще лучшее поведение, если сравнить его с вашей первой версией ls.py.

Прием переменных аргументов

В терминологии Click, переменный аргумент - это аргумент, который принимает неопределенное количество входных значений в командной строке. Этот тип аргументов довольно часто используется при разработке CLI. Например, команда Unix ls использует эту функцию, позволяя вам обрабатывать несколько каталогов одновременно.

Чтобы попробовать, создайте копию своей папки sample/ и выполните следующую команду:

$ ls sample/ sample_copy/
sample/:
hello.txt     lorem.md      realpython.md

sample_copy/:
hello.txt     lorem.md      realpython.md

Команда ls может использовать несколько целевых каталогов в командной строке. На выходе будет отображен список содержимого каждого каталога, как вы можете заключить из приведенного выше примера. Как вы можете имитировать это поведение с помощью Click и Python?

Декоратор @click.argument принимает аргумент с именем nargs, который позволяет вам заранее определить количество значений, которые может принимать аргумент в командной строке. Если вы установите для nargs значение -1, то базовый аргумент будет собирать неопределенное количество входных значений в кортеж.

Вот как вы можете воспользоваться преимуществами nargs для поддержки нескольких каталогов в вашем ls эмуляторе:

# ls.py v3

from pathlib import Path

import click

@click.command()
@click.argument(
    "paths",
    nargs=-1,
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(paths):
    for i, path in enumerate(paths):
        if len(paths) > 1:
            click.echo(f"{path}/:")
        for entry in path.iterdir():
            click.echo(f"{entry.name:{len(entry.name) + 5}}", nl=False)
        if i < len(paths) - 1:
            click.echo("\n")
        else:
            click.echo()

if __name__ == "__main__":
    cli()

В первой выделенной строке вы меняете имя аргумента с "path" на "paths", потому что теперь аргумент будет принимать несколько путей к каталогам. Затем вы устанавливаете для nargs значение -1, чтобы указать, что этот аргумент будет принимать несколько значений в командной строке.

В функции cli() вы меняете имя аргумента, чтобы оно соответствовало имени аргумента командной строки. Затем вы запускаете цикл по входным путям. Условный оператор выводит имя текущего каталога, имитируя то, что делает исходная команда ls.

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

После установки этих обновлений вы можете снова запустить приложение:

(venv) $ python ls.py sample/ sample_copy/
sample/:
lorem.md     realpython.md     hello.txt

sample_copy/:
lorem.md     realpython.md     hello.txt

Теперь ваша пользовательская команда ls ведет себя аналогично исходной команде Unix ls, когда вы передаете несколько целевых каталогов в командной строке. Это здорово! Вы узнали, как реализовать переменные аргументы с помощью Click.

Принимает аргументы файла

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

Чтобы проиллюстрировать, как вы можете использовать тип параметра File, скажем, что вы хотите эмулировать базовую функциональность команды Unix cat. Эта команда последовательно считывает файлы и записывает их содержимое в стандартный вывод , который является вашим экраном:

$ cat sample/hello.txt sample/realpython.md
Hello, Pythonista!

Welcome to Real Python!
At Real Python you'll learn all things Python from the ground up.
Their tutorials, books, and video courses are created, curated,
and vetted by a community of expert Pythonistas. With new content
published weekly, custom Python learning paths, and interactive
code challenges, you'll always find something to boost your skills.
Join 3,000,000+ monthly readers and take your Python skills to the
next level at realpython.com.

В этом примере вы используете cat для объединения содержимого двух файлов из вашего примерного каталога. Следующее приложение имитирует это поведение, используя тип параметра Click File:

# cat.py

import click

@click.command()
@click.argument(
    "files",
    nargs=-1,
    type=click.File(mode="r"),
)
def cli(files):
    for file in files:
        click.echo(file.read().rstrip())

if __name__ == "__main__":
    cli()

В этом примере для параметра type задано значение click.File. Режим "r" означает, что вы открываете файл для чтения.

Внутри cli() вы запускаете цикл for для перебора входных файлов и вывода их содержимого на экран. Важно отметить, что вам не нужно беспокоиться о закрытии каждого файла после прочтения его содержимого. Тип File автоматически закрывает его для вас, как только команда завершает выполнение.

Вот как это приложение работает на практике:

(venv) $ python cat.py sample/hello.txt sample/realpython.md
Hello, Pythonista!

Welcome to Real Python!
At Real Python you'll learn all things Python from the ground up.
Their tutorials, books, and video courses are created, curated,
and vetted by a community of expert Pythonistas. With new content
published weekly, custom Python learning paths, and interactive
code challenges, you'll always find something to boost your skills.
Join 3,000,000+ monthly readers and take your Python skills to the
next level at realpython.com.

Ваш cat.py скрипт работает практически аналогично команде Unix cat. Он принимает несколько файлов из командной строки, открывает их для чтения, считывает их содержимое и последовательно выводит его на экран. Отличная работа!

Предоставление опций в ваших приложениях Click

Команда Параметры - это еще одна мощная функция приложений Click. Параметры - это именованные необязательные аргументы, которые изменяют поведение команды. Вы передаете параметр команде, используя определенное имя, префикс которого в Unix-системах обычно состоит из одного тире (-) или двух тире (--). В Windows вы также можете найти варианты с другими префиксами, такими как косая черта (/).

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

Запрос на ввод значений
Действуют как флажки или переключатели функций
Извлекать их значения из переменных окружения

В отличие от аргументов, параметры могут принимать только фиксированное количество входных значений, и это число по умолчанию равно 1. Кроме того, вы можете указать параметр несколько раз, используя несколько параметров, но вы не можете сделать это с помощью аргументов.

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

Добавление параметров с одним значением

Чтобы добавить параметр в команду Click, вы будете использовать @click.option декоратор. Первый аргумент этого декоратора будет содержать название параметра.

Параметры интерфейса командной строки часто имеют длинное и короткое названия. Длинное название обычно описывает, что делает параметр, в то время как короткое название обычно состоит из одной буквы. При нажатии кнопки имена с одним начальным тире являются короткими, а имена с двумя начальными тире - длинными.

В Click наиболее простым типом параметра является параметр с одним значением, который принимает один аргумент в командной строке. Если вы не указываете тип параметра для значения параметра, нажмите кнопку "Принять". click.STRING введите.

Чтобы проиллюстрировать, как вы можете создавать параметры с помощью Click, скажем, что вы хотите написать CLI-приложение, которое эмулирует команду Unix tail. Эта команда отображает конец текстового файла:

$ tail sample/lorem.md
ac. Nulla sapien nulla, egestas at pretium ac, feugiat nec arcu. Donec
ullamcorper laoreet odio, id posuere nisl ullamcorper at.

### Nam Aliquam Ultricies Pharetra

Nam aliquam ultricies pharetra. Pellentesque accumsan finibus ex porta
aliquet. Morbi placerat sagittis tortor, ut maximus sem iaculis sit amet.
Aliquam sit amet libero dapibus, vehicula arcu non, pulvinar felis.
Suspendisse a risus magna. Nulla facilisi. Donec eu consequat ligula, iaculis
aliquet augue.

$ tail --lines 3 sample/lorem.md
Aliquam sit amet libero dapibus, vehicula arcu non, pulvinar felis.
Suspendisse a risus magna. Nulla facilisi. Donec eu consequat ligula, iaculis
aliquet augue.

По умолчанию tail отображает последние десять строк входного файла. Однако у команды есть опция -n или --lines, которая позволяет вам изменить это число, как вы можете видеть во втором примере выполнения выше, где вы напечатали только последние три строки из lorem.md.

Вы можете использовать Click для имитации поведения tail. В этом случае вам нужно добавить опцию, используя @click.option декоратор, как в приведенном ниже коде:

# tail.py

from collections import deque

import click

@click.command()
@click.option("-n", "--lines", type=click.INT, default=10)
@click.argument(
    "file",
    type=click.File(mode="r"),
)
def cli(file, lines):
    for line in deque(file, maxlen=lines):
        click.echo(line, nl=False)

if __name__ == "__main__":
    cli()

В этом примере вы сначала импортируете тип данных deque из модуля collections. Вы будете использовать этот тип, чтобы быстро получить окончательные строки вашего входного файла. Затем вы импортируете click как обычно.

Примечание: То, как вы используете deque в этом примере, взято из документации по Python на deque. Ознакомьтесь с разделом, посвященным deque рецептам, для получения дополнительных примеров.

В выделенной строке вы вызываете @click.option декоратор, чтобы добавить новую опцию к вашей команде Click. Первые два аргумента в этом вызове содержат краткое и длинное названия для опции соответственно.

Поскольку пользовательский ввод должен быть целым числом, вы используете click.INT для определения типа параметра. По умолчанию в tail отображаются последние десять строк, поэтому вы устанавливаете для default значение 10 и открываете для себя еще одну интересную особенность параметров Click. Они могут иметь значения по умолчанию.

Затем вы добавляете аргумент с именем "file", который имеет тип click.File. Вы уже знаете, как работает тип File.

В cli() в качестве аргументов вы берете файл и количество строк. Затем вы перебираете последние строки, используя объект deque. Этот конкретный объект deque может хранить не более lines элементов. Это гарантирует, что вы получите желаемое количество строк из конца входного файла.

Попробуйте tail.py, выполнив следующие команды:

(venv) $ python tail.py sample/lorem.md
ac. Nulla sapien nulla, egestas at pretium ac, feugiat nec arcu. Donec
ullamcorper laoreet odio, id posuere nisl ullamcorper at.

### Nam Aliquam Ultricies Pharetra

Nam aliquam ultricies pharetra. Pellentesque accumsan finibus ex porta
aliquet. Morbi placerat sagittis tortor, ut maximus sem iaculis sit amet.
Aliquam sit amet libero dapibus, vehicula arcu non, pulvinar felis.
Suspendisse a risus magna. Nulla facilisi. Donec eu consequat ligula, iaculis
aliquet augue.

(venv) $ python tail.py --lines 3 sample/lorem.md
Aliquam sit amet libero dapibus, vehicula arcu non, pulvinar felis.
Suspendisse a risus magna. Nulla facilisi. Donec eu consequat ligula, iaculis
aliquet augue.

(venv) $ python tail.py --help
Usage: tail.py [OPTIONS] FILE

Options:
  -n, --lines INTEGER
  --help               Show this message and exit.

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

Когда вы просматриваете страницу справки по вашей команде tail, вы видите, что параметр -n или --lines теперь отображается под заголовком Options. По умолчанию вы также получаете информацию о типе параметра опции, который в данном примере представляет собой целое число.

Создание многозначных параметров

Иногда требуется реализовать параметр, который принимает более одного входного значения в командной строке. В отличие от аргументов, параметры щелчка поддерживают только фиксированное количество входных значений. Вы можете настроить это число, используя nargs аргумент @click.option.

В приведенном ниже примере используется параметр --size, для которого требуется два входных значения: width и height:

# rectangle.py v1

import click

@click.command()
@click.option("--size", nargs=2, type=click.INT)
def cli(size):
    width, height = size
    click.echo(f"size: {size}")
    click.echo(f"{width} × {height}")

if __name__ == "__main__":
    cli()

В этом примере вы устанавливаете для nargs значение 2 в вызове @click.option декоратора, который определяет параметр --size. Этот параметр указывает Click, что параметр будет принимать два значения в командной строке.

Вот как это игрушечное приложение работает на практике:

(venv) $ python rectangle.py --size 400 200
size: (400, 200)
400 × 200

(venv) $ python rectangle.py --size 400
Error: Option '--size' requires 2 arguments.

(venv) $ python rectangle.py --size 400 200 100
Usage: rectangle.py [OPTIONS]
Try 'rectangle.py --help' for help.

Error: Got unexpected extra argument (100)

Параметр --size принимает два входных значения в командной строке. Click сохраняет эти значения в виде кортежа, который можно обработать внутри функции cli(). Обратите внимание, что параметр --size не принимает меньше или больше двух входных значений.

Click предоставляет альтернативный способ создания многозначных параметров. Вместо использования nargs аргумента @click.option можно задать для аргумента type значение кортежа. Рассмотрим следующую альтернативную реализацию вашего скрипта rectangle.py:

# rectangle.py v2

import click

@click.command()
@click.option("--size", type=(click.INT, click.INT))
def cli(size):
    width, height = size
    click.echo(f"size: {size}")
    click.echo(f"{width} × {height}")

if __name__ == "__main__":
    cli()

В этой альтернативной реализации rectangle.py в качестве аргумента type используется набор целых значений. Обратите внимание, что вы также можете использовать тип параметра click.Tuple для получения того же результата. Использование этого типа будет более явным, и вам нужно будет только сделать type=click.Tuple([int, int]).

Попробуйте эту новую версию вашего приложения:

(venv) $ python rectangle.py --size 400 200
size: (400, 200)
400 × 200

(venv) $ python rectangle.py --size 400
Error: Option '--size' requires 2 arguments.

(venv) $ python rectangle.py --size 400 200 100
Usage: rectangle.py [OPTIONS]
Try 'rectangle.py --help' for help.

Error: Got unexpected extra argument (100)

Эта реализация работает так же, как и та, в которой используется nargs=2. Однако, используя кортеж для аргумента type, вы можете настроить тип параметра для каждого элемента в кортеже, что может быть довольно удобной функцией в некоторых ситуациях.

Чтобы проиллюстрировать, как click.Tuple может вам помочь, рассмотрим следующий пример:

# person.py

import click

@click.command()
@click.option("--profile", type=click.Tuple([str, int]))
def cli(profile):
    click.echo(f"Hello, {profile[0]}! You're {profile[1]} years old!")

if __name__ == "__main__":
    cli()

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

Вот как это игрушечное приложение работает на практике:

(venv) $ python person.py --profile John 35
Hello, John! You're 35 years old!

(venv) $ python person.py --profile Jane 28.5
Usage: person.py [OPTIONS]
Try 'person.py --help' for help.

Error: Invalid value for '--profile': '28.5' is not a valid integer.

Параметр --profile принимает строку и целое значение. Если вы используете другой тип данных, то получите сообщение об ошибке. Проверка типа выполняется щелчком мыши.

Многократное указание параметра

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

# greet.py

import click

@click.command()
@click.option("--name", multiple=True)
def cli(name):
    for n in name:
        click.echo(f"Hello, {n}!")

if __name__ == "__main__":
    cli()

Аргументом multiple для @click.option является Логическое значение. Если вы установите для него значение True, то вы можете указать базовый параметр несколько раз.

Вот как это приложение работает на практике:

(venv) $ python greet.py --name Pythonista --name World
Hello, Pythonista!
Hello, World!

В этой команде вы указываете параметр --name два раза. Каждый раз вы используете другое входное значение. В результате приложение выводит на экран два приветствия, по одному при каждом повторении параметра. Далее вы узнаете больше о логических флагах.

Определение параметров в виде логических флагов

Логические флаги - это опции, которые вы можете включать или отключать. При нажатии кнопки принимаются два типа логических флагов. Первый тип позволяет вам определить переключатели вкл. и выкл.. Во втором типе предусмотрен только переключатель на. Чтобы задать флаг с параметрами вкл. и выкл., вы можете указать два флага, разделенных косой чертой (/).

В качестве примера флагов включено и выключено рассмотрим следующее приложение:

# upper_greet.py

import click

@click.command()
@click.argument("name", default="World")
@click.option("--upper/--no-upper", default=False)
def cli(name, upper):
    message = f"Hello, {name}!"
    if upper:
        message = message.upper()
    click.echo(message)

if __name__ == "__main__":
    cli()

В выделенной строке вы определяете параметр, который работает как флажок вкл. и выкл.. В этом примере --upper - это переключатель вкл. (или True), а --no-upper - это переключатель выкл. (или False) переключите. Обратите внимание, что для флага выкл. необязательно использовать префикс no-. Вы можете назвать его как хотите, в зависимости от вашего конкретного варианта использования.

Затем вы передаете upper в качестве аргумента своей функции cli(). Если upper равно true, то вводите приветственное сообщение в верхний регистр. В противном случае сообщение сохраняет исходный текст. Обратите внимание, что значение этого флага по умолчанию равно False, что означает, что приложение будет отображать сообщение без изменения его исходного оформления.

Вот как это приложение работает на практике:

(venv) $ python upper_greet.py Pythonista --upper
HELLO, PYTHONISTA!

(venv) $ python upper_greet.py Pythonista --no-upper
Hello, Pythonista!

(venv) $ python upper_greet.py Pythonista
Hello, Pythonista!

Когда вы запускаете свое приложение с флагом --upper, вы получаете приветствие в верхнем регистре. Когда вы запускаете приложение с флагом --no-upper, вы получаете сообщение в исходном виде. Наконец, при запуске приложения без флажка сообщение отображается без изменений, поскольку значение флага по умолчанию равно False.

Второй тип логического флага предоставляет только переключатель на или True. В этом случае, если вы укажете флаг в командной строке, то его значение будет True. В противном случае его значение будет False. Вы можете задать для параметра is_flag параметра @click.option() значение True, если вам нужно создать флаг такого типа.

Чтобы проиллюстрировать, как вы можете использовать эти флаги, вернитесь к своему симулятору ls. На этот раз вы добавите флаг -l или --long, который имитирует поведение аналогичного флага в исходной команде Unix ls. Вот обновленный код:

# ls.py v4

from datetime import datetime
from pathlib import Path

import click

@click.command()
@click.option("-l", "--long", is_flag=True)
@click.argument(
    "paths",
    nargs=-1,
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(paths, long):
    for i, path in enumerate(paths):
        if len(paths) > 1:
            click.echo(f"{path}/:")
        for entry in path.iterdir():
            entry_output = build_output(entry, long)
            click.echo(f"{entry_output:{len(entry_output) + 5}}", nl=long)
        if i < len(paths) - 1:
            click.echo("" if long else "\n")
        elif not long:
            click.echo()

def build_output(entry, long=False):
    if long:
        size = entry.stat().st_size
        date = datetime.fromtimestamp(entry.stat().st_mtime)
        return f"{size:>6d} {date:%b %d %H:%M:%S} {entry.name}"
    return entry.name

if __name__ == "__main__":
    cli()

Ничего себе! В этом коде появилось несколько новых функций. Сначала вы определяете параметр -l или --long в качестве логического флага, устанавливая для его аргумента is_flag значение True.

Внутри cli() вы обновляете цикл для получения обычного или длинного вывода в зависимости от выбора пользователя. В цикле вы вызываете вспомогательную функцию build_output(), чтобы сгенерировать соответствующий вывод для каждого случая.

Функция build_output() возвращает подробный вывод, когда long равно True, и минимальный вывод в противном случае. Подробные выходные данные будут содержать размер, дату изменения и название записи. Чтобы сгенерировать подробные выходные данные, вы используете такие инструменты, как Path.stat() и datetime объект с пользовательским форматом строка.

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

(venv) $ python ls.py -l sample/
  2609 Jul 13 15:27:59 lorem.md
   428 Jul 12 15:28:38 realpython.md
    44 Jul 12 15:26:49 hello.txt

(venv) $ python ls.py -l sample/ sample_copy/
sample/:
  2609 Jul 12 15:27:59 lorem.md
   428 Jul 12 15:28:38 realpython.md
    44 Jul 12 15:26:49 hello.txt

sample_copy/:
  2609 Jul 12 15:27:18 lorem.md
   428 Jul 12 15:28:48 realpython.md
    44 Jul 12 15:27:18 hello.txt

(venv) $ python ls.py sample/ sample_copy/
sample/:
lorem.md     realpython.md     hello.txt

sample_copy/:
lorem.md     realpython.md     hello.txt

Когда вы запускаете скрипт ls.py с флагом -l, вы получаете подробный вывод всех записей в целевом каталоге. Если вы запустите его без флага, то получите короткий результат.

Создание функциональных переключателей

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

Например, рассмотрим следующее обновление вашего приложения upper_greet.py:

# upper_greet.py v2

import click

@click.command()
@click.argument("name", default="World")
@click.option("--upper", "casing", flag_value="upper")
@click.option("--lower", "casing", flag_value="lower")
def cli(name, casing):
    message = f"Hello, {name}!"
    if casing == "upper":
        message = message.upper()
    elif casing == "lower":
        message = message.lower()
    click.echo(message)

if __name__ == "__main__":
    cli()

В новой версии upper_greet.py есть два параметра: --upper и --lower. Оба этих параметра работают с одним и тем же параметром, "casing". Вы передаете этот параметр в качестве аргумента функции cli().

Внутри cli() вы проверяете текущее значение casing и выполняете соответствующее преобразование сообщения. Если пользователь не укажет ни один из этих параметров в командной строке, то приложение отобразит сообщение в исходном виде:

(venv) $ python upper_greet.py --upper
HELLO, WORLD!

(venv) $ python upper_greet.py --lower
hello, world!

(venv) $ python upper_greet.py
Hello, World!

Переключатель --upper позволяет включить функцию прописных букв. Аналогично, переключатель --lower позволяет использовать функцию строчных букв в вашем приложении. Если вы запустите приложение без переключателя, то получите сообщение в исходном виде.

Важно отметить, что вы можете сделать один из параметров поведения вашего приложения по умолчанию, установив для его параметра default значение True. Например, если вы хотите, чтобы параметр --upper использовался по умолчанию, вы можете добавить default=True в определение параметра. В приведенном выше примере вы этого не сделали, потому что печать сообщения с использованием его оригинального оформления кажется подходящим и менее неожиданным решением.

Получение значения параметра из нескольких вариантов выбора

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

Вот приложение CLI, которое определяет параметр выбора с именем --weekday. Этот параметр будет принимать строку с целевым днем недели:

# days.py

import click

@click.command()
@click.option(
    "--weekday",
    type=click.Choice(
        [
            "Monday",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday",
            "Saturday",
            "Sunday",
        ]
    ),
)
def cli(weekday):
    click.echo(f"Weekday: {weekday}")

if __name__ == "__main__":
    cli()

В этом примере вы используете класс Choice, чтобы предоставить список дней недели в виде строк. Когда пользователь запускает это приложение, ему нужно будет указать день недели, соответствующий одному из значений в списке. В противном случае они получат сообщение об ошибке:

(venv) $ python days.py --weekday Monday
Weekday: Monday

(venv) $ python days.py --weekday Wednesday
Weekday: Wednesday

(venv) $ python days.py --weekday FRIDAY
Usage: days.py [OPTIONS]
Try 'days.py --help' for help.

Error: Invalid value for '--weekday': 'FRIDAY' is not one of 'Monday',
'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'.

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

У вас есть возможность обойти эту проблему с регистром, установив для аргумента case_sensitive значение False при создании экземпляра типа параметра Choice.

Получение параметров из переменных Окружения

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

Например, предположим, что вы создаете инструмент CLI для использования REST API. В этой ситуации вам может понадобиться секретный ключ для доступа к API. Один из способов справиться с этим ключом - экспортировать его в качестве переменной окружения и заставить ваше приложение считывать его оттуда.

В приведенном ниже примере вы пишете CLI-приложение для получения интересных космических снимков и видео с главной страницы API NASA . Чтобы получить доступ к этому API, вашему приложению нужен ключ API, который вы можете сохранить в переменной окружения и автоматически извлекать с помощью Click:

# nasa.py

import webbrowser

import click
import requests

BASE_URL = "https://api.nasa.gov/planetary"
TIMEOUT = 3

@click.command()
@click.option("--date", default="2021-10-01")
@click.option("--api-key", envvar="NASA_API_KEY")
def cli(date, api_key):
    endpoint = f"{BASE_URL}/apod"
    try:
        response = requests.get(
            endpoint,
            params={
                "api_key": api_key,
                "date": date,
            },
            timeout=TIMEOUT,
        )
    except requests.exceptions.RequestException as e:
        print(f"Error connecting to API: {e}")
        return

    try:
        url = response.json()["url"]
    except KeyError:
        print(f"No image available on {date}")
        return

    webbrowser.open(url)

if __name__ == "__main__":
    cli()

В этом примере вы импортируете webbrowser из стандартной библиотеки Python. Этот модуль позволяет быстро открывать URL-адреса в вашем браузере по умолчанию. Затем вы импортируете библиотеку requests для выполнения HTTP-запросов к целевому REST API.

Примечание: Чтобы узнать больше о доступе к REST API в вашем коде, ознакомьтесь с Python и API: выигрышная комбинация для чтения общедоступных данных.

В выделенной строке вы создаете параметр --api_key и присваиваете его аргументу envvar значение "NASA_API_KEY". Эта строка представляет собой имя, которое вы будете использовать для переменной окружения, в которой вы будете хранить ключ API.

В функции cli() вы отправляете HTTP-запрос к /apod конечной точке, получаете целевой URL-адрес и, наконец, открываете этот URL-адрес в своем браузере по умолчанию.

Примечание: Название конечной точки /apod является сокращением от астрономическая картина дня.

Чтобы попробовать вышеупомянутое CLI-приложение, выполните команды, приведенные ниже. Обратите внимание, что в этих командах вы будете использовать "DEMO_KEY" для доступа к API. Этот ключ имеет ограничения по скорости. Итак, если вы хотите создать свой собственный ключ, то вы можете сделать это на странице API:

(venv) $ export NASA_API_KEY="DEMO_KEY"
(venv) $ python nasa.py --date 2023-06-05

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

Важно отметить, что вы также можете указать ключ в командной строке, явно используя параметр --api-key, как обычно. Это удобно в ситуациях, когда переменная окружения не определена.

Запрос пользователю вводимых значений

Запрос пользователя на ввод данных является довольно распространенным требованием в CLI-приложениях. Запросы могут значительно улучшить работу пользователя с вашим приложением. К счастью, Click также предоставляет вам подсказки.

С помощью Click вы можете создать как минимум следующие типы приглашений:

Ввод подсказки
Пароль Подсказки
Подтверждение запросы

Вы можете создавать пользовательские приглашения, используя либо аргумент prompt для @click.option, либо функцию click.prompt(). У вас также будут специальные средства оформления, такие как @click.password_option и @click.confirmation_option, для создания подсказок ввода пароля и подтверждения.

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

# user.py

import click

@click.command()
@click.option("--name", prompt="Username")
@click.option("--password", prompt="Password", hide_input=True)
def cli(name, password):
    if name != read_username() or password != read_password():
        click.echo("Invalid user credentials")
    else:
        click.echo(f"User {name} successfully logged in!")

def read_password():
    return "secret"

def read_username():
    return "admin"

if __name__ == "__main__":
    cli()

Параметр --name содержит обычную подсказку для ввода, которую вы задаете с помощью аргумента prompt. Параметр --password содержит подсказку с дополнительной функцией скрытия ввода. Такое поведение идеально подходит для паролей. Чтобы установить эту новую функцию, вы используете флаг hide_input.

Если вы запустите это приложение из командной строки, то получите следующее поведение:

(venv) $ python user.py
Username: admin
Password:
User admin successfully logged in!

Как вы могли заметить, в подсказке Username на экране отображается введенное значение. В отличие от этого, приглашение Password скрывает вводимые данные при вводе, что является подходящим поведением для ввода пароля.

При работе с паролями обычным требованием может быть предоставление пользователю возможности изменить свой пароль. В этом случае вы можете использовать @click.password_option декоратор. Этот конструктор позволяет вам создать параметр пароля, который скрывает вводимые данные и запрашивает подтверждение. Если два пароля не совпадают, вы получаете сообщение об ошибке и снова появляется запрос пароля.

Вот наглядный пример того, как изменить пароль данного пользователя:

# set_password.py

import click

@click.command()
@click.option("--name", prompt="Username")
@click.password_option("--set-password", prompt="Password")
def cli(name, set_password):
    # Change the password here...
    click.echo("Password successfully changed!")
    click.echo(f"Username: {name}")
    click.echo(f"Password: {set_password}")

if __name__ == "__main__":
    cli()

Используя @click.password_option, вы можете создать запрос ввода пароля, который автоматически скрывает вводимые данные и запрашивает подтверждение. В этом примере вы создаете --set-password, который выполняет именно это. Вот как это работает на практике:

(venv) $ python set_password.py
Username: admin
Password:
Repeat for confirmation:
Error: The two entered values do not match.
Password:
Repeat for confirmation:
Password successfully changed!
Username: admin
Password: secret

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

Вы можете вручную запросить ввод данных у пользователей. Для этого вы можете воспользоваться функцией prompt(). Эта функция принимает несколько аргументов, которые позволяют вам создавать пользовательские подсказки и использовать их в других частях вашего кода, независимо от того, где вы определили параметры.

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

# add.py

import click

@click.command()
def cli():
    a = click.prompt("Enter an integer", type=click.INT, default=0)
    b = click.prompt("Enter another integer", type=click.INT, default=0)
    click.echo(f"{a} + {b} = {a + b}")

if __name__ == "__main__":
    cli()

В этом примере вы создаете две подсказки для ввода внутри cli(), используя функцию prompt(). В первом приглашении запрашивается значение a, а во втором - значение b. В обоих приглашениях проверяется, является ли введенное значение допустимым целым числом, и в противном случае отображается сообщение об ошибке. Если пользователь не вводит никаких данных, он может принять значение по умолчанию, 0, нажав Введите.

Вот как работает это приложение:

(venv) $ python add.py
Enter an integer [0]: 42.0
Error: '42.0' is not a valid integer.
Enter an integer [0]: 42
Enter another integer [0]: 7
42 + 7 = 49

При первой попытке ввода вы вводите число с плавающей запятой. Щелчок проверяет правильность введенных данных и выводит сообщение об ошибке. Затем вы вводите два допустимых целых значения и получаете успешный результат.

Click также предоставляет функцию, называемую confirm(). Эта функция удобна, когда вам нужно запросить у пользователя подтверждение для выполнения конфиденциального действия, такого как удаление файла или удаление пользователя.

Функция confirm() запросит подтверждение с помощью да или нет вопрос:

# remove.py

import click

@click.command()
@click.option("--remove-user")
def cli(remove_user):
    if click.confirm(f"Remove user '{remove_user}'?"):
        click.echo(f"User {remove_user} successfully removed!")
    else:
        click.echo("Aborted!")

if __name__ == "__main__":
    cli()

Функция confirm() возвращает логическое значение в зависимости от ответа пользователя на вопрос о подтверждении "да" или "нет". Если пользователь ответит "да", вы выполните запланированное действие. В противном случае вы прерываете его.

Вот пример использования этого приложения:

(venv) $ python remove.py --remove-user admin
Remove user 'admin'? [y/N]:
Aborted!

(venv) $ python remove.py --remove-user john
Remove user 'john'? [y/N]: y
User john successfully removed!

В первом примере вы принимаете ответ по умолчанию, N вместо нет, нажав Введите как ответ на запрос. Обратите внимание, что в CLI-приложениях вы часто обнаружите, что параметр default пишется с заглавной буквы, чтобы указать, что он используется по умолчанию. В приглашениях Click также используется этот общий шаблон.

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

Предоставление типов параметров для аргументов и опций

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

Вот некоторые из наиболее подходящих типов параметров, доступных в Click:

Parameter Type	Description
`click.STRING`	Represents Unicode strings and is the default parameter type for arguments and options
`click.INT`	Represents integer numbers
`click.FLOAT`	Represents floating-point numbers
`click.BOOL`	Represents Boolean values

Помимо этих констант, которые представляют примитивные типы, в Click также есть несколько удобных классов, которые вы можете использовать для определения других типов входных значений. Вы уже слышали о классах click.Path, click.File, click.Choice, и click.Tuple в предыдущих разделах. В дополнение к этим классам Click также включает в себя следующие:

Parameter Type Class	Description
`click.IntRange`	Restricts the input value to a range of integer numbers
`click.FloatRange`	Restricts the input value to a range of floating-point numbers
`click.DateTime`	Converts date strings into `datetime` objects

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

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

Создание подкоманд в Click

Вложенные команды или подкоманды являются одной из самых мощных и отличительных особенностей Click. Что такое вообще подкоманда? Многие приложения командной строки, такие как pip, pyenv, Poetry и git, широко используют подкоманды.

Например, pip содержит подкоманду install, которая позволяет устанавливать пакеты и библиотеки Python в заданной среде. Например, вы использовали pip install click в начале этого руководства для установки библиотеки Click.

Аналогично, приложение git имеет множество подкоманд, таких как pull, push и clone. Скорее всего, вы найдете несколько примеров CLI-приложений с подкомандами в своем ежедневном рабочем процессе, потому что подкоманды очень полезны в реальных приложениях.

В следующем разделе вы узнаете, как добавлять подкоманды к вашим приложениям Click с помощью декоратора @click.group. Вы узнаете о двух распространенных подходах к созданию подкоманд:

Немедленная регистрация подкоманд, что уместно, если у вас есть минимальное приложение в одном файле
Отсрочка регистрации подкоманды, что удобно, когда у вас сложное приложение, команды которого распределены по нескольким модулям

Прежде чем вы углубитесь в суть этого раздела, важно отметить, что в этом руководстве вы лишь поверхностно познакомитесь с подкомандами Click. Однако вы узнаете достаточно, чтобы начать использовать их в своих CLI-приложениях.

Немедленная регистрация подкоманды

Чтобы проиллюстрировать первый подход к созданию подкоманд в Click-приложениях, предположим, что вы хотите создать CLI-приложение с четырьмя подкомандами, представляющими арифметические операции:

add для сложения двух чисел вместе
sub для вычитания двух чисел
mul для умножения двух чисел
div для деления двух чисел

Чтобы создать это приложение, вы начинаете с создания файла с именем calc.py в вашем рабочем каталоге. Затем вы создаете группу команд, используя @click.group декоратор, как в приведенном ниже коде:

# calc.py v1

import click

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

В этом фрагменте кода вы создаете группу команд с именем cli, оформляя функцию cli() с помощью @click.group декоратора.

В этом конкретном примере функция cli() предоставляет точку входа для CLI приложения. Она не будет выполнять никаких конкретных операций. Вот почему он содержит только оператор pass. Однако другим приложениям может потребоваться принимать аргументы и опции в cli(), что вы можете реализовать как обычно.

Создав группу команд, вы можете сразу же начать добавлять новые подкоманды. Для этого вы используете декоратор, созданный с использованием названия группы и функции command(). Например, в приведенном ниже коде вы создаете команду add:

# calc.py v1

# ...

@cli.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def add(a, b):
    click.echo(a + b)

if __name__ == "__main__":
    cli()

В этом фрагменте кода для создания команды add используется @cli.command, а не @click.command. Таким образом, вы сообщаете Click, чтобы он присоединил команду add к группе cli.

В конце файла вы помещаете обычное имя-основную идиому для вызова функции cli() и запуска интерфейса командной строки. Вот и все! Ваша подкоманда add готова к использованию. Продолжайте и выполните следующую команду:

(venv) $ python calc.py add 3 8
11.0

Круто! Ваша подкоманда add работает должным образом. Она принимает два числа и складывает их вместе, выводя результат на экран в виде числа с плавающей запятой.

В качестве упражнения вы можете использовать подкоманды для операций вычитания, умножения и деления. Разверните раздел, который можно сворачивать, чтобы увидеть полное решение:

Вот полная реализация для вашего calc.py приложения:

# calc.py v1

import click

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

@cli.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def add(a, b):
    click.echo(a + b)

@cli.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def sub(a, b):
    click.echo(a - b)

@cli.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def mul(a, b):
    click.echo(a * b)

@cli.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def div(a, b):
    click.echo(a / b)

if __name__ == "__main__":
    cli()

Во всех новых подкомандах вы следуете тому же шаблону, что и в add. Вы присоединяете каждую из них к группе cli, а затем определяете ее аргументы и конкретную арифметическую операцию. Это был приятный опыт программирования, не так ли?

После того, как вы запишете остальные операции в виде подкоманд, попробуйте их из командной строки. Отлично, они работают! Но что, если у вас не все подкоманды готовы сразу? В этом случае вы можете отложить регистрацию своей подкоманды, о чем вы узнаете далее.

Отложенная регистрация подкоманды

Вместо использования @group_name.command() декоратора для добавления подкоманд поверх группы команд сразу, вы можете использовать group_name.add_command() для добавления или регистрации подкоманд позже.

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

Предположим, что вы переработали свое calc.py приложение из предыдущего раздела, и теперь оно имеет следующую структуру:

calc/
├── calc.py
└── commands.py

На этой диаграмме дерева каталогов представлены файлы calc.py и commands.py. В последнем файле вы разместили все свои команды, и он выглядит примерно так:

# commands.py

import click

@click.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def add(a, b):
    click.echo(a + b)

@click.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def sub(a, b):
    click.echo(a - b)

@click.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def mul(a, b):
    click.echo(a * b)

@click.command()
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def div(a, b):
    click.echo(a / b)

Обратите внимание, что в этом файле вы определили команды с помощью @click.command декоратора. Остальная часть кода - это тот же код, который вы использовали в предыдущем разделе. Как только у вас будет этот файл со всеми вашими подкомандами, вы сможете импортировать их из calc.py и использовать метод .add_command() для их регистрации:

# calc.py v2

import click
import commands

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

cli.add_command(commands.add)
cli.add_command(commands.sub)
cli.add_command(commands.mul)
cli.add_command(commands.div)

if __name__ == "__main__":
    cli()

В файле calc.py вы сначала обновляете импорт, чтобы включить модуль commands, который предоставляет реализации для подкоманд вашего приложения. Затем вы используете метод .add_command() для регистрации этих подкоманд в группе cli.

Если вы попробуете эту новую версию вашего приложения, то заметите, что оно работает так же, как и его первая версия:

(venv) $ python calc/calc.py add 3 8
11.0

Чтобы запустить приложение, вам необходимо указать новый путь, поскольку скрипт точки входа в приложение теперь находится в папке calc/. Как вы можете видеть, функциональность calc.py осталась прежней. Вы изменили только внутреннюю организацию своего кода.

В общем, вы будете использовать .add_command() для регистрации подкоманд, когда ваше CLI-приложение состоит из нескольких модулей и ваши команды распределены по этим модулям. Для базовых приложений с ограниченными функциональными возможностями вы можете сразу зарегистрировать команды с помощью @group_name.command декоратора, как вы делали в предыдущем разделе.

Настройка использования и справочных сообщений в приложении Click

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

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

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

Документирование команд и параметров

Команды и параметры Click принимают аргумент help, который вы можете использовать для предоставления конкретных справочных сообщений для них. Эти сообщения будут отображаться при запуске приложения с параметром --help. Чтобы проиллюстрировать это, вернитесь к самой последней версии вашего скрипта ls.py и проверьте его текущую страницу справки:

(venv) $ python ls.py --help
Usage: ls.py [OPTIONS] [PATHS]...

Options:
  -l, --long
  --help      Show this message and exit.

Эта страница справки хороша в качестве отправной точки. Ее наиболее ценной особенностью является то, что для ее создания вам не пришлось писать ни строчки кода. Библиотека Click автоматически сгенерирует ее для вас. Однако вы можете доработать его и сделать более удобным для пользователя и полным.

Для начала обновите код, добавив help аргумент в @click.command декоратор:

# ls.py v5

import datetime
from pathlib import Path

import click

@click.command(help="List the content of one or more directories.")
@click.option("-l", "--long", is_flag=True)
@click.argument(
    "paths",
    nargs=-1,
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(paths, long):
    # ...

В выделенной строке вы передаете аргумент help, содержащий строку, которая содержит общее описание того, что делает базовая команда. Теперь продолжайте и снова запустите приложение с параметром --help:

(venv) $ python ls.py --help
Usage: ls.py [OPTIONS] [PATHS]...

  List the content of one or more directories.

Options:
  -l, --long
  --help      Show this message and exit.

Страница справки приложения теперь выглядит по-другому. Она содержит общее описание функций приложения.

Важно отметить, что когда дело доходит до страниц справки по командам, строка документации базовой функции произведет тот же эффект, что и аргумент help. Таким образом, вы можете удалить аргумент help и ввести строку для функции cli(), чтобы получить эквивалентный результат. Попробуйте!

Примечание: Если в вашем приложении есть несколько подкоманд, нажмите кнопку, чтобы добавить раздел Commands на страницу справки и перечислить все команды. Если вы добавите справочные сообщения ко всем своим подкомандам, они будут отображаться рядом с названием команды.

В качестве упражнения вы можете добавить справочные сообщения в подкоманды вашего приложения calc.py. Вот как могла бы выглядеть страница справки приложения:

(venv) $ python calc.py --help
Usage: calc.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add  Add two numbers.
  div  Divide two numbers.
  mul  Multiply two numbers.
  sub  Subtract two numbers.

На этой странице справки каждая подкоманда отображает свое собственное справочное сообщение, которое довольно полезно с точки зрения пользователя.

Теперь обновите параметр --long, как в приведенном ниже коде, чтобы получить справочное сообщение с описанием:

# ls.py v6

import datetime
from pathlib import Path

import click

@click.command(help="List the content of one or more directories.")
@click.option(
    "-l",
    "--long",
    is_flag=True,
    help="Display the directory content in long format.",
)
@click.argument(
    "paths",
    nargs=-1,
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(paths, long):
    # ...

В определении параметра --long вы включаете аргумент help с описанием того, что делает этот конкретный параметр. Вот как это изменение повлияет на страницу справки приложения:

(venv) $ python ls.py --help
Usage: ls.py [OPTIONS] [PATHS]...

  List the content of one or more directories.

Options:
  -l, --long  Display the directory content in long format.
  --help      Show this message and exit.

Опция --long теперь содержит красивое описание, которое сообщает пользователю о ее назначении. Это здорово!

Документирование аргументов

В отличие от @click.command и @click.option, декоратор click.argument() не принимает аргумент help. Как сказано в документации по Click:

Это [отсутствие аргумента help] сделано в соответствии с общим соглашением инструментов Unix использовать аргументы только для самых необходимых задач и документировать их в тексте справки по командам, ссылаясь на них по имени. (Источник)

Итак, как вы можете документировать аргумент командной строки в приложении Click? Вы будете использовать строку документации базовой функции. Да, это звучит странно. Команды также используют эту строку документации. Итак, вам придется обращаться к аргументам по их именам. Например, вот как бы вы задокументировали аргумент PATHS в своем приложении ls.py:

# ls.py v6

import datetime
from pathlib import Path

import click

@click.command()
@click.option(
    "-l",
    "--long",
    is_flag=True,
    help="Display the directory content in long format.",
)
@click.argument(
    "paths",
    nargs=-1,
    type=click.Path(
        exists=True,
        file_okay=False,
        readable=True,
        path_type=Path,
    ),
)
def cli(paths, long):
    """List the content of one or more directories.

    PATHS is one or more directory paths whose content will be listed.
    """
    # ...

В этой обновленной версии ls.py сначала вы удаляете аргумент help из определения команды. Если вы этого не сделаете, строка документации не будет работать должным образом, поскольку аргумент help будет иметь преимущественную силу. Строка документации cli() содержит исходное справочное сообщение для команды. В нем также есть дополнительная строка, описывающая, что представляет собой аргумент PATHS. Обратите внимание, что вы ссылались на аргумент по его имени.

Вот как выглядит страница справки после этих обновлений:

(venv) $ python ls.py --help
Usage: ls.py [OPTIONS] [PATHS]...

  List the content of one or more directories.

  PATHS is one or more directory paths whose content will be listed.

Options:
  -l, --long  Display the directory content in long format.
  --help      Show this message and exit.

Эта страница справки выглядит неплохо! Вы задокументировали основную команду приложения и аргументы PATHS, используя строку документации базовой функции cli(). Теперь страница справки приложения предоставляет пользователю достаточно рекомендаций для эффективного его использования.

Подготовка приложения Click к установке и использованию

Когда вы погружаетесь в создание CLI-приложений с помощью Click, вы быстро замечаете, что официальная документация рекомендует переключиться с идиомы name-main на setuptools. Использование setuptools является предпочтительным способом установки, разработки, работы и даже распространения Click apps.

В этом руководстве вы использовали идиоматический подход во всех примерах, чтобы быстро найти решение. Теперь пришло время перейти к setuptools. В этом разделе вы будете использовать приложение calc.py в качестве примера проекта и начнете с создания надлежащего макета проекта для приложения.

Создайте макет проекта для вашего CLI-приложения

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

Создайте модули и пакеты для упорядочивания вашего кода.
Назовите основной пакет приложения на Python в честь самого приложения.
Назовите каждый модуль на Python в соответствии с его конкретным содержанием или функциональностью.
Добавьте модуль __main__.py в любой непосредственно исполняемый пакет Python.

Учитывая эти идеи, вы можете использовать следующую структуру каталогов для размещения вашего проекта calc:

calc/
│
├── calc/
│   ├── __init__.py
│   ├── __main__.py
│   └── commands.py
│
├── pyproject.toml
└── README.md

Папка calc/ является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:<<<2>> pyproject.toml setup.py pyproject.toml setup.py
README.md README.md

Папка calc/ является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:<<<2>>

является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:<<<2>> __init__.py calc/
__main__.py
commands.py

Папка __main__.py является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:<<<2>>

Папка

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

Папка __main__.py является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

# __main__.py

import click

from . import commands

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

cli.add_command(commands.add)
cli.add_command(commands.sub)
cli.add_command(commands.mul)
cli.add_command(commands.div)

Папка является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

Папка calc.py является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:<<<2>> commands calc

Папка

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

Папка commands.py является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

# commands.py

import click

@click.command(help="Add two numbers.")
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def add(a, b):
    click.echo(a + b)

@click.command(help="Subtract two numbers.")
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def sub(a, b):
    click.echo(a - b)

@click.command(help="Multiply two numbers.")
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def mul(a, b):
    click.echo(a * b)

@click.command(help="Divide two numbers.")
@click.argument("a", type=click.FLOAT)
@click.argument("b", type=click.FLOAT)
def div(a, b):
    click.echo(a / b)

Папка является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

Папка commands.py является корневым каталогом проекта. В этом каталоге хранятся следующие файлы:

Теперь, когда макет проекта готов, вы можете написать подходящий файл pyproject.toml и подготовить свой проект к разработке, использованию и даже распространению.

Создайте `pyproject.toml` Файл для вашего проекта Click

Файл pyproject.toml позволяет вам определить систему сборки приложения, а также множество других общих конфигураций. Вот минимальный пример того, как заполнить этот файл для вашего образца проекта calc:

# pyproject.toml

[build-system]
requires = ["setuptools>=65.5.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "calc"
version = "0.1.0"
description = "A CLI application that performs arithmetic operations."
readme = "README.md"
authors = [{ name = "Real Python", email = "info@realpython.com" }]
dependencies = [
    "click >= 8.1.3",
]

[project.scripts]
calc = "calc.__main__:cli"

[build-system] Заголовок таблицы определяет setuptools как систему сборки вашего приложения и определяет зависимости для сборки приложения.

Заголовок [project] позволяет вам предоставить общие метаданные для приложения. Эти метаданные могут включать множество пар ключ-значение, включая название приложения, версию, общее описание и так далее.

Ключ dependencies очень важен и удобен. С помощью этого ключа вы можете перечислить все зависимости проекта и их целевые версии. В этом примере единственной зависимостью является щелчок, и вы используете версию, большую или равную 8.1.3. Система сборки проекта возьмет этот список и автоматически установит все его элементы.

Ключ [project.scripts] очень важен и удобен. С помощью этого ключа вы можете перечислить все зависимости проекта и их целевые версии. В этом примере единственной зависимостью является щелчок, и вы используете версию, большую или равную cli(). Система сборки проекта возьмет этот список и автоматически установит все его элементы.<<<3>> calc

Ключ

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

Вы уже узнали, как создать виртуальную среду Python. Итак, продолжайте и откройте окно терминала. Затем перейдите в корневую папку вашего проекта calc. Как только вы окажетесь там, выполните следующие команды, чтобы создать новую среду:

PS> python -m venv venv
PS> venv\Scripts\activate

$ python -m venv venv
$ source venv/bin/activate

Отлично! У вас есть новая виртуальная среда в папке вашего проекта. Чтобы установить приложение в нее, воспользуйтесь -e из pip install. Этот параметр позволяет устанавливать пакеты, библиотеки и инструменты в редактируемом режиме.

Редактируемый режим позволяет работать с исходным кодом, а также пробовать последние изменения по мере их внедрения. Этот режим весьма полезен на этапе разработки.

Вот команда, которую вам нужно запустить для установки calc:

(venv) $ python -m pip install -e .

Как только вы выполните эту команду, ваше приложение calc будет установлено в вашей текущей среде Python. Чтобы проверить это, выполните следующую команду:

(venv) $ pip list
Package           Version
----------------- -------
calc              0.1.0
click             8.1.6
...

Команда pip list выводит список всех установленных в данный момент пакетов в данной среде. Как вы можете видеть из приведенного выше вывода, calc установлен. Еще один интересный момент заключается в том, что зависимость от проекта, click, также установлена. Да, ключ dependencies в файле pyproject.toml вашего проекта сотворил чудо.

Команда

выводит список всех установленных в данный момент пакетов в данной среде. Как вы можете видеть из приведенного выше вывода, установлен. Еще один интересный момент заключается в том, что зависимость от проекта, , также установлена. Да, ключ в файле вашего проекта сотворил чудо.

(venv) $ calc add 3 4
7.0

(venv) $ calc sub 3 4
-1.0

(venv) $ calc mul 3 4
12.0

(venv) $ calc div 3 4
0.75

(venv) $ calc --help
Usage: calc [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add  Add two numbers.
  div  Divide two numbers.
  mul  Multiply two numbers.
  sub  Subtract two numbers.

Команда выводит список всех установленных в данный момент пакетов в данной среде. Как вы можете видеть из приведенного выше вывода, установлен. Еще один интересный момент заключается в том, что зависимость от проекта, , также установлена. Да, ключ в файле вашего проекта сотворил чудо.

Команда calc выводит список всех установленных в данный момент пакетов в данной среде. Как вы можете видеть из приведенного выше вывода, Usage установлен. Еще один интересный момент заключается в том, что зависимость от проекта, calc, также установлена. Да, ключ calc.py в файле

вашего проекта сотворил чудо.

Команда

Теперь у вас есть общее представление о том, как работает библиотека Click в Python. Вы знаете, как использовать ее для создания мощных интерфейсов командной строки для небольших или крупных приложений и средств автоматизации. С помощью Click вы можете быстро создавать приложения, которые предоставляют аргументы, опции и подкоманды.

Вы также узнали, как настроить страницу справки вашего приложения, что может существенно улучшить ваш пользовательский опыт.

В этом руководстве вы узнали, как:

Создайте интерфейсы командной строки для своих приложений, используя Click и Python
Поддерживайте аргументов, параметры и подкоманды в ваших CLI-приложениях
Улучшите использование и страниц справки ваших CLI-приложений
Подготовьте приложение Click для установки, разработки, использования, и распространения

Библиотека Click предоставляет надежное и продуманное решение для создания расширяемых и мощных CLIS. Знание того, как использовать эту библиотеку, позволит вам писать эффективные и интуитивно понятные приложения командной строки, что является отличным навыком для разработчика на Python.

<статус завершения: article-slug="python-click" class="btn-group mb-0" data-api-article-bookmark-url="/api/v1/articles/python-click/bookmark/" данные-api-статья-статус завершения-url="/api/v1/articles/python-click/completion_status/"> <кнопка поделиться bluesky-text="Интересная статья #Python от @realpython.com :" email-body="Ознакомьтесь с этой статьей о Python:%0A%0acclick и Python: Создавайте расширяемые и компонуемые CLI-приложения" email-subject="Статья на Python для вас" twitter-text="Интересная статья на #Python от @realpython:" url="https://realpython.com/python-click /" url-title="Click и Python: создание расширяемых и компонуемых CLI-приложений">

Click и Python: Создание расширяемых и компонуемых CLI-приложений

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

Зачем использовать Click для разработки интерфейса командной строки

Как установить и настроить Click: Ваше первое CLI-приложение

Добавление аргументов в приложение Click

Добавление основных аргументов

Использование аргументов пути

Прием переменных аргументов

Принимает аргументы файла

Предоставление опций в ваших приложениях Click

Добавление параметров с одним значением

Создание многозначных параметров

Многократное указание параметра

Определение параметров в виде логических флагов

Создание функциональных переключателей

Получение значения параметра из нескольких вариантов выбора

Получение параметров из переменных Окружения

Запрос пользователю вводимых значений

Предоставление типов параметров для аргументов и опций

Создание подкоманд в Click

Немедленная регистрация подкоманды

Отложенная регистрация подкоманды

Настройка использования и справочных сообщений в приложении Click

Документирование команд и параметров

Документирование аргументов

Подготовка приложения Click к установке и использованию

Создайте макет проекта для вашего CLI-приложения

Создайте pyproject.toml Файл для вашего проекта Click

Ключ

Команда

Рекомендуемые записи по теме

Создайте `pyproject.toml` Файл для вашего проекта Click