1.1 protocols -- Protocol Definition, Declaration, and Adaptation

1.1 protocols -- Protocol Definition, Declaration, and Adaptation

The typical Python programmer is an integrator, someone who is connecting components from various vendors. Often times the interfaces between these components require an intermediate adapter. Usually the burden falls upon the programmer to study the interface exposed by one component and required by another, determine if they are directly compatible, or develop an adapter. Sometimes a vendor may even include the appropriate adapter, but then searching for the adapter and figuring out how to deploy the adapter takes time.

-- Martelli & Evans, PEP 246

This package builds on the object adaptation protocol presented in PEP 246 to make it easier for component authors, framework suppliers, and other developers to:

Specify what behavior a component requires or provides

Specify how to adapt the interface provided by one component to that required by another

Specify how to adapt objects of a particular type or class (even built-in types) to a particular required interface

Automatically adapt a supplied object to a required interface, and

Do all of the above, even when the components or frameworks involved were not written to take advantage of this package, and even if the frameworks have different mechanisms for defining interfaces.

Assuming that a particular framework either already supports this package, or has been externally adapted to do so, then framework users will typically use this package's declaration API to declare what interfaces their classes or objects provide, and/or to declare adaptations between interfaces or components.

For framework developers, this package offers an opportunity to replace tedious and repetitive type-checking code (such as isinstance(), type(), hasattr(), or interface checks) with single calls to adapt() instead. In addition, if the framework has objects that represent interfaces or protocols, the framework developer can make them usable with this package's declaration API by adding adapters for (or direct implementations of) the IOpenProtocol interface provided herein.

If the developer of a framework does not do these things, it may still be possible for a framework user or third-party developer to do them, in order to be able to use this package's API. The user of a framework can often call adapt() on a component before passing it to a non-adapting framework. And, it's possible to externally adapt a framework's interface objects as well.

For example, the protocols.zope_support and protocols.twisted_support modules define adapters that implement IOpenProtocol on behalf of Zope and Twisted Interface objects. This allows them to be used as arguments to this package's protocol declaration API. This works even though Zope and Twisted are completely unaware of the protocols package. (Of course, this does not give Zope or Twisted Interface objects all of the capabilities that Protocol objects have, but it does make most of their existing functionality accessible through the same API.)

Finally, framework and non-framework developers alike may also wish to use the Protocol and Interface base classes from this package to define protocols or interfaces of their own, or perhaps use some of the adaptation mechanisms supplied here to implement ``double dispatching'' or the ``visitor pattern''.

See Also:

PEP 246, Object Adaptation: PEP 246 describes an early version of the adaptation protocol used by this package.