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

# AutoArchive._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 (`IAppConfig`). It also allows to read various information about configured and stored archives.

It requires archiver service (`IArchiver` implementation) for the backup creation.

## Sub-Packages

- AutoArchive._archiving._core

## Modules

### iarchiving

`ArchiverTypes` and `BackupLevelRestartReasons` enums, `IArchiving` interface and `ArchiveInfo` class.

class `AutoArchive._archiving.iarchiving.` `IArchiving`

  Bases: `AutoArchive._mainf.iinterface_accessor.IComponentInterface`

  Provides access to the Archiving component.

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

    Parameters: | specFile (`str`) – Path to the archive specification file.
    Returns: | Information about an archive or `None`.
    Return type: | `ArchiveInfo`

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

    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.

    See also: `getStoredArchiveInfo()`

    Returns: | Iterable of archive names.
    Return type: | `Iterable<str>`

  `makeBackup`(specFile)

    Creates a backup based on `specFile`.

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

    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.

class `AutoArchive._archiving.iarchiving.` `ArchiveInfo`(name)

  Bases: `object`

  Information about an archive.

  Note

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

  `archiverType`

    Gets the archiver type for this archive.

    Note

    Value is guaranteed to be non-`None`.

    Return type: | `ArchiverTypes`

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

  `destDir`

    Gets the archive’s destination directory.

    Note

    Value is guaranteed to be non-`None`.

    Return type: | `str`

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

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

  `incremental`

    Gets the status of incremental archiving activation.

    Note

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

    Return type: | `bool`

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

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

  `name`

    Gets the name of the archive.

    Return type: | `str`

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

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

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

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

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

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

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

  `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._archiving.iarchiving.` `ArchiverTypes` = Tar, TarGz, TarBz2, TarXz, TarInternal, TarGzInternal, TarBz2Internal

  Archiver types.

`AutoArchive._archiving.iarchiving.` `BackupLevelRestartReasons` = NoRestart, RestartCountLimitReached, LastFullRestartAgeLimitReached, BackupLevelLimitReached, LastRestartAgeLimitReached

  Reasons for restarting of the backup level.

### iarchiver

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

class `AutoArchive._archiving.iarchiver.` `IArchiver`

  Bases: `object`

  SPI for backup creation and management.

  `backupFiles`(backupDefinition, compressionStrength=None)

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

  `backupFilesIncrementally`(backupDefinition, compressionStrength=None, level=None)

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

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

  `getSupportedFeatures`(backupType=None)

    Returns a set of supported features, ether 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

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

    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.
    Raises: | ValueError – If `backupDefinition.backupType` is not supported by the implementation. OSError – If a system error occurred during removing operation.

  `removeBackupIncrements`(backupDefinition, level=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.
    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._py_additions.event object>
  `fileAdd` = <AutoArchive._py_additions.event object>
  `supportedBackupTypes`

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

    Return type: | `set<BackupTypes>`

class `AutoArchive._archiving.iarchiver.` `BackupDefinition`

  Bases: `object`

  Container class for information needed to create a backup.

  `backupId`

    The backup identifier, typically the name is used.

    Return type: | `str`

  `backupType`

    Type of the backup.

    Return type: | `BackupTypes`

  `destination`

    Path to the directory which contains the backup.

    Return type: | `str`

  `excludeFiles`

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

    Return type: | `Set<str>`

  `includeFiles`

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

    Return type: | `Set<str>`

  `root`

    Path to the root directory of the source content.

    Return type: | `str`

`AutoArchive._archiving.iarchiver.` `MIN_COMPRESSION_STRENGTH` = 0

  Minimal compression strength value.

`AutoArchive._archiving.iarchiver.` `MAX_COMPRESSION_STRENGTH` = 9

  Maximal compression strength value.

`AutoArchive._archiving.iarchiver.` `BackupTypes` = Tar, TarGz, TarBz2, TarXz

  Backup types.

`AutoArchive._archiving.iarchiver.` `ArchiverFeatures` = CompressionStrength, Incremental

  Features that archiver service may support.

`AutoArchive._archiving.iarchiver.` `BackupSubOperations` = Unknown, UnknownFileOperation, Stat, Open, Read, Finish

  Operations executed during backup creation.

`AutoArchive._archiving.iarchiver.` `BackupOperationErrors` = UnknownError, UnknownOsError, PermissionDenied, SocketIgnored, UnknownTypeIgnored, FileChanged, SomeFilesChanged, DirectoryRenamed

  Errors that may occur during backup operation.