The following functions, classes, and interfaces are available from the top-level protocols package.
|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.
When invoked in the top-level code of a module, this function only accepts
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.
When used in a class body, this function works by temporarily replacing
__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!
|ob [, provides=[ ]][, doesNotProvide=[ ]])|
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.
|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.
|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.
|baseType, [methods=(), implicit=False])|
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
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
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
objects, so beware of using large method lists.)
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.
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.
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: