Source code for AutoArchive._archiving.iarchiving

# iarchiving.py
#
# Project: AutoArchive
# License: GNU GPLv3
#
# Copyright (C) 2003 - 2012 Róbert Čerňanský



""":data:`ArchiverTypes` and :attr:`BackupLevelRestartReasons` enums, :class:`IArchiving` interface and
:class:`ArchiveInfo` class."""



__all__ = ["ArchiverTypes", "BackupLevelRestartReasons", "IArchiving", "ArchiveInfo"]



# {{{ INCLUDES

from abc import *

from .._py_additions import *
from .._mainf import *

# }}} INCLUDES



# {{{ CONSTANTS

#: Archiver types.
ArchiverTypes = Enum(
    "Tar",
    "TarGz",
    "TarBz2",
    "TarXz",
    "TarInternal",
    "TarGzInternal",
    "TarBz2Internal")



#: Reasons for restarting of the :term:`backup level`.
BackupLevelRestartReasons = Enum(

    #: :term:`Backup level` restart did not occurred.
    "NoRestart",

    #: Maximal number of restarts to a lower :term:`backup level` was reached.  Full restart was done.
    "RestartCountLimitReached",

    #: Maximal age without full restart was reached.  Full restart was done.
    "LastFullRestartAgeLimitReached",

    #: Maximal :term:`backup level` reached.  Restart to a lower level was done.
    "BackupLevelLimitReached",

    #: Maximal age without a restart was reached.  Restart to a lower level was done.
    "LastRestartAgeLimitReached")

# }}} CONSTANTS



# {{{ CLASSES

[docs]class IArchiving(IComponentInterface): """Provides access to the :term:`Archiving` component.""" @abstractmethod
[docs] def makeBackup(self, specFile): """Creates a :term:`backup` based on ``specFile``. :param specFile: Path to the :term:`archive specification file`. :type specFile: ``str`` :raise ValueError: If the desired archiver type is not supported."""
@abstractmethod
[docs] def filterValidSpecFiles(self, specFiles): """Returns names of :term:`configured archives <configured archive>` from valid only :term:`archive specification files <archive specification file>` passed in ``specFiles``. :param specFiles: Paths to archive specification files that shall be validated and from which the names shall be retrieved. :type specFiles: ``Iterable<str>`` :return: Iterable of names of validly configured archives. :rtype: ``Iterable<str>``"""
@abstractmethod
[docs] def getArchiveInfo(self, specFile): """Returns information about archive represented by the ``specFile`` parameter. :param specFile: Path to the :term:`archive specification file`. :type specFile: ``str`` :return: Information about an archive or ``None``. :rtype: :class:`ArchiveInfo`"""
@abstractmethod
[docs] def getStoredArchiveInfo(self, archiveName): """Returns information about an archive from stored data. Unlike in the :meth:`getArchiveInfo` method the information is not read from the :term:`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 (:class:`.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: :meth:`getStoredArchiveNames()` :param archiveName: Name of the archive which information shall be returned. :type archiveName: ``str`` :return: Information about an archive or ``None`` if no data for the archive was found. :rtype: :class:`ArchiveInfo`"""
@abstractmethod
[docs] def getStoredArchiveNames(self): """Returns iterable of archive names which has some data stored in a persistent storage. See also: :meth:`getStoredArchiveInfo()` :return: Iterable of archive names. :rtype: ``Iterable<str>``"""
@abstractmethod
[docs] def purgeStoredArchiveData(self, archiveName): """Deletes all data stored for the archive named ``archiveName``. See also: :meth:`getStoredArchiveInfo()` :param archiveName: Name of the archive which data shall be purged. :type archiveName: ``str`` :raise KeyError: If ``archiveName`` does not have any stored data to purge. :raise OSError: If an error occurred during the operation of removing data from a physical storage."""
[docs]class ArchiveInfo(metaclass = ABCMeta): """Information about an archive. .. note:: Class should be instantiated by calling the :meth:`IArchiving.getArchiveInfo()` or \ :meth:`IArchiving.getStoredArchiveInfo()` factory methods.""" @abstractmethod def __init__(self, name): self._name = name self._path = None self._archiverType = ArchiverTypes.Tar self._destDir = "" self._incremental = None self._backupLevel = None self._nextBackupLevel = None self._restarting = None self._restartAfterLevel = None self._restartReason = None self._restartLevel = None self._restartCount = None self._fullRestartAfterCount = None self._lastRestart = None self._restartAfterAge = None self._lastFullRestart = None self._fullRestartAfterAge = None @property
[docs] def name(self): """Gets the name of the archive. :rtype: ``str``""" return self._name
@property
[docs] def path(self): """Gets the path to the archive's root. .. note:: Will be ``None`` if the archive's root can not be retrieved. :rtype: ``str``""" return self._path
@property
[docs] def archiverType(self): """Gets the archiver type for this archive. .. note:: Value is guaranteed to be non-\ ``None``. :rtype: :attr:`ArchiverTypes`""" return self._archiverType
@property
[docs] def destDir(self): """Gets the archive's destination directory. .. note:: Value is guaranteed to be non-\ ``None``. :rtype: ``str``""" return self._destDir
@property
[docs] def incremental(self): """Gets the status of incremental archiving activation. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving. :rtype: ``bool``""" return self._incremental
@property
[docs] def backupLevel(self): """Gets the current :term:`backup level`. .. note:: Will be ``None`` if the archive is not incremental or used :attr:`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* :attr:`incremental` value. If the archive was configured and created \ as incremental previously then the :term:`backup level` will be defined even if the current \ :attr:`incremental` value would be ``False`` and vice versa. :rtype: ``int``""" return self._backupLevel
@property
[docs] def nextBackupLevel(self): """Gets the next :term:`backup level`. See also :attr:`backupLevel`. .. note:: Will be ``None`` if the archive is not incremental or used :attr:`archiverType` does not support incremental archiving. :rtype: ``int``""" return self._nextBackupLevel
@property
[docs] def restarting(self): """Gets the status of :term:`backup level` restarting activation. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving. :rtype: ``bool``""" return self._restarting
@property
[docs] def restartAfterLevel(self): """Gets the maximal :term:`backup level`; after it is reached it will be restarted to a lower value. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving. :rtype: ``int``""" return self._restartAfterLevel
@property
[docs] def restartReason(self): """Gets the reason for the upcoming :term:`backup level` restart. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or the restart reason can not be determined. :rtype: :attr:`BackupLevelRestartReasons`""" return self._restartReason
@property
[docs] def restartLevel(self): """Gets a :term:`backup level` to which a next restart would be done. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving. :rtype: ``int``""" return self._restartLevel
@property
[docs] def restartCount(self): """Gets the number of :term:`backup level` restarts already performed. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if \ :attr:`restarting` was not enabled for the archive in the past. :rtype: ``int``""" return self._restartCount
@property
[docs] def fullRestartAfterCount(self): """Gets the number of restarts after which the :term:`backup level` will be restarted to 0. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if no value \ is defined for :attr:`.Options.FULL_RESTART_AFTER_COUNT`. :rtype: ``int``""" return self._fullRestartAfterCount
@property
[docs] def lastRestart(self): """Gets the date when the last :term:`backup level` restart occurred. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if \ :attr:`restarting` was not enabled for the archive in the past. :rtype: ``datetime.date``""" return self._lastRestart
@property
[docs] def restartAfterAge(self): """Gets the number of days after which the :term:`backup level` should be restarted. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if no value is defined for :attr:`.Options.RESTART_AFTER_AGE`. :rtype: ``int``""" return self._restartAfterAge
@property
[docs] def lastFullRestart(self): """Gets the date when the last :term:`backup level` restart to level 0 occurred. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if \ :attr:`restarting` was not enabled for the archive in the past. :rtype: ``datetime.date``""" return self._lastFullRestart
@property
[docs] def fullRestartAfterAge(self): """Gets the number of days after which the :term:`backup level` should be restarted to level 0. .. note:: Will be ``None`` if the :attr:`archiverType` does not support incremental archiving or if no value is defined for :attr:`.Options.FULL_RESTART_AFTER_AGE`. :rtype: ``int``""" return self._fullRestartAfterAge # }}} CLASSES