AutoArchive._configuration — AutoArchive Developer Manual (ver. 1.0.4)

# AutoArchive._configuration

Configuration component.

Provides access to configuration options read from `IMainfContext.appEnvironment.options` (command-line options), user configuration file and system configuration file. For that purpose it provides `IAppConfig` interface.

It also provides application’s persistent storage in a form of `IStorage` component interface.

For more information about `IAppConfig` and `IStorage` provided interfaces see `ConfigurationComponent`.

Component is designed to be used as the Mainf component. For that purpose it provides `IComponent` implementation in a form of `ConfigurationComponent` class.

## Sub-Packages

- AutoArchive._configuration._core

## Modules

### configuration_base

`ConfigurationBase` class.

class `AutoArchive._configuration.configuration_base.` `ConfigurationBase`

  Bases: `AutoArchive._configuration.iconfiguration.IConfiguration`

  See `IConfiguration`

  `__getitem__`(option)

    See: `IConfiguration.__getitem__()`.

  `getRawValue`(option)

    See: `IConfiguration.getRawValue()`.

  `options_` = None

    Stores options and their values. Key is of `Option` type and value is `object`.

### iapp_config

`IAppConfig` interface, `ConfigConstants` static class and `ArchiveSpecInfo` namedtuple.

class `AutoArchive._configuration.iapp_config.` `ArchiveSpecInfo`(name, path)

  Bases: `tuple`

  Holds information about an archive specification file; its name and full path.

  `name`

    Alias for field number 0

  `path`

    Alias for field number 1

class `AutoArchive._configuration.iapp_config.` `IAppConfig`

  Bases: `AutoArchive._configuration.iconfiguration.IConfiguration`, `AutoArchive._mainf.iinterface_accessor.IComponentInterface`

  Provides access to application configuration.

  `getArchiveSpecs`()

    Iterable of all known archive specification files.

    Returns: | Iterable of archive specification files information.
    Return type: | `Iterable<ArchiveSpecInfo>`
    Raises: | RuntimeError – If list of archive specification can not be obtained.

class `AutoArchive._configuration.iapp_config.` `ConfigConstants`

  Bases: `object`

  Configuration related constants.

  `ARCHIVE_SPEC_EXT` = '.aa'

    Extension of archive specification files.

### iconfiguration

`IConfiguration` interface.

class `AutoArchive._configuration.iconfiguration.` `IConfiguration`

  Bases: `object`

  Provides access to configuration options.

  `__getitem__`(option)

    Gets consolidated value of a configuration option.

    Method takes into account values of other option forms such as negation form and force form. For example if the raw value of the option FOO is 10 and raw value of FORCE_FOO is 5 then value 5 will be returned.

    The precedence order of option forms is following: force form > negation form > normal form; with force form as the highest and normal form as the lowest priority form.

    For options of type `bool` value `None` is never returned; it is converted to `False`.

    Parameters: | option (`Option`) – The option in the normal form for which the value should be returned.
    Returns: | The merged value of the passed `option` (can be `None`).
    Return type: | `object`
    Raises: | KeyError – If `option` does not exists.

  `getRawValue`(option)

    Gets the raw value of a configuration option or `None`.

    Unlike the `__getitem__()` this method returns the real raw value of the `option`.

    Parameters: | option (`Option`) – The option for which the value should be returned.
    Returns: | The raw value of the passed `option` (can be `None`).
    Return type: | `object`
    Raises: | KeyError – If `option` does not exists.

### istorage

`IStorage` interface.

class `AutoArchive._configuration.istorage.` `IStorage`

  Bases: `AutoArchive._mainf.iinterface_accessor.IComponentInterface`

  Provides access to a persistent storage.

  Stored content shall not be lost between program runs.

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

### istorage_portion

`IStoragePortion` interface.

class `AutoArchive._configuration.istorage_portion.` `IStoragePortion`

  Bases: `object`

  Provides access to a part of the persistent storage.

  Portion of the `IStorage` 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 `IStoragePortion`-type object.

  `getValue`(variable, section=None)

    Returns a cached value from the persistent storage.

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

  `realm`

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

    Return type: | `str`

  `section`

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

    Return type: | `str`

### options

`Options`, `OptionsUtils` static classes and `Option` class.

class `AutoArchive._configuration.options.` `Options`

  Bases: `object`

  Constants for configuration options.

  These constants should be used to access options in the `IConfiguration` implementation provided by the Configuration component.

  Note

  It is not allowed to change values of these constants.

  `ALL` = <Option all of type <class 'bool'>>

    Operate on all configured archive specification files.

  `ARCHIVER` = <Option archiver of type Tar, TarGz, TarBz2, TarXz, TarInternal, TarGzInternal, TarBz2Internal>

    Archiver type. Guaranteed to be defined.

  `ARCHIVE_SPECS_DIR` = <Option archive-specs-dir of type path>

    Directory where archive specification files will be searched. Guaranteed to be defined.

  `COMPRESSION_LEVEL` = <Option compression-level of type <class 'int'>>

    Compression strength level.

  `DEST_DIR` = <Option dest-dir of type path>

    Directory where the backup will be created. Guaranteed to be defined.

  `FORCE_ARCHIVER` = <Option force-archiver of type Tar, TarGz, TarBz2, TarXz, TarInternal, TarGzInternal, TarBz2Internal>

    Force archiver type regardless to what is specified in the archive specification file.

  `FORCE_COMPRESSION_LEVEL` = <Option force-compression-level of type <class 'int'>>

    Force compression level regardless to what is specified in the archive specification file.

  `FORCE_DEST_DIR` = <Option force-dest-dir of type path>

    Force the directory where the backup will be created.

  `FORCE_INCREMENTAL` = <Option force-incremental of type <class 'bool'>>

    Force incremental backup regardless to what is specified in the archive specification file.

  `FORCE_RESTARTING` = <Option force-restarting of type <class 'bool'>>

    Force the backup level restarting regardless to what is specified in the archive specification file.

  `FULL_RESTART_AFTER_AGE` = <Option full-restart-after-age of type <class 'int'>>

    Number of days after which the backup level is restarted to 0.

  `FULL_RESTART_AFTER_COUNT` = <Option full-restart-after-count of type <class 'int'>>

    Number of backup level restarts after which the level is restarted to 0.

  `INCREMENTAL` = <Option incremental of type <class 'bool'>>

    Incremental backup.

  `LEVEL` = <Option level of type <class 'int'>>

    Backup level used in incremental archiving.

  `MAX_RESTART_LEVEL_SIZE` = <Option max-restart-level-size of type <class 'int'>>

    Maximal percentage size of a backup (of level > 0) to which level is allowed restart to. The size is percentage of size of the level 0 backup file. If a backup of particular level has its size bigger than defined percentage, restart to that level will not be allowed.

  `NO_ALL` = <Option no-all of type <class 'bool'>>

    Do not operate on all configured archive specification files.

  `NO_INCREMENTAL` = <Option no-incremental of type <class 'bool'>>

    Disable incremental backup.

  `NO_RESTARTING` = <Option no-restarting of type <class 'bool'>>

    Turns off backup level restarting.

  `QUIET` = <Option quiet of type <class 'bool'>>

    Turns on quiet output. Only errors will be shown. If QUIET is turned on at the same level as VERBOSE (e. g. both are specified on the command line) then QUIET has higher priority than VERBOSE.

  `REMOVE_OBSOLETE_BACKUPS` = <Option remove-obsolete-backups of type <class 'bool'>>

    Turns on removing backups of levels that are no longer valid due to the backup level restart. All backups of the backup level higher than the one currently being created will be removed.

  `RESTARTING` = <Option restarting of type <class 'bool'>>

    Turns on backup level restarting.

  `RESTART_AFTER_AGE` = <Option restart-after-age of type <class 'int'>>

    Number of days after which the backup level is restarted. Similarly to `RESTART_AFTER_LEVEL` it will be restarted to level 1 or higher.

  `RESTART_AFTER_LEVEL` = <Option restart-after-level of type <class 'int'>>

    Maximal backup level. If reached, it will be restarted back to a lower level (which is typically level 1 but it depends on `MAX_RESTART_LEVEL_SIZE`). Guaranteed to be defined.

  `USER_CONFIG_DIR` = <Option user-config-dir of type path>

    User configuration directory. Guaranteed to be defined.

  `USER_CONFIG_FILE` = <Option user-config-file of type path>

    User configuration file. Guaranteed to be defined.

  `VERBOSE` = <Option verbose of type <class 'int'>>

    Turns on verbose output.

class `AutoArchive._configuration.options.` `OptionsUtils`

  Bases: `object`

  Various utility methods working with `Options`.

  classmethod `archiverTypeToStr`(archiverType)

    Converts `ArchiverTypes` to string representation.

    Value of the `archiverType` parameter is converted to a string representation that is accepted by the `strToOptionType()` method.

    Parameters: | archiverType (`ArchiverTypes`) – Archiver type that shall be converted.
    Returns: | String form of passed `archiverType`.
    Return type: | `str`
    Raises: | ValueError – If `archiverType` is not known.

  static `getAllOptions`()

    Iterator over all known options.

    Returns: | All options defined in `Options`.
    Return type: | `Iterator<Option>`

  static `getAllSpecialOptionTypes`()

    Iterator over all known special option types.

    Returns: | All option types defined in `SpecialOptionTypes`.
    Return type: | `Iterator<str>`

  classmethod `getOption`(optionName)

    Return option with given name.

    Parameters: | optionName (`str`) – Name of the option that shall be returned.
    Returns: | First option from `getAllOptions()` which name is `optionName`.
    Return type: | `Option`
    Raises: | KeyError – If option with name `optionName` does not exist.

  classmethod `isExistingOption`(optionName)

    Check whether an option with name `optionName` does exists in `OptionsUtils`.

    Parameters: | optionName (`str`) – Name of the option which existence shall be checked.
    Returns: | `True` if option with name `optionName` exists; `False` otherwise.
    Return type: | `bool`

  classmethod `strToOptionType`(option, optionValue)

    Converts string option value to its proper, defined type.

    Parameters: | option (`Option`) – Option which value shall be converted. optionValue (`str`) – Value to be converted.
    Returns: | Converted `optionValue`.
    Return type: | `object`
    Raises: | ValueError – If `optionValue` can not be converted to `option`’s type. RuntimeError – If `option`’s type is not supported.

  classmethod `tryGetForceForm`(option)

    Returns force form for `option` or `None`.

    Parameters: | option (`Option`) – An option in the normal form for which the force form for shall be returned.
    Returns: | Force form of the passed `option` or `None` if it does not have a force form.
    Return type: | `Option`

  classmethod `tryGetNegationForm`(option)

    Returns negation form for `option` or `None`.

    Parameters: | option (`Option`) – An option in the normal form for which the negation form for shall be returned.
    Returns: | Negation form of the passed `option` or `None` if it does not have a negation form.
    Return type: | `Option`

class `AutoArchive._configuration.options.` `Option`(name, optType)

  Bases: `object`

  Represents a configuration option.

  Parameters: | name (`str`) – Option name. optType (`type` or `str`) – Type of the option.

class `AutoArchive._configuration.options.` `SpecialOptionTypes`

  Bases: `object`

  Constants for special option types.

  Normally, options are of some standard type, such as `int`, `str`, etc. Some of them however, requires special handling for which the special option types are defined in this class.

  Note

  It is not allowed to change values of these constants.

  `PATH` = 'path'

    A filesystem path.