Обновление до более новых версий

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

Обновление до версии 7.0

Команды, которые получают свои имена от декорированной функции, теперь заменяют подчёркивания дефисами. Например, функция Python run_server теперь получит имя команды run-server. Есть несколько способов решить эту проблему:

Чтобы продолжить использовать новое поведение, зафиксируйте вашу зависимость на Click>=7 и обновите любую документацию, чтобы использовать дефисы.
Чтобы сохранить существующее поведение, добавьте явное имя команды с подчёркиваниями, например, @click.command("run_server").
Чтобы попробовать имя с дефисами, если имя с подчёркиваниями не было найдено, передайте token_normalize_func в контекст:
```
def normalize(name):
    return name.replace("_", "-")

@click.group(context_settings={"token_normalize_func": normalize})
def group():
    ...

@group.command()
def run_server():
    ...
```

Обновление до версии 3.2

Click 3.2 потребовал внести два изменения в многокомандные функции, которые были вызваны изменением между Click 2 и Click 3, последствия которого оказались более серьезными, чем ожидалось.

Вызовы контекста

Click 3.2 содержит исправление для функции Context.invoke() при использовании с другими командами. Первоначальная цель этой функции заключалась в вызове другой команды как будто она пришла из командной строки, когда ей передавался объект контекста вместо функции. Это использование было задокументировано только в одном месте в документации ранее, и в документации API не было надлежащего объяснения метода.

Основная проблема заключается в том, что до версии 3.2 этот вызов работал вопреки намерениям:

ctx.invoke(other_command, 'arg1', 'arg2')

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

Правильный вызов для вышеприведённой команды следующий:

ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')

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

API для цепочки многокомандных вызовов

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

Однако это предположение не работает с одной из гарантий API, которые были даны в прошлом. Поэтому эта функциональность была удалена в версии 3.2, так как уже была нерабочей. Вместо этого была восстановлена случайно нарушенная функциональность атрибута Context.invoked_subcommand.

Если вам необходимо узнать, какие именно команды будут вызваны, существуют различные способы решения этой задачи. Первый способ — позволить всем подкомандам возвращать функции, а затем вызывать эти функции в Context.result_callback().

Обновление до версии 2.0

Click 2.0 имеет одно изменение, нарушающее обратную совместимость, — это сигнатура для обратных вызовов параметров. До версии 2.0 обратный вызов вызывался с (ctx, value), а теперь с (ctx, param, value). Это изменение было необходимо, поскольку в противном случае повторное использование обратных вызовов стало бы слишком сложным.

Для облегчения перехода Click по-прежнему будет принимать старые обратные вызовы. Начиная с Click 3.0, он будет отображать предупреждение в stderr, чтобы побудить вас выполнить обновление.

Если вам нужно поддерживать как Click 1.0, так и Click 2.0, вы можете создать простую декоратор, который корректирует сигнатуры:

import click
from functools import update_wrapper

def compatcallback(f):
    # Click 1.0 does not have a version string stored, so we need to
    # use getattr here to be safe.
    if getattr(click, '__version__', '0.0') >= '2.0':
        return f
    return update_wrapper(lambda ctx, value: f(ctx, None, value), f)

С помощью этого помощника вы можете написать что-то вроде этого:

@compatcallback
def callback(ctx, param, value):
    return value.upper()

Обратите внимание, что поскольку Click 1.0 не передавал параметр, аргумент param здесь будет None, поэтому обратный вызов совместимости не мог использовать этот аргумент.