如何在Python中实现带有参数别名的弃用（Deprecation）

Question

我们正在开发一个 Python 库，并希望更改某些函数中的函数参数名称。我们希望保持向后兼容性，因此需要找到一种方法来为函数参数创建别名。

以下是一个例子： 旧版本：

class MyClass(object):
  def __init__(self, object_id):
    self.id = object_id

新版本:

class MyClass(object):
  def __init__(self, id_object):
    self.id = id_object

如何使类与两种调用方式兼容：

object1 = MyClass(object_id=1234)
object2 = MyClass(id_object=1234)

我当然可以创建像这样的东西：

class MyClass(object):
  def __init__(self, object_id=None, id_object=None):
    if id_object is not None:
      self.id = id_object
    else:
      self.id = object_id

但这会改变参数数量，我们严格希望避免这种情况。

是否可以声明方法别名或参数别名?

- Jonathan DEKHTIAR

---

您提出的解决方案允许不传递ID，我建议检查是否只传递了一个ID。 - user3483203

Answer 1

您可以编写一个装饰器：

from typing import Callable, Dict
import functools
import warnings


def deprecated_alias(**aliases: str) -> Callable:
    """Decorator for deprecated function and method arguments.

    Use as follows:

    @deprecated_alias(old_arg='new_arg')
    def myfunc(new_arg):
        ...

    """

    def deco(f: Callable):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            rename_kwargs(f.__name__, kwargs, aliases)
            return f(*args, **kwargs)

        return wrapper

    return deco


def rename_kwargs(func_name: str, kwargs: Dict[str, Any], aliases: Dict[str, str]):
    """Helper function for deprecating function arguments."""
    for alias, new in aliases.items():
        if alias in kwargs:
            if new in kwargs:
                raise TypeError(
                    f"{func_name} received both {alias} and {new} as arguments!"
                    f" {alias} is deprecated, use {new} instead."
                )
            warnings.warn(
                message=(
                    f"`{alias}` is deprecated as an argument to `{func_name}`; use"
                    f" `{new}` instead."
                ),
                category=DeprecationWarning,
                stacklevel=3,
            )
            kwargs[new] = kwargs.pop(alias)


class MyClass(object):
    @deprecated_alias(object_id='id_object')
    def __init__(self, id_object):
        self.id = id_object

另外，因为您正在使用Python 3，您可以将object_id设置为仅限关键字参数：

import warnings

class MyClass(object):
    #                                  v Look here
    def __init__(self, id_object=None, *, object_id=None):
        if id_object is not None and object_id is not None:
            raise TypeError("MyClass received both object_id and id_object")
        elif id_object is not None:
            self.id = id_object
        elif object_id is not None:
            warnings.warn("object_id is deprecated; use id_object", DeprecationWarning, 2)
            self.id = object_id
        else:
            raise TypeError("MyClass missing id_object argument")

- user2357112

---

@JoranBeasley：已添加弃用警告。 - user2357112

@shmee：哦，嗯。id_object 看起来比 object_id 更奇怪，所以我以为 object_id 是新的。已编辑。 - user2357112

@user2357112 哦，我可以想到一些情况下这种新的标记法似乎更可取。不管怎样，解决方案很好。我读过关于只有关键字参数的内容，但之前还没有见过它们的实际应用。看起来是一个很好的使用方法。 - shmee

如果在 id_object 后面还有其他必填参数怎么办？我们将不得不将它们全部变成可选的，并验证它们是否已实例化。这会使解决方案更加复杂，也会使其不够简洁。 - Yael Ben-Haim

@YaelBen-Haim：@deprecated_alias 装饰器实际上不需要您使 id_object 可选，或者在其后添加任何参数。 - user2357112

Answer 2

除了user2357112的答案之外，还有一种不太优雅的方法是使用元类工厂：

import warnings

def Deprecation(deprec):

    class DeprecMeta(type):

        def __call__(cls, *args, **kwargs):
            new_kwargs = {k : v for k, v in kwargs.items() if k not in deprec}
            for k in deprec:
                if k in kwargs:
                    warnings.warn("{0}: Deprecated call with '{0}'. Use '{1}' instead".format(
                            cls.__name__, k, deprec[k]))
                    if deprec[k] not in kwargs:
                        new_kwargs[deprec[k]] = kwargs[k]
                    else:
                        raise TypeError('{} received both {} and {}'.format(
                                cls.__name__, k, deprec[k]))

            obj = cls.__new__(cls, *args, **new_kwargs)
            obj.__init__(*args, **new_kwargs)
            return obj

    return DeprecMeta

class MyClass(object, metaclass = Deprecation({'object_id': 'id_object'})):

    def __init__(self, id_object):
        self.id = id_object

object2 = MyClass(object_id=1234)

- Jacques Gaudin

---

哇！！这个解决方案相当有趣，我会尝试一下，只是为了好玩 ;) 谢谢你的回答。 - Jonathan DEKHTIAR