1.1.9 Package Contents and Contained Modules
Description: Package Contents and Contained Modules
Keywords: ref

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

      from protocols import Interface, Attribute

      class IFoo(Interface):

          Bar = Attribute("""All IFoos must have a Bar attribute""")

  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.