dip.model

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

The core of the module is the Model class. Sub-classes define attributes as class attributes using model type classes such as Bool and 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 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 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.

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.

Any

class dip.model.Any

Base class: ValueTypeFactory

The Any class encapsulates any Python object.

__init__(default=None, **metadata)

Initialise the object.

Parameters:
  • default – the default value of the object.
  • **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.

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • default – is the default value of the bool.
  • **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.

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • default – is the default value of the callable.
  • **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.

Parameter: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')

Resolve a type specification which is either 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.
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(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied instance.
Returns:the copied instance.
delegates_to(instance)

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

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

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

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.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied 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.

Parameter:value – the dictionary to validate.
Returns:the validated dictionary.
validated_dict(value)

Return a dictionary containing validated keys and values.

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • *members – the list of members.
  • default – the default attribute value. If omitted then the first member is used.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied instance.
Returns:the copied instance.
validate(value)

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

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • default – the default value of the integer.
  • **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.

Parameter: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, **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.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied 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.

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • default – the default value of the integer.
  • **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.

Parameter: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=<dip.model.any.Any object at 0x2a4be50>, default=<object object at 0x26b2ae0>, **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.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied 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.

Parameter:value – the list to validate.
Returns:the validated list.
validated_list(value)

Return a list containing validated elements.

Parameter: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, exception=True)

This is called to create an instance of an object that implements an interface we are the meta-class of.

Parameters:
  • obj – is the object that may need adapting.
  • 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.
Returns:

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

__instancecheck__(instance)
Reimplemented to ensure that isinstance() treats an instance that implements an interface as being an instance of that interface.
__subclasscheck__(subclass)
Reimplemented to ensure that issubclass() treats a class that 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.

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=<dip.model.any.Any object at 0x2a55c90>, default=<object object at 0x26b2b90>, **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.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied 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.

Parameter:value – the set to validate.
Returns:the validated set.
validated_set(value)

Return a set containing validated elements.

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

Str

class dip.model.Str

Base class: ValueTypeFactory

The Str class encapsulates a Python string.

__init__(default='', **metadata)

Initialise the object.

Parameters:
  • default – the default value of the string.
  • **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.

Parameter: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, **metadata)

Initialise the object.

Parameters:
  • type – is the type object.
  • default – the default attribute value. If omitted then None is used.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied 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.

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

Parameter:**metadata – is additional meta-data stored with the type.
__set__(instance, value)
Reimplemented to pull the 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.

Tuple

class dip.model.Tuple

Base class: CollectionTypeFactory

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

__init__(element_type=<dip.model.any.Any object at 0x2a60210>, default=<object object at 0x26b2b70>, **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.
  • **metadata – is additional meta-data stored with the type.
copy(default)

Create a copy of this instance with a different default value.

Parameter:default – is the default value of the copied instance.
Returns:the copied instance.
validate(value)

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

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

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

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, metadata)

Initialise the object.

Parameters:
  • default – is the default value of the type.
  • 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(default)

Create a clone of this instance with a different default value.

Parameter:default – is the default value of the cloned instance.
Returns:the cloned instance.
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.

Parameter:default – is the default value of the cloned instance.
Returns:the cloned 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.
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.
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 in a sub-class.

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

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

the attribute’s type object.

get_change_trigger()

dip.model.get_change_trigger(model, name)

Get the change trigger for an attribute of a model. Types can decide not to generate AttributeChange instances if an attribute is not being observed.

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.

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

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

observe()

dip.model.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.

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.
  • connection_type – is the type of the underlying Qt connection.
  • remove – is set if the observer is to be removed.