AutoArchive._services.archiver — AutoArchive Developer Manual (ver. 2.0.6)

# AutoArchive._services.archiver

Archiver Service Component.

Provides services for creating the backup.

## Modules

### archiver_service_identification

`ArchiverServiceIdentification` interface.

class AutoArchive._services.archiver.archiver_service_identification.ArchiverServiceIdentification

  Bases: `IServiceIdentification`

  Identifies the Archiver service.

  Parameters required by the service upon creation:

  > `workDir`: Path to a writable directory. The service will use it as persistent storage (type `str`).

  interface

    alias of `TarArchiverProviderBase`

### archiver_service_provider_ids

`ArchiverServiceProviderIDs` enum.

AutoArchive._services.archiver.archiver_service_provider_ids.ArchiverServiceProviderIDs = TarInternal, TarExternal

  Implementations of the archiver service.

### backup_definition

`MIN_COMPRESSION_STRENGTH` and `MAX_COMPRESSION_STRENGTH` constants, `BackupTypes`, `ArchiverFeatures`, `BackupSubOperations`, `BackupOperationErrors` enums and `BackupDefinition` class.

class AutoArchive._services.archiver.backup_definition.BackupDefinition

  Bases: `object`

  Container class for information needed to create a backup.

  property backupId

    The backup identifier, typically the name is used.

    Return type:

      `str`

  property backupType

    Type of the backup.

    Return type:

      `BackupTypes`

  property destination

    Path to the directory which contains the backup.

    Return type:

      `str`

  property excludeFiles

    Set of excluded filesystem objects paths relative to `root`.

    Return type:

      `Set<str>`

  property includeFiles

    Set of source filesystem objects paths relative to `root`.

    Return type:

      `Set<str>`

  property root

    Path to the root directory of the source content.

    Return type:

      `str`

AutoArchive._services.archiver.backup_definition.ArchiverFeatures = CompressionStrength, Incremental

  Features that archiver service may support.

AutoArchive._services.archiver.backup_definition.BackupOperationErrors = UnknownError, UnknownOsError, PermissionDenied, SocketIgnored, UnknownTypeIgnored, FileChanged, SomeFilesChanged, DirectoryRenamed

  Errors that may occur during backup operation.

AutoArchive._services.archiver.backup_definition.BackupSubOperations = Unknown, UnknownFileOperation, Stat, Open, Read, Finish

  Operations executed during backup creation.

AutoArchive._services.archiver.backup_definition.BackupTypes = Tar, TarGz, TarBz2, TarXz, TarZst

  Backup types.

AutoArchive._services.archiver.backup_definition.MAX_COMPRESSION_STRENGTH: int = 9

  Maximal compression strength value.

AutoArchive._services.archiver.backup_definition.MIN_COMPRESSION_STRENGTH: int = 0

  Minimal compression strength value.

### tar_archiver_provider_base

`TarArchiverProviderBase` class.

class AutoArchive._services.archiver.tar_archiver_provider_base.TarArchiverProviderBase(workDir)

  Bases: `IService`

  Base class for tar archiver service providers.

  Abstract constructor of this class, should be called from derived constructors. It initializes the `workDir_` property.

  Parameters:

    workDir (`str`) – Path to a writable directory. The service will use it as persistent storage.

  classmethod getSupportedFeatures(backupType=None)

    Returns a set of supported features, either all of them or for given `backupType`.

    Parameters:

      backupType (`BackupTypes`) – The backup type for which the features shall be returned or `None` if all supported features shall be returned.

    Returns:

      Supported features for given `backupType` or all supported features.

    Return type:

      `set<ArchiverFeatures>`

    Raises:

      ValueError – If the given `backupType` is not supported by this service

  classmethod getWorkingPath_(properPath)
  classmethod raiseIfUnsupportedBackupType_(backupType)

    Raises an exception if the passed `backupType` is not supported by the implementation.

    See also: `TarArchiverProviderBase.supportedBackupTypes`.

    Parameters:

      backupType (`BackupTypes`) – The backup type that shall be checked.

    Raises:

      ValueError – If the passed `backupType` is not supported by the concrete implementation.

  classmethod raiseIfUnsupportedFeature_(backupType, compressionStrength=None, level=None)
  static getBackupFilePath_(backupId, backupType, destination, level=None, keepingId=None)

    Assembles the backup file name and returns a path to it.

    Parameters:

      - backupId (`str`) – ID of the backup for which the path shall be returned.

      - backupType (`BackupTypes`) – Type of the backup.

      - destination (`str`) – Path to the directory where the to the backup shall be created.

      - level (`int`) – Backup level.

      - keepingId (`str`) – Path of the kept backup with this ID will be returned. `None` if path of the actual (not kept) backup shall be returned.

    Returns:

      Path to the backup file.

    Return type:

      `str`

  abstractmethod backupFiles(backupDefinition, compressionStrength=None, overwriteAtStart=False)

    Creates a backup.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines the backup that shall be created. All attributes of the passed instance has to be initialized.

      - compressionStrength (`int`) – Value from interval <MIN_COMPRESSION_STRENGTH, MAX_COMPRESSION_STRENGTH> representing the strength of compression. It has to be non-None only for backup types that supports compression and compression strength setting.

      - overwriteAtStart (`bool`) – If `True`, backups are overwritten at the start of creation; otherwise they are overwritten at the end of creation (new backups are created with temporary name first and renamed when completed).

    Returns:

      Path to the created backup.

    Return type:

      `str`

    Raises:

      - RuntimeError – If `compressionStrength` is non-`None` and `backupDefinition.backupType` does not supports compression or compression strength setting. If an unknown error occurred during backup creation.

      - ValueError – If `compressionStrength` is outside of required interval or if `backupDefinition.backupType` is not supported by the implementation.

      - OSError – If a system error occurred while making the backup.

    Performs basic checks before the backup creation.

    Note

    Derived classes should call this base method on the beginning of the overridden method.

  abstractmethod backupFilesIncrementally(backupDefinition, compressionStrength=None, level=None, overwriteAtStart=False)

    Creates an incremental backup.

    A backup of specified level or the next level in a row will be created. The maximal backup level will be increased (see `getMaxBackupLevel()`).

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines the backup that shall be created. All attributes of the passed instance has to be initialized.

      - compressionStrength (`int`) – Value from interval <MIN_COMPRESSION_STRENGTH, MAX_COMPRESSION_STRENGTH> representing the strength of compression. It has to be non-None only for backup types that supports compression and compression strength setting.

      - level (`int`) – Backup level that shall be created. If `None`, the next level in a row will be created, which is the the one returned by `getMaxBackupLevel()`. The value has to be from interval <0, `getMaxBackupLevel()`>.

      - overwriteAtStart (`bool`) – If `True`, backups are overwritten at the start of creation; otherwise they are overwritten at the end of creation (new backups are created with temporary name first and renamed when completed).

    Returns:

      Path to the created backup.

    Return type:

      `str`

    Raises:

      - RuntimeError – If `compressionStrength` is non-`None` and `backupDefinition.backupType` does not supports compression or compression strength setting. If an unknown error occurred during backup creation.

      - ValueError – If `compressionStrength` or `level` is outside of required interval or if `backupDefinition.backupType` is not supported by the implementation.

      - NotImplementedError – If incremental backup is not supported.

      - OSError – If a system error occurred while making the backup.

    Performs basic checks before the incremental backup creation.

    Note

    Derived classes should call this base method on the beginning of the overridden method.

  doesAnyBackupLevelExist(backupDefinition, fromLevel=0, keepingId=None)

    Returns `True`, if one or more backup levels of a backup defined by `backupDefinition` exists.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines the backup which existence shall be queried.

      - fromLevel (`int`) – The specified backup level and above will be checked for existence. The value has to be >= 0.

      - keepingId (`str`) – The kept backup with this ID will be checked for existence. `None` if the actual (not kept) backup will be checked.

    Returns:

      `True` if any backup level exists, `False` otherwise.

    Return type:

      `bool`

    Raises:

      ValueError – If `backupDefinition.backupType` is not supported by the implementation.

  doesBackupExist(backupDefinition, level=None, keepingId=None)

    Returns `True`, if backup exists.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines the backup which existence shall be queried.

      - level (`int`) – The level of backup of which existence shall be checked. If `None`, existence of non-incremental backup will be checked. The value has to be >= 0.

      - keepingId (`str`) – The kept backup with this ID will be checked for existence. `None` if the actual (not kept) backup will be checked.

    Returns:

      `True` if the backup exists, `False` otherwise.

    Return type:

      `bool`

    Raises:

      ValueError – If `backupDefinition.backupType` is not supported by the implementation.

  getMaxBackupLevel(backupId)

    Determines and returns maximal backup level that can be created.

    Parameters:

      backupId (`str`) – ID of the backup for which the level shall be determined.

    Returns:

      The maximal backup level that can be created by `backupFilesIncrementally()`.

    Return type:

      `int`

    Raises:

      - NotImplementedError – If incremental backup is not supported.

      - OSError – If a system error occurred.

  getStoredBackupIds()

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

    See also: `purgeStoredBackupData()`.

    Returns:

      Iterable of archive names.

    Return type:

      `Iterable<str>`

    Raises:

      OSError – If a system error occurred.

  keepBackup(backupDefinition, keepingId, newKeepingId, level=None)

    Keeps a backup with `keepingId` under the `newKeepingId`.

    See also: `doesBackupExist()` or `doesAnyBackupLevelExist()`.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines the backup that shall be kept.

      - keepingId (`str`) – The ID under which the backup is currently kept. `None` if it is not kept yet.

      - newKeepingId (`str`) – The ID under which the backup is shall be kept.

      - level (`int`) – The level of backup of which shall be kept. If `None`, non-incremental backup will be kept. The value has to be >= 0.

    Raises:

      - ValueError – If `backupDefinition.backupType` is not supported by the implementation or if `newKeepingId` is `None` or empty string.

      - FileExistsError – If backup with the specified `newKeepingId` already exists.

      - FileNotFoundError – If backup with the specified `keepingId` does not exist.

      - OSError – If a system error occurred.

  purgeStoredBackupData(backupId)

    Removes internal data from a persistent storage for the passed `backupId`.

    See also: `getStoredBackupIds()`.

    Parameters:

      backupId (`str`) – ID of the backup of which data shall be purged.

    Raises:

      OSError – If a system error occurred.

  removeBackup(backupDefinition, keepingId=None)

    Remove a backup.

    Backup defined by `backupDefinition` will be removed.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines backup that shall be removed. `BackupDefinition.backupId`, `BackupDefinition.backupType` and `BackupDefinition.destination` attributes of the passed instance has to be initialized.

      - keepingId (`str`) – The ID under which the backup is currently kept. `None` if it is not kept.

    Raises:

      - ValueError – If `backupDefinition.backupType` is not supported by the implementation.

      - OSError – If a system error occurred during removing operation.

  removeBackupIncrements(backupDefinition, level=None, keepingId=None)

    Remove backup increments starting from `level`.

    Backups (increments) of backup level higher or equal than `level` or higher that the current backup level - in case `level` is `None` - will be removed. The maximal backup level (`getMaxBackupLevel()`) will be set to the value `level`.

    Parameters:

      - backupDefinition (`BackupDefinition`) – Defines backup that shall be removed. `BackupDefinition.backupId`, `BackupDefinition.backupType` and `BackupDefinition.destination` attributes of the passed instance has to be initialized.

      - level (`int`) – The first level that shall be removed. All backups of levels higher or equal than `level` will be removed. If `None`, backups of levels higher or equal than the one returned by `getMaxBackupLevel()` will be removed. The value has to be >= 0.

      - keepingId (`str`) – The ID under which the backup is currently kept. `None` if it is not kept.

    Raises:

      - ValueError – If `level` is outside of required interval or if `backupDefinition.backupType` is not supported by the implementation.

      - NotImplementedError – If incremental backup is not supported.

      - OSError – If a system error occurred during removing operation.

  backupOperationError = <AutoArchive._infrastructure.py_additions.event object>
  fileAdd = <AutoArchive._infrastructure.py_additions.event object>
  abstract property supportedBackupTypes

    Gets a set of backup types supported by this archiver service.

    Return type:

      `set<BackupTypes>`

  property workDir_

    Gets path to the working directory.

    Return type:

      `str`

### _archiver_service_component

class AutoArchive._services.archiver._archiver_service_component.ArchiverServiceComponent(applicationContext, serviceAccessor: ServiceAccessor)

  Bases: `IServiceComponent`

  Service component for archiver services.

  Registers service identified by `ArchiverServiceIdentification` with two providers identified via ArchiverServiceProviderIDs.

  destroyServices()

    See: `IServiceComponent.destroyServices()`

### _external_tar_archiver_provider

class AutoArchive._services.archiver._external_tar_archiver_provider._ExternalTarArchiverProvider(workDir)

  Bases: `TarArchiverProviderBase`

  External archiver service provider.

  See also: `TarArchiverProviderBase`.

  Raises:

    OSError – If creation of the snapshot directory failed.

  classmethod getSupportedFeatures(backupType=None)

    See: `TarArchiverProviderBase.getSupportedFeatures()`.

  backupFiles(backupDefinition, compressionStrength=None, overwriteAtStart=False)

    See: `TarArchiverProviderBase.backupFiles()`.

  backupFilesIncrementally(backupDefinition, compressionStrength=None, level=None, overwriteAtStart=False)

    See: `TarArchiverProviderBase.backupFilesIncrementally()`.

  doesAnyBackupLevelExist(backupDefinition, fromLevel=0, keepingId=None)

    See: `TarArchiverProviderBase.doesAnyBackupLevelExist()`.

  getMaxBackupLevel(backupId)

    See: `TarArchiverProviderBase.getMaxBackupLevel()`.

  getStoredBackupIds()

    See: `TarArchiverProviderBase.getStoredBackupIds()`.

  purgeStoredBackupData(backupId)

    See: `TarArchiverProviderBase.purgeStoredBackupData()`.

  removeBackupIncrements(backupDefinition, level=None, keepingId=None)

    See: `TarArchiverProviderBase.removeBackupIncrements()`.

  supportedBackupTypes = frozenset({0, 1, 2, 3, 4})

### _internal_tar_archiver_provider

`_InternalTarArchiverProvider` class.

class AutoArchive._services.archiver._internal_tar_archiver_provider._InternalTarArchiverProvider(workDir)

  Bases: `TarArchiverProviderBase`

  Internal archiver service provider.

  See also: `TarArchiverProviderBase`.

  classmethod getSupportedFeatures(backupType=None)

    See: `TarArchiverProviderBase.getSupportedFeatures()`.

  backupFiles(backupDefinition, compressionStrength=None, overwriteAtStart=False)

    See: `TarArchiverProviderBase.backupFiles()`.

  backupFilesIncrementally(backupDefinition, compressionStrength=None, level=None, overwriteAtStart=False)

    See: `TarArchiverProviderBase.backupFilesIncrementally()`.

  supportedBackupTypes = frozenset({0, 1, 2})