1.1.9 Package Contents and Contained Modules

The following functions, classes, and interfaces are available from the top-level protocols package.

adapt( component, protocol [, default])

Return an implementation of protocol (a protocol object) for component (any object). The implementation returned may be component, or an adapter that implements the protocol on its behalf. If no implementation is available, return default. If no default is provided, raise protocols.AdaptationFailure.

A detailed description of this function's operations and purpose may be found in section 1.1.3.

exception AdaptationFailure: New in version 0.9.3. A subclass of TypeError and NotImplementedError, this exception type is raised by adapt() when no implementation can be found, and no default was supplied.

class Adapter( ob, proto)

New in version 0.9.1. This base class provides a convenient __init__ method for adapter classes. To use it, just subclass protocols.Adapter and add methods to implement the desired interface(s). (And of course, declare what interfaces the adapter provides, for what types, and so on.) Your subclass' methods can use the following attribute, which will have been set by the __init__ method:

subject: The subject attribute of an Adapter instance is the ob supplied to its constructor. That is, it is the object being adapted.

advise( **kw)

Declare protocol relationships for the containing class or module. All parameters must be supplied as keyword arguments. This function must be called directly from a class or module body, or a SyntaxError results at runtime. Different arguments are accepted, according to whether the function is called within a class or module.

When invoked in the top-level code of a module, this function only accepts the moduleProvides keyword argument. When invoked in the body of a class definition, this function accepts any keyword arguments except moduleProvides. The complete list of keyword arguments can be found in section 1.1.6.

Note: When used in a class body, this function works by temporarily replacing the __metaclass__ of the class. If your class sets an explicit __metaclass__, it must do so before advise() is called, or the protocol declarations will not occur!

adviseObject( ob [, provides=[ ]][, doesNotProvide=[ ]]): Declare that ob provides (or does not provide) the specified protocols. This is shorthand for calling declareAdapterForObject() with NO_ADAPTER_NEEDED and DOES_NOT_SUPPORT as adapters from the object to each of the specified protocols. Note, therefore, that ob may need to support IOpenProvider, and the listed protocols must be adaptable to IOpenProtocol. See section 1.1.6, ``Protocol Declarations for Individual Objects'', for more information on using adviseObject.

class Attribute( doc[,name=None, value=None])

This class is used to document attributes required by an interface. An example usage:

$\begin{verbatim}from protocols import Interface, Attribute \par class IFoo(Inter... ... Bar = Attribute(''''''All IFoos must have a Bar attribute'''''') \end{verbatim}$

If you are using the ``Abstract Base Class'' or ABC style of interface documentation, you may wish to also use the name and value attributes. If supplied, the Attribute object will act as a data descriptor, supplying value as a default value, and storing any newly set value in the object's instance dictionary. This is useful if you will be subclassing the abstract base and creating instances of it, but still want to have documentation appear in the interface. When the interface is displayed with tools like pydoc or help(), the attribute documentation will be shown.

declareAdapter( factory, provides[, forTypes=[ ]][, forProtocols=[ ]][, forObjects=[ ]])

Declare that factory is an IAdapterFactory whose return value provides the protocols listed in provides as an adapter for the classes/types listed in forTypes, for objects providing the protocols listed in forProtocols, and for the specific objects listed in forObjects.

This function is shorthand for calling the primitive declaration functions (declareAdapterForType, declareAdapterForProtocol, and declareAdapterForObject) for each of the protocols listed in provides and each of the items listed in the respective keyword arguments.

declareImplementation( typ[, instancesProvide=[ ]][, instancesDoNotProvide=[ ]])

Declare that instances of class or type typ do or do not provide implementations of the specified protocols. instancesProvide and instancesDoNotProvide must be sequences of protocol objects that provide (or are adaptable to) the IOpenProtocol interface, such as protocols.Interface subclasses, or Interface objects from Zope or Twisted.

This function is shorthand for calling declareAdapterForType() with NO_ADAPTER_NEEDED and DOES_NOT_SUPPORT as adapters from the type to each of the specified protocols. Note, therefore, that the listed protocols must be adaptable to IOpenProtocol.

DOES_NOT_SUPPORT( component, protocol): This function simply returns None. It is a placeholder used whenever an object, type, or protocol does not implement or imply another protocol. Whenever adaptation is not possible, but the protocols API function you are calling requires an adapter, you should supply this function as the adapter. Some protocol implementations, such as the one for Zope interfaces, are unable to handle adapters other than NO_ADAPTER_NEEDED and DOES_NOT_SUPPORT.

class Interface: Subclass this to create a "pure" interface. See section 1.1.4 for more details.

class AbstractBase: New in version 0.9.3. Subclass this to create an "abstract base class" or "ABC" interface. See section 1.1.4 for more details.

NO_ADAPTER_NEEDED( component, protocol): This function simply returns component. It is a placeholder used whenever an object, type, or protocol directly implements or implies another protocol. Whenever an adapter is not required, but the protocols API function you are calling requires an adapter, you should supply this function as the adapter. Some protocol implementations may be unable to handle adapters other than NO_ADAPTER_NEEDED and DOES_NOT_SUPPORT.

protocolForType( baseType,[methods=(), implicit=False])

New in version 0.9.1. Return a protocol object that represents the subset of baseType denoted by methods. It is guaranteed that you will receive the same protocol object if you call this routine more than once with eqivalent paremeters. This behavior is preserved even across pickling and unpickling of the returned protocol object.

baseType should be a type object, and methods should be a sequence of attribute or method names. (The order of the names is not important.) The implicit flag allows adapting objects that don't explicitly declare support for the protocol.

If you supply a true value for the implicit flag, the returned protocol will also adapt objects that have the specified methods or attributes. In other words, protocolForType(file, ['read','close'], True) returns a protocol that will consider any object with read and close methods to provide that protocol, as well as objects that explicitly support protocolForType(file, ['read','close']).

A more detailed description of this function's operations and purpose may be found in section 1.1.8.

(Note: this function may generate up to 2**len(methods) protocol objects, so beware of using large method lists.)

protocolForURI( uri): New in version 0.9.1. Return a protocol object that represents the supplied URI or UUID string. It is guaranteed that you will receive the same protocol object if you call this routine more than once with equal strings. This behavior is preserved even across pickling and unpickling of the returned protocol object.
The purpose of this function is to permit modules to refer to protocols defined in another module, that may or may not be present at runtime. A more detailed description of this function's operations and purpose may be found in section 1.1.8.

sequenceOf( protocol)

New in version 0.9.1. Return a protocol object that represents a sequence of objects adapted to protocol. Thus, protocols.sequenceOf(IFoo) is a protocol that represents a protocols.IBasicSequence of objects supporting the IFoo protocol. It is guaranteed that you will receive the same protocol object if you call this routine more than once with the same protocol, even across pickling and unpickling of the returned protocol object.

When this function creates a new sequence protocol, it automatically declares an adapter function from protocols.IBasicSequence to the new protocol. The adapter function returns the equivalent of [adapt(x,protocol) for x in sequence], unless one of the adaptations fails, in which case it returns None, causing the adaptation to fail.

The built-in list and tuple types are declared as implementations of protocols.IBasicSequence, so protocols returned by sequenceOf() can be used immediately to convert lists or tuples into lists of objects supporting protocol. If you need to adapt other kinds of sequences using your sequenceProtocol(), you will need to declare that those sequences implement protocols.IBasicSequence unless they subclass tuple, list, or some other type that implements protocols.IBasicSequence.

class StickyAdapter( ob, proto)

New in version 0.9.1. This base class is the same as the Adapter class, but with an extra feature. When a StickyAdapter instance is created, it declares itself as an adapter for its subject, so that subsequent adapt() calls will return the same adapter instance. (Technically, it declares an adapter function that returns itself.)

This approach is useful when an adapter wants to hold information on behalf of its subject, that must not be lost when the subject is adapted in more than one place.

Note that for a StickyAdapter subclass to be useful, the types it adapts must support IOpenProvider. See section 1.1.6, ``Protocol Declarations for Individual Objects'' for more information on this. Also, you should never declare that a StickyAdapter subclass adapts an individual object (as opposed to a type or protocol), since such a declaration would create a conflict when the adapter instance tries to register itself as an adapter for that same object and protocol.

StickyAdapter adds one attribute to those defined by Adapter:

attachForProtocols: A tuple of protocols to be declared by the constructor. Define this in your subclass' body to indicate what protocols it should attach itself for.