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

Включение автозаполнения

Автозаполнение доступно только если скрипт установлен и вызывается через точку входа, а не через команду python. См. Интеграцию Setuptools. После установки исполняемого файла вызов его со специальной переменной окружения переведёт Click в режим автозаполнения.

Для включения автозаполнения пользователь должен зарегистрировать специальную функцию в своей оболочке. Точный скрипт зависит от используемой оболочки. Click выведет его, если вызван с _{FOO_BAR}_COMPLETE, установленным в значение {shell}_source. {FOO_BAR} — имя исполняемого файла, в котором тире заменены на нижние подчёркивания. Использование верхнего регистра для имён переменных окружения является традицией, но не строго обязательным. Эта традиция помогает отличать переменные окружения от обычных переменных и команд оболочки, делая скрипты и конфигурационные файлы более читабельными и удобными для поддержки. Встроенные оболочки — bash, zsh, и fish.

Предоставьте своим пользователям следующие инструкции, адаптированные к имени вашей программы. В качестве примера используется foo-bar.

eval "$(_FOO_BAR_COMPLETE=bash_source foo-bar)"

eval "$(_FOO_BAR_COMPLETE=zsh_source foo-bar)"

_FOO_BAR_COMPLETE=fish_source foo-bar | source

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

_FOO_BAR_COMPLETE=bash_source foo-bar > ~/.foo-bar-complete.bash

. ~/.foo-bar-complete.bash

_FOO_BAR_COMPLETE=zsh_source foo-bar > ~/.foo-bar-complete.zsh

. ~/.foo-bar-complete.zsh

_FOO_BAR_COMPLETE=fish_source foo-bar > ~/.config/fish/completions/foo-bar.fish

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

Настройка автозаполнения для пользовательских типов

При создании пользовательского ParamType, переопределите его метод shell_complete(), чтобы обеспечить автозаполнение для параметров с этим типом. Метод должен возвращать список объектов CompletionItem. Помимо значения, эти объекты содержат метаданные, которые могут использоваться поддержкой оболочек. Встроенные реализации используют type для указания специальной обработки путей и help для оболочек, поддерживающих отображение строки справки рядом с предложением.

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

class EnvVarType(ParamType):
    name = "envvar"

    def shell_complete(self, ctx, param, incomplete):
        return [
            CompletionItem(name)
            for name in os.environ if name.startswith(incomplete)
        ]

@click.command()
@click.option("--ev", type=EnvVarType())
def cli(ev):
    click.echo(os.environ[ev])

Переопределение автозаполнения значений

Автозаполнение значений для параметра можно настроить без пользовательского типа, предоставив функцию shell_complete. Функция используется вместо любого автозаполнения, предоставляемого типом. Ей передаются 3 ключевых аргумента:

• ctx — текущий контекст команды.
• param — текущий параметр, запрашивающий автозаполнение.
• incomplete — частичное слово, которое дополняется. Может быть пустой строкой, если ещё не введено ни одного символа.

Функция должна возвращать список объектов CompletionItem, или в качестве сокращения может возвращать список строк.

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

def complete_env_vars(ctx, param, incomplete):
    return [k for k in os.environ if k.startswith(incomplete)]

@click.command()
@click.argument("name", shell_complete=complete_env_vars)
def cli(name):
    click.echo(f"Name: {name}")
    click.echo(f"Value: {os.environ[name]}")

Добавление поддержки для оболочки

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

Поддержка оболочек предоставляется подклассами ShellComplete, зарегистрированными с помощью add_completion_class(). Когда Click вызывается в режиме автозаполнения, он вызывает source() для вывода скрипта автозаполнения или complete() для вывода предложений. Базовый класс предоставляет реализации по умолчанию, которые требуют реализации некоторых более мелких частей.

Сначала вам нужно будет выяснить, как работает система автозаполнения вашей оболочки, и написать скрипт для интеграции её с Click. Он должен вызвать вашу программу с переменной окружения _{FOO_BAR}_COMPLETE , установленной в значение {shell}_complete, и передать полные аргументы и неполное значение. Как он передаёт эти значения и формат ответа на запрос автозаполнения от Click — зависит от вас.

В вашем подклассе установите source_template в скрипт автозаполнения. Реализация по умолчанию выполнит форматирование % со следующими переменными:

• complete_func — безопасное имя функции автозаполнения, определённой в скрипте.
• complete_var — имя переменной окружения для передачи инструкции {shell}_complete.
• foo_bar — имя исполняемого файла, который дополняется.

Пример кода предназначен для вымышленной оболочки «My Shell» или «mysh» в сокращении.

from click.shell_completion import add_completion_class
from click.shell_completion import ShellComplete

_mysh_source = """\
%(complete_func)s {
    response=$(%(complete_var)s=mysh_complete %(foo_bar)s)
    # parse response and set completions somehow
}
call-on-complete %(foo_bar)s %(complete_func)s
"""

@add_completion_class
class MyshComplete(ShellComplete):
    name = "mysh"
    source_template = _mysh_source

Далее, реализуйте get_completion_args(). Это необходимо для получения, анализа и возвращения полных аргументов и неполного значения из скрипта автозаполнения. Например, для реализации Bash переменная окружения COMP_WORDS содержит аргументы командной строки в виде строки, а переменная окружения COMP_CWORD содержит индекс неполного аргумента. Метод должен возвращать кортеж (args, incomplete).

import os
from click.parser import split_arg_string

class MyshComplete(ShellComplete):
    ...

    def get_completion_args(self):
        args = split_arg_string(os.environ["COMP_WORDS"])

        if os.environ["COMP_PARTIAL"] == "1":
            incomplete = args.pop()
            return args, incomplete

        return args, ""

Наконец, реализуйте format_completion(). Этот метод используется для форматирования каждого объекта CompletionItem в строку. Например, реализация Bash возвращает f"{item.type},{item.value} (она не поддерживает строки справки), а реализация Zsh возвращает каждую часть, разделённую новой строкой, заменяя пустые строки справки заполнитель _. Этот формат полностью зависит от того, что вы анализируете с помощью своего скрипта автозаполнения.

Значение type обычно является plain, но может быть другим значением, на котором может переключаться скрипт автозаполнения. Например, file или dir могут сказать оболочке, что она должна обрабатывать автозаполнение путей, так как оболочка в этом лучше, чем Click.

class MyshComplete(ShellComplete):
    ...

    def format_completion(self, item):
        return f"{item.type}\t{item.value}"

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

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

_FOO_BAR_COMPLETE=mysh_source foo-bar