@overload 对比 @when

@overload 装饰器是更通用的 @when 装饰器的常用简写。它允许您省略要重载的函数的名称，但代价是要求目标函数必须在本地命名空间中。它也不支持除了通过参数注解指定的条件之外，添加其他条件。以下函数定义具有相同的效果，除了名称绑定副作用（将在下面描述）

from overloading import when

@overload
def flatten(ob: basestring):
    yield ob

@when(flatten)
def flatten(ob: basestring):
    yield ob

@when(flatten)
def flatten_basestring(ob: basestring):
    yield ob

@when(flatten, (basestring,))
def flatten_basestring(ob):
    yield ob

上面的第一个定义会将 flatten 绑定到它之前绑定的任何内容。如果 flatten 已经绑定到 when 装饰器的第一个参数，那么第二个定义也会做同样的事情。如果 flatten 未绑定或绑定到其他内容，它将重新绑定到给定的函数定义。上面最后两个定义将始终将 flatten_basestring 绑定到给定的函数定义。

使用这种方法，您可以给方法一个描述性名称（在回溯中通常很有用！）并在以后重用该方法。

除非另有规定，所有 overloading 装饰器都具有与 @when 相同的签名和绑定规则。它们接受一个函数和一个可选的“谓词”对象。

默认的谓词实现是一个类型元组，与重载函数的参数进行位置匹配。但是，可以使用扩展 API创建并注册任意数量的其他类型的谓词，然后这些谓词将与 @when 以及本模块创建的其他装饰器（如 @before、@after 和 @around）一起使用。

执行“下一个”方法

如果重载函数的第一个参数名为 __proceed__，它将被传递一个表示下一个最具体方法的可调用对象。例如，这段代码

def foo(bar:object, baz:object):
    print "got objects!"

@overload
def foo(__proceed__, bar:int, baz:int):
    print "got integers!"
    return __proceed__(bar, baz)

将打印“got integers!”，然后是“got objects!”。

如果没有下一个最具体的方法，__proceed__ 将被绑定到 NoApplicableMethods 实例。当调用时，将引发一个新的 NoApplicableMethods 实例，其中包含传递给第一个实例的参数。

类似地，如果下一个最具体方法之间在优先级上存在歧义，__proceed__ 将被绑定到 AmbiguousMethods 实例，如果调用，它将引发一个新的实例。

因此，方法可以检查 __proceed__ 是否为错误实例，或者直接调用它。NoApplicableMethods 和 AmbiguousMethods 错误类有一个共同的基类 DispatchError，所以 isinstance(__proceed__, overloading.DispatchError) 足以识别 __proceed__ 是否可以安全调用。

（实现说明：使用像 __proceed__ 这样的魔术参数名可能可以被一个魔术函数取代，该函数将被调用以获取下一个方法。然而，魔术函数会降低性能，并且可能在非 CPython 平台上更难实现。但是，通过魔术参数名进行方法链式调用可以在任何支持从函数创建绑定方法的 Python 平台上高效实现——只需递归地绑定每个要链式调用的函数，使用以下函数或错误作为绑定方法的 im_self。）

“之前”和“之后”方法

除了上面所示的简单下一个方法链式调用之外，有时还需要其他方法组合方式。例如，“观察者模式”有时可以通过向函数添加额外的方法来实现，这些方法在正常实现之前或之后执行。

为了支持这些用例，overloading 模块将提供 @before、@after 和 @around 装饰器，它们大致对应于 Common Lisp 对象系统 (CLOS) 中的相同类型方法，或 AspectJ 中相应的“advice”类型。

与 @when 类似，所有这些装饰器都必须传递要重载的函数，并且可以选择接受一个谓词

from overloading import before, after

def begin_transaction(db):
    print "Beginning the actual transaction"

@before(begin_transaction)
def check_single_access(db: SingletonDB):
    if db.inuse:
        raise TransactionError("Database already in use")

@after(begin_transaction)
def start_logging(db: LoggableDB):
    db.set_log_level(VERBOSE)

@before 和 @after 方法在主函数体之前或之后调用，并且 永远不会被视为模糊的。也就是说，拥有多个具有相同或重叠签名的“before”或“after”方法不会导致任何错误。模糊性通过方法添加到目标函数的顺序来解决。

“之前”方法按照最具体方法优先的顺序调用，具有模糊性的方法按照它们添加的顺序执行。所有“之前”方法都在函数的任何“主要”方法（即正常的 @overload 方法）执行之前调用。

“之后”方法以 相反 的顺序调用，在所有函数“主要”方法执行完毕后。也就是说，它们以最不具体方法优先的顺序执行，具有模糊性的方法以它们添加顺序的相反顺序执行。

“之前”和“之后”方法的返回值会被忽略，任何方法（主要或其他）抛出的未捕获异常都会立即终止分派过程。“之前”和“之后”方法不能有 __proceed__ 参数，因为它们不负责调用任何其他方法。它们只是作为在主要方法之前或之后的一种通知而被调用。

因此，“之前”和“之后”方法可以用于检查或建立前置条件（例如，如果条件不满足则引发错误）或确保后置条件，而无需重复任何现有功能。

“环绕”方法

@around 装饰器将方法声明为“环绕”方法。“环绕”方法与主要方法非常相似，只是最不具体的“环绕”方法比最具体的“之前”方法具有更高的优先级。

然而，与“before”和“after”方法不同，“Around”方法 负责 调用它们的 __proceed__ 参数，以继续调用过程。“Around”方法通常用于转换输入参数或返回值，或者用特殊的错误处理或 try/finally 条件来包装特定情况，例如

from overloading import around

@around(commit_transaction)
def lock_while_committing(__proceed__, db: SingletonDB):
    with db.global_lock:
        return __proceed__(db)

它们也可以通过 不 调用 __proceed__ 函数来替换特定情况下的正常处理。

给“环绕”方法的 __proceed__ 将是下一个适用的“环绕”方法，一个 DispatchError 实例，或者一个合成方法对象，它将调用所有“之前”方法，然后是主要方法链，然后是所有“之后”方法，并返回主要方法链的结果。

因此，与普通方法一样，可以检查 __proceed__ 是否为 DispatchError 实例，或者直接调用它。“环绕”方法应返回 __proceed__ 返回的值，除非它希望修改或替换整个函数的不同返回值。

自定义组合

上述装饰器（@overload、@when、@before、@after 和 @around）共同实现了 CLOS 中所谓的“标准方法组合”——方法组合中最常见的模式。

然而，有时应用程序或库可能需要更复杂的方法组合类型。例如，如果您希望有“折扣”方法，返回一个百分比折扣，并从主要方法返回的值中扣除，您可能会这样写

from overloading import always_overrides, merge_by_default
from overloading import Around, Before, After, Method, MethodList

class Discount(MethodList):
    """Apply return values as discounts"""

    def __call__(self, *args, **kw):
        retval = self.tail(*args, **kw)
        for sig, body in self.sorted():
            retval -= retval * body(*args, **kw)
        return retval

# merge discounts by priority
merge_by_default(Discount)

# discounts have precedence over before/after/primary methods
always_overrides(Discount, Before)
always_overrides(Discount, After)
always_overrides(Discount, Method)

# but not over "around" methods
always_overrides(Around, Discount)

# Make a decorator called "discount" that works just like the
# standard decorators...
discount = Discount.make_decorator('discount')

# and now let's use it...
def price(product):
    return product.list_price

@discount(price)
def ten_percent_off_shoes(product: Shoe)
    return Decimal('0.1')

类似的技术可用于实现各种 CLOS 风格的方法限定符和组合规则。创建自定义方法组合对象及其相应装饰器的过程将在扩展 API部分中详细描述。

顺便说一下，请注意所示的 @discount 装饰器将与通过其他代码定义的任何新谓词正确工作。例如，如果 zope.interface 将其接口类型注册为作为参数注解正确工作，您将能够基于其接口类型指定折扣，而不仅仅是类或 overloading 定义的接口类型。

类似地，如果像 RuleDispatch 或 PEAK-Rules 这样的库注册了适当的谓词实现和分派引擎，那么也可以将这些谓词用于折扣，例如

from somewhere import Pred  # some predicate implementation

@discount(
    price,
    Pred("isinstance(product,Shoe) and"
         " product.material.name=='Blue Suede'")
)
def forty_off_blue_suede_shoes(product):
    return Decimal('0.4')

定义自定义谓词类型和分派引擎的过程也在扩展 API部分中详细描述。

抽象方法和具体方法

顺便说一下，请注意 @abstract 装饰器不限于在接口定义中使用；它可以在任何您希望创建最初没有方法的“空”通用函数的地方使用。特别是，它不需要在类内部使用。

另请注意，接口方法不必是抽象的；例如，可以编写如下接口：

class IWriteMapping(Interface):
    @abstract
    def __setitem__(self, key, value):
        """This has to be implemented"""

    def update(self, other:IReadMapping):
        for k, v in IReadMapping(other).items():
            self[k] = v

只要为某种类型定义了 __setitem__，上述接口将提供一个可用的 update() 实现。然而，如果某些特定类型（或一对类型）有更高效的方式来处理 update() 操作，仍然可以为这种情况注册适当的重载。

子类化和重组

接口可以被子类化

class ISizedStack(IStack):
    @abstract
    def __len__(self):
        """Return the number of items on the stack"""

# define __len__ support for ISizedStack
when(ISizedStack.__len__, (list,))(list.__len__)

或通过组合现有接口的函数来组装

class Sizable(Interface):
    __len__ = ISizedStack.__len__

# list now implements Sizable as well as ISizedStack, without
# making any new declarations!

如果接口中定义的任何方法在运行时作用于该类的实例时，都不能保证引发 NoApplicableMethods 错误，那么在特定时间点，该类可以被认为是“适配”该接口的。

然而，在正常使用中，是“求饶比请求更容易”。也就是说，通过将对象适配到接口（例如 IStack(mylist)）或直接调用接口方法（例如 IStack.push(mylist, 42)）来使用对象上的接口比尝试弄清楚对象是否可适配（或直接实现）接口更容易。

在类中实现接口

可以使用 declare_implementation() 函数声明一个类直接实现一个接口

from overloading import declare_implementation

class Stack(object):
    def __init__(self):
        self.data = []
    def push(self, ob):
        self.data.append(ob)
    def pop(self):
        return self.data.pop()

declare_implementation(IStack, Stack)

上述 declare_implementation() 调用大致等同于以下步骤

when(IStack.push, (Stack,object))(lambda self, ob: self.push(ob))
when(IStack.pop, (Stack,))(lambda self, ob: self.pop())

也就是说，在 Stack 的任何子类的实例上调用 IStack.push() 或 IStack.pop()，将简单地委托给其实际的 push() 或 pop() 方法。

为了效率起见，当 s 是 Stack 的实例时，调用 IStack(s) 可能返回 s 而不是 IStack 适配器。（请注意，当 x 已经是 IStack 适配器时，调用 IStack(x) 将始终返回未更改的 x；这是在已知被适配对象 直接 实现接口而无需适配的情况下允许的额外优化。）

为了方便，在类头中声明实现可能很有用，例如

class Stack(metaclass=Implementer, implements=IStack):
    ...

而不是在套件末尾调用 declare_implementation()。

接口作为类型说明符

Interface 子类可以用作参数注解，以指示重载可接受的对象类型，例如

@overload
def traverse(g: IGraph, s: IStack):
    g = IGraph(g)
    s = IStack(s)
    # etc....

然而，请注意，仅使用接口作为类型说明符，实际参数不会以任何方式更改或适配。您必须显式地将对象强制转换为适当的接口，如上所示。

然而，请注意，其他接口使用模式是可能的。例如，其他接口实现可能不支持适配，或者可能要求函数参数已经适配到指定的接口。因此，将接口用作类型说明符的具体语义取决于您实际使用的接口对象。

然而，对于本 PEP 定义的接口对象，其语义如上所述。如果 I1 的继承层次结构中的描述符集合是 I2 的继承层次结构中描述符的真超集，则接口 I1 被认为比另一个接口 I2“更具体”。

因此，例如，ISizedStack 比 ISizable 和 ISizedStack 都更具体，而与这些接口之间的继承关系无关。这纯粹是关于这些接口中包含哪些操作的问题——并且操作的 名称 并不重要。

接口（至少是 overloading 提供的接口）总是被认为不如具体类具体。其他接口实现可以自行决定它们的特异性规则，包括接口之间以及接口与类之间。

接口中的非方法属性

实现 Interface 实际上以相同的方式处理所有属性和方法（即描述符）：它们的 __get__（如果存在，还有 __set__ 和 __delete__）方法会以包装（适配）对象作为“self”来调用。对于函数，这会产生一个绑定方法，将通用函数链接到包装对象。

对于非函数属性，最简单的方法是使用内置的 property，以及相应的 fget、fset 和 fdel 属性来指定

class ILength(Interface):
    @property
    @abstract
    def length(self):
        """Read-only length attribute"""

# ILength(aList).length == list.__len__(aList)
when(ILength.length.fget, (list,))(list.__len__)

或者，可以将 _get_foo() 和 _set_foo() 等方法定义为接口的一部分，并根据这些方法定义属性，但这对于用户在创建直接实现接口的类时正确实现会有些困难，因为他们需要匹配所有单独的方法名称，而不仅仅是属性或特性的名称。