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.
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: IFormat
The ICodecsFactory interface defines the API of factories that create object decoders and encoders.
Base class: Interface
The IDecoder interface defines the API of an object decoder.
An object is decoded from a byte stream.
Parameters: |
|
---|---|
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. |
Base class: Interface
The IEncoder interface defines the API of an object encoder.
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: |
|
---|---|
Returns: | the next section of the encoded byte stream. |
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.
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. |
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. |
Base class: Interface
The IIOManager interface defines the API of an i/o manager.
Get the list of the storage instances that an object can be read from.
Parameters: |
|
---|---|
Returns: | the list of storage instances. |
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. |
Get the list of the storage instances that an object can be written to.
Parameters: |
|
---|---|
Returns: | the list of storage instances. |
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 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. |
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 an object from a storage location.
Parameters: |
|
---|---|
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 an object to a storage location.
Parameters: |
|
---|
Base class: Interface
The IStorageFactory interface defines the API of storage factories.
A new instance of the storage is created and returned.
Returns: | a new instance of the storage. |
---|
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. |
Base class: Interface
The IStorageLocation interface defines the API of a storage location.
Base class: Interface
The IStoragePolicy interface defines the API of a storage policy.
The policy determines if an object is allowed to be stored in a particular type of storage.
Parameters: |
|
---|---|
Returns: | True if the object is allowed to be stored. |
Base class: Interface
The IStorageUi interface defines the API used to implement the user interface that selects an explicit storage location.
Get an updated location from the user where an object should be read from.
Parameters: |
|
---|
Get an updated location from the user where an object should be written to.
Parameters: |
|
---|
Create a widget that allows the user to browse the storage and select a read location.
Parameters: |
|
---|---|
Returns: | the QWidget that implements the browser. |
Create a widget that allows the user to browse the storage and select a write location.
Parameters: |
|
---|---|
Returns: | the QWidget that implements the browser. |
Base class: IStorage
The IStreamingStorage interface defines the API of streaming storage.
Base class: IStorageFactory
The IStreamingStorageFactory interface defines the API of streaming storage factories.
Base class: IStorage
The IStructuredStorage interface defines the API of structured storage.
Base classes: IStorageFactory, IFormat
The IStorageFactory interface defines the API of structured storage factories.
Base exception: Exception
The StorageError class is an exception raised when there is an error accessing a particular storage location.