1.1 protocols -- Protocol Definition, Declaration, and Adaptation
Description: protocols -- Protocol Definition, Declaration, and Adaptation
Keywords: ref

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