Сообщить об ошибке.

Настройка страницы справки сценария

Модуль click позволяет очень легко вносить изменения/дополнять автоматически генерируемую страницу справки сценария командной строки. Генерируемые страницы справки в настоящее время не настраиваются с точки зрения их макета, можно изменить только текст.

Содержание:

Справочный текст опции и/или команды.

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

import click

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

if __name__ == '__main__':
    test()

Сценарий выведет:

$ python3 test.py --help
Usage: test [OPTIONS] NAME

  This script prints hello NAME COUNT times.

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

Справочный текст позиционных параметров сценария.

Модуль click автоматически НЕ генерирует справку по позиционным параметрам сценария, а декоратор @click.argument() НЕ принимает аргумент help. Согласно общему соглашению инструментов командной строки Unix, позиционные параметры сценария должны использоваться только для самых очевидных и необходимых значений. По этому, модуль click рекомендует документировать эти параметры вручную, в тексте справки к функции этой команды, ссылаясь на них по имени.

@click.command()
@click.argument('filename')
def test(filename):
    """Print FILENAME."""
    click.echo(filename)

Вывод сценария:

$ python3 test.py --help
# Usage: test.py [OPTIONS] FILENAME
# 
#   Print FILENAME.
# 
# Options:
#   --help  Show this message and exit.

Или можно явно предоставить описание параметра:

@click.command()
@click.argument('filename')
def test(filename):
    """Print FILENAME.

    FILENAME: is the name of the file to check.
    """
    click.echo(filename)

Сценарий выведет:

$ python3 test.py --help
# Usage: test.py [OPTIONS] FILENAME
# 
#   Print FILENAME.
# 
#   FILENAME is the name of the file to check.
# 
# Options:
#   --help  Show this message and exit.

Предотвращение переноса текста справки в терминале.

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

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

import click

@click.command()
def test():
    """
    По умолчанию модуль `click` выполняет перенос
    текста в зависимости от ширины терминала.
    В некоторых случаях это может стать проблемой.

    \b
    Переформатирование 
    можно 
    отключить.

    А это абзац снова
    будет завернут.
    """

if __name__ == '__main__':
    test()

Сценарий выведет:

$ python3 test.py --help
# Usage: test.py [OPTIONS]
# 
#   По умолчанию модуль `click` выполняет перенос текста в зависимости от
#   ширины терминала. В некоторых случаях это может стать проблемой.
# 
#   Переформатирование 
#   можно 
#   отключить.
# 
#   А это абзац снова будет завернут.
# 
# Options:
#   --help  Show this message and exit.

Усечение длинных справочных текстов.

Модуль click получает текст справки по команде из строк документации функции. И если строка документации уже используются для описания аргументов функции, которые она принимает, то наверное, строки param: и return: в тексте справки сценария будут лишними.

Для обрезки текста справки можно использовать экранированный символ \f. Текст, расположенный после этого маркета выводится не будет.

@click.command()
@click.pass_context
def test(ctx):
    """
    By default, the `click ' module performs
    text wrapping depending on the width of the terminal.
    \f

    :param click.core.Context ctx: Click context.
    """

Сценарий выведет:

$ python3 test.py --help
# Usage: test.py [OPTIONS]
# 
#   By default, the `click ' module performs text wrapping depending on the
#   width of the terminal.
# 
# Options:
#   --help  Show this message and exit.

Мета-переменные.

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

Это можно настроить на всех уровнях:

@click.command(options_metavar='<options>')
@click.option('--count', default=1, help='number of greetings',
              metavar='<int>')
@click.argument('name', metavar='<name>')
def test(count, name):
    """This script prints hello <name> <int> times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

Сценарий выведет:

$ python3 test.py --help
Usage: test.py <options> <name>

  This script prints hello <name> <int> times.

Options:
  --count <int>  number of greetings
  --help         Show this message and exit.

Краткая справка по вложенным командам.

Для подкоманд создается короткий фрагмент справки. По умолчанию, это первое предложение строки документации функции этой команды, если оно не слишком длинное. Эту строку также можно изменить аргументом short_help, переданным в декоратор @group.command():

@click.group()
def test():
    """A simple command line tool."""

@test.command('init', short_help='init the repo')
def init():
    """Initializes the repository."""

@test.command('delete', short_help='delete the repo')
def delete():
    """Deletes the repository."""

Сценарий выведет:

$ python3 test.py --help
Usage: test.py [OPTIONS] COMMAND [ARGS]...

  A simple command line tool.

Options:
  --help  Show this message and exit.

Commands:
  delete  delete the repo
  init    init the repo

Изменение названия опции --help.

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

В этом примере к опции --help добавляется ее короткая версия -h:

CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])

@click.command(context_settings=CONTEXT_SETTINGS)
def test():
    pass

Сценарий выведет:

$ python3 test.py -h
Usage: test.py [OPTIONS]

Options:
  -h, --help  Show this message and exit.