dip.io

The dip.io module implements the infrastructure for defining and interfacing with storage.

Plugins must provide appropriate support for the following extension points:

dip.io.codecs
This must be supported by any plugin that configures an object implementing the dip.io.IIoManager interface. A contribution must implement the dip.io.ICodec interface.
dip.io.storage_factories
This must be supported by any plugin that configures an object implementing the dip.io.IIoManager interface. A contribution must implement the dip.io.IStorageFactory interface.
dip.io.storage_policies
This must be supported by any plugin that configures an object implementing the dip.io.IIoManager interface. A contribution must be a callable.

BaseStorage

class dip.io.BaseStorage

Base class: Model

The BaseStorage storage class is an optional base class for implementations of IStorage.

decoder_for_model(model, location)

Returns one of the storage’s codecs that can be used to decode a model. An exception is raised if there is no suitable codec.

Parameters:
  • model – is the model.
  • location – is the location. This is only used in exceptions.
Returns:

the codec.

encoder_for_model(model, location)

Returns one of the storage’s codecs that can be used to encode a model. An exception is raised if there is no suitable codec.

Parameters:
  • model – is the model.
  • location – is the location. This is only used in exceptions.
Returns:

the codec.

FormatError

exception dip.io.FormatError

Base exception: StorageError

The FormatError class is an exception raised when there is an error decoding or encoding an object at a particular storage location.

ICodec

class dip.io.ICodec

Base class: Interface

The ICodec interface defines the API of codecs.

decoder_interface = Subclass(Interface)
The interface that a model must implement. It is None if there is no decoder.
encoder_interface = Subclass(Interface)
The interface that a model must implement. It is None if there is no encoder.
format = Str()
The identifier of the format.
decode(model, source, location)

A model is decoded from a byte stream.

Parameters:
  • model – is the model.
  • source – is an iterator that will return the byte stream to be decoded.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.
Returns:

the decoded model. This may be the original model populated from the storage location, or it may be a different model (of an appropriate type) created from the storage location. If None is returned then it is assumed that the decoding was abandoned and the user informed appropriately.

encode(model, location)

A model is encoded as a byte stream.

Parameters:
  • model – is the model.
  • location – is the storage location where the encoded model will be written to. It is mainly used for error reporting.
Returns:

a generator that will return sections of the encoded byte stream.

IFilterHints

class dip.io.IFilterHints

Base class: Interface

The IFilterHints interface defines hints provided by a model to storage regarding filters, typically used to select files with particular extension names.

filter = Str()
The filter string in the format used by QFileDialog.

IIoManager

class dip.io.IIoManager

Base class: Interface

The IIoManager interface defines the API of an i/o manager.

codecs = List(ICodec)
The available codecs.
storage_factories = List(IStorageFactory)
The available storage factories.
storage_policies = List(Callable())
The storage policies that determines if a format is allowed to be written to or read from storage represented by a particular implementation of IStorage. Each policy is called with the format identifier and the storage as arguments. A policy should return True if the access is allowed. All policies must return True for the access to proceed.
ui = Instance(IIoManagerUi)
The storage-independent user interfaces.
read(model, location, format)

Read a model from a location using a particular format.

Parameters:
  • model – is the model.
  • location – is the location as a string. This should identify a valid and unambiguous storage location.
  • format – is the format.
Returns:

the read model. This may be the original model populated from the storage location, or it may be a different model (of an appropriate type) created from the storage location. If None is returned then it is assumed that the read was abandoned and the user informed appropriately.

readable_locations_from_string(location, format='')

Get the list of readable storage location instances for which a location specified as a string is valid.

Parameters:
  • location – is the location as a string.
  • format – is the identifier of the optional format.
Returns:

the list of storage location instances.

readable_storage(format='')

Get the list of the storage instances that can be read from using a particular format.

Parameter:format – is the identifier of the optional format.
Returns:the list of storage instances.
write(model, location, format)

Write a model to a location using a particular format.

Parameters:
  • model – is the model.
  • location – is the location as a string. This should identify a valid and unambiguous storage location.
  • format – is the format.
writeable_locations_from_string(location, format='')

Get the list of writeable storage location instances for which a location specified as a string is valid.

Parameters:
  • location – is the location as a string.
  • format – is the identifier of the optional format.
Returns:

the list of storage location instances.

writeable_storage(format='')

Get the list of the storage instances that can be written to using a particular format.

Parameter:format – is the identifier of the optional format.
Returns:the list of storage instances.

IIoManagerUi

class dip.io.IIoManagerUi

Base class: Interface

The IIoManagerUi interface defines the API that implements the various storage-independent user interfaces.

choose_storage_title = Str()
The text of the title used in the wizard pages asking the user to choose a storage location.
choose_readable_location_subtitle = Str()
The text of the sub-title used in the wizard page asking the user to choose a readable storage location.
choose_readable_storage_subtitle = Str()
The text of the sub-title used in the wizard page asking the user to choose some readable storage.
choose_storage_title = Str()
The text of the title used in the wizard pages asking the user to choose some storage.
choose_readable_location_subtitle = Str()
The text of the sub-title used in the wizard page asking the user to choose a writeable storage location.
choose_writeable_storage_subtitle = Str()
The text of the sub-title used in the wizard page asking the user to choose some writeable storage.
io_manager = Instance(.IIoManager)
The i/o manager that this is the user interface for.
readable_location_wizard_page(id='')

Create a wizard page factory for asking the user to provide a readable storage location.

Parameter:id – is the optional identifier of the page.
Returns:the wizard page factory. The page’s view will be an implementation of IViewStack.
readable_storage_location(window_title, default_location=None, format='', hints=None, parent=None)

Ask the user to provide a readable storage location.

Parameters:
  • window_title – is the window title to use in any wizards and dialogs.
  • storage_list – is the storage from which the use may choose. If it is not specified then a list of all available readable storage is used.
  • default_location – is the optional default location.
  • format – is the identifier of the optional format.
  • hints – is an optional source of hints.
  • parent – is the optional parent view.
Returns:

the storage location or None if the user declined to provide one.

readable_storage_wizard_page(bind_to, storage_list=None, id='')

Create a wizard page factory for asking the user to select from a list of readable storage.

Parameters:
  • bind_to – is the attribute of the model containing the selected storage.
  • storage_list – is the optional list of available readable storage.
  • id – is the optional identifier of the page.
Returns:

the wizard page factory.

writeable_location_wizard_page(id='')

Create a wizard page factory for asking the user to provide a writeable storage location.

Parameter:id – is the optional identifier of the page.
Returns:the wizard page factory. The page’s view will be an implementation of IViewStack.
writeable_storage_location(window_title, default_location=None, format='', hints=None, parent=None)

Ask the user to provide a writeable storage location.

Parameters:
  • window_title – is the window title to use in any wizards and dialogs.
  • default_location – is the optional default location.
  • format – is the identifier of the optional format.
  • hints – is an optional source of hints.
  • parent – is the optional parent view.
Returns:

the storage location or None if the user declined to provide one.

writeable_storage_wizard_page(bind_to, storage_list=None, id='')

Create a wizard page factory for asking the user to select from a list of writeable storage.

Parameters:
  • bind_to – is the attribute of the model containing the selected storage.
  • storage_list – is the optional list of available writeable storage.
  • id – is the optional identifier of the page.
Returns:

the wizard page factory.

IStorage

class dip.io.IStorage

Base class: Interface

The IStorage interface defines the API of a particular type of storage.

codecs = List(ICodec)
The codecs that can be used.
ui = Instance(IStorageUi)
The storage-specific user interfaces.
explicit_location(location)

If the storage has explicit storage locations (i.e. a location is independent on the value of a model) then convert such a location specified as a string to an IStorageLocation instance.

Parameter:location – is the location as a string. It should be valid for the storage.
Returns:the IStorageLocation instance or None if the storage does not have explicit storage locations.
implicit_location(model)

If the storage has implicit storage locations (i.e. a location is dependent on the value of a model) then create such a location for the model.

Parameter:model – is the model.
Returns:the location or None if the storage does not have implicit storage locations.
read(model, location)

Read a model from a storage location.

Parameters:
  • model – is the model.
  • location – is the storage location where the model is read from.
Returns:

the read model. This may be the original model populated from the storage location, or it may be a different model (of an appropriate type) created from the storage location. If None is returned then it is assumed that the read was abandoned and the user informed appropriately.

readable_location(location)

Convert a location specified as a string to a readable IStorageLocation instance if possible.

Parameter:location – is the location as a string.
Returns:the IStorageLocation instance or None if the location was not valid for this storage.
write(model, location)

Write a model to a storage location.

Parameters:
  • model – is the model.
  • location – is the storage location where the model is written to.
writeable_location(location)

Convert a location specified as a string to a writeable IStorageLocation instance if possible.

Parameter:location – is the location as a string.
Returns:the IStorageLocation instance or None if the location was not valid for this storage.

IStorageBrowser

class dip.io.IStorageBrowser

Base class: Interface

The IStorageBrowser interface defines the API implemented by a view that allows the user to browse storage and select a valid storage location.

invalid_reason = Str()
This explains why the storage location is invalid. It will be an empty string if the location is valid.
location = Instance(IStorageLocation)
The storage location that the user uses the view to set.
storage = Instance(IStorage)
The storage.

IStorageFactory

class dip.io.IStorageFactory

Base class: Interface

The IStorageFactory interface defines the API of a factory for creating implementations of IStorage.

readable = Bool(True)
This is set if the storage is readable.
writeable = Bool(True)
This is set if the storage is writeable.
__call__(codecs)

Create a storage instance.

Parameter:codecs – is the list of codecs that can be used by the storage.
Returns:the storage instance.

IStorageLocation

class dip.io.IStorageLocation

Base class: Interface

The IStorageLocation interface defines the API of a storage location. Once created a storage location object will only ever refer to one specific location, i.e. a storage location object is never updated to refer to a different location.

storage = Instance(IStorage)
The storage that the location refers to.
__str__()

Return a string representation of the location. This must be able to be parsed by an implementation of valid_location().

Returns:the string representation.

IStorageUi

class dip.io.IStorageUi

Base class: Interface

The IStorageUi interface defines the API that implements the various storage specific user interfaces.

storage = Instance(.IStorage)
The storage that this is the user interface for.
get_read_location(window_title, default_location=None, hints=None, parent=None)

Get a new location from the user to read from.

Parameters:
  • window_title – is the window title, typically used as the title of a dialog.
  • default_location – is an optional default location.
  • hints – is an optional source of hints.
  • parent – is the optional parent view.
Returns:

the new location or None if the user cancelled.

get_write_location(window_title, default_location=None, hints=None, parent=None)

Get a new location from the user to write to.

Parameters:
  • window_title – is the window title, typically used as the title of a dialog.
  • default_location – is an optional default location.
  • hints – is an optional source of hints.
  • parent – is the optional parent view.
Returns:

the new location or None if the user cancelled.

read_browser(default_location=None, hints=None)

Create a view that allows the user to browse storage and select a read location.

Parameters:
  • default_location – is an optional default location.
  • hints – is an optional source of hints.
Returns:

the view which must implement, or can be adapted to, IStorageBrowser.

write_browser(default_location=None, hints=None)

Create a view that allows the user to browse storage and select a write location.

Parameters:
  • default_location – is an optional default location.
  • hints – is an optional source of hints.
Returns:

the view which must implement, or can be adapted to, IStorageBrowser.

IStreamingStorageFactory

class dip.io.IStreamingStorageFactory

Base class: IStorageFactory

The IStreamingStorageFactory interface defines the API of a factory that creates an instance of streaming storage.

IStructuredStorageFactory

class dip.io.IStructuredStorageFactory

Base classes: IStorageFactory, ICodec

The IStructuredStorageFactory interface defines the API of a factory that creates an instance of structured storage.

IoManager

class dip.io.IoManager

Base class: Singleton

The IoManager class is a singleton that provides access to a default i/o manager.

instance = Instance(IIoManager)
The i/o manager instance.

StorageError

exception dip.io.StorageError

Base exception: Exception

The StorageError class is an exception raised when there is an error accessing a particular storage location.