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

# AutoArchive._archiving._core

Archiving component internal package.

## Modules

### archiving_component

`ArchivingComponent` class.

class `AutoArchive._archiving._core.archiving_component.` `ArchivingComponent`(interfaceAccessor)

  Bases: `AutoArchive._mainf.icomponent.IComponent`, `AutoArchive._archiving.iarchiving.IArchiving`

  Provides an interface for working with archives.

  During construction it registers itself as `IArchiving` component interface to `interfaceAccessor`.

  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.

  `filterValidSpecFiles`(specFiles)

    See: `IArchiving.filterValidSpecFiles()`.

  `getArchiveInfo`(specFile)

    See: `IArchiving.getArchiveInfo()`

    Warning

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

  `getStoredArchiveInfo`(archiveName)

    See: `IArchiving.getStoredArchiveInfo()`.

    Warning

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

  `getStoredArchiveNames`()

    See: `IArchiving.getStoredArchiveNames()`.

    Warning

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

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

    See also: `IArchiving.makeBackup()`.

  `purgeStoredArchiveData`(archiveName)

    See: `IArchiving.purgeStoredArchiveData()`.

    Warning

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

  `run`()

    See: `IComponent.run()`.

### _archiver_manipulator

`_ArchiverManipulator` class.

class `AutoArchive._archiving._core._archiver_manipulator.` `_ArchiverManipulator`(backupInformationProvider, interfaceAccessor)

  Bases: `object`

  Performs actions with backups.

  Uses `IArchiver` services to manipulate with or create backups.

  Note

  `backupInformationProvider` is not updated by this class.

  Parameters: | backupInformationProvider – Represents the archive that this instance shall be manipulating with. interfaceAccessor (`IInterfaceAccessor`) – An `IInterfaceAccessor` instance.
  Raises: | RuntimeError – If the archiver service could not be created.

  `createBackup`()

    Runs the archiver and creates a backup.

    Returns: | Path to the created backup.
    Return type: | `str`
    Raises: | RuntimeError – If the backup operation was aborted due to a fatal error. OSError – If a system error occurred while making the backup.

  `isOptionSupported`(option)

    Returns `True` if the passed `option` is supported by the current configuration of this instance.

    Whether an option is supported or not depends on the archiver type set in the archive specification file that is currently attached.

    Parameters: | option (`Option`) – The option which shall be tested for support.
    Returns: | `True` if the passed `option` is supported; `False` otherwise.
    Return type: | `bool`

  `saveBackupLevelInfo`(backupFilePath)

    Saves all the information required for backup level restarting to the persistent storage.

    Note

    This method should be called only once after the backup was created.

    Parameters: | backupFilePath (`str`) – Path to the created backup.

  classmethod `tryPurgeStoredArchiveData`(archiveName, userConfigDir, storage)

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

    See also: `_BackupInformationProvider.getStoredArchiveNames()`

    Parameters: | archiveName (`str`) – Name of the archive which data shall be purged. userConfigDir (`str`) – Path to the user configuration directory. storage (`IStorage`) – The application storage.
    Returns: | `True` if data was purged; `False` otherwise.
    Return type: | `bool`
    Raises: | RuntimeError – If the archiver service could not be created. OSError – If an error occurred during the operation of removing data from a physical storage.

### _backup_information_provider

`_BackupInformationProvider` class.

class `AutoArchive._archiving._core._backup_information_provider.` `_BackupInformationProvider`(archiveSpec, interfaceAccessor)

  Bases: `object`

  Provides information about backups.

  Parameters: | archiveSpec (`_ArchiveSpec`) – Archive specification of the backup that this instance will provide information about. interfaceAccessor (`IInterfaceAccessor`) – An `IInterfaceAccessor` instance.
  Raises: | RuntimeError – If the archiver service could not be created. OSError – If a system error occurred.

  static `getBackupLevelForBackup`(archiveName, userConfigDir)

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

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

  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`

  classmethod `getStoredArchiveNames`(userConfigDir, storage)

    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: | userConfigDir (`str`) – Path to the user configuration directory. storage (`IStorage`) – The application storage.
    Returns: | Set of archive names.
    Return type: | `set<str>`
    Raises: | RuntimeError – If the archiver service could not be created.

  `archiveSpec`

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

    Return type: | `_ArchiveSpec`

  `currentBackupLevel`

    Gets the current backup level or `None`.

    Return type: | `int`

  `nextBackupLevel`

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

    Return type: | `int`

  `restartLevel`

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

    Return type: | `int`

  `restartReason`

    Gets the reason for upcoming backup level restart.

    Return type: | `BackupLevelRestartReasons`

### _archiving_constants

`_ArchiverMaps` and `_RestartStorageVariables` classes.

class `AutoArchive._archiving._core._archiving_constants.` `_ArchiverMaps`

  Bases: `object`

  Mappings which involves archiver types.

  `ARCHIVER_TYPE_TO_SERVICE_MAP` = {0: 1, 1: 1, 2: 1, 3: 1, 4: 0, 5: 0, 6: 0}

class `AutoArchive._archiving._core._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'

### _archive_spec

`_ArchiveSpec` class.

class `AutoArchive._archiving._core._archive_spec.` `_ArchiveSpec`(specFile, configuration, componentUi=None)

  Bases: `AutoArchive._configuration.configuration_base.ConfigurationBase`

  The archive specification.

  Contains all information needed to create the backup such as the name, list of files which shall be included into the backup, list of files to exclude, etc. These values can be configured in the archive specification file (`specFile`) or in the general configuration such as command line or configuration files. Options that can be read from this class are defined as static attributes of `_ArchiveSpecOptions` and `Options`. If an option is not defined in the archive specification file it is read from `configuration`.

  The instance is fully populated during construction.

  Parameters: | specFile (`str`) – Archive specification file name (the “.aa file”). configuration (`IConfiguration`) – The application’s configuration. componentUi (`IComponentUi`) – The application’s UI interface. If `None` then messages about non-accessible files or other errors during processing of included and excluded file lists will not be shown.
  Raises: | IOError – If `specFile` can not be opened. LookupError – If a section or an option is missing in `specFile`. SyntaxError – If `specFile` can not be parsed. KeyError – If an invalid (unsupported) section or option is found in the archive specification file. ValueError – If option’s value is not correct.

  `getRawValue`(option)

    See: `IConfiguration.getValue()`.

class `AutoArchive._archiving._core._archive_spec.` `_ArchiveSpecOptions`

  Bases: `object`

  Constants for options used specifically in the archive specification file.

  These constants should be used to access options in `_ArchiveSpec`.

  Note

  It is not allowed to change values of these constants.

  `EXCLUDE_FILES` = <Option exclude-files of type <class 'str'>>
  `INCLUDE_FILES` = <Option include-files of type <class 'str'>>
  `NAME` = <Option name of type <class 'str'>>
  `PATH` = <Option path of type path>