1.1.9.2 protocols.interfaces -- Package Interfaces

1.1.9.2 `protocols.interfaces` -- Package Interfaces

Note: All of the interfaces listed here can also be imported directly from the top-level protocols package. However, you will probably only need them if you are extending the framework, as opposed to merely using it.

class IOpenProtocol

This interface documents the behavior required of protocol objects in order to be used with the protocols declaration API (the functions whose names begin with declare or advise.) The declaration API functions will attempt to adapt() supplied protocols to this interface.

The methods an IOpenProtocol implementation must supply are:

addImpliedProtocol( proto, adapter, depth): Declare that this protocol can be adapted to protocol proto via the IAdapterFactory supplied in adapter, at the specified implication level depth. The protocol object should ensure that the implied protocol is able to adapt objects implementing its protocol (typically by recursively invoking declareAdapterForType() with increased depth and appropriately composed adapters), and notify any registered implication listeners via their newProtocolImplied() methods. If the protocol already implied proto, this method should have no effect and send no notifications unless the new adapter and depth represent a ``shorter path'' as described in section 1.1.7.

registerImplementation( klass, adapter, depth): Declare that instances of type or class klass can be adapted to this protocol via the IAdapterFactory supplied in adapter, at the specified implication level depth. Unless adapter is DOES_NOT_SUPPORT, the protocol object must ensure that any protocols it implies are also able to perform the adaptation (typically by recursively invoking declareAdapterForType() with increased depth and appropriately composed adapters for its implied protocols). If the protocol already knew a way to adapt instances of klass, this method should be a no-op unless the new adapter and depth represent a ``shorter path'' as described in section 1.1.7.

registerObject( ob, adapter, depth): Ensure that the specific object ob will be adapted to this protocol via the IAdapterFactory supplied in adapter, at the specified implication level depth. The protocol object must also ensure that the object can be adapted to any protocols it implies. This method may be implemented by adapting ob to IOpenProvider, calling the declareProvides() method, and then recursively invoking declareAdapterForObject with increased depth and appropriately composed adapters for the protocols' implied protocols.

addImplicationListener( listener): Ensure that listener (an IImplicationListener) will be notified whenever an implied protocol is added to this protocol, or an implication path from this protocol is shortened. The protocol should at most retain a weak reference to listener. Note that if a protocol can guarantee that no notices will ever need to be sent, it is free to implement this method as a no-op. For example, Zope interfaces cannot imply any protocols besides their base interfaces, which are not allowed to change. Therefore, no change notifications would ever need to be sent, so the IOpenProtocol adapter for Zope interfaces implements this method as a no-op.

Note: IOpenProtocol is a subclass of IAdaptingProtocol, which means that implementations must therefore meet its requirements as well, such as having an __adapt__() method.

class IOpenProvider

This interface documents the behavior required of an object to be usable with adviseObject(). Note that some protocol objects, such as the IOpenProtocol adapter for Zope interfaces, can handle adviseObject() operations without adapting the target object to IOpenProvider. This should be considered an exception, rather than the rule. However, the protocols package declares default adapters so that virtually any Python object that doesn't already have a __conform__() method can be adapted to IOpenProvider automatically.

declareProvides( protocol, adapter, depth): Declare that this object can provide protocol if adapted by the IAdapterFactory supplied in adapter, at implication level depth. Return a true value if the new adapter was used, or a false value if the object already knew a ``shorter path'' for adapting to protocol (as described in section 1.1.7). Typically, an implementation of this method will also adapt protocol to IOpenProtocol, and then register with addImplicationListener() to receive notice of any protocols that might be implied by protocol in future.

class IImplicationListener

This interface documents the behavior required of an object supplied to the IOpenProtocol.addImplicationListener() method. Such objects must be weak-referenceable, usable as a dictionary key, and supply the following method:

newProtocolImplied( srcProto, destProto, adapter, depth): Receive notice that an adaptation was declared from srcProto to destProto, using the IAdapterFactory adapter, at implication level depth.
When used as part of an IOpenProvider implementation, this method is typically used to recursively invoke declareAdapterForObject() with increased depth and appropriately composed adapters from protocols already supported by the object.

class IOpenImplementor

If an class or type supplied to declareAdapterForType supports this interface, it will be notified of the declaration and any future declarations that affect the class, due to current or future protocol implication relationships. Supporting this interface is not necessary; it is provided as a hook for advanced users. Note that to declare a class or type as an IOpenImplementor, you must call

adviseObject(theClass,
provides=[IOpenImplementor])

after the class definition or place advise(classProvides=[IOpenImplementor]) in the body of the class, since this interface must be provided by the class itself, not by its instances. (Of course, if you implement this interface via a metaclass, you can declare that the metaclass' instances provide the interface.)

Notification to classes supporting IOpenImplementor occurs via the following method:

declareClassImplements( protocol, adapter, depth): Receive notice that instances of the class support protocol via the the IAdapterFactory supplied in adapter, at implication level depth.

class IAdapterFactory: An interface documenting the requirements for an object to be used as an adapter factory: i.e., that it be a callable accepting an object to be adapted.) This interface is not used by the protocols package except as documentation.

class IProtocol: An interface documenting the basic requirements for an object to be used as a protocol for adapt(): i.e., that it be usable as a dictionary key. This interface is not used by the protocols package except as documentation.

class IAdaptingProtocol: An interface documenting the requirements for a protocol object to be able to adapt objects when used with adapt(): i.e., that it have a __adapt__ method that accepts the object to be adapted and returns either an object providing the protocol or None. This interface is not used by the protocols package except as documentation. It is a subclass of IProtocol, so any implementation of this interface must support the requirements defined by IProtocol as well.