@overload vs. @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 绑定到它之前绑定的任何内容。第二个也将执行相同的操作，如果它已绑定到 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”方法不会导致任何错误。歧义是使用将方法添加到目标函数的顺序来解决的。

“Before”方法首先调用最具体的那个方法，模棱两可的方法按添加顺序执行。所有“before”方法都在函数的任何“primary”方法（即正常的 @overload 方法）执行之前调用。

“After”方法以**相反**的顺序调用，在函数的所有“primary”方法执行之后。也就是说，它们首先执行最不具体的那个方法，模棱两可的方法按添加顺序的反序执行。

“before”和“after”方法的返回值将被忽略，任何由**任何**方法（primary或其他）引发的未捕获异常都会立即结束分派过程。“Before”和“after”方法不能具有 __proceed__ 参数，因为它们不负责调用任何其他方法。它们只是在primary方法之前或之后作为通知被调用。

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

“环绕”方法

@around 装饰器将方法声明为“around”方法。“Around”方法非常类似于primary方法，除了最不具体的“around”方法比最具体的“before”方法具有更高的优先级。

但是，与“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__ 函数。

传递给“around”方法的 __proceed__ 将是下一个适用的“around”方法、一个 DispatchError 实例，或者一个合成方法对象，该对象将调用所有“before”方法，然后调用primary方法链，然后调用所有“after”方法，并返回primary方法链的结果。

因此，就像普通方法一样，可以检查 __proceed__ 是否为 DispatchError，或者简单地调用它。“around”方法应该返回 __proceed__ 返回的值，除非它希望修改或替换它，以作为整个函数的不同返回值。

自定义组合

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

但是，有时应用程序或库可能需要更复杂类型的方法组合。例如，如果您希望拥有返回折扣百分比的“discount”方法，以从primary方法返回的值中减去，您可以编写如下代码：

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() 方法。

为了提高效率，调用 IStack(s)（其中 s 是 Stack 的实例），**可能**会返回 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() 之类的方法定义为接口的一部分，并且根据这些方法定义属性，但这对于用户在创建直接实现接口的类时正确实现来说有点困难，因为他们随后需要匹配所有单独的方法名称，而不仅仅是属性或属性的名称。