1.1.9.2 protocols.interfaces -- Package Interfaces
Description: protocols.interfaces -- Package Interfaces
Keywords: ref

###
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.