AutoArchive._infrastructure.storage — AutoArchive Developer Manual (ver. 2.0.2)

# AutoArchive._infrastructure.storage

Storage component.

Implements application’s persistent storage in a form of `FileStorage` class. It should be constructed by some infrastructure component and distributed to other components. Individual components should not instantiate it directly.

## Modules

### _file_storage

`FileStorage` class.

class AutoArchive._infrastructure.storage._file_storage.FileStorage(configuration)

  Bases: `object`

  Application’s persistent storage.

  Provides access to application’s persistent storage. Any arbitrary variables can be saved to it. Data are stored in text files.

  This storage implementation utilizes local filesystem, specifically a subdirectory of user configuration directory named `storage`. Data are stored in text files. The directory is automatically created if it does not exists. Storage content is read upon construction and cached into memory. This class does not provide any means to re-read the storage content from disk.

  Note

  This class can be instantiated only once.

  Parameters

    configuration (`IConfiguration`) – Application configuration.

  createStoragePortion(section=None, realm=None)

    Returns IStoragePortion instance set to `section` and `realm`.

    Note

    If `section` or `realm` does not exists the implementation should not create either of them right away but rather on first value save.

    Parameters

      - section (`str`) – Name of a section within a realm.

      - realm (`str`) – Name of a separate storage entity (typically represented by a file).

    Returns

      `IStoragePortion` instance

    Return type

      `IStoragePortion`

  getRealms()

    Returns all realms that exists in the storage.

    Returns

      Iterable of realm names.

    Return type

      `Iterable<str>`

  getValue(variable, section=None, realm=None)

    Returns a cached value from the persistent storage.

    Parameters

      - variable (`str`) – The name of the variable which value shall be read.

      - section (`str`) – Name of a section within a realm.

      - realm (`str`) – Name of a separate storage entity (typically represented by a file).

    Returns

      Value of the passed `variable`.

    Return type

      `str`

    Raises

      KeyError – If `variable`, `section` or `realm` does not exists.

  hasVariable(variable, section=None, realm=None)

    Returns `True` if the storage contains `variable`.

    Parameters

      - variable (`str`) – Name of the variable which presence shall be determined.

      - section (`str`) – Name of a section within a realm.

      - realm (`str`) – Name of a separate storage entity (typically represented by a file).

    Returns

      `True` if `variable` is present in the storage.

    Return type

      `bool`

  removeRealm(realm)

    Deletes the `realm` including all information that contains from the persistent storage.

    Parameters

      realm (`str`) – Name of a separate storage entity (typically represented by a file).

    Raises

      - KeyError – If `realm` does not exists.

      - OSError – If an error occurred during the operation of removing data from a physical storage.

  saveValue(variable, value, section=None, realm=None)

    Saves a value to the persistent storage.

    A value passed as `value` parameter will be saved to the persistent storage under the name passed as `variable` argument.

    Note

    A string representation of the value is saved (str(value)).

    Parameters

      - variable (`str`) – The name under which the value will be saved.

      - value (`object`) – The value that shall be saved.

      - section (`str`) – Name of a section within a realm.

      - realm (`str`) – Name of a separate storage entity (typically represented by a file).

  tryRemoveVariable(variable, section=None, realm=None)

    Removes variable from the persistent storage.

    If variable existed to be removed, returns `True`; otherwise return `False`.

    Parameters

      - variable (`str`) – The name of the variable which value shall be removed.

      - section (`str`) – Name of a section within a realm.

      - realm (`str`) – Name of a separate storage entity (typically represented by a file).

    Returns

      `True` if variable existed; `False` otherwise.

    Return type

      `bool`

    Raises

      KeyError – If `section` or `realm` does not exists.

### _storage_portion

`_StoragePortion` class.

class AutoArchive._infrastructure.storage._storage_portion._StoragePortion(storage, section, realm)

  Bases: `object`

  Provides access to a part of the persistent storage.

  Portion of a storage (which can be any `FileStorage`-like class) that can be accessed is defined by `realm` and `section`. While the `section` can be changed dynamically, `realm` can not be changed for entire lifetime of the `_StoragePortion`-type object.

  See also: `FileStorage`.

  Parameters

    - storage (`FileStorage`) – Storage which portion shall this instance provide access to.

    - section (`str`) – Section that shall be accessed by default.

    - realm (`str`) – Realm that this portion shall provide access to.

  getValue(variable, section=None)

    Returns a cached value from the persistent storage.

    Parameters

      - variable (`str`) – The name of the variable which value shall be read.

      - section (`str`) – Name of a section within `realm`.

    Returns

      Value of the passed `variable`.

    Return type

      `str`

    Raises

      KeyError – If `variable` or `section` does not exists.

  hasVariable(variable, section=None)

    Returns `true` if the storage contains `variable`.

    Parameters

      - variable (`str`) – Name of the variable which presence shall be determined.

      - section (`str`) – Name of a section within a realm.

    Returns

      `true` if `variable` is present in the storage.

    Return type

      `bool`

  saveValue(variable, value, section=None)

    Saves a value to the persistent storage.

    A value passed as `value` parameter will be saved to a persistent storage under the name passed as `variable` argument.

    Note

    A string representation of the value is saved (str(value)).

    Parameters

      - variable (`str`) – The name under which the value will be saved.

      - value (`object`) – The value that shall be saved.

      - section (`str`) – Name of a section within `realm`.

  tryRemoveVariable(variable, section=None)

    Removes variable from the persistent storage.

    If variable existed to be removed, returns `True`; otherwise return `False`.

    Parameters

      - variable (`str`) – The name of the variable which value shall be removed.

      - section (`str`) – Name of a section within `realm`.

    Returns

      `True` if variable existed; `False` otherwise.

    Return type

      `bool`

    Raises

      KeyError – If `section` does not exists.

  property realm

    Gets the realm in which this `IStoragePortion` instance operates.

    Return type

      `str`

  property section

    Gets or sets the section in which this `IStoragePortion` instance operates by default.

    Return type

      `str`