附加组件 0.7

基本API

如果你需要，你可以查询插件的存在

>>> Persistence.exists_for(aThing)
True

默认情况下，它不存在

>>> anotherThing = Thing()
>>> Persistence.exists_for(anotherThing)
False

直到你直接引用它，例如

>>> Persistence(aThing) is Persistence(anotherThing)
False

此时它当然存在

>>> Persistence.exists_for(anotherThing)
True

并保持其状态，与主题相关联

>>> Persistence(anotherThing) is Persistence(anotherThing)
True

除非你删除它（或其主题被垃圾收集）

>>> Persistence.delete_from(anotherThing)
>>> Persistence.exists_for(anotherThing)
False

插件键和实例

插件存储在其主题的__dict__中，如果没有（或是一个具有只读__dict__的类型对象），则通过弱引用与主题相关联的专用字典中存储。

默认情况下，字典键是插件类本身，因此每个主题只有一个插件实例

>>> aThing.__dict__
{<class 'Persistence'>: <Persistence object at...>}

但在某些情况下，你可能希望为特定主题拥有多个给定插件类的实例。（例如，PEAK-Rules使用插件来表示规则中包含的不同表达式上的索引。）为此，你可以重新定义你的插件__init__方法，使其除了主题外还接受额外的参数。这些额外参数成为实例存储下的键的一部分，这样就可以为给定对象存在多个插件实例

>>> class Index(AddOn, dict):
...     def __init__(self, subject, expression):
...         self.expression = expression

>>> something = Thing()
>>> Index(something, "x>y")["a"] = "b"
>>> dir(something)
['__doc__', '__module__', (<class 'Index'>, 'x>y')]

>>> "a" in Index(something, "z<22")
False

>>> Index(something, "x>y")
{'a': 'b'}

>>> Index(something, "x>y").expression
'x>y'

>>> dir(something)
['__doc__', '__module__', (<class 'Index'>, 'x>y'), (<class 'Index'>, 'z<22')]

>>> Index.exists_for(something, 'x>y')
True

>>> Index.exists_for(anotherThing, 'q==42')
False

默认情况下，插件类的键要么是类本身，要么是包含类的元组，后面跟着插件主题构造函数调用后出现的任何参数。然而，你可以在子类中重新定义addon_key类方法，并将其更改为不同的操作。例如，你可以让不同的插件类生成重叠的键，或者你可以使用参数的属性来生成键。你甚至可以生成一个字符串键，以使插件作为属性附加！

>>> class Leech(AddOn):
...     def addon_key(cls):
...         return "__leech__"
...     addon_key = classmethod(addon_key)

>>> something = Thing()

>>> Leech(something) is something.__leech__
True

addon_key方法只接收构造函数调用中主题之后出现的参数。因此，在上面的例子中，它没有接收任何参数。如果我们用额外的参数调用它，我们将得到一个错误

>>> Leech(something, 42)
Traceback (most recent call last):
  ...
TypeError: addon_key() takes exactly 1 argument (2 given)

自然，你的addon_key和__init__（以及/或__new__）方法也应该就参数的数量及其含义达成一致！

通常，你应该将你的插件类（或某些插件类）作为键的一部分，以便使与他人的插件类发生冲突成为不可能。在适用的情况下，键也应设计为线程安全。（有关更多详细信息，请参阅下文线程关注点部分。）

角色存储和垃圾收集

顺便说一句，上面提到的使用字符串作为附加键的方法并不总是能使附加属性成为主题的属性！如果一个对象没有 __dict__ 或 __dict__ 不可写（例如类型对象），那么附加属性将存储在另一个地方的弱键字典中。

>>> class NoDict(object):
...     __slots__ = '__weakref__'

>>> dictless = NoDict()

>>> Leech(dictless)
<Leech object at ...>

>>> dictless.__leech__
Traceback (most recent call last):
  ...
AttributeError: 'NoDict' object has no attribute '__leech__'

当然，如果一个对象既没有字典也不是弱引用，那就根本无法为其存储附加属性。

>>> ob = object()
>>> Leech(ob)
Traceback (most recent call last):
  ...
TypeError: cannot create weak reference to 'object' object

然而，在 peak.util.addons 模块中有一个 addons_for() 函数，你可以使用 PEAK-Rules 建议（advice）来扩展它。一旦你添加了一个支持类型的方法，否则这个类型无法与附加属性一起使用，你应该能够使用任何类型的附加对象。当然，前提是你能够实现合适的存储机制！

最后，关于垃圾回收说几句。如果你想避免创建引用循环，不要在附加属性中存储主题的引用。即使 __init__ 和 __new__ 消息传递了主题，你也没有义务存储主题，通常也不需要这样做。通常，访问附加属性的代码知道正在使用哪个主题，并在需要时将其传递给附加属性的方法。附加属性通常不需要在 __new__() 和 __init__() 调用之后继续保持对主题的引用。

除非有其他引用，否则附加属性实例通常会在其主题被垃圾回收时一起被回收。如果它们保持对主题的引用，它们的垃圾回收可能会被延迟，直到 Python 的循环收集器运行。但是，如果没有保持引用，它们通常会在主题被删除时立即被删除。

>>> def deleting(r):
...     print "deleting", r

>>> from weakref import ref

>>> r = ref(Leech(something), deleting)
>>> del something
deleting <weakref at ...; dead>

然而，存储在主题实例字典之外的附加属性可能需要更长的时间，因为 Python 处理弱引用回调。

也不建议在你的附加对象上实现 __del__ 方法，尤其是如果你保留了主题的引用。在这种情况下，垃圾回收可能变得不可能，附加属性和其主题都会“泄露”（即永久占用内存而不被回收）。

类插件

有时，将附加属性附加到类而不是实例上是有用的。当然，你可以使用普通的 AddOn 类，因为它们与经典类和新式类型（包括内置类型）一起工作得很好。

>>> Persistence.exists_for(int)
False

>>> Persistence(int) is Persistence(int)
True

>>> Persistence.exists_for(int)
True

>>> class X: pass

>>> Persistence.exists_for(X)
False

>>> Persistence(X) is Persistence(X)
True

>>> Persistence.exists_for(X)
True

但是，有时你有专门为向类添加元数据而设计的附加属性，可能通过类或方法装饰器来实现。在这种情况下，你需要一种方法在主题存在之前就访问附加属性！

ClassAddOn 基类提供了这样的机制。它添加了一个额外的类方法 for_enclosing_class()，你可以使用它来访问当前在调用者作用域中定义的类的附加属性。例如，假设我们想要一个方法装饰器，它将方法添加到某个类级别的注册表中。

>>> from peak.util.addons import ClassAddOn

>>> class SpecialMethodRegistry(ClassAddOn):
...     def __init__(self, subject):
...         self.special_methods = {}
...         super(SpecialMethodRegistry, self).__init__(subject)

>>> def specialmethod(func):
...     smr = SpecialMethodRegistry.for_enclosing_class()
...     smr.special_methods[func.__name__] = func
...     return func

>>> class Demo:
...     def dummy(self, foo):
...         pass
...     dummy = specialmethod(dummy)

>>> SpecialMethodRegistry(Demo).special_methods
{'dummy': <function dummy at ...>}

>>> class Demo2(object):
...     def dummy(self, foo):
...         pass
...     dummy = specialmethod(dummy)

>>> SpecialMethodRegistry(Demo2).special_methods
{'dummy': <function dummy at ...>}

你当然可以使用类附加属性的常规附加属性 API。

>>> SpecialMethodRegistry.exists_for(int)
False

>>> SpecialMethodRegistry(int).special_methods['x'] = 123

>>> SpecialMethodRegistry.exists_for(int)
True

但是，你不能明确地删除它们，它们必须自然地被垃圾回收。

>>> SpecialMethodRegistry.delete_from(Demo)
Traceback (most recent call last):
  ...
TypeError: ClassAddOns cannot be deleted

>>> class SpecialMethodRegistry(ClassAddOn):
...     def __init__(self, subject):
...         print "init called for", subject
...         self.special_methods = {}
...         super(SpecialMethodRegistry, self).__init__(subject)
...
...     def created_for(self, cls):
...         print "created for", cls.__name__

>>> class Demo:
...     def dummy(self, foo):
...         pass
...     dummy = specialmethod(dummy)
init called for None
created for Demo

>>> SpecialMethodRegistry(float)
init called for <type 'float'>
created for float
<SpecialMethodRegistry object at ...>

>>> SpecialMethodRegistry(float)    # created_for doesn't get called again
<SpecialMethodRegistry object at ...>

>>> class Index(ClassAddOn):
...     def __init__(self, subject, expr):
...         self.expr = expr
...         self.funcs = []
...         super(Index, self).__init__(subject)

>>> def indexedmethod(expr):
...     def decorate(func):
...         Index.for_enclosing_class(expr).funcs.append(func)
...         return func
...     return decorate

>>> class Demo:
...     def dummy(self, foo):
...         pass
...     dummy = indexedmethod("x*y")(dummy)

>>> Index(Demo, "x*y").funcs
[<function dummy at ...>]

>>> Index(Demo, "y+z").funcs
[]

>>> def special_methods(**kw):
...     smr = SpecialMethodRegistry.for_enclosing_class()
...     smr.special_methods.update(kw)

>>> class Demo:
...     special_methods(x=23, y=55)
init called for None
created for Demo

>>> SpecialMethodRegistry(Demo).special_methods
{'y': 55, 'x': 23}

>>> special_methods(z=42)
Traceback (most recent call last):
  ...
SyntaxError: Class decorators may only be used inside a class statement

>>> def sm(**kw):
...     special_methods(**kw)

>>> class Demo:
...     sm(x=23, y=55)
Traceback (most recent call last):
  ...
SyntaxError: Class decorators may only be used inside a class statement

>>> def special_methods(level=2, **kw):
...     smr = SpecialMethodRegistry.for_enclosing_class(level=level)
...     smr.special_methods.update(kw)

>>> def sm(**kw):
...     special_methods(level=3, **kw)

>>> class Demo:
...     sm(x=23)
...     special_methods(y=55)
init called for None
created for Demo

>>> SpecialMethodRegistry(Demo).special_methods
{'y': 55, 'x': 23}

>>> from peak.util.addons import Registry

>>> class MethodGoodness(Registry):
...     """Dictionary of method goodness"""

>>> def goodness(value):
...     def decorate(func):
...         MethodGoodness.for_enclosing_class()[func.__name__]=value
...         return func
...     return decorate

>>> class Demo(object):
...     def aMethod(self, foo):
...         pass
...     aMethod = goodness(17)(aMethod)
...     def another_method(whinge, spam):
...         woohoo
...     another_method = goodness(-99)(another_method)

>>> MethodGoodness(Demo)
{'aMethod': 17, 'another_method': -99}

>>> class Demo2(Demo):
...     def another_method(self, fixed):
...         pass
...     another_method = goodness(42)(another_method)

>>> MethodGoodness(Demo2)
{'another_method': 42, 'aMethod': 17}

>>> MethodGoodness(Demo).defined_in_class
{'aMethod': 17, 'another_method': -99}

>>> MethodGoodness(Demo2).defined_in_class
{'another_method': 42}

线程关注点

只要扩展键不包含任何具有__hash__或__equals__方法的对象（与不调用任何Python代码的纯C代码相对），则扩展查找和创建是线程安全的（即没有竞态条件）。在递归的情况下，如果键是元组，则只包含内置类型实例的键的扩展，或者从内置类型继承其__hash__和__equals__方法类型的扩展，可以以线程安全的方式初始化。

然而，这并不意味着不能同时为同一主题创建两个或多个扩展实例！如果你希望代码是线程安全的，扩展类__new__或__init__方法中的代码必须不假设它将是附加到其主题的唯一扩展实例。

这是因为扩展访问机制允许多个线程同时创建扩展实例，但只有一个对象会赢得成为“唯一”扩展实例的竞争，没有线程事先知道它是否会赢。因此，如果你希望你的扩展实例在初始化时对构造函数参数执行某些操作，你必须放弃你的扩展是线程安全的，或者使用某种其他锁定机制。

当然，扩展初始化只是整个线程安全难题的一小部分。除非你的扩展仅存在于计算其主题的某些不可变元数据，否则你的扩展的其他方法也必须是线程安全的。

实现这一目标的一种方法，是使用@synchronized装饰器，结合使用Locking扩展。

>>> class Locking(AddOn):
...     def __init__(self, subject):
...         from threading import RLock
...         self.lock = RLock()
...     def acquire(self):
...         print "acquiring"
...         self.lock.acquire()
...     def release(self):
...         self.lock.release()
...         print "released"

>>> def synchronized(func):
...     def wrapper(self, *__args,**__kw):
...         Locking(self).acquire()
...         try:
...             func(self, *__args,**__kw)
...         finally:
...             Locking(self).release()
...
...     from peak.util.decorators import rewrap
...     return rewrap(func, wrapper)

>>> class AnotherThing:
...     def ping(self):
...         print "ping"
...     ping = synchronized(ping)

>>> AnotherThing().ping()
acquiring
ping
released

如果Locking()扩展构造函数不是线程安全的，则此装饰器将无法正确执行其任务，因为两个访问尚未拥有扩展的对象的线程可能会锁定两个不同的锁，并且同时运行所谓的“同步”方法！

（总的来说，线程安全性比看起来更难。但至少你不需要担心正确实现它的这个小小部分。）

当然，同步方法会比普通方法慢，这也是为什么 AddOns 除了解决线程安全问题的那一点外，不做任何其他操作，以避免惩罚非线程代码。正如 PEAK 的座右铭所说，STASCTAP！（简单的事情简单，复杂的事情可能。）

邮件列表

有关本软件的问题、讨论和错误报告应发送至 PEAK 邮件列表；有关详细信息，请参阅 http://www.eby-sarna.com/mailman/listinfo/PEAK/。