如何将Click的device选项重命名为family并保持向后兼容？

需求背景 #

需要将现有--device/-d选项替换为--family/-f，要求：

• 用户使用旧选项--device时仍能正常运行
• 触发 deprecation 警告提示用户切换新选项
• 帮助文档中仅显示新选项--family，隐藏旧选项

问题分析 #

之前尝试使用"--device/--family"语法报错，是因为该语法仅适用于布尔类型选项，而当前选项是带可选值的非布尔类型，因此不能用这种方式实现别名。

解决方案 #

通过添加两个独立选项，结合回调函数处理旧选项的兼容逻辑：

代码实现 #

import warnings
import click
from typing import TypeVar, Union, Callable, Any

FC = TypeVar("FC", bound=Union[Callable[..., Any], click.Command])

def device_options(options: FC) -> FC:
    """Setup options for device family."""
    # 新的正式选项：--family/-f，显示在帮助文档中
    options = click.option(
        "-f",
        "--family",
        type=click.Choice(STH.devices()),
        help="Specify the device family",
        required=True,
    )(options)
    
    # 旧兼容选项：--device/-d，隐藏不显示在帮助中
    options = click.option(
        "-d",
        "--device",
        type=click.Choice(STH.devices()),
        help=click.HiddenHelp(),  # 隐藏该选项的帮助文档
        required=False,
        callback=handle_device_deprecation
    )(options)
    return options

def handle_device_deprecation(ctx, param, value):
    if value is not None:
        # 检查是否同时传入新旧选项，避免冲突
        if ctx.params.get("family") is not None:
            raise click.BadParameter("请勿同时使用--device和--family，请使用--family替代")
        
        # 发出废弃警告
        warnings.warn(
            "--device/-d 已废弃，请使用 --family/-f 选项",
            DeprecationWarning,
            stacklevel=2
        )
        # 将旧选项的值映射到新选项参数
        ctx.params["family"] = value
    return value

关键细节说明 #

1. 隐藏旧选项：通过help=click.HiddenHelp()让--device不在帮助文档中显示
2. 警告触发：当用户使用--device时，通过warnings.warn发出 deprecation 提示
3. 值映射：在回调函数中将旧选项的值赋值给新选项的参数，保证业务逻辑无需修改
4. 冲突处理：添加判断避免用户同时传入新旧选项，防止参数歧义

效果验证 #

• 运行命令时使用--device：正常执行逻辑，同时控制台输出 deprecation 警告
• 查看帮助文档（如--help）：仅显示--family/-f选项，看不到--device
• 同时使用--device和--family：抛出明确的参数错误提示

内容的提问来源于stack exchange，提问作者Maria