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."""
[docs] @abstractmethod
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."""
[docs] @abstractmethod
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>``"""
[docs] @abstractmethod
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`"""
[docs] @abstractmethod
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`"""
[docs] @abstractmethod
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>``"""
[docs] @abstractmethod
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
def name(self):
"""Gets the name of the archive.
:rtype: ``str``"""
return self._name
@property
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
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
def destDir(self):
"""Gets the archive's destination directory.
.. note:: Value is guaranteed to be non-\ ``None``.
:rtype: ``str``"""
return self._destDir
@property
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
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
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
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
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
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
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
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
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
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
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
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
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