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.

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.

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.
readable_locations_from_string(format, location)

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

Parameters:
  • format – is the identifier of the format.
  • location – is the location as a string.
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 format.
Returns:the list of storage instances.
writeable_locations_from_string(format, location)

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

Parameters:
  • format – is the identifier of the format.
  • location – is the location as a string.
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 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(dip.io.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, storage_list=None, default_location=None, 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.
  • 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, storage_list=None, default_location=None, 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.
  • storage_list – is the storage from which the use may choose. If it is not specified then a list of all available writeable storage is used.
  • default_location – is the optional default location.
  • 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.

codec = Instance(ICodec)
The codec to 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.

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__(codec)

Create a storage instance.

Parameter:codec – is the codec to 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(dip.io.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 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 be adapted to, IStorageBrowser.

write_browser(default_location=None, hints=None)

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