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.

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

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

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

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

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

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

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

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

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