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

Тексты справки

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

Простой пример:

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

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

$ hello --help
Usage: hello [OPTIONS] NAME

  This script prints hello NAME COUNT times.

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

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

$ touch --help
Usage: touch [OPTIONS] FILENAME

  Print FILENAME.

Options:
  --help  Show this message and exit.

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

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

$ touch --help
Usage: touch [OPTIONS] FILENAME

  Print FILENAME.

  FILENAME is the name of the file to check.

Options:
  --help  Show this message and exit.

Предотвращение переформатирования

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

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

Пример:

@click.command()
def cli():
    """First paragraph.

    This is a very long second paragraph and as you
    can see wrapped very early in the source text
    but will be rewrapped to the terminal width in
    the final output.

    \b
    This is
    a paragraph
    without rewrapping.

    And this is a paragraph
    that will be rewrapped again.
    """

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

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

  This is a very long second paragraph and as you can see wrapped very early in
  the source text but will be rewrapped to the terminal width in the final
  output.

  This is
  a paragraph
  without rewrapping.

  And this is a paragraph that will be rewrapped again.

Options:
  --help  Show this message and exit.

Чтобы изменить максимальную ширину, передайте max_content_width при вызове команды.

cli(max_content_width=120)

Обрезка текстов справки

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

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

Пример:

@click.command()
@click.pass_context
def cli(ctx):
    """First paragraph.

    This is a very long second
    paragraph and not correctly
    wrapped but it will be rewrapped.
    \f

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

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

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

  This is a very long second paragraph and not correctly wrapped but it will be
  rewrapped.

Options:
  --help  Show this message and exit.

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

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

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

Пример:

$ hello --help
Usage: hello <options> <name>

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

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

Короткая справка по команде

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

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

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

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

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

$ repo.py
Usage: repo.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

Справка эпилога команды

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

@click.command(epilog='Check out our docs at https://click.palletsprojects.com/ for more details')
def init():
    """Initializes the repository."""

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

$ repo.py --help
Usage: repo.py [OPTIONS]

  Initializes the repository.

Options:
  --help  Show this message and exit.

  Check out our docs at https://click.palletsprojects.com/ for more details

Настройка параметра справки

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

В этом примере параметры по умолчанию изменяются на -h и --help вместо просто --help:

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

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

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

$ cli -h
Usage: cli [OPTIONS]

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