dip.model

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

Adapter

class dip.model.Adapter

Base class: Model

The Adapter class is the base class for all adapters.

adaptee = Any()

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

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

Parameters:adaptee – is the object to be adapted. Returns:True if the object can be adapted. This default implementation always returns True.

Any

class dip.model.Any

Base class: ValueTypeFactory

The Any class encapsulates any Python object.

__init__(default=None, allow_none=True, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – the default value of the object.
• allow_none – True if None is a valid value. The default is True.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate an object according to the constraints. An exception is raised if the object is invalid.

Parameters:value – the object to validate. Returns:the validated object.

AttributeChange

class dip.model.AttributeChange

Base class: 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 observe().

model = Instance(Model)

The model containing the changed attribute.

name = Str()

The name of the changed 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.

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.

Bool

class dip.model.Bool

Base class: ValueTypeFactory

The Bool class encapsulates a Python bool.

__init__(default=False, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – is the default value of the bool.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate a bool according to the constraints. An exception is raised if the bool is invalid.

Parameters:value – the bool to validate. Returns:the validated bool.

Callable

class dip.model.Callable

Base class: ValueTypeFactory

The Callable class encapsulates any callable object.

__init__(default=None, allow_none=True, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – is the default value of the callable.
• allow_none – True if None is a valid value. The default is True.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate an object according to the constraints. An exception is raised if the object is invalid.

Parameters:value – the object to validate. Returns:the validated object.

ChangeTrigger

class dip.model.ChangeTrigger

Base class: QObject

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

changed = pyqtSignal(object)

The signal that is emitted when an attribute is changed.

CollectionTypeFactory

class dip.model.CollectionTypeFactory

Base class: ValueTypeFactory

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

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

Parameters:

• type_specification – the type specification to resolve.
• context – is the context in which the type is used and is only used in the text of exceptions.
• allow_none – is True if the type specification can be None.

Returns:

the resolved type.

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

Parameters:

• collection_type – is the type associated with the collection.
• other – is the type to validate.
• context – is the context in which the type is used and is only used in the text of exceptions.

classmethod validate_collection_value(contained_type, value)

Validate a value contained in a collection. An exception is raised if the value is invalid.

Parameters:

• contained_type – is the Python type or ValueTypeFactory sub-class that is the value is expected to be.
• value – is the value to validate.

Returns:

the validated value.

DelegatedTo

class dip.model.DelegatedTo

Base class: ValueTypeFactory

The DelegatedTo class implements a delegate for another typed attribute.

__init__(to, **metadata)

Initialise the object.

Parameters:

• to – is the attribute path of the attribute to delegate to.
• **metadata – is additional meta-data stored with the type.

__get__(instance, owner)

Reimplemented to get the real value from the instance.

__set__(instance, value)

Reimplemented to validate the value before setting it.

copy()

Create a copy of this instance.

Returns:the copied instance.

delegates_to(instance)

Get the containing model and name of the attribute that the delegate is acting for.

Parameters:instance – is the DelegatedTo instance. Returns:a tuple of the containing model and the name of the attribute.

validate(value)

Validate a value. This is only called to validate the default value which is a dummy.

Parameters:value – the value to validate. Returns:the validated value.

Dict

class dip.model.Dict

Base class: MutableTypeFactory

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

__init__(key_type=None, value_type=None, default=<object object at 0x1004530f0>, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• 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.
• 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.
• default – is the default value of the dictionary. If is it omitted then an empty dictionary is the default.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

get_default_value()

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

Returns:a copy of the default value.

validate(value)

Validate a dictionary according to the constraints. An exception is raised if the dictionary is invalid.

Parameters:value – the dictionary to validate. Returns:the validated dictionary.

validated_dict(value)

Return a dictionary containing validated keys and values.

Parameters:value – the dictionary of (possibly) invalid keys and values. Returns:a corresponding dictionary of validated keys and values.

Enum

class dip.model.Enum

Base class: ValueTypeFactory

The Enum class encapsulates a fixed set of string values.

__init__(*members, default=None, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• *members – the list of members.
• default – the default attribute value. If omitted then the first member is used.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

validate(value)

Validate an object according to the constraints. An exception is raised if the object is invalid.

Parameters:value – the object to validate. Returns:the validated object.

Float

class dip.model.Float

Base class: ValueTypeFactory

The Float class encapsulates a Python float.

__init__(default=0.0, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – the default value of the integer.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate a float according to the constraints. An exception is raised if the float is invalid.

Parameters:value – the float to validate. Returns:the validated float.

Instance

class dip.model.Instance

Base class: CollectionTypeFactory

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

__init__(*types, default=None, allow_none=True, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• *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.
• default – the default attribute value. If omitted then None is used.
• allow_none – True if None is a valid value. The default is True.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

classmethod different(value1, value2)

Reimplemented to compare two instances to see if they are different.

Parameters:

• value1 – is the first value.
• value2 – is the second value.

Returns:

True if the values are different.

validate(value)

Validate an instance according to the constraints. An exception is raised if the instance is invalid.

Parameters:value – the instance to validate. Returns:the validated instance.

Int

class dip.model.Int

Base class: ValueTypeFactory

The Int class encapsulates a Python integer.

__init__(default=0, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – the default value of the integer.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate an integer according to the constraints. An exception is raised if the integer is invalid.

Parameters:value – the integer to validate. Returns:the validated integer.

Interface

class dip.model.Interface

The Interface class is the base class for all interfaces. A class is shown to implement an interface by decorating it with 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 adapter is returned that adapts the object to the interface. An exception is raised if an appropriate adapter could not be found.

List

class dip.model.List

Base class: MutableTypeFactory

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

__init__(element_type=None, default=<object object at 0x100453100>, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• 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.
• default – is the default value of the list. If is it omitted then an empty list is the default.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

get_default_value()

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

Returns:a copy of the default value.

validate(value)

Validate a list according to the constraints. An exception is raised if the list is invalid.

Parameters:value – the list to validate. Returns:the validated list.

validated_list(value)

Return a list containing validated elements.

Parameters:value – the list of (possibly) invalid elements. Returns:a corresponding list of validated elements.

MappingProxy

class dip.model.MappingProxy

The MappingProxy class implements a 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.

static __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.

MetaInterface

class dip.model.MetaInterface

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

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

Parameters:

• obj – is the object that may need adapting.
• 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.
• cache – is True if any adapter that is created is cached so that the same adapter is returned next time one is needed.
• exception – is True if an exception should be raised if an adapter would be needed but an appropriate one could not be found.
• 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.

Returns:

an object, possibly an adapter, that implements the interface.

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

__subclasscheck__(subclass)

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

MetaModel

class dip.model.MetaModel

Base class: pyqtWrapperType

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

__call__(*args, **kwargs)

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

static __new__(meta_cls, name, bases, cls_dict)

Reimplemented to create the type cache.

MetaSingleton

class dip.model.MetaSingleton

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

__call__(*args, **kwargs)

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

__getattr__(name)

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

Model

class dip.model.Model

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

MutableTypeFactory

class dip.model.MutableTypeFactory

Base class: CollectionTypeFactory

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

bind(model, value, rebind=False)

This is called when a model attribute is being bound or rebound.

Parameters:

• model – is the model.
• value – is the attribute’s new value.
• rebind – is set if the attribute already has a value.

Set

class dip.model.Set

Base class: MutableTypeFactory

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

__init__(element_type=None, default=<object object at 0x100453110>, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• 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.
• default – is the default value of the set. If is it omitted then an empty set is the default.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

get_default_value()

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

Returns:a copy of the default value.

validate(value)

Validate a set according to the constraints. An exception is raised if the set is invalid.

Parameters:value – the set to validate. Returns:the validated set.

validated_set(value)

Return a set containing validated elements.

Parameters:value – the set of (possibly) invalid elements. Returns:a corresponding set of validated elements.

Singleton

class dip.model.Singleton

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

instance = Any()

The managed instance.

singleton = None

The singleton.

Str

class dip.model.Str

Base class: ValueTypeFactory

The Str class encapsulates a Python string.

__init__(default='', allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• default – the default value of the string.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

validate(value)

Validate a string according to the constraints. An exception is raised if the string is invalid.

Parameters:value – the string to validate. Returns:the validated string.

Subclass

class dip.model.Subclass

Base class: CollectionTypeFactory

The Subclass class encapsulates any type object.

__init__(type, default=None, allow_none=True, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

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

copy()

Create a copy of this instance.

Returns:the copied instance.

classmethod different(value1, value2)

Reimplemented to compare two sub-classes to see if they are different.

Parameters:

• value1 – is the first value.
• value2 – is the second value.

Returns:

True if the values are different.

validate(value)

Validate an object according to the constraints. An exception is raised if the object is invalid.

Parameters:value – the object to validate. Returns:the validated object.

Trigger

class dip.model.Trigger

Base class: 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).

__init__(**metadata)

Initialise the object.

Parameters:**metadata – is additional meta-data stored with the type.

__set__(instance, value)

Reimplemented to pull the trigger.

Tuple

class dip.model.Tuple

Base class: CollectionTypeFactory

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

__init__(element_type=None, default=<object object at 0x100453120>, allow_none=False, getter=None, setter=None, **metadata)

Initialise the object.

Parameters:

• 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.
• default – is the default value of the tuple. If is it omitted then an empty tuple is the default.
• allow_none – True if None is a valid value. The default is False.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• **metadata – is additional meta-data stored with the type.

copy()

Create a copy of this instance.

Returns:the copied instance.

validate(value)

Validate a tuple according to the constraints. An exception is raised if the tuple is invalid.

Parameters:value – the tuple to validate. Returns:the validated tuple.

TypeFactory

class dip.model.TypeFactory

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

__init__(metadata)

Initialise the object.

Parameters:metadata – is a dictionary of additional meta-data stored with the type.

__delete__(instance)

Raise an exception as attributes cannot be deleted.

__get__(instance, owner)

Raise an exception as there is no value to get.

__set__(instance, value)

This must be reimplemented by a sub-class.

clone()

Create a clone of this instance.

Returns:the cloned instance.

ValidationError

exception dip.model.ValidationError

Base exception: TypeError

The ValidationError exception is raised when a value is invalid.

ValidationTypeError

exception dip.model.ValidationTypeError

Base exception: ValidationError

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

ValueTypeFactory

class dip.model.ValueTypeFactory

Base class: TypeFactory

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

__init__(default, allow_none, getter, setter, metadata)

Initialise the object.

Parameters:

• default – is the default value of the type.
• allow_none – True if None is a valid value.
• getter – is the optional attribute getter.
• setter – is the optional attribute setter.
• metadata – is a dictionary of additional meta-data stored with the type.

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

__get__(instance, owner)

Reimplemented to get the real value from the instance.

__set__(instance, value)

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

bind(model, value, rebind=False)

This is called when a model attribute is being bound or rebound.

Parameters:

• model – is the model.
• value – is the attribute’s new value.
• rebind – is set if the attribute already has a value.

clone()

Create a clone of this instance.

Returns:the cloned instance.

copy()

Create a copy of this instance. This implementation is suitable for types that don’t have any additional data.

Returns:the copied instance.

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 different(value1, value2)

Compare two valid values to see if they are different.

Parameters:

• value1 – is the first value.
• value2 – is the second value.

Returns:

True if the values are different.

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.

Returns:the default value.

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.

set_default_value(default)

Set the type’s default value.

Parameters:default – is the new default value.

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.

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.

Parameters:value – the value to validate. Returns:the validated value (which may be normalised in some way).

adapt()

dip.model.adapt(*adapted, to)

A class decorator that marks one or more classes, which must be sub-classes of Adapter, as being able to adapt an object to one or more interfaces. An instance of the adapter will be automatically created when required. Like the implements() class decorator any attributes of the interfaces that are not already present in the adapter are automatically added.

Parameters:

• *adapted – is the list of types of object to be adapted.
• to – is the interface (or list of interfaces) that the object is adapted to.

clone_model()

dip.model.clone_model(model)

Create a clone of a model. Note that individual attributes are not recursively cloned.

Parameters:model – is the Model instance. Returns:the clone.

get_attribute_type()

dip.model.get_attribute_type(model, name)

Get the TypeFactory sub-class instance for an attribute of a model.

Parameters:

• model – is the Model instance.
• name – is the name of the attribute (and may not be an attribute path..

Returns:

the attribute’s type object.

get_attribute_types()

dip.model.get_attribute_types(model, attribute_type_type=None)

Get the TypeFactory sub-class instances for all attributes of a model.

Parameters:

• model – is the model
• attribute_type_type – is the optional TypeFactory sub-class. If this is specified then only attributes of this type will be returned.

Returns:

the list of attribute types.

get_change_trigger()

dip.model.get_change_trigger(model, name)

Get the change trigger for an attribute of a model.

Parameters:

• model – is the Model instance.
• name – is the name of the attribute in the model.

Returns:

the ChangeTrigger instance or None if the attribute is not being observed.

get_model_types()

dip.model.get_model_types(model_type)

Get a copy of the dictionary of TypeFactory sub-class instances, keyed by attribute name, for a model type.

Parameters:model_type – is the Model sub-class. Returns:the dictionary of type objects.

implements()

dip.model.implements(*interfaces)

A class decorator that marks the class as implementing one or more interfaces. If a class implements an interface then issubclass() will return True when tested against the interface, 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.

Parameters:*interfaces – are the interfaces that the class implements.

isadapted()

dip.model.isadapted(adaptee, interface)

See if an object has been adapted to an interface.

Parameters:

• adaptee – is the object.
• interface – is the interface.

Returns:

True if the object has been adapted to the interface.

notify_observers()

dip.model.notify_observers(name, model, new, old)

Notify any observers about a change to the value of an attribute of a model.

Parameters:

• name – is the name of the attribute in the model.
• model – is the Model instance.
• new – is the new value of the attribute.
• old – is the old value of the attribute.

observe()

dip.model.observe(name, model=<object object at 0x1004530e0>, observer=<object object at 0x1004530e0>, 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.

Parameters:

• name – is the name of the attribute in the model to observe. This may be an attribute path. If the last part of the name is ‘*’ then all the attributes are observed.
• model – is the Model instance. This must not be specified when used as a decorator.
• observer – is the callable that is called when the attribute’s value changes. The observer is passed an AttributeChange instance as its argument. This must not be specified when used as a decorator.
• remove – is set if the observer is to be removed.

resolve_attribute_path()

dip.model.resolve_attribute_path(name, model)

Return the sub-model and name referenced by an attribute path.

Parameters:

• name – is the name of the attribute and may be an attribute path.
• model – is the model.

Returns:

the attribute name (which will not be an attribute path) and the sub-model.