The dip.io module implements the infrastructure for defining and interfacing with storage.
Plugins must provide appropriate support for the following extension points:
Base class: Model
The BaseStorage storage class is an optional base class for implementations of IStorage.
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: |
|
---|---|
Returns: | the codec. |
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: |
|
---|---|
Returns: | the codec. |
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.
Base class: Interface
The ICodec interface defines the API of codecs.
A model is decoded from a byte stream.
Parameters: |
|
---|---|
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. |
A model is encoded as a byte stream.
Parameters: |
|
---|---|
Returns: | a generator that will return sections of the encoded byte stream. |
Base class: Interface
The IIoManager interface defines the API of an i/o manager.
Read a model from a location using a particular format.
Parameters: |
|
---|---|
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. |
Get the list of readable storage location instances for which a location specified as a string is valid.
Parameters: |
|
---|---|
Returns: | the list of storage location instances. |
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 a model to a location using a particular format.
Parameters: |
|
---|
Get the list of writeable storage location instances for which a location specified as a string is valid.
Parameters: |
|
---|---|
Returns: | the list of storage location instances. |
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. |
Base class: Interface
The IIoManagerUi interface defines the API that implements the various storage-independent user interfaces.
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. |
Ask the user to provide a readable storage location.
Parameters: |
|
---|---|
Returns: | the storage location or None if the user declined to provide one. |
Create a wizard page factory for asking the user to select from a list of readable storage.
Parameters: |
|
---|---|
Returns: | the wizard page factory. |
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. |
Ask the user to provide a writeable storage location.
Parameters: |
|
---|---|
Returns: | the storage location or None if the user declined to provide one. |
Create a wizard page factory for asking the user to select from a list of writeable storage.
Parameters: |
|
---|---|
Returns: | the wizard page factory. |
Base class: Interface
The IStorage interface defines the API of a particular type of storage.
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. |
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 a model from a storage location.
Parameters: |
|
---|---|
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. |
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 a model to a storage location.
Parameters: |
|
---|
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. |
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.
Base class: Interface
The IStorageFactory interface defines the API of a factory for creating implementations of IStorage.
Create a storage instance.
Parameter: | codecs – is the list of codecs that can be used by the storage. |
---|---|
Returns: | the storage instance. |
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.
Return a string representation of the location. This must be able to be parsed by an implementation of valid_location().
Returns: | the string representation. |
---|
Base class: Interface
The IStorageUi interface defines the API that implements the various storage specific user interfaces.
Get a new location from the user to read from.
Parameters: |
|
---|---|
Returns: | the new location or None if the user cancelled. |
Get a new location from the user to write to.
Parameters: |
|
---|---|
Returns: | the new location or None if the user cancelled. |
Create view that allows the user to browse storage and select a read location.
Parameters: |
|
---|---|
Returns: | the view which must implement, or be adapted to, IStorageBrowser. |
Create view that allows the user to browse storage and select a write location.
Parameters: |
|
---|---|
Returns: | the view which must implement, or be adapted to, IStorageBrowser. |
Base class: IStorageFactory
The IStreamingStorageFactory interface defines the API of a factory that creates an instance of streaming storage.
Base classes: IStorageFactory, ICodec
The IStructuredStorageFactory interface defines the API of a factory that creates an instance of structured storage.
Base class: Singleton
The IoManager class is a singleton that provides access to a default i/o manager.
Base exception: Exception
The StorageError class is an exception raised when there is an error accessing a particular storage location.