dip.io

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

Most of the functionality provided by the module is used by the rest of dip.

Applications will, typically, only need to define an implementation of the ICodecsFactory interface for the data the application wants to store. The dip.io.codecs module contains an appropriate XML decoder and encoder which do much of the work if the data is to be stored as XML and is implemented as a Model.

dip includes support for using the filesystem as storage. Some applications or environments may also need to define additional types of storage. This is done by providing appropriate implementations of the IStreamingStorageFactory or IStructuredStorageFactory interfaces.

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.

ICodecsFactory

class dip.io.ICodecsFactory

Base class: IFormat

The ICodecsFactory interface defines the API of factories that create object decoders and encoders.

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

A new instance of the object decoder is created and returned.

Returns:an implementation of IDecoder.
encoder()

A new instance of the object encoder is created and returned.

Returns:an implementation of IEncoder.

IDecoder

class dip.io.IDecoder

Base class: Interface

The IDecoder interface defines the API of an object decoder.

factory = Instance(ICodecsFactory)
The codecs factory that created this decoder.
decode(obj, source, location)

An object is decoded from a byte stream.

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

the decoded object. This may be the original object populated from the byte stream, or it may be a different object (of an appropriate type) created from the byte stream.

IEncoder

class dip.io.IEncoder

Base class: Interface

The IEncoder interface defines the API of an object encoder.

factory = Instance(ICodecsFactory)
The codecs factory that created this encoder.
encode(obj, location)

An object is encoded as a byte stream. This should be implemented as a generator as it will be called in a loop. This allows large objects to be encoded without requiring the whole byte stream to be held in memory.

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

the next section of the encoded byte stream.

IFormat

class dip.io.IFormat

Base class: Interface

The IFormat interface is implemented by objects that need to impose a format on an object to see if the object can be stored.

id = Str()
The identifier of the format.
name = Str()
The name of the format.
decodes(obj)

Determines if an object can be decoded from this format.

Parameter:obj – is the object.
Returns:True if the object can be decoded from this format.
encodes(obj)

Determines if an object can be encoded to this format.

Parameter:obj – is the object.
Returns:True if the object can be encoded to this format.

IIOManager

class dip.io.IIOManager

Base class: Interface

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

codecs_factories = List(ICodecsFactory)
The available codecs factories.
policy = Instance(IStoragePolicy)
The policy that determines if an object is allowed to be stored in persistent storage represented by a particular implementation of IStorage.
storage_factories = List(IStorageFactory)
The available storage factories.
readable_storage(obj, exclude_format=None, include_format=None, storage_factories=None)

Get the list of the storage instances that an object can be read from.

Parameters:
  • obj – is the object.
  • exclude_format – is the optional identifier of a format that will be used to exclude factories that can handle it.
  • include_format – is the optional identifier of a format that will be used to include factories that can handle it.
  • storage_factories – is the optional list of storage factories that are considered. If it is None then all storage factories are considered.
Returns:

the list of storage instances.

storage_factories_for_location(location)

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

Parameter:location – is the location as a string.
Returns:the list of storage factories.
writeable_storage(obj, exclude_format=None, include_format=None, storage_factories=None)

Get the list of the storage instances that an object can be written to.

Parameters:
  • obj – is the object.
  • exclude_format – is the optional identifier of a format that will be used to exclude factories that can handle it.
  • include_format – is the optional identifier of a format that will be used to include factories that can handle it.
  • storage_factories – is the optional list of storage factories that are considered. If it is None then all storage factories are considered.
Returns:

the list of storage instances.

IStorage

class dip.io.IStorage

Base class: Interface

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

factory = Instance(IStorageFactory)
The storage factory that created this storage.
ui = Instance(IStorageUi)
The user interface used to obtain storage locations from the user.
explicit_location(location='')

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

Parameter:location – is the location as a string. The string may be empty, but otherwise should be valid for the storage.
Returns:the IStorageLocation instance or None if the storage does not have explicit storage locations.
implicit_location(obj)

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

Parameter:obj – is the object to create the location for.
Returns:the location or None if the storage does not have implicit storage locations.
read(obj, location)

Read an object from a storage location.

Parameters:
  • obj – is the object to populate from the storage location.
  • location – is the storage location where the object is read from.
Returns:

the read object. This may be the original object populated from the storage location, or it may be a different object (of an appropriate type) created from the storage location.

write(obj, location)

Write an object to a storage location.

Parameters:
  • obj – is the object to write.
  • location – is the storage location where the object is written to.

IStorageFactory

class dip.io.IStorageFactory

Base class: Interface

The IStorageFactory interface defines the API of storage factories.

__call__()

A new instance of the storage is created and returned.

Returns:a new instance of the storage.
valid_location(location)

Check if a location specified as a string is valid for this storage.

Parameter:location – is the location as a string.
Returns:True if the location is valid.

IStorageLocation

class dip.io.IStorageLocation

Base class: Interface

The IStorageLocation interface defines the API of a storage location.

location = Str()
The string representation of the location as seen by the user. It must be unique for a particular location and be updated when the location changes.
storage = Instance(IStorage)
The storage that the location refers to.

IStoragePolicy

class dip.io.IStoragePolicy

Base class: Interface

The IStoragePolicy interface defines the API of a storage policy.

__call__(obj, storage)

The policy determines if an object is allowed to be stored in a particular type of storage.

Parameters:
  • obj – is the object to be stored.
  • storage – is the IStorageFactory implementation for the storage that can store the object, but may not be allowed to.
Returns:

True if the object is allowed to be stored.

IStorageUi

class dip.io.IStorageUi

Base class: Interface

The IStorageUi interface defines the API used to implement the user interface that selects an explicit storage location.

storage = Instance(dip.io.IStorage)
The storage that this is the user interface for.
get_read_location(toolkit, location)

Get an updated location from the user where an object should be read from.

Parameters:
  • toolkit – is the IToolkit implementation that can be used to create any user interface.
  • location – is the location that is updated by the user. If the user cancelled then its location attribute is set to an empty string.
get_write_location(toolkit, location)

Get an updated location from the user where an object should be written to.

Parameters:
  • toolkit – is the IToolkit implementation that can be used to create any user interface.
  • location – is the location that is updated by the user. If the user cancelled then its location attribute is set to an empty string.
read_browser(toolkit, location)

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

Parameters:
  • toolkit – is the IToolkit implementation that can be used to create the browser.
  • location – is the location that is updated by the user.
Returns:

the QWidget that implements the browser.

write_browser(toolkit, location)

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

Parameters:
  • toolkit – is the IToolkit implementation that can be used to create the browser.
  • location – is the location that is updated by the user.
Returns:

the QWidget that implements the browser.

IStreamingStorage

class dip.io.IStreamingStorage

Base class: IStorage

The IStreamingStorage interface defines the API of streaming storage.

codecs_factory = Instance(ICodecsFactory)
The factory used to create the decoder and encoder that converts an object from and to a stream of bytes.

IStreamingStorageFactory

class dip.io.IStreamingStorageFactory

Base class: IStorageFactory

The IStreamingStorageFactory interface defines the API of streaming storage factories.

name = Str()
The name of the storage.

IStructuredStorage

class dip.io.IStructuredStorage

Base class: IStorage

The IStructuredStorage interface defines the API of structured storage.

IStructuredStorageFactory

class dip.io.IStructuredStorageFactory

Base classes: IStorageFactory, IFormat

The IStorageFactory interface defines the API of structured storage factories.

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.