:mod:`dip.model`
================
.. module:: dip.model

The :mod:`dip.model` module implements a declarative type system for
Python.

The core of the module is the :class:`~dip.model.Model` class.  Sub-classes
define attributes as class attributes using model type classes such as
:class:`~dip.model.Bool` and :class:`~dip.model.Str`.  When such a sub-class is
instantiated then corresponding instance attributes are automatically created.

A model will enforce an attribute's type when rebinding it to a different
value.  It will also apply any additional constraints imposed by a particular
type.  For example the :class:`~dip.model.Int` type can impose minimum and
maximum values.  All types can provide an default value (that may be
overridden) for an attribute.

The initial values of attributes can be delayed until they are actually
needed.  This can be used to implement the lazy loading of Python modules.

An attribute can be observed and arbitrary Python code invoked when its value
changes.

The :class:`~dip.model.MappingProxy` class can be used to adapt, with some
limitations, any Python mapping object to a model.

Most of the APIs described support the definition of new attribute types.  If
you simply want to see how to use existing types then you only need to look at
the ``__init__()`` methods of type classes.


:class:`Adapter`
----------------
.. class:: Adapter

    Base class: :class:`~dip.model.Model`

    The Adapter class is the base class for all :term:`adapters<adapter>`.
        

    .. attribute:: adaptee = Any()

        The object that is being adapted.  It will be set automatically when the
        adapter is created.


:class:`Any`
------------
.. class:: Any

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Any class encapsulates any Python object. 

    .. method:: Any.__init__(default=None, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the object.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Any.validate(value)

        Validate an object according to the constraints.  An exception is
        raised if the object is invalid.
        
        :param value:
            the object to validate.
        :return:
            the validated object.


:class:`AttributeChange`
------------------------
.. class:: AttributeChange

    Base class: :class:`~dip.model.Model`

    The AttributeChange class contains the information that describes an
    observable change to a typed attribute.  An instance is passed to the
    observer defined using :func:`~dip.model.observe`.

    .. attribute:: model = Instance(Model)

        The model containing the changed attribute.

    .. attribute:: name = Str()

        The name of the changed attribute.

    .. attribute:: new = Any()

        The new value of the attribute.  If the type of the attribute is a
        collection, e.g. a list, then the value is a collection of the items that
        have been added.  Note that an item may appear in both in both ``new``
        and ``old``.

    .. attribute:: old = Any()

        The old value of the attribute.  If the type of the attribute is a
        collection, e.g. a list, then the value is a collection of the items that
        have been removed.  Note that an item may appear in both in both ``new``
        and ``old``.


:class:`Bool`
-------------
.. class:: Bool

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Bool class encapsulates a Python bool. 

    .. method:: Bool.__init__(default=False, **metadata)

        Initialise the object.
        
        :param default:
            is the default value of the bool.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Bool.validate(value)

        Validate a bool according to the constraints.  An exception is
        raised if the bool is invalid.
        
        :param value:
            the bool to validate.
        :return:
            the validated bool.


:class:`Callable`
-----------------
.. class:: Callable

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Callable class encapsulates any callable object. 

    .. method:: Callable.__init__(default=None, **metadata)

        Initialise the object.
        
        :param default:
            is the default value of the callable.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Callable.validate(value)

        Validate an object according to the constraints.  An exception is
        raised if the object is invalid.
        
        :param value:
            the object to validate.
        :return:
            the validated object.


:class:`ChangeTrigger`
----------------------
.. class:: ChangeTrigger

    Base class: :class:`~PyQt4.QtCore.QObject`

    The ChangeTrigger class communicates a change on behalf of a particular
    instance of an attribute.

    .. attribute:: changed = pyqtSignal(object)

        The signal that is emitted when an attribute is changed.


:class:`CollectionTypeFactory`
------------------------------
.. class:: CollectionTypeFactory

    Base class: :class:`~dip.model.ValueTypeFactory`

    The CollectionTypeFactory class is a base class for all types that
    encapsulate objects of a particular type.

    .. classmethod:: CollectionTypeFactory.resolve_type(type_specification, context='element')

        Resolve a type specification which is either a Python type (i.e. an
        instance of ``type``), an instance of
        :class:`~dip.model.ValueTypeFactory` or a string that is the "full"
        name of a Python type.  The string form allows types to be specified
        while avoiding circular imports.
        
        :param type_specification:
            the type specification to resolve.
        :param context:
            is the context in which the type is used and is only used in the
            text of exceptions.
        :return:
            the resolved type.

    .. classmethod:: CollectionTypeFactory.validate_collection_type(collection_type, other, context='element')

        Validate a type (either an instance of the builtin ``type`` or an
        instance of an attribute type factory) against a type associated with a
        collection.  An exception is raised if the types are not compatible.
        
        :param collection_type:
            is the type associated with the collection.
        :param other:
            is the type to validate.
        :param context:
            is the context in which the type is used and is only used in the
            text of exceptions.

    .. classmethod:: CollectionTypeFactory.validate_collection_value(contained_type, value)

        Validate a value contained in a collection.  An exception is raised
        if the value is invalid.
        
        :param contained_type:
            is the Python type or :class:`~dip.model.ValueTypeFactory`
            sub-class that is the value is expected to be.
        :param value:
            is the value to validate.
        :return:
            the validated value.


:class:`DelegatedTo`
--------------------
.. class:: DelegatedTo

    Base class: :class:`~dip.model.ValueTypeFactory`

    The DelegatedTo class implements a delegate for another typed
    attribute.

    .. method:: DelegatedTo.__init__(to, **metadata)

        Initialise the object.
        
        :param to:
            is the :term:`attribute path` of the attribute to delegate to.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: DelegatedTo.__get__(instance, owner)

        Reimplemented to get the real value from the instance. 

    .. method:: DelegatedTo.__set__(instance, value)

        Reimplemented to validate the value before setting it. 

    .. method:: DelegatedTo.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: DelegatedTo.delegates_to(instance)

        Get the containing model and name of the attribute that the
        delegate is acting for.
        
        :param instance:
            is the :class:`~dip.model.DelegatedTo` instance.
        :return:
            a tuple of the containing model and the name of the attribute.

    .. method:: DelegatedTo.validate(value)

        Validate a value.  This is only called to validate the default
        value which is a dummy.
        
        :param value:
            the value to validate.
        :return:
            the validated value.


:class:`Dict`
-------------
.. class:: Dict

    Base class: :class:`~dip.model.MutableTypeFactory`

    The Dict class encapsulates a Python dictionary with keys and values
    of particular types.

    .. method:: Dict.__init__(key_type=<dip.model.any.Any object at 0x2a43d50>, value_type=<dip.model.any.Any object at 0x2a43d90>, default=<object object at 0x26b2ad0>, **metadata)

        Initialise the object.
        
        :param key_type:
            the type of each key of the dictionary.  If it is omitted then
            keys of any type are allowed.  If it is a string then it is
            the "full" name of the type.  The string form allows types to be
            specified while avoiding circular imports.
        :param value_type:
            the type of each value of the dictionary.  If it is omitted then
            values of any type are allowed.  If it is a string then it is
            the "full" name of the type.  The string form allows types to be
            specified while avoiding circular imports.
        :param default:
            is the default value of the dictionary.  If is it omitted then an
            empty dictionary is the default.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Dict.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: Dict.get_default_value()

        Reimplemented to return a copy of the default because dictionaries
        are mutable.
        
        :return:
            a copy of the default value.

    .. method:: Dict.validate(value)

        Validate a dictionary according to the constraints.  An exception
        is raised if the dictionary is invalid.
        
        :param value:
            the dictionary to validate.
        :return:
            the validated dictionary.

    .. method:: Dict.validated_dict(value)

        Return a dictionary containing validated keys and values.
        
        :param value:
            the dictionary of (possibly) invalid keys and values.
        :return:
            a corresponding dictionary of validated keys and values.


:class:`Enum`
-------------
.. class:: Enum

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Enum class encapsulates a fixed set of string values. 

    .. method:: Enum.__init__(*members, default=None, **metadata)

        Initialise the object.
        
        :param \*members:
            the list of members.
        :param default:
            the default attribute value.  If omitted then the first member is
            used.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Enum.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: Enum.validate(value)

        Validate an object according to the constraints.  An exception is
        raised if the object is invalid.
        
        :param value:
            the object to validate.
        :return:
            the validated object.


:class:`Float`
--------------
.. class:: Float

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Float class encapsulates a Python float. 

    .. method:: Float.__init__(default=0.0, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the integer.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Float.validate(value)

        Validate a float according to the constraints.  An exception is
        raised if the float is invalid.
        
        :param value:
            the float to validate.
        :return:
            the validated float.


:class:`Instance`
-----------------
.. class:: Instance

    Base class: :class:`~dip.model.CollectionTypeFactory`

    The Instance class encapsulates an instance of a number of types. 

    .. method:: Instance.__init__(*types, default=None, **metadata)

        Initialise the object.
        
        :param \*types:
            the allowable types of the instance.  If no types are specified
            then an instance of any type is allowed.  If any type is a string
            then it is the "full" name of the type.  The string form allows
            types to be specified while avoiding circular imports.
        :param default:
            the default attribute value.  If omitted then ``None`` is used.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Instance.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. classmethod:: Instance.different(value1, value2)

        Reimplemented to compare two instances to see if they are
        different.
        
        :param value1:
            is the first value.
        :param value2:
            is the second value.
        :return:
            ``True`` if the values are different.

    .. method:: Instance.validate(value)

        Validate an instance according to the constraints.  An exception
        is raised if the instance is invalid.
        
        :param value:
            the instance to validate.
        :return:
            the validated instance.


:class:`Int`
------------
.. class:: Int

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Int class encapsulates a Python integer. 

    .. method:: Int.__init__(default=0, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the integer.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Int.validate(value)

        Validate an integer according to the constraints.  An exception is
        raised if the integer is invalid.
        
        :param value:
            the integer to validate.
        :return:
            the validated integer.


:class:`Interface`
------------------
.. class:: Interface

    The Interface class is the base class for all
    :term:`interfaces<interface>`.  A class is shown to implement an interface
    by decorating it with :func:`~dip.model.implements`.  An interface cannot
    be instantiated.  If it called with an object argument then either that
    argument is returned if it implements the interface, or an :term:`adapter`
    is returned that adapts the object to the interface.  An exception is
    raised if an appropriate adapter could not be found.


:class:`List`
-------------
.. class:: List

    Base class: :class:`~dip.model.MutableTypeFactory`

    The List class encapsulates a Python list with elements of a
    particular type.

    .. method:: List.__init__(element_type=<dip.model.any.Any object at 0x2a4be50>, default=<object object at 0x26b2ae0>, **metadata)

        Initialise the object.
        
        :param element_type:
            the type of each element of the list.  If it is omitted then
            elements of any type are allowed.  If it is a string then it is
            the "full" name of the type.  The string form allows types to be
            specified while avoiding circular imports.
        :param default:
            is the default value of the list.  If is it omitted then an empty
            list is the default.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: List.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: List.get_default_value()

        Reimplemented to return a copy of the default because lists are
        mutable.
        
        :return:
            a copy of the default value.

    .. method:: List.validate(value)

        Validate a list according to the constraints.  An exception is
        raised if the list is invalid.
        
        :param value:
            the list to validate.
        :return:
            the validated list.

    .. method:: List.validated_list(value)

        Return a list containing validated elements.
        
        :param value:
            the list of (possibly) invalid elements.
        :return:
            a corresponding list of validated elements.


:class:`MappingProxy`
---------------------
.. class:: MappingProxy

    The MappingProxy class implements a :class:`~dip.model.Model` based
    proxy for a mapping type.  It is assumed that the mapping has string keys.
    Note that changes made to the object being proxied cannot be observed.

    .. staticmethod:: MappingProxy.__new__(mapping)

        Create the proxy.  We make modifications to the class dictionary
        that are specific to the mapping, therefore we need to create a new
        type each time.


:class:`MetaInterface`
----------------------
.. class:: MetaInterface

    Base class: :class:`~dip.model.MetaModel`

    The MetaInterface class is the meta-class for Interface and is
    responsible for making an interface appear to be a super-class and invoking
    adapters when necessary.

    .. method:: MetaInterface.__call__(obj, exception=True)

        This is called to create an instance of an object that implements
        an interface we are the meta-class of.
        
        :param obj:
            is the object that may need adapting.
        :param exception:
            is True if an exception should be raised if the object couldn't be
            adapted.  If False then None is returned if the object couldn't be
            adapted.
        :return:
            an object, possibly an adapter, that implements the interface.

    .. method:: MetaInterface.__instancecheck__(instance)

        Reimplemented to ensure that isinstance() treats an instance that
        implements an interface as being an instance of that interface.

    .. method:: MetaInterface.__subclasscheck__(subclass)

        Reimplemented to ensure that issubclass() treats a class that
        implements an interface as being a sub-class of that interface.


:class:`MetaModel`
------------------
.. class:: MetaModel

    Base class: :class:`~PyQt4.QtCore.pyqtWrapperType`

    The MetaModel class is the meta-class for Model and is responsible for
    initialising the attributes of an instance.

    .. method:: MetaModel.__call__(*args, **kwargs)

        This is called to create an instance of a class we are a
        meta-class of.

    .. staticmethod:: MetaModel.__new__(meta_cls, name, bases, cls_dict)

        Reimplemented to create the type cache. 


:class:`Model`
--------------
.. class:: Model

    The Model class is the base class for all classes that have typed
    attributes.


:class:`MutableTypeFactory`
---------------------------
.. class:: MutableTypeFactory

    Base class: :class:`~dip.model.CollectionTypeFactory`

    The MutableTypeFactory class is a base class for all mutable types. 

    .. method:: MutableTypeFactory.bind(model, value, rebind=False)

        This is called when a model attribute is being bound or rebound.
        
        :param model:
            is the model.
        :param value:
            is the attribute's new value.
        :param rebind:
            is set if the attribute already has a value.


:class:`Set`
------------
.. class:: Set

    Base class: :class:`~dip.model.MutableTypeFactory`

    The Set class encapsulates a Python set with elements of a particular
    type.

    .. method:: Set.__init__(element_type=<dip.model.any.Any object at 0x2a55c90>, default=<object object at 0x26b2b90>, **metadata)

        Initialise the object.
        
        :param element_type:
            the type of each element of the set.  If it is omitted then
            elements of any type are allowed.  If it is a string then it is
            the "full" name of the type.  The string form allows types to be
            specified while avoiding circular imports.
        :param default:
            is the default value of the set.  If is it omitted then an empty
            set is the default.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Set.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: Set.get_default_value()

        Reimplemented to return a copy of the default because sets are
        mutable.
        
        :return:
            a copy of the default value.

    .. method:: Set.validate(value)

        Validate a set according to the constraints.  An exception is
        raised if the set is invalid.
        
        :param value:
            the set to validate.
        :return:
            the validated set.

    .. method:: Set.validated_set(value)

        Return a set containing validated elements.
        
        :param value:
            the set of (possibly) invalid elements.
        :return:
            a corresponding set of validated elements.


:class:`Str`
------------
.. class:: Str

    Base class: :class:`~dip.model.ValueTypeFactory`

    The Str class encapsulates a Python string. 

    .. method:: Str.__init__(default='', **metadata)

        Initialise the object.
        
        :param default:
            the default value of the string.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Str.validate(value)

        Validate a string according to the constraints.  An exception is
        raised if the string is invalid.
        
        :param value:
            the string to validate.
        :return:
            the validated string.


:class:`Subclass`
-----------------
.. class:: Subclass

    Base class: :class:`~dip.model.CollectionTypeFactory`

    The Subclass class encapsulates any type object. 

    .. method:: Subclass.__init__(type, default=None, **metadata)

        Initialise the object.
        
        :param type:
            is the type object.
        :param default:
            the default attribute value.  If omitted then ``None`` is used.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Subclass.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. classmethod:: Subclass.different(value1, value2)

        Reimplemented to compare two sub-classes to see if they are
        different.
        
        :param value1:
            is the first value.
        :param value2:
            is the second value.
        :return:
            ``True`` if the values are different.

    .. method:: Subclass.validate(value)

        Validate an object according to the constraints.  An exception is
        raised if the object is invalid.
        
        :param value:
            the object to validate.
        :return:
            the validated object.


:class:`Trigger`
----------------
.. class:: Trigger

    Base class: :class:`~dip.model.TypeFactory`

    The Trigger class represents an asynchronous event.  Attributes of
    this type can be observed and can be set to any value (which is then
    discarded).

    .. method:: Trigger.__init__(**metadata)

        Initialise the object.
        
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Trigger.__set__(instance, value)

        Reimplemented to pull the trigger. 

    .. method:: Trigger.observer(observer_func)

        This is used to decorate a method that will be invoked when the
        value of a typed attribute changes.  The name of the method should be
        the same as the name of the attribute.


:class:`Tuple`
--------------
.. class:: Tuple

    Base class: :class:`~dip.model.CollectionTypeFactory`

    The Tuple class encapsulates a Python tuple with elements of a
    particular type.

    .. method:: Tuple.__init__(element_type=<dip.model.any.Any object at 0x2a60210>, default=<object object at 0x26b2b70>, **metadata)

        Initialise the object.
        
        :param element_type:
            the type of each element of the tuple.  If it is omitted then
            elements of any type are allowed.  If it is a string then it is
            the "full" name of the type.  The string form allows types to be
            specified while avoiding circular imports.
        :param default:
            is the default value of the tuple.  If is it omitted then an empty
            tuple is the default.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Tuple.copy(default)

        Create a copy of this instance with a different default value.
        
        :param default:
            is the default value of the copied instance.
        :return:
            the copied instance.

    .. method:: Tuple.validate(value)

        Validate a tuple according to the constraints.  An exception is
        raised if the tuple is invalid.
        
        :param value:
            the tuple to validate.
        :return:
            the validated tuple.


:class:`TypeFactory`
--------------------
.. class:: TypeFactory

    The TypeFactory class is the base class for all classes that create
    attribute types.

    .. method:: TypeFactory.__init__(metadata)

        Initialise the object.
        
        :param metadata:
            is a dictionary of additional meta-data stored with the type.

    .. method:: TypeFactory.__delete__(instance)

        Raise an exception as attributes cannot be deleted. 

    .. method:: TypeFactory.__get__(instance, owner)

        Raise an exception as there is no value to get. 

    .. method:: TypeFactory.__set__(instance, value)

        This must be reimplemented by a sub-class. 


:exc:`ValidationError`
----------------------
.. exception:: ValidationError

    Base exception: :class:`~builtins.TypeError`

    The ValidationError exception is raised when a value is invalid. 


:exc:`ValidationTypeError`
--------------------------
.. exception:: ValidationTypeError

    Base exception: :class:`~dip.model.ValidationError`

    The ValidationTypeError exception is raised when a value has an
    invalid type.


:class:`ValueTypeFactory`
-------------------------
.. class:: ValueTypeFactory

    Base class: :class:`~dip.model.TypeFactory`

    The ValueTypeFactory class is the base class for all classes that
    create attribute types that have an associated stored value.

    .. method:: ValueTypeFactory.__init__(default, metadata)

        Initialise the object.
        
        :param default:
            is the default value of the type.
        :param metadata:
            is a dictionary of additional meta-data stored with the type.

    .. method:: ValueTypeFactory.__call__(getter_func)

        This is used to implicitly define a typed attribute by decorating
        the getter method.  The name of the method is used as the name of the
        attribute.

    .. method:: ValueTypeFactory.__get__(instance, owner)

        Reimplemented to get the real value from the instance. 

    .. method:: ValueTypeFactory.__set__(instance, value)

        Reimplemented to validate the value before setting it and to
        trigger any changes.

    .. method:: ValueTypeFactory.bind(model, value, rebind=False)

        This is called when a model attribute is being bound or rebound.
        
        :param model:
            is the model.
        :param value:
            is the attribute's new value.
        :param rebind:
            is set if the attribute already has a value.

    .. method:: ValueTypeFactory.clone(default)

        Create a clone of this instance with a different default value.
        
        :param default:
            is the default value of the cloned instance.
        :return:
            the cloned instance.

    .. method:: ValueTypeFactory.copy(default)

        Create a copy of this instance with a different default value.
        This implementation is suitable for types that don't have any
        additional data.
        
        :param default:
            is the default value of the cloned instance.
        :return:
            the cloned instance.

    .. method:: ValueTypeFactory.default(default_func)

        This is used to decorate a method that will be invoked to provide
        the default value of a typed attribute.  The name of the method should
        be the same as the name of the attribute.

    .. classmethod:: ValueTypeFactory.different(value1, value2)

        Compare two valid values to see if they are different.
        
        :param value1:
            is the first value.
        :param value2:
            is the second value.
        :return:
            ``True`` if the values are different.

    .. method:: ValueTypeFactory.get_default_value()

        Get the type's default value.  This implementation is appropriate
        for immutable types.  Mutable types should reimplement it and return a
        copy of the default.
        
        :return:
            the default value.

    .. method:: ValueTypeFactory.getter(getter_func)

        This is used to decorate a method that will be invoked to get the
        value of a typed attribute.  The name of the method should be the same
        as the name of the attribute.

    .. method:: ValueTypeFactory.observer(observer_func)

        This is used to decorate a method that will be invoked when the
        value of a typed attribute changes.  The name of the method should be
        the same as the name of the attribute.

    .. method:: ValueTypeFactory.setter(setter_func)

        This is used to decorate a method that will be invoked to set the
        value of a typed attribute.  The name of the method should be the same
        as the name of the attribute.

    .. method:: ValueTypeFactory.validate(value)

        Validate a value according to the type's constraints.  An
        exception is raised if the value is invalid.
        
        This must be reimplemented in a sub-class.
        
        :param value:
            the value to validate.
        :return:
            the validated value (which may be normalised in some way).


:func:`adapt`
-------------
.. function:: adapt(*adapted, to)

    A class decorator that marks one or more classes, which must be
    sub-classes of :class:`~dip.model.Adapter`, as being able to
    :term:`adapt<adapter>` an object to one or more
    :term:`interfaces<interface>`.  An instance of the adapter will be
    automatically created when required.  Like the
    :func:`~dip.model.implements` class decorator any attributes of the
    interfaces that are not already present in the adapter are automatically
    added.
    
    :param \*adapted:
        is the list of types of object to be adapted.
    :param to:
        is the interface (or list of interfaces) that the object is adapted to.


:func:`clone_model`
-------------------
.. function:: clone_model(model)

    Create a clone of a model.  Note that individual attributes are not
    recursively cloned.
    
    :param model:
        is the :class:`~dip.model.Model` instance.
    :return:
        the clone.


:func:`get_attribute_type`
--------------------------
.. function:: get_attribute_type(model, name)

    Get the :class:`~dip.model.TypeFactory` sub-class instance for an
    attribute of a model.
    
    :param model:
        is the :class:`~dip.model.Model` instance.
    :param name:
        is the name of the attribute.
    :return:
        the attribute's type object.


:func:`get_change_trigger`
--------------------------
.. function:: get_change_trigger(model, name)

    Get the change trigger for an attribute of a model.  Types can decide
    not to generate :class:`~dip.model.AttributeChange` instances if an
    attribute is not being observed.
    
    :param model:
        is the :class:`~dip.model.Model` instance.
    :param name:
        is the name of the attribute in the model.
    :return:
        the :class:`~dip.model.ChangeTrigger` instance or ``None`` if the
        attribute is not being observed.


:func:`get_model_types`
-----------------------
.. function:: get_model_types(model_type)

    Get a copy of the dictionary of :class:`~dip.model.TypeFactory`
    sub-class instances, keyed by attribute name, for a model type.
    
    :param model_type:
        is the :class:`~dip.model.Model` sub-class.
    :return:
        the dictionary of type objects.


:func:`implements`
------------------
.. function:: implements(*interfaces)

    A class decorator that marks the class as implementing one or more
    interfaces.  If a class implements an interface then :func:`issubclass`
    will return ``True`` when tested against the interface, :func:`isinstance`
    will return ``True`` when an instance of the class is tested against the
    interface.  The decorator will automatically add any attributes of an
    interface that are not already present in the class.
    
    :param \*interfaces:
        are the interfaces that the class implements.


:func:`isadapted`
-----------------
.. function:: isadapted(adaptee, interface)

    See if an object has been adapted to an interface.
    
    :param adaptee:
        is the object.
    :param interface:
        is the interface.
    
    :return:
        True if the object has been adapted to the interface.


:func:`observe`
---------------
.. function:: observe(name, model=<object object at 0x26b2ac0>, observer=<object object at 0x26b2ac0>, connection_type=0, remove=False)

    An attribute of a model is observed and an observer called when its
    value changes.  This can also be used as a method decorator that uses the
    decorated method as the observer.
    
    :param name:
        is the name of the attribute in the model to observe.  This may be an
        :term:`attribute path`.  If the last part of the name is '*' then all
        the attributes are observed.
    :param model:
        is the :class:`~dip.model.Model` instance.  This must not be specified
        when used as a decorator.
    :param observer:
        is the callable that is called when the attribute's value changes.  The
        observer is passed an :class:`~dip.model.AttributeChange` instance as
        its argument.  This must not be specified when used as a decorator.
    :param connection_type:
        is the type of the underlying Qt connection.
    :param remove:
        is set if the observer is to be removed.
