API

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

Декораторы

click.command(name: Callable[[...], Any]) → Command

click.command(name:str|None, cls:Type[CmdType], **attrs:Any) → Callable[[Callable[[...],Any]],CmdType]

click.command(name:None=None, *, cls:Type[CmdType], **attrs:Any) → Callable[[Callable[[...],Any]],CmdType]

click.command(name:str|None=None, cls:None=None, **attrs:Any) → Callable[[Callable[[...],Any]],Command]

Создаёт новый Command и использует декорированную функцию в качестве обратного вызова. Также автоматически прикрепляет все декорированные option() и argument() в качестве параметров команды.

Имя команды по умолчанию соответствует имени функции, заменив подчёркивания на дефисы. Если вы хотите изменить это, вы можете передать желаемое имя в качестве первого аргумента.

Все ключевые аргументы передаются базовому классу команды. Для аргумента params, все декорированные параметры добавляются в конец списка.

После декорирования функция превращается в экземпляр Command, который можно вызвать как утилиту командной строки или прикрепить к команде Group.

Parameters:

name – имя команды. По умолчанию соответствует имени функции с заменой подчёркиваний на дефисы.
cls – класс команды, который необходимо создать. По умолчанию Command.

Изменено в версии 8.1: Этот декоратор может быть применён без скобок.

Изменено в версии 8.1: Аргумент params может быть использован. Декорированные параметры добавляются в конец списка.

END_OF_DOCUMENT_MARKER

click.group(name: Callable[[...], Any]) → Group
click.group(name:str|None, cls:Type[GrpType], **attrs:Any) → Callable[[Callable[[...],Any]],GrpType]
click.group(name:None=None, *, cls:Type[GrpType], **attrs:Any) → Callable[[Callable[[...],Any]],GrpType]
click.group(name:str|None=None, cls:None=None, **attrs:Any) → Callable[[Callable[[...],Any]],Group]: Создаёт новую группу Group с функцией в качестве обратного вызова. Это работает аналогично command() с той лишь разницей, что параметр cls установлен в Group.

Изменено в версии 8.1: Этот декоратор может быть применён без скобок.

click.argument(*param_decls, cls=None, **attrs)

Присоединяет аргумент к команде. Все позиционные аргументы передаются как параметры объявления к Argument; все именованные аргументы передаются без изменений (кроме cls). Это эквивалентно созданию экземпляра Argument вручную и его прикреплению к списку Command.params.

Для стандартного класса аргумента, обратитесь к Argument и Parameter для описания параметров.

Параметры:

cls (Type[Argument] | None) – класс аргумента для создания экземпляра. По умолчанию это Argument.
param_decls (str) – Передаётся как позиционные аргументы конструктору cls.
attrs (Any) – Передаётся как именованные аргументы конструктору cls.

Возвращаемый тип:

Callable[[FC], FC]

click.option(*param_decls, cls=None, **attrs)

Присоединяет опцию к команде. Все позиционные аргументы передаются как параметры объявления к Option; все именованные аргументы передаются без изменений (кроме cls). Это эквивалентно созданию экземпляра Option вручную и его прикреплению к списку Command.params.

Для стандартного класса опции, обратитесь к Option и Parameter для описания параметров.

Параметры:

cls (Type[Option] | None) – класс опции для создания экземпляра. По умолчанию это Option.
param_decls (str) – Передаётся как позиционные аргументы конструктору cls.
attrs (Any) – Передаётся как именованные аргументы конструктору cls.

Возвращаемый тип:

Callable[[FC], FC]

click.password_option(*param_decls, **kwargs)

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

Параметры:

param_decls (str) – Одно или несколько имён параметров. По умолчанию значение "--password".
kwargs (Any) – Дополнительные аргументы передаются в option().

Тип возвращаемого значения:

Callable[[FC], FC]

click.confirmation_option(*param_decls, **kwargs)

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

Параметры:

param_decls (str) – Одно или несколько имён параметров. По умолчанию значение "--yes".
kwargs (Any) – Дополнительные аргументы передаются в option().

Тип возвращаемого значения:

Callable[[FC], FC]

click.version_option(version=None, *param_decls, package_name=None, prog_name=None, message=None, **kwargs)

Добавить параметр --version, который сразу выводит номер версии и завершает программу.

Если version не предоставлен, Click попытается определить его, используя importlib.metadata.version() для получения версии package_name. В Python < 3.8 необходимо установить обратную совместимость importlib_metadata.

Если package_name не предоставлен, Click попытается определить его, проанализировав кадры стека. Это будет использоваться для определения версии, поэтому оно должно соответствовать имени установленного пакета.

Параметры:

version (str | None) – Номер версии для отображения. Если не предоставлен, Click попытается определить его.
param_decls (str) – Одно или несколько имён параметров. По умолчанию значение "--version".
package_name (str | None) – Имя пакета для определения версии. Если не предоставлено, Click попытается определить его.
prog_name (str | None) – Имя командной строки для отображения в сообщении. Если не предоставлено, оно будет определено из команды.
message (str | None) – Сообщение для отображения. Доступны значения %(prog)s, %(package)s, и %(version)s. По умолчанию "%(prog)s, version %(version)s".
kwargs (Any) – Дополнительные аргументы передаются в option().

Исключения:

RuntimeError – version не удалось определить.

Тип возвращаемого значения:

Callable[[FC], FC]

Изменения

Изменено в версии 8.0: Добавлен параметр package_name, и значение %(package)s для сообщений.

Изменено в версии 8.0: Используйте importlib.metadata вместо pkg_resources. Версия определяется на основе имени пакета, а не имени точки входа. Имя пакета Python должно соответствовать имени установленного пакета или быть передано с package_name=.

click.help_option(*param_decls, **kwargs)

Добавить параметр --help, который сразу выводит страницу справки и завершает программу.

Это обычно не нужно, так как параметр --help автоматически добавляется к каждой команде, если не передано add_help_option=False.

Параметры:

param_decls (str) – Одно или несколько имён параметров. По умолчанию значение "--help".
kwargs (Any) – Дополнительные аргументы передаются в option().

Тип возвращаемого значения:

Callable[[FC], FC]

click.pass_context(f)

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

Параметры:: f (t.Callable[te.Concatenate[Context, P], R]) –
Тип возвращаемого значения:: t.Callable[P, R]

click.pass_obj(f)

Аналогично pass_context(), но передаёт объект только в контекст (Context.obj). Это полезно, если этот объект представляет состояние вложенной системы.

Параметры:: f (t.Callable[te.Concatenate[t.Any, P], R]) –
Тип возвращаемого значения:: t.Callable[P, R]

click.make_pass_decorator(object_type, ensure=False)

Принимая тип объекта, создаёт декоратор, который будет работать аналогично pass_obj(), но вместо передачи объекта текущего контекста, он найдёт самый внутренний контекст типа object_type().

Это генерирует декоратор, который работает примерно так:

from functools import update_wrapper

def decorator(f):
    @pass_context
    def new_func(ctx, *args, **kwargs):
        obj = ctx.find_object(object_type)
        return ctx.invoke(f, obj, *args, **kwargs)
    return update_wrapper(new_func, f)
return decorator

Параметры:

object_type (Type[T]) – тип объекта для передачи.
ensure (bool) – если установлено в True, новый объект будет создан и запомнен в контексте, если его там ещё нет.

Тип возвращаемого значения:

Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]

click.decorators.pass_meta_key(key, *, doc_description=None)

Создайте декоратор, который передаёт ключ из click.Context.meta в качестве первого аргумента декорированной функции.

Параметры:

ключ (str) – Ключ в Context.meta для передачи.
описание_объекта (str | None) – Описание передаваемого объекта, вставляемое в строку документации декоратора. По умолчанию «ключ ‘ключ’ из Context.meta».

Тип возвращаемого значения:

t.Callable[[t.Callable[te.Concatenate[t.Any, P], R]], t.Callable[P, R]]

Журнал изменений

Новая версия 8.0.

Утилиты

click.echo(message=None, file=None, nl=True, err=False, color=None)

Выводит сообщение и перевод строки в стандартный вывод или файл. Его следует использовать вместо print(), так как он обеспечивает лучшую поддержку различных данных, файлов и сред.

По сравнению с print(), это делает следующее:

Обеспечивает, что кодировка вывода не неправильно настроена в Linux.
Поддерживает Unicode в консоли Windows.
Поддерживает запись в двоичные выходы и поддержку записи байтов в текстовые выходы.
Поддерживает цвета и стили в Windows.
Удаляет ANSI-коды цвета и стиля, если вывод не похож на интерактивную оболочку.
Всегда сбрасывает вывод.

Параметры:

сообщение (Any | None) – Строка или байты для вывода. Другие объекты преобразуются в строки.
файл (IO[Any] | None) – Файл для записи. По умолчанию stdout.
err (bool) – Записать в stderr вместо stdout.
nl (bool) – Вывести перевод строки после сообщения. Включено по умолчанию.
цвет (bool | None) – Принудительно отображать или скрывать цвета и другие стили. По умолчанию Click удаляет цвет, если вывод не похож на интерактивную оболочку.

Тип возвращаемого значения:

None

Журнал изменений

Изменено в версии 6.0: Поддержка вывода Unicode в консоли Windows. Click не изменяет sys.stdout, поэтому sys.stdout.write() и print() по-прежнему не будут поддерживать Unicode.

Изменено в версии 4.0: Добавлен параметр color.

Новая версия 3.0: Добавлен параметр err.

Изменено в версии 2.0: Поддержка цветов в Windows, если установлен colorama.

click.echo_via_pager(text_or_generator, color=None)

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

Журнал изменений

Изменено в версии 3.0: Добавлен флаг color.

Параметры:

текст_или_генератор (Iterable[str] | Callable[[], Iterable[str]] | str) – Текст для страницы или, альтернативно, генератор, который выводит текст на страницу.
цвет (bool | None) – управляет тем, поддерживает ли страница ANSI-цвета или нет. По умолчанию используется автоматическое определение.

Тип возвращаемого значения:

None

click.prompt(text, default=None, hide_input=False, confirmation_prompt=False, type=None, value_proc=None, prompt_suffix=': ', show_default=True, err=False, show_choices=True)

Запрашивает ввод пользователя. Это удобная функция, которую можно использовать для запроса ввода пользователя позже.

Если пользователь прерывает ввод, отправив сигнал прерывания, эта функция перехватит его и вызовет исключение Abort.

Параметры:

текст (str) – текст для отображения запроса.
значение_по_умолчанию (Any | None) – значение по умолчанию для использования, если ввод не происходит. Если это не указано, программа будет запрашивать ввод до его прерывания.
скрыть_ввод (bool) – если установлено в true, значение ввода будет скрыто.
запрос_подтверждения (bool | str) – Запросить повторный ввод для подтверждения значения. Может быть установлено в строку вместо True для настройки сообщения.
тип (ParamType | Any | None) – тип для проверки значения.
обработчик_значения (Callable[[str], Any] | None) – если этот параметр указан, это функция, которая вызывается вместо преобразования типа для преобразования значения.
постфикс_запроса (str) – постфикс, который должен быть добавлен к запросу.
показывать_значение_по_умолчанию (bool) – отображает или скрывает значение по умолчанию в запросе.
err (bool) – если установлено в true, файл по умолчанию перенаправляется в stderr вместо stdout, как и при использовании echo.
показывать_выбор (bool) – Отображать или скрывать варианты, если тип, который был передан, является Choice. Например, если тип - это Choice "день" или "неделя", show_choices - true и текст - "Сгруппировать по", то запрос будет "Сгруппировать по (день, неделя):".

Тип возвращаемого значения:

Any

Журнал изменений

Новая версия 8.0: confirmation_prompt может быть настраиваемой строкой.

Новая версия 7.0: Добавлен параметр show_choices.

Новая версия 6.0: Добавлена поддержка Unicode для cmd.exe в Windows.

Новая версия 4.0: Добавлен параметр err.

click.confirm(text, default=False, abort=False, prompt_suffix=': ', show_default=True, err=False)

Запрашивает подтверждение (вопрос да/нет).

Если пользователь прерывает ввод, отправляя сигнал прерывания, эта функция перехватит его и вызовет исключение Abort.

Параметры:

text (str) – вопрос, который нужно задать.
default (bool | None) – Значение по умолчанию, которое будет использоваться, если ввод не задан. Если None, повторно запрашивает ввод, пока не будет введен ответ.
abort (bool) – если установлено в True, отрицательный ответ прерывает выполнение, вызывая исключение Abort.
prompt_suffix (str) – суффикс, который нужно добавить к запросу.
show_default (bool) – отображает или скрывает значение по умолчанию в запросе.
err (bool) – если установлено в true, файл по умолчанию использует stderr вместо stdout, аналогично с параметром echo.

Тип возвращаемого значения:

bool

Изменения

Изменено в версии 8.0: Повторно запрашивает ввод, пока не будет введен ответ, если default установлено в None.

Добавлена в версии 4.0: Добавлен параметр err.

click.progressbar(iterable=None, length=None, label=None, show_eta=True, show_percent=None, show_pos=False, item_show_func=None, fill_char='#', empty_char='-', bar_template='%(label)s [%(bar)s] %(info)s', info_sep=' ', width=36, file=None, color=None, update_min_steps=1)

Эта функция создаёт итерируемый контекстный менеджер, который можно использовать для итерирования по чему-либо, отображая полосу прогресса. Он будет итерироваться по iterable или length элементам (которые подсчитываются). Во время итерирования эта функция будет выводить отрисованную полосу прогресса в указанный file (по умолчанию стандартный вывод) и попытается рассчитать оставшееся время и многое другое. По умолчанию эта полоса прогресса не будет отрисована, если файл не является терминалом.

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

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

Не должно быть никакого вывода, иначе полоса прогресса будет непреднамеренно уничтожена.

Пример использования:

with progressbar(items) as bar:
    for item in bar:
        do_something_with(item)

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

with progressbar(length=chunks.total_bytes) as bar:
    for chunk in chunks:
        process_chunk(chunk)
        bar.update(chunks.bytes)

Метод update() также принимает необязательное значение, определяющее current_item в новой позиции. Это полезно при использовании вместе с item_show_func для настройки вывода на каждый ручной шаг:

with click.progressbar(
    length=total_size,
    label='Unzipping archive',
    item_show_func=lambda a: a.filename
) as bar:
    for archive in zip_file:
        archive.extract()
        bar.update(archive.size, archive)

Параметры:

iterable (Iterable[V] | None) – итерируемый объект. Если не указан, требуется длина.
length (int | None) – количество элементов для итерирования. По умолчанию полоса прогресса попытается узнать длину итерируемого объекта, что может или не может сработать. Если итерируемый объект также указан, этот параметр можно использовать для переопределения длины. Если итерируемый объект не указан, полоса прогресса будет итерироваться по диапазону заданной длины.
label (str | None) – метка, отображаемая рядом с полосой прогресса.
show_eta (bool) – включает или отключает отображение оценочного времени. Автоматически отключается, если длина не может быть определена.
show_percent (bool | None) – включает или отключает отображение процента. По умолчанию True если итерируемый объект имеет длину или False если нет.
show_pos (bool) – включает или отключает отображение абсолютной позиции. По умолчанию False.
item_show_func (Callable[[V | None], str | None] | None) – Функция, вызываемая с текущим элементом, которая может вернуть строку для отображения рядом с полосой прогресса. Если функция возвращает None, ничего не отображается. Текущий элемент может быть None, например, при входе и выходе из полосы.
fill_char (str) – символ для отображения заполненной части полосы прогресса.
empty_char (str) – символ для отображения незаполненной части полосы прогресса.
bar_template (str) – строка форматирования, используемая в качестве шаблона для полосы. Параметрами в ней являются label для метки, bar для полосы прогресса и info для секции информации.
info_sep (str) – разделитель между несколькими элементами информации (eta и т.д.).
width (int) – ширина полосы прогресса в символах, 0 означает полную ширину терминала.
file (TextIO | None) – файл для записи. Если это не терминал, печатается только метка.
color (bool | None) – управляет тем, поддерживает ли терминал ANSI-цвета или нет. По умолчанию автоматическое определение. Это необходимо только если ANSI-коды включены где-либо в выводе полосы прогресса, что по умолчанию не так.
update_min_steps (int) – Отображать только тогда, когда завершено заданное количество обновлений. Это позволяет настроить для очень быстрых итераторов.

Тип возвращаемого значения:

ProgressBar[V]

Изменения

Изменено в версии 8.0: Вывод отображается, даже если время выполнения меньше 0,5 секунды.

Изменено в версии 8.0: item_show_func показывает текущий элемент, а не предыдущий.

Изменено в версии 8.0: Метки дублируются, если вывод не является TTY. Возвращает изменения, внесенные в 7.0, которые удалили весь вывод.

Добавлена в версии 8.0: Добавлен параметр update_min_steps.

Изменено в версии 4.0: Добавлен параметр color. Добавлен метод update к объекту.

Новая в версии 2.0.

click.clear()

Очищает экран терминала. Это приведет к очистке всего видимого пространства терминала и перемещению курсора в верхний левый угол. Ничего не делает, если не подключён к терминалу.

Изменения

Новая в версии 2.0.

Тип возвращаемого значения:: None

END_OF_DOCUMENT_MARKER

click.style(text, fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, reset=True)

Стилезует текст с помощью ANSI-стилей и возвращает новую строку. По умолчанию стилизация является самодостаточной, что означает, что в конце строки выводится код сброса. Это можно предотвратить, передав reset=False.

Примеры:

click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))

Поддерживаемые имена цветов:

black (возможно, серый)
red
green
yellow (возможно, оранжевый)
blue
magenta
cyan
white (возможно, светло-серый)
bright_black
bright_red
bright_green
bright_yellow
bright_blue
bright_magenta
bright_cyan
bright_white
reset (сбросить только код цвета)

Если терминал его поддерживает, цвет также можно указать как:

Целое число в интервале [0, 255]. Терминал должен поддерживать 8-битный/256-цветной режим.
Кортеж RGB из трёх целых чисел в [0, 255]. Терминал должен поддерживать 24-битный/полноцветный режим.

См. https://en.wikipedia.org/wiki/ANSI_color и https://gist.github.com/XVilka/8346728 для получения дополнительной информации.

Параметры:

text (Любой тип) – строка, которую нужно стилизовать с помощью кодов ANSI.
fg (int | Кортеж[int, int, int] | строка | None) – если указано, это станет цветом переднего плана.
bg (int | Кортеж[int, int, int] | строка | None) – если указано, это станет цветом заднего плана.
… (и так далее)

Тип возвращаемого значения:

строка

Изменения

Изменено в версии 8.0: Нестроковый message преобразуется в строку.

Изменено в версии 8.0: Добавлена поддержка кодов цвета 256 и RGB.

Изменено в версии 8.0: Добавлены параметры strikethrough, italic, и overline.

Изменено в версии 7.0: Добавлена поддержка ярких цветов.

Добавлено в версии 2.0.

click.unstyle(text)

Удаляет информацию об ANSI-стилизации из строки. Обычно нет необходимости использовать эту функцию, так как функция echo Click автоматически удалит стилизацию при необходимости.

Изменения

Добавлено в версии 2.0.

Параметры:: text (строка) – текст, из которого нужно удалить информацию о стиле.
Тип возвращаемого значения:: строка

click.secho(message=None, file=None, nl=True, err=False, color=None, **styles)

Эта функция объединяет echo() и style() в один вызов. Таким образом, следующие два вызова эквивалентны:

click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))

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

Типы, не являющиеся строками, будут преобразованы в str. Однако, bytes передаются непосредственно в echo() без применения стиля. Если вы хотите стилизовать байты, представляющие текст, сначала вызовите bytes.decode().

Изменения

Изменено в версии 8.0: Нестроковый message преобразуется в строку. Байты передаются без применения стиля.

Добавлено в версии 2.0.

Параметры:

message (Любой тип | None) –
… (и так далее)

Тип возвращаемого значения:

None

click.edit(text=None, editor=None, env=None, require_save=True, extension='.txt', filename=None)

Редактирует заданный текст в определённом редакторе. Если указан редактор (должен быть полным путём к исполняемому файлу, но используется стандартный путь поиска операционной системы для нахождения исполняемого файла), он переопределяет обнаруженный редактор. Необязательно, можно использовать некоторые переменные окружения. Если редактор закрыт без изменений, None возвращается. В случае прямого редактирования файла значение возврата всегда None, и require_save и extension игнорируются.

Если редактор не может быть открыт, возникает UsageError.

Примечание для Windows: для упрощения кроссплатформенного использования новые строки автоматически преобразуются из POSIX в Windows и наоборот. Таким образом, в сообщении здесь будут \n в качестве разделителей строк.

Параметры:

text (AnyStr | None) – текст для редактирования.
editor (str | None) – необязательно, редактор для использования. По умолчанию используется автоматическое определение.
env (Mapping[str, str] | None) – переменные окружения, передаваемые редактору.
require_save (bool) – если это True, то отсутствие сохранения в редакторе приведёт к возвращаемому значению %%%CODE_BLOCK_175%%.
extension (str) – расширение, чтобы сообщить редактору. По умолчанию .txt, но изменение может повлиять на подсветку синтаксиса.
filename (str | None) – если указано, будет отредактирован этот файл вместо предоставленного содержимого текста. В этом случае временный файл не будет использоваться как косвенное обращение.

Тип возвращаемого значения:

AnyStr | None

click.launch(url, wait=False, locate=False)

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

Примеры:

click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)

Изменения

Введено в версии 2.0.

Параметры:

url (str) – URL или имя файла для запуска.
wait (bool) – Дожидаться завершения программы перед возвратом. Это работает только если запущенная программа блокируется. В частности, xdg-open в Linux не блокируется.
locate (bool) – если установлено в True, вместо запуска приложения, связанного с URL, будет попытка запуска файлового менеджера с указанным файлом. Это может иметь странные эффекты, если URL не указывает на файловую систему.

Тип возвращаемого значения:

int

click.getchar(echo=False)

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

Обратите внимание, что это всегда читает из терминала, даже если что-то передано в стандартный ввод.

Примечание для Windows: в редких случаях при вводе не-ASCII символов эта функция может подождать второго символа, а затем вернуть оба сразу. Это происходит потому, что некоторые символы Unicode похожи на маркеры специальных клавиш.

Изменения

Введено в версии 2.0.

Параметры:: echo (bool) – если установлено в True, прочитанный символ также будет отображаться в терминале. По умолчанию он не отображается.
Тип возвращаемого значения:: str

click.pause(info=None, err=False)

Эта команда останавливает выполнение и ждёт нажатия любой клавиши пользователем для продолжения. Это аналогично команде «pause» в командных файлах Windows. Если программа не запускается через терминал, эта команда ничего не сделает.

Изменения

Введено в версии 4.0: Добавлен параметр err.

Введено в версии 2.0.

Параметры:

info (str | None) – Сообщение, которое вывести перед паузой. По умолчанию "Press any key to continue...".
err (bool) – если установлено в message идёт в stderr вместо stdout, также как и с echo.

Тип возвращаемого значения:

None

click.get_binary_stream(name)

Возвращает системный поток для обработки байтов.

Параметры:: name (te.Literal['stdin', 'stdout', 'stderr']) – имя потока для открытия. Допустимые имена — 'stdin', 'stdout' и 'stderr'
Тип возвращаемого значения:: BinaryIO

click.get_text_stream(name, encoding=None, errors='strict')

Возвращает системный поток для обработки текста. Обычно возвращает обернутый поток над бинарным потоком, возвращённым из get_binary_stream(), но также может использовать сокращения для уже корректно настроенных потоков.

Параметры:

name (te.Literal['stdin', 'stdout', 'stderr']) – имя потока для открытия. Допустимые имена — 'stdin', 'stdout' и 'stderr'
encoding (str | None) – переопределяет обнаруженную кодировку по умолчанию.
errors (str | None) – переопределяет режим обработки ошибок по умолчанию.

Тип возвращаемого значения:

TextIO

click.open_file(filename, mode='r', encoding=None, errors='strict', lazy=False, atomic=False)

Открыть файл с дополнительным поведением для обработки '-' для указания стандартного потока, леничного открытия при записи и атомарной записи. Аналогично поведению параметра File.

Если '-' используется для открытия stdout или stdin, поток обернётся, чтобы его использование в контекстном менеджере не закрывало его. Это позволяет использовать функцию без случайного закрытия стандартного потока:

with open_file(filename) as f:
    ...

Параметры:

filename (str | PathLike[str]) – Имя или путь к файлу для открытия, или '-' для stdin/stdout.
mode (str) – Режим открытия файла.
encoding (str | None) – Кодировка для декодирования или кодирования файла, открытого в текстовом режиме.
errors (str | None) – Режим обработки ошибок.
lazy (bool) – Отложить открытие файла до его использования. Для режима чтения файл временно открывается для поднятия ошибок доступа, затем закрывается до повторного чтения.
atomic (bool) – Запись в временный файл и замена исходного файла при закрытии.

Тип возвращаемого значения:

IO[Any]

Изменения

Новое в версии 3.0.

click.get_app_dir(app_name, roaming=True, force_posix=False)

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

Например, для приложения "Foo Bar", могут быть возвращены следующие папки:

Mac OS X:: ~/Library/Application Support/Foo Bar
Mac OS X (POSIX):: ~/.foo-bar
Unix:: ~/.config/foo-bar
Unix (POSIX):: ~/.foo-bar
Windows (роуминг):: C:\Users\<user>\AppData\Roaming\Foo Bar
Windows (не роуминг):: C:\Users\<user>\AppData\Local\Foo Bar

Изменения

Новое в версии 2.0.

Параметры:

app_name (str) – имя приложения. Должно быть должным образом прописным и может содержать пробелы.
roaming (bool) – определяет, должна ли папка быть роуминговой на Windows. Не имеет эффекта в других системах.
force_posix (bool) – если это установлено в True, то в любой POSIX-системе папка будет храниться в домашней папке с ведущей точкой вместо XDG config home или darwin’s application support folder.

Тип возвращаемого значения:

str

click.format_filename(filename, shorten=False)

Форматирует имя файла как строку для отображения. Гарантирует возможность отображения имени файла, заменяя любые недопустимые байты или суррогатные экраны в имени на символ замены �.

Недопустимые байты или суррогатные экраны вызовут ошибку при записи в поток с errors="strict". Это обычно происходит с stdout, когда локаль, например, en_GB.UTF-8.

Однако многие сценарии безопасны для записи суррогатов благодаря PEP 538 и PEP 540, включая:

Запись в stderr, использующую errors="backslashreplace".
Система имеет LANG=C.UTF-8, C, или POSIX. Python открывает stdout и stderr с errors="surrogateescape".
Никто из LANG/LC_* не установлен. Python предполагает LANG=C.UTF-8.
Python запускается в режиме UTF-8 с PYTHONUTF8=1 или -X utf8. Python открывает stdout и stderr с errors="surrogateescape".

Параметры:

filename (str | bytes | PathLike[str] | PathLike[bytes]) – Форматирует имя файла для отображения в пользовательском интерфейсе. Также преобразует имя файла в строку Unicode без ошибок.
shorten (bool) – необязательно, укорачивает имя файла, удаляя предшествующий путь.

Тип возвращаемого значения:

str

Команды

class click.BaseCommand(name, context_settings=None)

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

Например, она может использоваться для связи Click с другими системами, такими как argparse или docopt.

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

Журнал изменений

Изменено в версии 2.0: Добавлен параметр context_settings.

Параметры:

name (str | None) – имя команды для использования, если группа не переопределяет его.
context_settings (MutableMapping[str, Any] | None) – необязательный словарь с значениями по умолчанию, передаваемыми объекту контекста.

context_class: псевдоним Context

allow_extra_args = False: значение по умолчанию для флага Context.allow_extra_args.

allow_interspersed_args = True: значение по умолчанию для флага Context.allow_interspersed_args.

ignore_unknown_options = False: значение по умолчанию для флага Context.ignore_unknown_options.

name: имя, которое считает команда. При регистрации команды в Group группа установит имя команды по умолчанию с этой информацией. Вместо этого следует использовать атрибут Context info_name.

context_settings: MutableMapping[str, Any]: необязательный словарь с значениями по умолчанию, передаваемый в контекст.

to_info_dict(ctx)

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

Используйте click.Context.to_info_dict() для обхода всей структуры CLI.

Параметры:: ctx (Контекст) – Context, представляющий эту команду.
Тип возвращаемого значения:: Словарь[строка, любой]

Журнал изменений

Добавлено в версии 8.0.

make_context(info_name, args, parent=None, **extra)

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

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

Параметры:

info_name (строка | None) – имя информации для данного вызова. Как правило, это наиболее описательное имя для скрипта или команды. Для скрипта верхнего уровня, как правило, это имя скрипта; для команд ниже это имя команды.
args (список[строка]) – аргументы для парсинга в виде списка строк.
parent (Контекст | None) – родительский контекст, если доступен.
extra (любой) – дополнительные ключевые аргументы, передаваемые конструктору контекста.

Тип возвращаемого значения:

Контекст

Журнал изменений

Изменено в версии 8.0: Добавлен атрибут context_class.

parse_args(ctx, args)

Принимая контекст и список аргументов, это создаёт парсер и анализирует аргументы, а затем изменяет контекст по мере необходимости. Это автоматически вызывается make_context().

Параметры:

ctx (Контекст) –
args (список[строка]) –

Тип возвращаемого значения:

список[строка]

invoke(ctx)

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

Параметры:: ctx (Контекст) –
Тип возвращаемого значения:: любой

shell_complete(ctx, incomplete)

Возвращает список дополнений для неполного значения. Рассматривает имена связанных многокоманд.

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

Параметры:

ctx (Контекст) – контекст вызова для этой команды.
incomplete (строка) – значение, которое завершается. Может быть пустым.

Тип возвращаемого значения:

список[Элемент завершения]

Журнал изменений

Добавлено в версии 8.0.

main(args: Sequence[str] | None = None, prog_name: str | None = None, complete_var: str | None = None, standalone_mode: te.Literal[True] = True, **extra: Any) → te.NoReturn

main(args:Sequence[str]|None=None, prog_name:str|None=None, complete_var:str|None=None, standalone_mode:bool=True, **extra:Any) → Any

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

Этот метод также доступен, вызывая экземпляр Command напрямую.

Параметры:

args – аргументы, которые должны быть использованы для разбора. Если не предоставлены, используется sys.argv[1:].
prog_name – имя программы, которое должно быть использовано. По умолчанию имя программы строится, взяв имя файла из sys.argv[0].
complete_var – переменная среды, которая управляет поддержкой завершения ввода bash. По умолчанию это "_<prog_name>_COMPLETE" с prog_name в верхнем регистре.
standalone_mode – поведение по умолчанию — вызов скрипта в автономном режиме. Click затем обработает исключения и преобразует их в сообщения об ошибках, и функция никогда не вернётся, но завершит интерпретатор. Если это значение установлено в False, они будут переданы вызывающей стороне, и возвращаемое значение этой функции — возвращаемое значение invoke().
windows_expand_args – Расширять шаблоны glob, пользовательский каталог и переменные среды в аргументах командной строки в Windows.
extra – дополнительные ключевые аргументы передаются конструктору контекста. Дополнительную информацию см. в Context.

Changelog

Изменено в версии 8.0.1: Добавлен параметр windows_expand_args для отключения расширения аргументов командной строки в Windows.

Изменено в версии 8.0: При получении аргументов из sys.argv в Windows шаблоны glob, пользовательский каталог и переменные среды расширяются.

Изменено в версии 3.0: Добавлен параметр standalone_mode.

class click.Command(name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, no_args_is_help=False, hidden=False, deprecated=False)

Команды являются основным строительным блоком командных интерфейсов в Click. Базовая команда обрабатывает разбор командной строки и может перенаправлять дополнительный разбор командам, вложенным ниже.

Параметры:

name (str | None) – имя команды для использования, если группа не переопределяет его.
context_settings (MutableMapping[str, Any]) – необязательный словарь с параметрами по умолчанию, которые передаются объекту контекста.
callback (Callable[[...], Any] | None) – вызываемая функция. Это необязательно.
params (List[Parameter] | None) – параметры для регистрации с этой командой. Это могут быть объекты Option или Argument.
help (str | None) – строка справки для этой команды.
epilog (str | None) – как строка справки, но выводится в конце страницы справки после всего остального.
short_help (str | None) – короткая справка для этой команды. Она отображается в списке команд родительской команды.
add_help_option (bool) – по умолчанию каждая команда регистрирует опцию --help. Это можно отключить с помощью этого параметра.
no_args_is_help (bool) – управляет тем, что происходит, если не указаны аргументы. Этот параметр отключён по умолчанию. Если включён, он добавит --help как аргумент, если не переданы аргументы.
hidden (bool) – скрыть эту команду из вывода справки.
deprecated (bool) – выводит сообщение, указывающее, что команда устарела.
options_metavar (str | None) –

Изменено в версии 8.1: help, epilog, и short_help хранятся необработанными, вся форматирование выполняется при выводе текста справки, а не при инициализации, и выполняется даже если не используется декоратор @command.

Изменения

Изменено в версии 8.0: Добавлен repr для отображения имени команды.

Изменено в версии 7.1: Добавлен параметр no_args_is_help.

Изменено в версии 2.0: Добавлен параметр context_settings.

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

params: List[Parameter]: список параметров для этой команды в порядке их отображения на странице справки и выполнения. Параметры eager будут обрабатываться автоматически перед не-eager параметрами.

to_info_dict(ctx)

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

Используйте click.Context.to_info_dict() для обхода всей структуры CLI.

Параметры:: ctx (Context) – Context, представляющий эту команду.
Тип возвращаемого значения:: Dict[str, Any]

Изменения

Добавлена в версии 8.0.

get_usage(ctx)

Форматирует строку использования в строку и возвращает её.

Внутренне вызывает format_usage().

Параметры:: ctx (Context) –
Тип возвращаемого значения:: str

format_usage(ctx, formatter)

Записывает строку использования в форматировщик.

Этот метод низкого уровня вызывается get_usage().

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

collect_usage_pieces(ctx)

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

Параметры:: ctx (Context) –
Тип возвращаемого значения:: List[str]

get_help_option_names(ctx)

Возвращает имена опции справки.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: List[str]

get_help_option(ctx)

Возвращает объект опции справки.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: Option | None

make_parser(ctx)

Создаёт основной парсер опций для этой команды.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: OptionParser

END_OF_DOCUMENT_MARKER

get_help(ctx)

Форматирует справку в строку и возвращает её.

Внутренне вызывает format_help().

Параметры:: ctx (Context) –
Тип возвращаемого значения:: str

get_short_help_str(limit=45)

Получает краткую справку для команды или создаёт её, сокращая длинную строку справки.

Параметры:: limit (int) –
Тип возвращаемого значения:: str

format_help(ctx, formatter)

Записывает справку в форматировщик, если он существует.

Этот метод является низкоуровневым и вызывается методом get_help().

Вызывает следующие методы:

format_usage()
format_help_text()
format_options()
format_epilog()

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

format_help_text(ctx, formatter)

Записывает текст справки в форматировщик, если он существует.

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

format_options(ctx, formatter)

Записывает все опции в форматировщик, если они существуют.

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

format_epilog(ctx, formatter)

Записывает эпилог в форматировщик, если он существует.

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

parse_args(ctx, args)

Принимая контекст и список аргументов, создаёт парсер и анализирует аргументы, затем изменяет контекст по необходимости. Автоматически вызывается make_context().

Параметры:

ctx (Context) –
args (List[str]) –

Тип возвращаемого значения:

List[str]

invoke(ctx)

Принимая контекст, вызывает прикреплённый обработчик (если он существует) правильным способом.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: Any

shell_complete(ctx, incomplete)

Возвращает список дополнений для неполного значения. Рассматривает имена опций и цепочки многокоманд.

Параметры:

ctx (Context) – Контекст вызова для этой команды.
incomplete (str) – Дополняемое значение. Может быть пустым.

Тип возвращаемого значения:

List[CompletionItem]

Changelog

Новое в версии 8.0.

class click.MultiCommand(name=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **attrs)

Многокомандное исполнение — это базовая реализация команды, которая перенаправляет вызов подкомандам. Наиболее распространённым вариантом является Group.

Параметры:

invoke_without_command (bool) – управляет тем, как вызывается сама многокомандная структура. По умолчанию она вызывается только если указана подкоманда.
no_args_is_help (bool | None) – управляет тем, что происходит, если не указаны аргументы. Этот параметр включён по умолчанию, если invoke_without_command отключен, или выключен, если он включён. Если он включён, то будет добавлен аргумент --help если не переданы аргументы.
subcommand_metavar (str | None) – строка, используемая в документации для обозначения места подкоманды.
chain (bool) – если установлено в True, включено объединение нескольких подкоманд. Это ограничивает форму команд, так как они не могут иметь необязательные аргументы, но позволяет объединять несколько команд.
result_callback (Callable[[...], Any] | None) – обратный вызов результата для прикрепления к этой многокомандной структуре. Его можно установить или изменить позже с помощью декоратора result_callback().
attrs (Any) – Другие аргументы команды, описанные в Command.
name (str | None) –

allow_extra_args = True: Значение по умолчанию для флага Context.allow_extra_args.

allow_interspersed_args = False: Значение по умолчанию для флага Context.allow_interspersed_args.

to_info_dict(ctx)

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

Используйте click.Context.to_info_dict(), чтобы пройти по всей структуре командной строки.

Параметры:: ctx (Context) – Представление Context этой команды.
Тип возвращаемого значения:: Dict[str, Any]

Изменения

Введено в версии 8.0.

collect_usage_pieces(ctx)

Возвращает все части, которые входят в строку использования, и возвращает их в виде списка строк.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: List[str]

format_options(ctx, formatter)

Записывает все опции в форматировщик, если они существуют.

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

result_callback(replace=False)

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

Пример:

@click.group()
@click.option('-i', '--input', default=23)
def cli(input):
    return 42

@cli.result_callback()
def process_result(result, input):
    return result + input

Параметры:: replace (bool) – если установлено в True, уже существующий обратный вызов результата будет удалён.
Тип возвращаемого значения:: Callable[[F], F]

Изменения

Изменено в версии 8.0: Переименовано из resultcallback.

Введено в версии 3.0.

format_commands(ctx, formatter)

Дополнительные методы форматирования для многокомандных методов, которые добавляют все команды после опций.

Параметры:

ctx (Context) –
formatter (HelpFormatter) –

Тип возвращаемого значения:

None

parse_args(ctx, args)

На основе контекста и списка аргументов создаёт парсер и анализирует аргументы, затем изменяет контекст по мере необходимости. Это вызывается автоматически make_context().

Параметры:

ctx (Context) –
args (List[str]) –

Тип возвращаемого значения:

List[str]

invoke(ctx)

На основе контекста вызывается прикреплённый обратный вызов (если он существует) соответствующим образом.

Параметры:: ctx (Context) –
Тип возвращаемого значения:: Any

END_OF_DOCUMENT_MARKER

get_command(ctx, cmd_name)

По заданному контексту и имени команды возвращает объект Command, если он существует, или None.

Параметры:

ctx (Контекст) –
cmd_name (строка) –

Тип возвращаемого значения:

Команда | None

list_commands(ctx)

Возвращает список имён подкоманд в порядке их отображения.

Параметры:: ctx (Контекст) –
Тип возвращаемого значения:: Список[строка]

shell_complete(ctx, incomplete)

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

Параметры:

ctx (Контекст) – Контекст вызова этой команды.
incomplete (строка) – Завершаемое значение. Может быть пустым.

Тип возвращаемого значения:

Список[ЭлементЗавершения]

Изменения

Новое в версии 8.0.

class click.Group(name=None, commands=None, **attrs)

Группа позволяет команде иметь вложенные подкоманды. Это наиболее распространённый способ реализации вложенности в Click.

Параметры:

name (str | None) – Имя команды группы.
commands (MutableMapping[str, Command] | Sequence[Command] | None) – Словарь, сопоставляющий имена с объектами Command. Также может быть списком объектов Command, который будет использован для создания словаря с помощью Command.name.
attrs (Any) – Другие аргументы команды, описанные в MultiCommand, Command и BaseCommand.

Изменения

Изменено в версии 8.0: Аргумент commands может быть списком объектов команд.

command_class: Type[Command] | None = None: Если задано, используется декоратором command() группы в качестве стандартного класса Command. Это полезно, чтобы все подкоманды использовали пользовательский класс команды.

Изменения

Добавлен в версии 8.0.

group_class: Type[Group] | Type[type] | None = None

Если задано, используется декоратором group() группы в качестве стандартного класса Group. Это полезно, чтобы все подгруппы использовали пользовательский класс группы.

Если установлено специальное значение type (буквально group_class = type), класс этой группы будет использоваться в качестве стандартного класса. Это позволяет пользовательскому классу группы продолжать создавать пользовательские группы.

Изменения

Добавлен в версии 8.0.

commands: MutableMapping[str, Command]: Зарегистрированные подкоманды по их экспортированным именам.

add_command(cmd, name=None)

Регистрирует другую Command с этой группой. Если имя не задано, используется имя команды.

Параметры:

cmd (Command) –
name (str | None) –

Возвращаемое значение:

None

command(__func: Callable[[...], Any]) → Command

command(*args:Any, **kwargs:Any) → Callable[[Callable[[...],Any]],Command]

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

Для настройки класса команды установите атрибут command_class.

Изменено в версии 8.1: Этот декоратор может быть применён без скобок.

Изменения

Изменено в версии 8.0: Добавлен атрибут command_class.

group(__func: Callable[[...], Any]) → Group

group(*args:Any, **kwargs:Any) → Callable[[Callable[[...],Any]],Group]

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

Для настройки класса группы установите атрибут group_class.

Изменено в версии 8.1: Этот декоратор может быть применён без скобок.

Изменения

Изменено в версии 8.0: Добавлен атрибут group_class.

get_command(ctx, cmd_name)

Принимая контекст и имя команды, возвращает объект Command, если он существует, иначе возвращает None.

Параметры:

ctx (Context) –
cmd_name (str) –

Возвращаемое значение:

Command | None

list_commands(ctx)

Возвращает список имён подкоманд в порядке их отображения.

Параметры:: ctx (Контекст) –
Тип возвращаемого значения:: Список[строка]

class click.CommandCollection(name=None, sources=None, **attrs)

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

См. MultiCommand и Command для описания name и attrs.

Параметры:

name (строка | None) –
sources (Список[Многокомандный объект] | None) –
attrs (любой) –

sources: List[MultiCommand]: Список зарегистрированных многокомандных объектов.

add_source(multi_cmd)

Добавляет новый многокомандный объект в диспетчер цепочки.

Параметры:: multi_cmd (Многокомандный объект) –
Тип возвращаемого значения:: None

get_command(ctx, cmd_name)

Принимая контекст и имя команды, возвращает объект Command, если он существует, или возвращает None.

Параметры:

ctx (Контекст) –
cmd_name (строка) –

Тип возвращаемого значения:

Команда | None

list_commands(ctx)

Возвращает список имён подкоманд в порядке их отображения.

Параметры:: ctx (Контекст) –
Тип возвращаемого значения:: Список[строка]

Параметры

class click.Parameter(param_decls=None, type=None, required=False, default=None, callback=None, nargs=None, multiple=False, metavar=None, expose_value=True, is_eager=False, envvar=None, shell_complete=None)

Параметр команды представлен в двух вариантах: Option или Argument. Другие подклассы в настоящее время не поддерживаются по умолчанию, так как некоторые внутренние компоненты для парсинга преднамеренно не завершены.

Некоторые настройки поддерживаются как опциями, так и аргументами.

Параметры:

param_decls (Sequence[str] | None) – объявления параметров для этой опции или аргумента. Это список флагов или имён аргументов.
type (ParamType | Any | None) – тип, который должен быть использован. Либо ParamType, либо Python-тип. Последний автоматически преобразуется в первый, если это поддерживается.
required (bool) – указывает, является ли параметр обязательным.
default (Any | Callable[[], Any] | None) – значение по умолчанию, если параметр опущен. Также может быть вызываемой функцией, которая вызывается при необходимости значения по умолчанию без аргументов.
callback (Callable[[Контекст, Параметр, Any], Any] | None) – функция для дополнительной обработки или валидации значения после преобразования типа. Она вызывается как f(ctx, param, value) и должна вернуть значение. Вызывается для всех источников, включая запросы пользователя.
nargs (int | None) – количество аргументов для сопоставления. Если не 1, возвращаемое значение — кортеж, а не единственное значение. Значение по умолчанию для nargs — 1 (кроме случая, когда тип — кортеж, тогда это арность кортежа). Если nargs=-1, все оставшиеся параметры собираются.
metavar (str | None) – способ отображения значения на странице справки.
expose_value (bool) – если это True , то значение передаётся в обратный вызов команды и сохраняется в контексте, иначе игнорируется.
is_eager (bool) – значения с eager-обработкой обрабатываются до значений с non eager-обработкой. Это не должно устанавливаться для аргументов, или это изменит порядок обработки.
envvar (Sequence[str] | str | None) – строка или список строк, которые являются переменными окружения, которые должны быть проверены.
shell_complete (Callable[[Контекст, Параметр, str], Список[ЭлементЗавершения] | Список[str]] | None) – функция, которая возвращает пользовательские завершения оболочки. Используется вместо завершения типа параметра, если задано. Принимает ctx, param, incomplete и должна вернуть список CompletionItem или список строк.
multiple (bool) –

Изменения

Изменено в версии 8.0: process_value проверяет обязательные параметры и ограниченные nargs, и вызывает обратный вызов параметра перед возвратом значения. Это позволяет обратному вызову проверять запросы пользователя. full_process_value удалено.

Изменено в версии 8.0: autocompletion переименовано в shell_complete и имеет новые семантики, описанные выше. Старое имя устарело и будет удалено в 8.1, до тех пор пока не будет обернуто для соответствия новым требованиям.

Изменено в версии 8.0: Для multiple=True, nargs>1, значение по умолчанию должно быть списком кортежей.

Изменено в версии 8.0: Установка значения по умолчанию больше не требуется для nargs>1, оно будет равно None. multiple=True или nargs=-1 будут равны ().

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

Изменено в версии 2.0: Изменена подпись обратного вызова параметра, чтобы она также принимала параметр. Старый формат обратного вызова по-прежнему будет работать, но он будет выводить предупреждение, чтобы дать вам возможность легче перенести код.

to_info_dict()

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

Используйте click.Context.to_info_dict() для обхода всей структуры CLI.

Изменения

Добавлена в версии 8.0.

Тип возвращаемого значения:: Словарь[str, Any]

property human_readable_name: str: Возвращает имя параметра, понятное человеку. Это то же самое, что и имя для опций, но метапеременная для аргументов.

get_default(ctx: Context, call: te.Literal[True] = True) → Any | None

get_default(ctx:Context, call:bool=True) → Any|Callable[[],Any]|None

Получить значение по умолчанию для параметра. Сначала пытается получить значение с помощью Context.lookup_default(), затем использует локальное значение по умолчанию.

Параметры:

ctx – Текущий контекст.
call – Если значение по умолчанию является вызываемым объектом, вызвать его. Выключить для возврата вызываемого объекта вместо его результата.

Изменения

Изменено в версии 8.0.2: Преобразование типов больше не выполняется при получении значения по умолчанию.

Изменено в версии 8.0.1: Преобразование типов может завершиться ошибкой в режиме гибкого разбора. Некорректные значения по умолчанию не помешают отображению текста справки.

Изменено в версии 8.0: Сначала проверяет ctx.default_map.

Изменено в версии 8.0: Добавлен параметр call.

type_cast_value(ctx, value)

Преобразовать и валидировать значение по отношению к type, multiple, и nargs параметра.

Параметры:

ctx (Context) –
value (Any) –

Тип возвращаемого значения:

Any

get_error_hint(ctx)

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

Параметры:: ctx (Context) –
Тип возвращаемого значения:: str

shell_complete(ctx, incomplete)

Возвращает список завершений для незавершенного значения. Если функция shell_complete была задана во время инициализации, она используется. В противном случае используется функция type shell_complete().

Параметры:

ctx (Context) – Контекст вызова для этой команды.
incomplete (str) – Завершенное значение. Может быть пустым.

Тип возвращаемого значения:

List[CompletionItem]

Изменения

Добавлено в версии 8.0.

class click.Option(param_decls=None, show_default=None, prompt=False, confirmation_prompt=False, prompt_required=True, hide_input=False, is_flag=None, flag_value=None, multiple=False, count=False, allow_from_autoenv=True, type=None, help=None, hidden=False, show_choices=True, show_envvar=False, **attrs)

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

Все остальные параметры передаются конструктору параметра.

Параметры:

show_default (bool | str | None) – Показывать значение по умолчанию для этого параметра в тексте справки. Значения не отображаются по умолчанию, если Context.show_default не True. Если это значение является строкой, то в скобках отображается эта строка вместо фактического значения. Это особенно полезно для динамических параметров. Для одноэлементных логических флагов по умолчанию скрывается, если его значение False.
show_envvar (bool) – Управляет отображением переменной окружения на странице справки. Обычно переменные окружения не отображаются.
prompt (bool | str) – Если установлено в True или непустую строку, то пользователя попросят ввести данные. Если установлено в True, запрос будет именем параметра, написанным с большой буквы.
confirmation_prompt (bool | str) – Запрашивает повторное подтверждение значения, если оно было запрошено. Может быть установлено в строку вместо True для настройки сообщения.
prompt_required (bool) – Если установлено в False, пользователь будет запрошен для ввода только тогда, когда параметр указан как флаг без значения.
hide_input (bool) – Если это True, вход в запросе будет скрыт от пользователя. Это полезно для ввода паролей.
is_flag (bool | None) – принудительно делает этот параметр флагом. По умолчанию определяется автоматически.
flag_value (Any | None) – какое значение должно использоваться для этого флага, если он включен. Устанавливается в булево значение автоматически, если строка параметра содержит косую черту для обозначения двух параметров.
multiple (bool) – если это установлено в True, аргумент принимается несколько раз и записывается. Это похоже на nargs по своему действию, но поддерживает произвольное количество аргументов.
count (bool) – этот флаг заставляет параметр увеличивать целое число.
allow_from_autoenv (bool) – если это включено, значение этого параметра будет взято из переменной окружения в случае, если префикс определен в контексте.
help (str | None) – строка справки.
hidden (bool) – скрыть этот параметр от вывода справки.
attrs (Any) – Другие аргументы команд, описанные в Parameter.
param_decls (Sequence[str] | None) –
type (ParamType | Any | None) –
show_choices (bool) –

Изменено в версии 8.1.0: Отступы текста справки очищаются здесь вместо только в @option декораторе.

Изменено в версии 8.1.0: Параметр show_default переопределяет Context.show_default.

Изменено в версии 8.1.0: Значение по умолчанию для одноэлементного логического флага не отображается, если значение по умолчанию False.

Журнал изменений

Изменено в версии 8.0.1: type определяется из flag_value при предоставлении.

class click.Argument(param_decls, required=None, **attrs)

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

Все параметры передаются конструктору Parameter.

Параметры:

param_decls (Sequence[str]) –
required (bool | None) –
attrs (Any) –

Контекст

class click.Context(command, parent=None, info_name=None, obj=None, auto_envvar_prefix=None, default_map=None, terminal_width=None, max_content_width=None, resilient_parsing=False, allow_extra_args=None, allow_interspersed_args=None, ignore_unknown_options=None, help_option_names=None, token_normalize_func=None, color=None, show_default=None)

Контекст — это специальный внутренний объект, который хранит состояние, относящееся к выполнению скрипта на каждом уровне. Он обычно невидим для команд, если они не получат к нему доступ.

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

Контекст можно использовать как менеджер контекста, в этом случае он вызовет close() при завершении.

Параметры:

команда (Команда) — класс команды для этого контекста.
родитель (Контекст | None) — родительский контекст.
имя_информации (str | None) — имя информации для этого вызова. Обычно это наиболее описательное имя для скрипта или команды. Для скрипта верхнего уровня это обычно имя скрипта, для команд ниже — имя скрипта.
объект (Любой | None) — произвольный объект пользовательских данных.
префикс_автоматической_переменной_окружения (str | None) — префикс для использования в автоматических переменных окружения. Если это None , чтение из переменных окружения отключено. Это не влияет на вручную заданные переменные окружения, которые всегда считываются.
словарь_по_умолчанию (Изменяемое отображение[str, Любой] | None) — словарь (как объект) с значениями по умолчанию для параметров.
ширина_терминала (int | None) — ширина терминала. По умолчанию наследуется от родительского контекста. Если контекст не определяет ширину терминала, применяется автоматическое определение.
максимальная_ширина_содержимого (int | None) — максимальная ширина содержимого, отображаемого Click (в настоящее время это влияет только на страницы справки). По умолчанию составляет 80 символов, если не переопределено. Другими словами: даже если терминал больше, Click не будет форматировать вещи шире 80 символов по умолчанию. Кроме того, форматировщики могут добавить некоторое сопоставление по безопасности справа.
устойчивое_разбирание (bool) — если этот флаг включен, Click будет парсить без взаимодействия или вызова обратного вызова. Значения по умолчанию также будут игнорироваться. Это полезно для реализации таких функций, как поддержка автодополнения.
разрешить_дополнительные_аргументы (bool | None) — если это установлено в True, дополнительные аргументы в конце не будут вызывать ошибку и будут сохранены в контексте. По умолчанию наследуется от команды.
разрешить_вмещающиеся_аргументы (bool | None) — если это установлено в False, опции и аргументы не могут быть смешаны. По умолчанию наследуется от команды.
игнорировать_неизвестные_опции (bool | None) — дает инструкции Click игнорировать опции, которые ему неизвестны, и сохранять их для дальнейшей обработки.
имена_опций_справки (Список[str] | None) — необязательно, список строк, определяющих, как называется параметр справки по умолчанию. По умолчанию ['--help'].
функция_нормализации_токен (Вызываемый[[str], str] | None) — необязательная функция, используемая для нормализации токенов (опции, варианты и т. д.). Это, например, может использоваться для реализации поведения, нечувствительного к регистру.
цвет (bool | None) — управляет тем, поддерживает ли терминал ANSI-цвета или нет. По умолчанию — автоматическое определение. Это необходимо только в том случае, если в текстах, которые печатает Click, используются ANSI-коды, что по умолчанию не так. Это, например, повлияет на вывод справки.
показать_значение_по_умолчанию (bool | None) — Показывать значение по умолчанию для команд. Если это значение не установлено, оно по умолчанию соответствует значению из родительского контекста. Command.show_default переопределяет это значение по умолчанию для конкретной команды.

Изменено в версии 8.1: Параметр show_default переопределяется Command.show_default, а не наоборот.

Журнал изменений

Изменено в версии 8.0: Параметр show_default по умолчанию принимает значение из родительского контекста.

Изменено в версии 7.1: Добавлен параметр show_default.

Изменено в версии 4.0: Добавлены параметры color, ignore_unknown_options, и max_content_width.

Изменено в версии 3.0: Добавлены параметры allow_extra_args и allow_interspersed_args.

Изменено в версии 2.0: Добавлены параметры resilient_parsing, help_option_names, и token_normalize_func.

formatter_class: псевдоним HelpFormatter

parent: родительский контекст или None если его нет.

command: команда Command для данного контекста.

info_name: описательное имя информации

params: Dict[str, Any]: Карта имён параметров и их обработанных значений. Параметры с expose_value=False не сохраняются.

args: List[str]: оставшиеся аргументы.

protected_args: List[str]: защищенные аргументы. Это аргументы, которые добавляются перед args в определенных сценариях парсинга, но никогда не передаются другим аргументам. Это используется для реализации вложенного парсинга.

obj: Any: сохранённый пользовательский объект.

invoked_subcommand: str | None

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

Если включена цепочка вызовов, это будет '*' в случае выполнения каких-либо команд. Однако определить, какие именно, невозможно. Если вам нужна эта информация, используйте result_callback().

terminal_width: int | None: Ширина терминала (None — автоматическое определение).

max_content_width: int | None: Максимальная ширина форматированного содержимого (None подразумевает разумное значение по умолчанию, которое составляет 80 для большинства случаев).

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

Журнал изменений

Новое в версии 3.0.

allow_interspersed_args: bool: Указывает, разрешает ли контекст смешивание аргументов и опций или нет.

Журнал изменений

Новое в версии 3.0.

END_OF_DOCUMENT_MARKER

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

Changelog

Добавлена в версии 4.0.

help_option_names: List[str]: Названия опций справки.

token_normalize_func: Callable[[str], str] | None: Необязательная функция нормализации токенов. Это опции, варианты, команды и т. д.

resilient_parsing: bool: Указывает, включена ли устойчивая обработка. В этом случае Click сделает все возможное, чтобы не возникло ошибок, и значения по умолчанию будут проигнорированы. Полезно для автодополнения.

color: bool | None: Управляет отображением стилизованного вывода.

show_default: bool | None: Показывать значения параметров по умолчанию при форматировании текста справки.

to_info_dict()

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

with Context(cli) as ctx:
    info = ctx.to_info_dict()

Changelog

Добавлена в версии 8.0.

Тип возвращаемого значения:: Dict[str, Any]

scope(cleanup=True)

Этот вспомогательный метод можно использовать с объектом контекста, чтобы повысить его до текущего локального объекта потока (см. get_current_context()). По умолчанию он вызывает функции очистки, которые можно отключить, установив cleanup в False. Функции очистки обычно используются для таких задач, как закрытие дескрипторов файлов.

Если очистка нужна, объект контекста также можно использовать как контекстный менеджер.

Пример использования:

with ctx.scope():
    assert get_current_context() is ctx

Это эквивалентно:

with ctx:
    assert get_current_context() is ctx

Changelog

Добавлена в версии 5.0.

Параметры:: cleanup (bool) – управляет тем, будут ли выполняться функции очистки. По умолчанию эти функции выполняются. В некоторых ситуациях контекст требуется только временно, в таком случае это можно отключить. Вложенные вставки автоматически откладывают очистку.
Тип возвращаемого значения:: Iterator[Context]

property meta: Dict[str, Any]

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

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

Пример использования:

LANG_KEY = f'{__name__}.lang'

def set_language(value):
    ctx = get_current_context()
    ctx.meta[LANG_KEY] = value

def get_language():
    return get_current_context().meta.get(LANG_KEY, 'en_US')

Changelog

Добавлена в версии 5.0.

make_formatter()

Создаёт HelpFormatter для вывода справки и использования.

Чтобы быстро настроить класс форматирования, без его переопределения, установите атрибут formatter_class.

Changelog

Изменено в версии 8.0: Добавлен атрибут formatter_class.

Тип возвращаемого значения:: HelpFormatter

with_resource(context_manager)

Регистрирует ресурс так, как будто он был использован в with инструкции. Ресурс будет очищен при выходе из контекста.

Использует contextlib.ExitStack.enter_context(). Вызывает метод __enter__() ресурса и возвращает результат. При выходе из контекста, закрывает стек, который вызывает метод __exit__() ресурса.

Для регистрации функции очистки для чего-то, что не является контекстным менеджером, используйте call_on_close(). Или используйте функцию из contextlib, чтобы сначала преобразовать это в контекстный менеджер.

@click.group()
@click.option("--name")
@click.pass_context
def cli(ctx):
    ctx.obj = ctx.with_resource(connect_db(name))

Параметры:: context_manager (ContextManager[V]) – Контекстный менеджер для входа.
Возвращаемое значение:: То, что возвращает context_manager.__enter__().
Тип возвращаемого значения:: V

Changelog

Добавлена в версии 8.0.

call_on_close(f)

Регистрирует функцию, которая будет вызвана при завершении работы контекста.

Это можно использовать для закрытия ресурсов, открытых во время выполнения скрипта. Ресурсы, которые поддерживают протокол контекстного менеджера Python, которые будут использоваться в with инструкции, должны быть зарегистрированы с помощью with_resource().

Параметры:: f (Callable[[...], Any]) – Функция для выполнения при завершении.
Тип возвращаемого значения:: Callable[[…], Any]

close()

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

Тип возвращаемого значения:: None

property command_path: str: Вычисленный путь к команде. Используется для информации usage на странице справки. Автоматически создаётся путём объединения имён информации цепочки контекстов до корня.

find_root()

Находит внешний контекст.

Тип возвращаемого значения:: Context

find_object(object_type)

Находит ближайший объект заданного типа.

Параметры:: object_type (Type[V]) –
Тип возвращаемого значения:: V | None

END_OF_DOCUMENT_MARKER

ensure_object(object_type)

Как find_object(), но устанавливает внутренний объект на новый экземпляр object_type если он не существует.

Параметры:: object_type (Type[V]) –
Тип возвращаемого значения:: V

lookup_default(name: str, call: te.Literal[True] = True) → Any | None

lookup_default(name:str, call:te.Literal[False]=True) → Any|Callable[[],Any]|None

Получение значения по умолчанию для параметра из default_map.

Параметры:

name – Название параметра.
call – Если значение по умолчанию — вызываемый объект, вызвать его. Отключить, чтобы вернуть вызываемый объект вместо его вызова.

Журнал изменений

Изменено в версии 8.0: Добавлен параметр call.

fail(message)

Прерывает выполнение программы со специфическим сообщением об ошибке.

Параметры:: message (str) – сообщение об ошибке для прерывания.
Тип возвращаемого значения:: te.NoReturn

abort()

Прерывает скрипт.

Тип возвращаемого значения:: te.NoReturn

exit(code=0)

Выходит из приложения с заданным кодом выхода.

Параметры:: code (int) –
Тип возвращаемого значения:: te.NoReturn

get_usage()

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

Тип возвращаемого значения:: str

get_help()

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

Тип возвращаемого значения:: str

invoke(__callback: Callable[[...], V], *args: Any, **kwargs: Any) → V

invoke(__callback:Command, *args:Any, **kwargs:Any) → Any

Вызывает обратный вызов команды точно так же, как он ожидает. Есть два способа вызвать этот метод:

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

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

Журнал изменений

Изменено в версии 8.0: Все kwargs отслеживаются в params, поэтому они будут переданы, если forward() вызывается на нескольких уровнях.

forward(_Context__cmd, *args, **kwargs)

Аналогично invoke(), но заполняет значения по умолчанию для ключевых аргументов из текущего контекста, если другая команда этого требует. Это не может вызывать обратные вызовы напрямую, только другие команды.

Журнал изменений

Изменено в версии 8.0: Все kwargs отслеживаются в params, поэтому они будут переданы, если forward вызывается на нескольких уровнях.

Параметры:

_Context__cmd (Command) –
args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

Any

set_parameter_source(name, source)

Установить источник параметра. Это указывает на местоположение, откуда было получено значение параметра.

Параметры:

name (str) – Название параметра.
source (ParameterSource) – Член ParameterSource.

Тип возвращаемого значения:

None

END_OF_DOCUMENT_MARKER

get_parameter_source(name)

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

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

Параметры:: name (str) – Имя параметра.
Тип возвращаемого значения:: ParameterSource

Журнал изменений

Изменено в версии 8.0: Возвращает None если параметр не был получен из любого источника.

click.get_current_context(silent: te.Literal[False] = False) → Context

click.get_current_context(silent:bool=False) → t.Optional['Context']

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

Для помещения текущего контекста можно использовать Context.scope().

Журнал изменений

Введено в версии 5.0.

Параметры:: silent – если установлено в True возвращаемое значение None если контекст недоступен. По умолчанию возникает исключение RuntimeError.

class click.core.ParameterSource(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Это Enum перечисляющее, которое указывает источник значения параметра.

Используйте click.Context.get_parameter_source() для получения источника параметра по имени.

Журнал изменений

Изменено в версии 8.0: Используйте Enum и удалите метод validate.

Изменено в версии 8.0: Добавлен значение PROMPT.

COMMANDLINE = 1: Значение было предоставлено аргументами командной строки.

ENVIRONMENT = 2: Значение было предоставлено переменной среды.

DEFAULT = 3: Использовано значение по умолчанию, указанное для параметра.

DEFAULT_MAP = 4: Использовано значение по умолчанию, предоставленное Context.default_map.

PROMPT = 5: Использовано подсказку для подтверждения значения по умолчанию или для ввода значения.

END_OF_DOCUMENT_MARKER

Типы

click.STRING = STRING

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

click.INT = INT

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

click.FLOAT = FLOAT

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

click.BOOL = BOOL

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

click.UUID = UUID

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

click.UNPROCESSED = UNPROCESSED

Параметры:

value (Any) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

Any

class click.File(mode='r', encoding=None, errors='strict', lazy=None, atomic=False)

Определяет параметр как файл для чтения или записи. Файл автоматически закрывается после завершения контекста (после завершения работы команды).

Файлы можно открывать для чтения или записи. Специальное значение - указывает на stdin или stdout в зависимости от режима.

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

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

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

См. Аргументы файла для получения дополнительной информации.

Параметры:

mode (str) –
encoding (str | None) –
errors (str | None) –
lazy (bool | None) –
atomic (bool) –

class click.Path(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None, executable=False)

Тип Path похож на тип File, но возвращает имя файла вместо открытого файла. Можно включить различные проверки для валидации типа файла и разрешений.

Параметры:

exists (bool) – Файл или директория должны существовать для валидности значения. Если это не установлено в True, и файла не существует, все последующие проверки пропускаются без предупреждений.
file_okay (bool) – Разрешить файл в качестве значения.
dir_okay (bool) – Разрешить директорию в качестве значения.
readable (bool) – если true, выполняется проверка на читаемость.
writable (bool) – если true, выполняется проверка на возможность записи.
executable (bool) – если true, выполняется проверка на возможность выполнения.
resolve_path (bool) – Сделать значение абсолютным и разрешить все символические ссылки. ~ не расширяется, так как это должно выполняться только оболочкой.
allow_dash (bool) – Разрешить одиночный символ тире в качестве значения, что указывает на стандартный поток (но не открывает его). Используйте open_file() для обработки открытия этого значения.
path_type (Type[Any] | None) – Преобразуйте входное значение пути к этому типу. Если None, используйте стандартное поведение Python, которое равно str. Полезно для преобразования в pathlib.Path.

Изменено в версии 8.1: Добавлен параметр executable.

Изменения

Изменено в версии 8.0: Разрешено передавать path_type=pathlib.Path.

Изменено в версии 6.0: Добавлен параметр allow_dash.

class click.Choice(choices, case_sensitive=True)

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

Вы должны передавать только список или кортеж вариантов. Другие итерируемые объекты (например, генераторы) могут привести к неожиданным результатам.

Результирующее значение всегда будет одним из исходно переданных вариантов, независимо от case_sensitive или любых ctx.token_normalize_func.

Пример см. в Параметры выбора.

Параметры:

case_sensitive (bool) – Установите в false, чтобы сделать выбор нечувствительным к регистру. По умолчанию true.
choices (Sequence[str]) –

class click.IntRange(min=None, max=None, min_open=False, max_open=False, clamp=False)

Ограничьте значение click.INT диапазоном допустимых значений. См. Параметры диапазона.

Если min или max не переданы, любое значение принимается в этом направлении. Если min_open или max_open включены, соответствующая граница не включена в диапазон.

Если clamp включен, значение за пределами диапазона обрезается до границы вместо ошибки.

Изменения

Изменено в версии 8.0: Добавлены параметры min_open и max_open.

Параметры:

min (float | None) –
max (float | None) –
min_open (bool) –
max_open (bool) –
clamp (bool) –

class click.FloatRange(min=None, max=None, min_open=False, max_open=False, clamp=False)

Ограничьте значение click.FLOAT диапазоном допустимых значений. См. Параметры диапазона.

Если clamp включен, значение за пределами диапазона обрезается до границы вместо ошибки. Это не поддерживается, если какая-либо граница помечена open.

Изменения

Изменено в версии 8.0: Добавлены параметры min_open и max_open.

Параметры:

min (float | None) –
max (float | None) –
min_open (bool) –
max_open (bool) –
clamp (bool) –

class click.DateTime(formats=None)

Тип DateTime преобразует строковые даты в объекты datetime.

Проверяемые форматы строк настраиваются, но по умолчанию используют некоторые распространённые (не учитывающие часовые пояса) форматы ISO 8601.

При указании форматов DateTime вы должны передавать только список или кортеж. Другие итерируемые объекты, такие как генераторы, могут привести к неожиданным результатам.

Строки формата обрабатываются с помощью datetime.strptime, и это определяет разрешённые строки формата.

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

Параметры:: formats (Sequence[str] | None) – Список или кортеж строк формата даты, в порядке их проверки. По умолчанию '%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S'.

class click.Tuple(types)

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

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

Это можно выбрать, используя литерал кортежа Python в качестве типа.

Параметры:: types (Sequence[Type[Any] | ParamType]) – список типов, которые должны использоваться для элементов кортежа.

class click.ParamType

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

Для реализации пользовательского типа, необходимо создать подкласс и реализовать по меньшей мере следующее:

Атрибут класса name должен быть установлен.
Вызов экземпляра типа с None должен возвращать None. Это уже реализовано по умолчанию.
convert() должен преобразовывать строковые значения в правильный тип.
convert() должен принимать значения, которые уже являются правильного типа.
Он должен уметь преобразовывать значение, если аргументы ctx и param являются None. Это может произойти при преобразовании входных данных запроса.

name: str: описательное имя этого типа

envvar_list_splitter: ClassVar[str | None] = None: Если ожидается список этого типа, а значение взято из переменной окружения в виде строки, это то, что разделяет его на части. None означает любой пробел. Для всех параметров общим правилом является то, что пробелы их разделяют. Исключение составляют пути и файлы, которые по умолчанию разделяются os.path.pathsep («:» в Unix и «;» в Windows).

to_info_dict()

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

Используйте click.Context.to_info_dict() для обхода всей структуры CLI.

Изменения

Добавлена в версии 8.0.

Тип возвращаемого значения:: Dict[str, Any]

get_metavar(param)

Возвращает значение metavar по умолчанию для этого параметра, если оно предоставляется.

Параметры:: param (Parameter) –
Тип возвращаемого значения:: str | None

get_missing_message(param)

При необходимости может возвращать дополнительную информацию об отсутствующем параметре.

Изменения

Добавлена в версии 2.0.

Параметры:: param (Parameter) –
Тип возвращаемого значения:: str | None

convert(value, param, ctx)

Преобразование значения в правильный тип. Это не вызывается, если значение является None (отсутствующее значение).

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

Аргументы param и ctx могут быть None в определенных ситуациях, например, при преобразовании входных данных запроса.

Если значение не может быть преобразовано, вызовите fail() с описательным сообщением.

Параметры:

value (Any) – значение для преобразования.
param (Parameter | None) – параметр, использующий этот тип для преобразования своего значения. Может быть None.
ctx (Context | None) – текущий контекст, который получил это значение. Может быть None.

Тип возвращаемого значения:

Any

split_envvar_value(rv)

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

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

Параметры:: rv (str) –
Тип возвращаемого значения:: Sequence[str]

fail(message, param=None, ctx=None)

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

Параметры:

message (str) –
param (Parameter | None) –
ctx (Context | None) –

Тип возвращаемого значения:

t.NoReturn

shell_complete(ctx, param, incomplete)

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

Параметры:

ctx (Context) – контекст вызова для этой команды.
param (Parameter) – параметр, запрашивающий завершение.
incomplete (str) – завершаемое значение. Может быть пустым.

Тип возвращаемого значения:

List[CompletionItem]

Изменения

Добавлена в версии 8.0.

Исключения

exception click.ClickException(message)

Исключение, которое Click может обработать и показать пользователю.

Параметры:: message (str) –
Тип возвращаемого значения:: None

exception click.Abort: Внутреннее исключение сигнализации, которое сигнализирует Click об отмене.

exception click.UsageError(message, ctx=None)

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

Параметры:

message (str) – сообщение об ошибке для отображения.
ctx (Контекст | None) – необязательно, контекст, который вызвал эту ошибку. Click автоматически заполняет контекст в некоторых ситуациях.

Тип возвращаемого значения:

None

exception click.BadParameter(message, ctx=None, param=None, param_hint=None)

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

Журнал изменений

Новая версия 2.0.

Параметры:

param (Параметр | None) – объект параметра, который вызвал эту ошибку. Его можно опустить, и Click при необходимости сам прикрепит эту информацию.
param_hint (str | None) – строка, отображающая имя параметра. Это можно использовать как альтернативу param в случаях, когда должна произойти пользовательская проверка. Если это строка, она используется как есть, если это список, каждый элемент заключается в кавычки и разделяется.
message (str) –
ctx (Контекст | None) –

Тип возвращаемого значения:

None

exception click.FileError(filename, hint=None)

Выбрасывается, если файл не может быть открыт.

Параметры:

filename (str) –
hint (str | None) –

Тип возвращаемого значения:

None

exception click.NoSuchOption(option_name, message=None, possibilities=None, ctx=None)

Выбрасывается, если Click попытался обработать опцию, которой не существует.

Журнал изменений

Новая версия 4.0.

Параметры:

option_name (str) –
message (str | None) –
possibilities (Sequence[str] | None) –
ctx (Контекст | None) –

Тип возвращаемого значения:

None

exception click.BadOptionUsage(option_name, message, ctx=None)

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

Журнал изменений

Новая версия 4.0.

Параметры:

option_name (str) – имя опции, используемой неправильно.
message (str) –
ctx (Контекст | None) –

Тип возвращаемого значения:

None

exception click.BadArgumentUsage(message, ctx=None)

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

Журнал изменений

Новая версия 6.0.

Параметры:

message (str) –
ctx (Контекст | None) –

Тип возвращаемого значения:

None

Форматирование

class click.HelpFormatter(indent_increment=2, width=None, max_width=None)

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

В настоящее время он всегда записывает данные в память.

Параметры:

indent_increment (int) – дополнительный приращение для каждого уровня.
width (int | None) – ширина текста. По умолчанию — ширина терминала, ограниченная максимумом в 78 символов.
max_width (int | None) –

write(string)

Записывает строку Unicode в внутренний буфер.

Параметры:: string (str) –
Тип возвращаемого значения:: None

indent()

Увеличивает отступ.

Тип возвращаемого значения:: None

dedent()

Уменьшает отступ.

Тип возвращаемого значения:: None

write_usage(prog, args='', prefix=None)

Записывает строку использования в буфер.

Параметры:

prog (str) – имя программы.
args (str) – список аргументов, разделенных пробелами.
prefix (str | None) – Префикс для первой строки. По умолчанию "Usage: ".

Тип возвращаемого значения:

None

write_heading(heading)

Записывает заголовок в буфер.

Параметры:: heading (str) –
Тип возвращаемого значения:: None

write_paragraph()

Записывает абзац в буфер.

Тип возвращаемого значения:: None

write_text(text)

Записывает переформатированный текст в буфер. Это переформатирует и сохраняет абзацы.

Параметры:: text (str) –
Тип возвращаемого значения:: None

write_dl(rows, col_max=30, col_spacing=2)

Записывает список определений в буфер. Обычно так форматируются опции и команды.

Параметры:

rows (Sequence[Tuple[str, str]]) – список кортежей из двух элементов для терминов и значений.
col_max (int) – максимальная ширина первого столбца.
col_spacing (int) – количество пробелов между первым и вторым столбцом.

Тип возвращаемого значения:

None

section(name)

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

Параметры:: name (str) – имя раздела, которое записывается как заголовок.
Тип возвращаемого значения:: Iterator[None]

indentation()

Менеджер контекста, увеличивающий отступ.

Тип возвращаемого значения:: Iterator[None]

getvalue()

Возвращает содержимое буфера.

Тип возвращаемого значения:: str

click.wrap_text(text, width=78, initial_indent='', subsequent_indent='', preserve_paragraphs=False)

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

Если обрабатываются абзацы, абзац может быть префиксрован пустой строкой, содержащей символ \b (\x08) для указания того, что переформатирование в этом блоке не должно происходить.

Параметры:

text (str) – текст, который должен быть переформатирован.
width (int) – максимальная ширина текста.
initial_indent (str) – начальный отступ, который должен быть помещен в первой строке в виде строки.
subsequent_indent (str) – строка отступа, которая должна быть помещена в каждой последующей строке.
preserve_paragraphs (bool) – если этот флаг установлен, переформатирование будет разумно обрабатывать абзацы.

Тип возвращаемого значения:

str

Обработка входных данных

class click.OptionParser(ctx=None)

Парсер опций — внутренний класс, предназначенный для обработки опций и аргументов. Он моделируется по образцу optparse и предлагает аналогичный, но значительно упрощённый API. Обычно его не следует использовать напрямую, так как высокоуровневые классы Click оборачивают его за вас.

Он не так расширяем, как optparse или argparse, так как не реализует функции, реализованные на более высоком уровне (например, типы или значения по умолчанию).

Параметры:: ctx (Контекст | None) — необязательно, Context, в котором должен работать этот парсер.

ctx: Контекст Context для этого парсера. Это может быть None в некоторых продвинутых случаях.

allow_interspersed_args: bool: Контролирует, как парсер обрабатывает вложенные аргументы. Если это значение установлено в False, парсер остановится на первом не являющемся опцией аргументе. Click использует это для безопасной реализации вложенных подкоманд.

ignore_unknown_options: bool: Указывает парсеру, как обрабатывать неизвестные опции. По умолчанию он генерирует ошибку (что разумно), но есть второй режим, в котором он игнорирует её и продолжает обработку после перемещения всех неизвестных опций в результирующие аргументы.

add_option(obj, opts, dest, action=None, nargs=1, const=None)

Добавляет новую опцию с именем dest в парсер. Назначение не выводится (в отличие от optparse) и должно быть явно указано. Действие может быть любым из store, store_const, append, append_const или count.

%%CODE_BLOCK_693%% может быть использовано для идентификации опции в списке порядка, возвращаемом парсером.

Параметры:

obj (CoreOption) —
opts (Последовательность[строка]) —
dest (строка | None) —
action (строка | None) —
nargs (целое число) —
const (любой тип | None) —

Тип возвращаемого значения:

None

add_argument(obj, dest, nargs=1)

Добавляет позиционный аргумент с именем dest в парсер.

%%CODE_BLOCK_696%% может быть использовано для идентификации опции в порядке списка, возвращаемом парсером.

Параметры:

obj (CoreArgument) —
dest (строка | None) —
nargs (целое число) —

Тип возвращаемого значения:

None

parse_args(args)

Обрабатывает позиционные аргументы и возвращает (values, args, order) для обработанных опций и аргументов, а также оставшиеся аргументы, если таковые имеются. Порядок — список объектов в том порядке, в котором они появляются в командной строке. Если аргументы появляются несколько раз, они также будут запоминаться несколько раз.

Параметры:: args (список[строка]) —
Тип возвращаемого значения:: кортеж[словарь[строка, любой тип], список[строка], список[CoreParameter]]

Автозаполнение оболочки

См. Автозаполнение оболочки для получения информации об активации и настройке системы автозаполнения оболочки Click.

class click.shell_completion.CompletionItem(value, type='plain', help=None, **kwargs)

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

При создании объекта можно передавать произвольные параметры, к которым можно получить доступ с помощью item.attr. Если атрибут не был передан, при обращении к нему будет возвращено None.

Параметры:

value (Any) – Предложение автозаполнения.
type (str) – Сообщает оболочке о предоставлении специальной поддержки автозаполнения для типа. Click использует "dir" и "file".
help (str | None) – Строка, отображаемая рядом со значением, если поддерживается.
kwargs (Any) – Произвольные метаданные. Встроенные реализации не используют это, но пользовательские автозаполнения типов, сопряженные с пользовательской поддержкой оболочки, могут использовать их.

class click.shell_completion.ShellComplete(cli, ctx_args, prog_name, complete_var)

Базовый класс для предоставления поддержки автозаполнения оболочки. Подкласс для заданной оболочки переопределит атрибуты и методы для реализации инструкций автозаполнения (source и complete).

Параметры:

cli (BaseCommand) – Вызываемая команда.
prog_name (str) – Имя исполняемого файла в оболочке.
complete_var (str) – Имя переменной среды, которая содержит инструкцию автозаполнения.
ctx_args (MutableMapping[str, Any]) –

Журнал изменений

Введено в версии 8.0.

name: ClassVar[str]: Имя для регистрации оболочки с помощью add_completion_class(). Оно используется в инструкциях автозаполнения ({name}_source и {name}_complete).

source_template: ClassVar[str]: Шаблон скрипта автозаполнения, отформатированный source(). Он должен быть предоставлен подклассами.

property func_name: str: Имя функции оболочки, определенной скриптом автозаполнения.

source_vars()

Переменные для форматирования source_template.

По умолчанию это предоставляет complete_func, complete_var, и prog_name.

Тип возвращаемого значения:: Dict[str, Any]

source()

Создайте скрипт оболочки, определяющий функцию автозаполнения. По умолчанию это использует форматирование %, чтобы отформатировать source_template со словарем, возвращаемым source_vars().

Тип возвращаемого значения:: str

get_completion_args()

Используйте переменные среды, определенные скриптом оболочки, для возвращения кортежа args, incomplete. Это должно быть реализовано подклассами.

Тип возвращаемого значения:: Tuple[List[str], str]

get_completions(args, incomplete)

Определите контекст и последнюю завершенную команду или параметр из аргументов завершения. Вызовите метод объекта shell_complete для получения завершений для незавершенного значения.

Параметры:

args (List[str]) – Список завершенных аргументов до незавершенного значения.
incomplete (str) – Завершаемое значение. Может быть пустым.

Тип возвращаемого значения:

List[CompletionItem]

format_completion(item)

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

Параметры:: item (CompletionItem) – Элемент автозаполнения для форматирования.
Тип возвращаемого значения:: str

complete()

Создайте данные автозаполнения, которые нужно отправить обратно в оболочку.

По умолчанию это вызывает get_completion_args(), получает автозаполнения, затем вызывает format_completion() для каждого автозаполнения.

Тип возвращаемого значения:: str

click.shell_completion.add_completion_class(cls, name=None)

Зарегистрируйте подкласс ShellComplete под заданным именем. Имя будет предоставлено переменной среды с инструкцией автозаполнения во время автозаполнения.

Параметры:

cls (ShellCompleteType) – Класс автозаполнения, который будет обрабатывать автозаполнение для оболочки.
name (str | None) – Имя для регистрации класса. По умолчанию используется атрибут name класса.

Тип возвращаемого значения:

ShellCompleteType

END_OF_DOCUMENT_MARKER

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

class click.testing.CliRunner(charset='utf-8', env=None, echo_stdin=False, mix_stderr=True)

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

Параметры:

charset (str) – кодировка символов для входных и выходных данных.
env (Mapping[str, str | None] | None) – словарь с переменными окружения для переопределения.
echo_stdin (bool) – если это установлено в True, то чтение из stdin записывается в stdout. Это полезно для демонстрации примеров в некоторых случаях. Обратите внимание, что обычные запросы будут автоматически выводить ввод.
mix_stderr (bool) – если это установлено в False, то stdout и stderr сохраняются как независимые потоки. Это полезно для приложений с философией Unix, у которых есть предсказуемый stdout и шумный stderr, так что каждый из них может быть измерен независимо.

get_default_prog_name(cli)

Для данного объекта команды возвращает имя программы по умолчанию для нее. По умолчанию используется значение атрибута name или "root", если он не задан.

Параметры:: cli (BaseCommand) –
Тип возвращаемого значения:: str

make_env(overrides=None)

Возвращает переопределения окружения для вызова скрипта.

Параметры:: overrides (Mapping[str, str | None] | None) –
Тип возвращаемого значения:: Mapping[str, str | None]

isolation(input=None, env=None, color=False)

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

Это делается автоматически в методе invoke().

Параметры:

input (str | bytes | IO[Any] | None) – поток ввода, который нужно поместить в sys.stdin.
env (Mapping[str, str | None] | None) – переопределения окружения в виде словаря.
color (bool) – использовать ли цвет в выводе. Приложение всё ещё может явно переопределить это.

Тип возвращаемого значения:

Iterator[Tuple[BytesIO, BytesIO | None]]

Журнал изменений

Изменено в версии 8.0: stderr открывается с errors="backslashreplace" вместо значения по умолчанию "strict".

Изменено в версии 4.0: Добавлен параметр color.

invoke(cli, args=None, input=None, env=None, catch_exceptions=True, color=False, **extra)

Вызывает команду в изолированной среде. Аргументы передаются непосредственно скрипту командной строки, а ключевые аргументы extra передаются функции main() команды.

Это возвращает объект Result.

Параметры:

cli (BaseCommand) – вызываемая команда
args (Sequence[str] | str | None) – аргументы вызова. Может быть передан как итерируемый объект или строка. При передаче в виде строки будет интерпретироваться как команда оболочки Unix. Дополнительные сведения см. в shlex.split().
input (str | bytes | IO[Any] | None) – входные данные для sys.stdin.
env (Mapping[str, str | None] | None) – переопределения окружения.
catch_exceptions (bool) – ловить ли любые исключения кроме SystemExit.
extra (Any) – ключевые аргументы для передачи в main().
color (bool) – использовать ли цвет в выводе. Приложение всё ещё может явно переопределить это.

Тип возвращаемого значения:

Result

Журнал изменений

Изменено в версии 8.0: У объекта результата есть атрибут return_value со значением, возвращённым вызываемой командой.

Изменено в версии 4.0: Добавлен параметр color.

Изменено в версии 3.0: Добавлен параметр catch_exceptions.

Изменено в версии 3.0: У объекта результата есть атрибут exc_info со стеком отладки, если он доступен.

END_OF_DOCUMENT_MARKER

isolated_filesystem(temp_dir=None)

Менеджер контекста, создающий временную директорию и меняющий текущую рабочую директорию на неё. Это изолирует тесты, влияющие на содержимое текущей рабочей директории, предотвращая их взаимное влияние.

Параметры:: temp_dir (str | PathLike[str] | None) – Создать временную директорию в этой директории. Если указано, созданная директория не удаляется при выходе.
Тип возвращаемого значения:: Iterator[str]

Журнал изменений

Изменено в версии 8.0: Добавлен параметр temp_dir.

class click.testing.Result(runner, stdout_bytes, stderr_bytes, return_value, exit_code, exception, exc_info=None)

Содержит захваченный результат вызываемого CLI скрипта.

Параметры:

runner (CliRunner) –
stdout_bytes (bytes) –
stderr_bytes (bytes | None) –
return_value (Any) –
exit_code (int) –
exception (BaseException | None) –
exc_info (Tuple[Type[BaseException], BaseException, TracebackType] | None) –

runner: Запустивший результат runner

stdout_bytes: Стандартный вывод в виде байтов.

stderr_bytes: Стандартная ошибка в виде байтов, или None, если недоступна

return_value: Значение, возвращённое вызываемой командой.

Журнал изменений

Новое в версии 8.0.

exit_code: Код выхода в виде целого числа.

exception: Исключение, которое произошло, если таковое имелось.

exc_info: Трекбэк

property output: str: Стандартный вывод в виде строкового значения Юникод.

property stdout: str: Стандартный вывод в виде строкового значения Юникод.

property stderr: str: Стандартная ошибка в виде строкового значения Юникод.