AutoArchive._application.archiving — AutoArchive Developer Manual (ver. 2.0.6)

# AutoArchive._application.archiving

Archiving component.

Provides the core functionality of the application. Executes an archiver and creates a backup based on provided archive specification file and configuration. It also allows to read various information about configured and stored archives. It requires archiver service (`ArchiverServiceIdentification`) for the backup creation.

## Sub-Packages

- AutoArchive._application.archiving.actions
- AutoArchive._application.archiving.archive_spec
- AutoArchive._application.archiving._archiver_manipulator

## Modules

### _archive_info

`_BackupLevelRestartReasons` enum and `_ArchiveInfo` class.

class AutoArchive._application.archiving._archive_info._ArchiveInfo(name)

  Bases: `object`

  Information about an archive.

  Note

  Class should be instantiated by calling the `_Archiving.getArchiveInfo()` or `_Archiving.getStoredArchiveInfo()` factory methods.

  property archiverType

    Gets the archiver type for this archive.

    Note

    Value is guaranteed to be non-`None`.

    Return type:

      `ArchiverTypes`

  property backupLevel

    Gets the current backup level.

    Note

    Will be `None` if the archive is not incremental or used `archiverType` does not support incremental archiving.

    Note

    For archiver types that supports incremental archiving, whether the return value will be `None` or not does not depend on the current `incremental` value. If the archive was configured and created as incremental previously then the backup level will be defined even if the current `incremental` value would be `False` and vice versa.

    Return type:

      `int`

  property destDir

    Gets the archive’s destination directory.

    Note

    Value is guaranteed to be non-`None`.

    Return type:

      `str`

  property fullRestartAfterAge

    Gets the number of days after which the backup level should be restarted to level 0.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if no value is defined for `Options.FULL_RESTART_AFTER_AGE`.

    Return type:

      `int`

  property fullRestartAfterCount

    Gets the number of restarts after which the backup level will be restarted to 0.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if no value is defined for `Options.FULL_RESTART_AFTER_COUNT`.

    Return type:

      `int`

  property incremental

    Gets the status of incremental archiving activation.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving.

    Return type:

      `bool`

  property lastFullRestart

    Gets the date when the last backup level restart to level 0 occurred.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if `restarting` was not enabled for the archive in the past.

    Return type:

      `datetime.date`

  property lastRestart

    Gets the date when the last backup level restart occurred.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if `restarting` was not enabled for the archive in the past.

    Return type:

      `datetime.date`

  property name

    Gets the name of the archive.

    Return type:

      `str`

  property nextBackupLevel

    Gets the next backup level.

    See also `backupLevel`.

    Note

    Will be `None` if the archive is not incremental or used `archiverType` does not support incremental archiving.

    Return type:

      `int`

  property path

    Gets the path to the archive’s root.

    Note

    Will be `None` if the archive’s root can not be retrieved.

    Return type:

      `str`

  property restartAfterAge

    Gets the number of days after which the backup level should be restarted.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if no value is defined for `Options.RESTART_AFTER_AGE`.

    Return type:

      `int`

  property restartAfterLevel

    Gets the maximal backup level; after it is reached it will be restarted to a lower value.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving.

    Return type:

      `int`

  property restartCount

    Gets the number of backup level restarts already performed.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or if `restarting` was not enabled for the archive in the past.

    Return type:

      `int`

  property restartLevel

    Gets a backup level to which a next restart would be done.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving.

    Return type:

      `int`

  property restartReason

    Gets the reason for the upcoming backup level restart.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving or the restart reason can not be determined.

    Return type:

      `_BackupLevelRestartReasons`

  property restarting

    Gets the status of backup level restarting activation.

    Note

    Will be `None` if the `archiverType` does not support incremental archiving.

    Return type:

      `bool`

AutoArchive._application.archiving._archive_info._BackupLevelRestartReasons

  Reasons for restarting of the backup level.

### _archiving

class AutoArchive._application.archiving._archiving._Archiving(componentUi, applicationContext, serviceAccessor, commandExecutor)

  Bases: `object`

  Provides means for working with archives.

  Several methods of this class requires an archive specification file as the input parameter (usually named `specFile`). This file should contain all information required to create the backup. Its format is defined by the standard `configparser` module. It has to contain section `[Content]` and may contain section `[Archive]`. The `[Content]` section requires following options to be present: `path`, `include-files` and `exclude-files`. Optionally, `name` can be present. Options in the archive specification file has higher priority than those in the configuration.

  Parameters:

    - componentUi (`CmdlineUi`) – Access to user interface.

    - applicationContext (`ApplicationContext`) – Application context.

    - serviceAccessor (`IServiceAccessor`) – Access to services.

    - commandExecutor (`_CommandExecutor`) – For executing commands before and after backup creation.

  filterValidSpecFiles(specFiles)

    Returns names of configured archives from valid only archive specification files passed in `specFiles`.

    Parameters:

      specFiles (`Iterable<str>`) – Paths to archive specification files that shall be validated and from which the names shall be retrieved.

    Returns:

      Iterable of names of validly configured archives.

    Return type:

      `Iterable<str>`

  getArchiveInfo(specFile)

    Returns information about archive represented by the `specFile` parameter.

    Warning

    This method utilizes the user configuration directory so the option `Options.USER_CONFIG_DIR` has to point to an existing directory.

    Parameters:

      specFile (`str`) – Path to the archive specification file.

    Returns:

      Information about an archive or `None`.

    Return type:

      `_ArchiveInfo`

  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.

    Raise:

      OSError: If an error occurred while reading archive specification directory.

  getStoredArchiveInfo(archiveName)

    Returns information about an archive from stored data.

    Unlike in the `getArchiveInfo()` method the information is not read from the archive specification file but from other stored data about the archive created by the component in previous runs. Such data can be fetched for example from application storage (`IStorage`) or other sources specific to the archiver. It is expected that the large portion of data will be missing in the returned information.

    Warning

    This method utilizes the user configuration directory so the option `Options.USER_CONFIG_DIR` has to point to an existing directory.

    See also: `getStoredArchiveNames()`

    Parameters:

      archiveName (`str`) – Name of the archive which information shall be returned.

    Returns:

      Information about an archive or `None` if no data for the archive was found.

    Return type:

      `_ArchiveInfo`

  getStoredArchiveNames()

    Returns iterable of archive names which has some data stored in a persistent storage.

    Warning

    This method utilizes the user configuration directory so the option `Options.USER_CONFIG_DIR` has to point to an existing directory.

    See also: `getStoredArchiveInfo()`

    Returns:

      Iterable of archive names.

    Return type:

      `Iterable<str>`

  makeBackup(specFile)

    Creates the backup based on `specFile`.

    The result can be a file with a full backup or an incremental backup of some particular level. This depends on the archive specification file (`specFile`), the configuration (`IConfiguration`), previous operations with the `specFile` and the time. Some of the properties of `_ArchiveInfo` returned by the method `getArchiveInfo()` can be used to determine what the result will be. The path and name of the created file will be assembled as follows: “<Options.DEST_DIR>/<archive_name>[.<backup_level>].<archiver_specific_extension>”.

    Method uses `CmdlineUi`-like interface to report errors, warnings et al. to the user.

    Warning

    This method utilizes the user configuration directory so the option `Options.USER_CONFIG_DIR` has to point to an existing directory.

    Parameters:

      specFile (`str`) – Path to the archive specification file.

    Raises:

      ValueError – If the desired archiver type is not supported.

  purgeStoredArchiveData(archiveName)

    Deletes all data stored for the archive named `archiveName`.

    Warning

    This method utilizes the user configuration directory so the option `Options.USER_CONFIG_DIR` has to point to an existing directory.

    See also: `getStoredArchiveInfo()`

    Parameters:

      archiveName (`str`) – Name of the archive which data shall be purged.

    Raises:

      - KeyError – If `archiveName` does not have any stored data to purge.

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

### _archiving_constants

class AutoArchive._application.archiving._archiving_constants._RestartStorageVariables

  Bases: `object`

  Names of storage variables for backup level restarting.

  BACKUP_SIZE = 'archiving-size-level'
  LAST_FULL_RESTART = 'archiving-last-full-restart'
  LAST_RESTART = 'archiving-last-restart'
  RESTART_COUNT = 'archiving-restart-count'

### _backup_information_provider

class AutoArchive._application.archiving._backup_information_provider._BackupInformationProvider(archiveSpec, componentUi, storage, serviceAccessor: ServiceAccessor)

  Bases: `object`

  Provides information about backups.

  Parameters:

    - archiveSpec (`ArchiveSpec`) – Archive specification of the backup that this instance will provide information about.

    - storage (`IStorage`) – Application storage.

    - componentUi (`CmdlineUi`) – Access to the user interface.

    - serviceAccessor (`IServiceAccessor`) – An `IServiceAccessor` instance.

  Raises:

    - RuntimeError – If the archiver service could not be created.

    - OSError – If a system error occurred.

  static getBackupLevelForBackup(archiveName, userConfigDir, serviceAccessor)

    Returns current backup level for the passed `archiveName`.

    Parameters:

      - archiveName (`str`) – Name of the archive for which the backup level shall be returned.

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

      - serviceAccessor (`IServiceAccessor`) – Service accessor.

    Returns:

      Current backup level for `archiveName` or None

    Return type:

      `int`

    Raises:

      - RuntimeError – If the archiver service could not be created.

      - OSError – If a system error occurred.

  static getRestartDate(storageVariable, storagePortion)

    Reads the date of a backup level restart from storage and returns it.

    Parameters:

      - storageVariable (`str`) – Variable that holds the restart date in the persistent storage.

      - storagePortion (`IStoragePortion`) – The persistent storage where the variable is located.

    Returns:

      A backup level restart date.

    Return type:

      `datetime.date`

  static getStoredArchiveNames(storage, serviceAccessor)

    Returns iterable of archive names which has some data stored in a persistent storage.

    Persistent storages from which archive names are retrieved are specific to the concrete archiver service. A typical storage used by archivers is the application storage (`IStorage`).

    Parameters:

      - storage (`IStorage`) – The application storage.

      - serviceAccessor (`IServiceAccessor`) – Service accessor.

    Returns:

      Set of archive names.

    Return type:

      `set<str>`

    Raises:

      RuntimeError – If the archiver service could not be created.

  getLastFullRestartDate()

    Reads the last full restart date from the persistent storage and returns it.

    Returns:

      Date of the last full backup level restart.

    Return type:

      `datetime.date`

  getLastRestartDate()

    Reads the last restart date from the persistent storage and returns it.

    Returns:

      Date of the last backup level restart.

    Return type:

      `datetime.date`

  property archiveSpec

    Gets the archive specification that corresponds to the backup about which this instance provides information.

    Return type:

      `ArchiveSpec`

  property currentBackupLevel

    Gets the current backup level or `None`.

    Return type:

      `int`

  property nextBackupLevel

    Gets the backup level that would be created if the backup creation was triggered.

    Return type:

      `int`

  property restartLevel

    Gets a backup level to which a next restart would be done.

    Return type:

      `int`

  property restartReason

    Gets the reason for upcoming backup level restart.

    Return type:

      `_BackupLevelRestartReasons`

### _command_executor

class AutoArchive._application.archiving._command_executor._CommandExecutor(configuration, externalCommandExecutor: ExternalCommandExecutor, componentUi)

  Bases: `object`

  executeAfterAllCommand()
  executeAfterCommand(archiveSpec)
  executeBeforeAllCommand()
  executeBeforeCommand(archiveSpec)

### _utils

class AutoArchive._application.archiving._utils._Utils

  Bases: `object`

  classmethod getOrCreateArchiverService(serviceAccessor: ServiceAccessor, archiveSpec: ConfigurationBase) → TarArchiverProviderBase