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

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

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

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

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

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

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__(codecs)¶

Create a storage instance.

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

`dip.io`¶

`BaseStorage`¶

`FormatError`¶

`ICodec`¶

`IFilterHints`¶

`IIoManager`¶

`IIoManagerUi`¶

`IStorage`¶

`IStorageBrowser`¶

`IStorageFactory`¶

`IStorageLocation`¶

`IStorageUi`¶

`IStreamingStorageFactory`¶

`IStructuredStorageFactory`¶

`IoManager`¶

`StorageError`¶

Table Of Contents

Previous topic

Next topic

This Page