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

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


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

    .. classmethod:: Adapter.isadaptable(adaptee)

        Determine if this adapter can adapt a particular object.  It is
        only called after it is known that the adapter can handle the object's
        type.
        
        :param adaptee:
            is the object to be adapted.
        :return:
            ``True`` if the object can be adapted.  This default implementation
            always returns ``True``.


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

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

    The Any class encapsulates any Python object. 

    .. method:: Any.__init__(default=None, allow_none=True, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the object.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``True``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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, allow_none=False, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            is the default value of the bool.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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, allow_none=True, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            is the default value of the callable.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``True``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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.

    .. method:: ChangeTrigger.__init__()

        Initialize the instance. 


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

    .. method:: CollectionTypeFactory.resolve_type(type_specification, context='element', allow_none=True)

        Resolve a type specification which is either ``None``, a Python
        type (i.e. an instance of ``type``), an instance of
        :class:`~dip.model.ValueTypeFactory` or a string that is the absolute
        or relative 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.
        :param allow_none:
            is ``True`` if the type specification can be ``None``.
        :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()

        Create a copy of this 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=None, value_type=None, default=<object object at 0xc98ac0>, allow_none=False, getter=None, setter=None, **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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Dict.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. 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, allow_none=False, getter=None, setter=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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Enum.copy()

        Create a copy of this 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, allow_none=False, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the integer.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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, allow_none=True, getter=None, setter=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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``True``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Instance.copy()

        Create a copy of this 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, allow_none=False, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the integer.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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=None, default=<object object at 0xc98af0>, allow_none=False, getter=None, setter=None, **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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: List.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. 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, adapt=True, cache=True, exception=True, adapter=None)

        This is called to create an instance of an object that implements
        an interface, either directly or by adaptation.
        
        :param obj:
            is the object that may need adapting.
        :param adapt:
            is ``True`` if an adapter is to be created if needed.  If ``False``
            then ``None`` is returned unless the object already implements the
            interface or an appropriate adapter has already been created.
        :param cache:
            is ``True`` if any adapter that is created is cached so that the
            same adapter is returned next time one is needed.
        :param exception:
            is ``True`` if an exception should be raised if an adapter would be
            needed but an appropriate one could not be found.
        :param adapter:
            is the adapter to use.  If it is ``None`` then an appropriate
            adapter is chosed automatically.  If it is not ``None`` then the
            other optional arguments are ignored.
        :return:
            an object, possibly an adapter, that implements the interface.

    .. method:: MetaInterface.__instancecheck__(instance)

        Reimplemented to ensure that isinstance() treats an object that
        directly implements an interface as being an instance of that
        interface.  Note that an object that only implements an interface using
        adaptation is not considered an instance.

    .. method:: MetaInterface.__subclasscheck__(subclass)

        Reimplemented to ensure that issubclass() treats a class that
        directly 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:`MetaSingleton`
----------------------
.. class:: MetaSingleton

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

    The MetaSingleton class is the meta-class for Singleton and is
    responsible for enforcing the singleton behaviour and implementing a
    read-only proxy for the managed instance.

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

        This is called to create a new singleton instance or to return the
        one created previously.

    .. method:: MetaSingleton.__getattr__(name)

        This will ensure that a singleton exists and proxy any unknown
        attribute accesses to the managed instance.


: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=None, default=<object object at 0xc98b40>, allow_none=False, getter=None, setter=None, **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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Set.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. 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:`Singleton`
------------------
.. class:: Singleton

    The Singleton class is a base class for those classes implemented as a
    singleton and that manage an instance.

    .. attribute:: instance = Any()

        The managed instance.

    .. attribute:: singleton = None

        The singleton.


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

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

    The Str class encapsulates a Python string. 

    .. method:: Str.__init__(default='', allow_none=False, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param default:
            the default value of the string.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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, allow_none=True, getter=None, setter=None, **metadata)

        Initialise the object.
        
        :param type:
            is the type object.
        :param default:
            the default attribute value.  If omitted then ``None`` is used.
        :param allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``True``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Subclass.copy()

        Create a copy of this 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. 


: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=None, default=<object object at 0xc98b50>, allow_none=False, getter=None, setter=None, **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 allow_none:
            ``True`` if ``None`` is a valid value.  The default is ``False``.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :param \*\*metadata:
            is additional meta-data stored with the type.

    .. method:: Tuple.copy()

        Create a copy of this 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. 

    .. method:: TypeFactory.clone()

        Create a clone of this instance.
        
        :return:
            the cloned instance.

    .. method:: TypeFactory.copy()

        Create a copy of this instance.
        
        :return:
            the copied instance.

    .. method:: TypeFactory.observed(observed_func)

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


: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, allow_none, getter, setter, metadata)

        Initialise the object.
        
        :param default:
            is the default value of the type.
        :param allow_none:
            ``True`` if ``None`` is a valid value.
        :param getter:
            is the optional attribute getter.
        :param setter:
            is the optional attribute setter.
        :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()

        Create a clone of this instance.
        
        :return:
            the cloned instance.

    .. method:: ValueTypeFactory.copy()

        Create a copy of this instance.  This implementation is suitable
        for types that don't have any additional data.
        
        :return:
            the copied 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 ensure a copy of the default
        is returned.
        
        :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.set_default_value(default)

        Set the type's default value.
        
        :param default:
            is the new default value.

    .. 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 by 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 (and may not be an :term:`attribute path`..
    :return:
        the attribute's type object.


:func:`get_attribute_types`
---------------------------
.. function:: get_attribute_types(model, attribute_type_type=None)

    Get the :class:`~dip.model.TypeFactory` sub-class instances for all
    attributes of a model.
    
    :param model:
        is the model
    :param attribute_type_type:
        is the optional :class:`~dip.model.TypeFactory` sub-class.  If this is
        specified then only attributes of this type will be returned.
    :return:
        the list of attribute types.


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

    Get the change trigger for an attribute of a model.
    
    :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:`notify_observers`
------------------------
.. function:: notify_observers(name, model, new, old)

    Notify any observers about a change to the value of an attribute of a
    model.
    
    :param name:
        is the name of the attribute in the model.
    :param model:
        is the :class:`~dip.model.Model` instance.
    :param new:
        is the new value of the attribute.
    :param old:
        is the old value of the attribute.


:func:`observe`
---------------
.. function:: observe(name, model=<object object at 0xc98ab0>, observer=<object object at 0xc98ab0>, 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 remove:
        is set if the observer is to be removed.


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

    Return the sub-model and name referenced by an :term:`attribute path`.
    
    :param name:
        is the name of the attribute and may be an attribute path.
    :param model:
        is the model.
    :return:
        the attribute name (which will not be an attribute path) and the
        sub-model.


:func:`unadapted`
-----------------
.. function:: unadapted(obj)

    Return an unadapted object from what might be an adapter.
    
    :param obj:
        is the object, which may be an adapter.
    :return:
        the unadapted object.
