owmeta_core.capability module

Defines ‘capabilities’, pieces of functionality that an object needs which must be injected. The receiver of the capability is called a capable.

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 capable 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 capable: the capable receives the provider and a reference to the capability provided, but how the capable uses the provider is up to the capable. This is important because the user of the capable should not condition its behavior on the particular capability provider used, although it may change its behavior based on which capabilities the capable has.

Note, that there may be some providers that lose their ability to provide a capability after they have been bound to a capable. 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 CannotProvideCapability may validly be asked if it can provide the capability again – if it still cannot provide the capability, it should communicate that by returning None from its provides_to method.

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. For instance, a provider can retain an index that it downloads to answer provides_to, but if that index can expire, the provider should check for that and retrieve an updated index if necessary.

exception owmeta_core.capability.CannotProvideCapability(cap, provider)

Bases: Exception

Thrown by a provider when it cannot provide the capability during the object’s execution

Parameters

capCapability

the capabiilty

providerProvider

the provider which failed to provide cap

exception owmeta_core.capability.NoProviderAvailable(cap, receiver, providers)

Bases: Exception

Thrown when there is no provider available for a capabiilty

Attributes

capCapability

The capability that was sought

receiverCapable

The object for which the capability was sought

Parameters

capCapability

The capability that was sought

receiverCapable

The object for which the capability was sought

providerslist of Provider

Providers that were tried for the capability

exception owmeta_core.capability.NoProviderGiven(cap, receiver=None)

Bases: Exception

Thrown by a Capable when a Capability is needed, but none has been provided by a call to accept_capability_provider

Parameters

capCapability

The capability that was sought

receiverCapable

The object for which a capability was needed

exception owmeta_core.capability.UnwantedCapability

Bases: Exception

Thrown by a Capable when accept_capability_provider is offered a provider for a capability that it does not “want”, meaning it doesn’t have the code to use it. This can happen when a sub-class of a Capable declares a needed capability without overriding accept_capability_provider to accept that capability.

class owmeta_core.capability.Capability(*args, **kwargs)

Bases: object

A capability.

class owmeta_core.capability.Capable

Bases: object

An object which can have capabilities

accept_capability_provider(cap, provider)

The Capable should replace any previously accepted provider with the one given.

The capability should be checked to determine which capability is being provided, even if only one is declared on the class, so that if a sub-class defines a capability without defining how to accept it, then the wrong actions won’t be taken. In case the capability isn’t recognized, it is generally better to pass it to the super() implementation rather than failing to allow for cooperative multiple inheritance.

Parameters

capCapability

the capabiilty

providerProvider

the provider which provides cap

property needed_capabilities

The list of needed capabilities. These should be treated as though they are required for any of the object’s methods.

property wanted_capabilities

The list of wanted capabilities. These should be treated as though they are optional. The Capable subclass must determine how to deal with the provider not being available.

class owmeta_core.capability.Provider

Bases: object

A capability provider.

In general, providers should do any general setup in their initializer, and setup for any source passed into provides_to method if, in fact, the provider does provide the needed capabilities

provides(cap, obj)

Returns a provider of the given capability if it’s one this provider provides; otherwise, returns None.

Parameters

capCapability

The capability to provide

objCapable

The object to provide the capability to

Returns

Provider or None

provides_to(obj, cap)

Returns a Provider if the provider provides a capability to the given object; otherwise, returns None.

The default implementation always returns None. Implementers of Provider should check they can actually provide the capability for the given object rather than just that they might be able to.

It’s best to do setup for providing the capability before exiting this method rather than, for instance, in the methods of the returned provider when the Capable is trying to use it.

Parameters

objCapable

The object needing/wanting the capability

capCapability

The capability needed/wanted

Returns

Provider or None

owmeta_core.capability.get_provider(ob, cap, provs)

Get provider for a capabilty that can provide to the given object

Parameters

obCapable

Object needing the capability

capCapability

Capability needed

provslist of Provider

All providers available

Returns

Provider

A provider of the given capability or None

owmeta_core.capability.get_providers(cap, provs, ob)

Get providers for a capabilty

Parameters

capCapability

Capability needed

provslist of Provider

All providers available

Yields

Provider

A Provider that provides the given capability

owmeta_core.capability.is_capable(ob)

Returns true if the given object can accept capability providers

Parameters

obobject

An object which may be a Capable

Returns

bool

True if the given object accepts capability providers of some kind. Otherwise, false.

owmeta_core.capability.provide(ob, provs)

Provide capabilities to ob out of provs

Parameters

obobject

An object which may need capabilities

provslist of Provider

The providers available

Raises

NoProviderAvailable

when there is no provider available