PyOpenWorm.capability module¶
Defines ‘capabilities’, pieces of functionality that an object needs which must be injected.
A given capability can be provided by more than one capability provider, but, for a given set of providers, only one will be bound at a time. Logically, each provider that provides the capability is asked, in a user-provided preference order, whether it can provide the capability for the specific object and the first one which can provide the capability is bound to the object.
The core idea is dependency injection: a capability does not modify the object: the object receives the provider and an identifier for the capability provided, but how the object uses the provider is up to the object. This is important because the user of the object should not condition its behavior on the particular capability provider used, although it may know about which capabilities the object has.
Note, that there may be some providers that lose their ability to provide a capability. This loss should be communicated with a ‘CannotProvideCapability’ exception when the relevant methods are called on the provider. This may allow certain operations to be retried with a provider lower on the capability order, but a provider that throws CannotProvide may validly be asked if it can provide the capability again – if it still cannot provide the capability, it should communicate that when asked.
Providers may keep state between calls to provide a capability, but their
correctness must not depend on any ordering of method calls except that, of
course, their __init__ is called first.