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

# AutoArchive._infrastructure.configuration

Configuration component.

Provides access to configuration options read from `ApplicationContext.appEnvironment.options` (command-line options), user configuration file and system configuration file. For that purpose it provides `ConfigurationBase` implementation via `ConfigurationFactory`. Configuration should be created centrally by some common component and that instance distributed to other components. Individual components should not call `ConfigurationFactory` directly.

For more information about `ConfigurationBase` provided interface see `ConfigurationFactory`.

## Modules

### configuration_base

`ConfigurationBase` class.

class AutoArchive._infrastructure.configuration.configuration_base.ConfigurationBase

  Bases: `object`

  Provides access to configuration options.

  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.

  options_

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

### options

`Options`, `OptionsUtils` and `SpecialOptionTypes` static classes. `Option` class and `ArchiverTypes` enum.

class AutoArchive._infrastructure.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._infrastructure.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, TarZst, 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.

  COMMAND_AFTER_ALL_BACKUPS = <Option command-after-all-backups of type <class 'str'>>

    Arbitrary command that will be executed after backup creation for the set of selected archives.

  COMMAND_AFTER_BACKUP = <Option command-after-backup of type <class 'str'>>

    Arbitrary command to execute after each backup creation.

  COMMAND_BEFORE_ALL_BACKUPS = <Option command-before-all-backups of type <class 'str'>>

    Arbitrary command that will be executed before backup creation for the set of selected archives.

  COMMAND_BEFORE_BACKUP = <Option command-before-backup of type <class 'str'>>

    Arbitrary command to execute prior to each backup creation.

  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, TarZst, TarInternal, TarGzInternal, TarBz2Internal>

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

  FORCE_COMMAND_AFTER_BACKUP = <Option force-command-after-backup of type <class 'str'>>

    Force configuration of the command to execute after each backup creation.

  FORCE_COMMAND_BEFORE_BACKUP = <Option force-command-before-backup of type <class 'str'>>

    Force configuration of the command to execute prior to each backup creation.

  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_OVERWRITE_AT_START = <Option force-overwrite-at-start of type <class 'bool'>>

    Force backup overwriting behavior 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.

  KEEP_OLD_BACKUPS = <Option keep-old-backups of type <class 'bool'>>

    Turn on backup keeping. When a backup is about to be overwritten, it is renamed instead.

  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_KEEP_OLD_BACKUPS = <Option no-keep-old-backups of type <class 'bool'>>

    Turn off backup keeping.

  NO_OVERWRITE_AT_START = <Option no-overwrite-at-start of type <class 'bool'>>

    Do not overwrite backup at the start of creation. Overwrite after the new backup is created.

  NO_REMOVE_OBSOLETE_BACKUPS = <Option no-remove-obsolete-backups of type <class 'bool'>>

    Turn off obsolete backups removing.

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

    Turn off backup level restarting.

  NUMBER_OF_OLD_BACKUPS = <Option number-of-old-backups of type <class 'int'>>

    Number of old backups to keep when `KEEP_OLD_BACKUPS` is enabled. Guaranteed to be defined.

  OVERWRITE_AT_START = <Option overwrite-at-start of type <class 'bool'>>

    If enabled, backups are overwritten at the start of creation. If disabled (default), backups are overwritten at the end of creation. Enabling this option can be useful with big backups and low free space on the backup volume.

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

    Turn 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'>>

    Turn 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'>>

    Turn 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'>>

    Turn on verbose output.

class AutoArchive._infrastructure.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._infrastructure.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.

AutoArchive._infrastructure.configuration.options.ArchiverTypes = Tar, TarGz, TarBz2, TarXz, TarZst, TarInternal, TarGzInternal, TarBz2Internal

  Archiver types.

### _configuration_factory

`ConfigurationFactory` class.

class AutoArchive._infrastructure.configuration._configuration_factory.ConfigurationFactory

  Bases: `object`

  Support of configuration options and a persistent storage.

  During `makeConfiguration()` call it creates `IConfiguration` implementation instance. It also creates user configuration directory and archive specifications directory if either of them does not exists.

  The `ConfigurationBase`-like class provides access to configuration options. It is instantiated and populated during `makeConfiguration()` call from `ApplicationContext.appEnvironment.options` (command-line options) and from configuration files. The system configuration file is “/etc/aa/aa.conf”. The user configuration file location is determined by values of `Options.USER_CONFIG_FILE` and `Options.USER_CONFIG_DIR` options. The user configuration directory is automatically created if it does not exists. The format of configuration files is defined by the standard `configparser` module (without interpolation).

  The `ConfigurationBase` implementation instance is populated in the way that same options specified in multiple sources overrides each other so that the order of precedence from highest to lowest is following: command-line, user configuration file, system configuration file. However the implementation recognizes certain types of options that does not follow this rule (see `ConfigurationBase.__getitem__()`).

  Some of the options, if not specified in neither of possible sources, has some predefined default value. The list of these options with their predefined value follows:

  - `Options.ARCHIVER`: `ArchiverTypes.TarGz`

  - `Options.DEST_DIR`: `os.curdir`

  - `Options.RESTART_AFTER_LEVEL`: 10

  - `Options.ARCHIVE_SPECS_DIR`: `Options.USER_CONFIG_DIR` + “archive_specs”

  - `Options.USER_CONFIG_FILE`: `Options.USER_CONFIG_DIR` + “aa.conf”

  - `Options.USER_CONFIG_DIR`: “~/.config/aa”

  - `Options.NUMBER_OF_OLD_BACKUPS`: 1

  - options of type `bool`: `False`

  classmethod makeConfiguration(appEnvironment)

    Creates and populates configuration.

    Parameters

      appEnvironment (`AppEnvironment`) – Application environment.

### _configuration

`_Configuration` class.

class AutoArchive._infrastructure.configuration._configuration._Configuration

  Bases: `AutoArchive._infrastructure.configuration.configuration_base.ConfigurationBase`

  Application’s configuration.

  Provides access to application’s configuration. All configuration options that can be accessed via this class are defined as static attributes of `Options`.

  After construction, all options are added and initialized to `None`. It is expected that concrete values will be added using the `_addOrReplaceOption()` method.

  _addOrReplaceOption(optionName, value)

    Adds an option and its value replacing the value if already exists.

    String representation of the value is expected. It will be converted to a proper type defined by the option.

    Parameters

      - optionName (`str`) – Option that will be added or replaced.

      - value (`str`) – Value of passed option with name `optionName`.

    Raises

      - KeyError – If option with name `optionName` does not exists.

      - ValueError – If option’s value is not correct.

### _cmdline_arguments_processor

`_CmdlineArgumentsProcessor` class.

class AutoArchive._infrastructure.configuration._cmdline_arguments_processor._CmdlineArgumentsProcessor(optparseValues)

  Bases: `object`

  Processes command-line arguments and populates `IConfiguration` instance.

  Parameters

    optparseValues (`optparse.Values`) – Command-line options and their values.

  populateConfiguration(configuration)

    Populates `configuration` with options specified on the command line.

    Note

    Options that are not defined in the `Options` class are skipped; it is assumed that they are commands for command-line UI.

    Parameters

      configuration (`_Configuration`) – Configuration that should be populated.

### _config_file_processor

`_ConfigFileProcessor` class.

class AutoArchive._infrastructure.configuration._config_file_processor._ConfigFileProcessor(appEnvironment, factoryUserConfigDir, factoryUserConfigFileProvider, userConfigDir=None, userConfigFile=None)

  Bases: `object`

  Processes configuration files and populates `IConfiguration` instance.

  Parameters

    - appEnvironment (`AppEnvironment`) – `AppEnvironment` instance.

    - factoryUserConfigDir (`str`) – Pre-defined path to the user configuration directory.

    - factoryUserConfigFileProvider (`function{str, =>str}`) – Function that returns path to the user configuration file based on the passed configuration directory.

    - userConfigDir (`str`) – Path to the user configuration directory.

    - userConfigFile (`str`) – Path to the user configuration file.

  populateConfiguration(configuration)

    Populates `configuration` with options.

    Parameters

      configuration (`_Configuration`) – Configuration that should be populated.