CedarBackup3.config

Provides configuration-related objects.

Summary

Cedar Backup stores all of its configuration in an XML document typically called cback3.conf. The standard location for this document is in /etc, but users can specify a different location if they want to.

The Config class is a Python object representation of a Cedar Backup XML configuration file. The representation is two-way: XML data can be used to create a Config object, and then changes to the object can be propogated back to disk. A Config object can even be used to create a configuration file from scratch programmatically.

The Config class is intended to be the only Python-language interface to Cedar Backup configuration on disk. Cedar Backup will use the class as its internal representation of configuration, and applications external to Cedar Backup itself (such as a hypothetical third-party configuration tool written in Python or a third party extension module) should also use the class when they need to read and write configuration files.

Backwards Compatibility

The configuration file format has changed between Cedar Backup 1.x and Cedar Backup 2.x. Any Cedar Backup 1.x configuration file is also a valid Cedar Backup 2.x configuration file. However, it doesn’t work to go the other direction, as the 2.x configuration files contains additional configuration is not accepted by older versions of the software.

XML Configuration Structure

A Config object can either be created “empty”, or can be created based on XML input (either in the form of a string or read in from a file on disk). Generally speaking, the XML input must result in a Config object which passes the validations laid out below in the Validation section.

An XML configuration file is composed of seven sections:

  • reference: specifies reference information about the file (author, revision, etc)

  • extensions: specifies mappings to Cedar Backup extensions (external code)

  • options: specifies global configuration options

  • peers: specifies the set of peers in a master’s backup pool

  • collect: specifies configuration related to the collect action

  • stage: specifies configuration related to the stage action

  • store: specifies configuration related to the store action

  • purge: specifies configuration related to the purge action

Each section is represented by an class in this module, and then the overall Config class is a composition of the various other classes.

Any configuration section that is missing in the XML document (or has not been filled into an “empty” document) will just be set to None in the object representation. The same goes for individual fields within each configuration section. Keep in mind that the document might not be completely valid if some sections or fields aren’t filled in - but that won’t matter until validation takes place (see the Validation section below).

Unicode vs. String Data

By default, all string data that comes out of XML documents in Python is unicode data (i.e. u"whatever"). This is fine for many things, but when it comes to filesystem paths, it can cause us some problems. We really want strings to be encoded in the filesystem encoding rather than being unicode. So, most elements in configuration which represent filesystem paths are coverted to plain strings using util.encodePath. The main exception is the various absoluteExcludePath and relativeExcludePath lists. These are not converted, because they are generally only used for filtering, not for filesystem operations.

Validation

There are two main levels of validation in the Config class and its children. The first is field-level validation. Field-level validation comes into play when a given field in an object is assigned to or updated. We use Python’s property functionality to enforce specific validations on field values, and in some places we even use customized list classes to enforce validations on list members. You should expect to catch a ValueError exception when making assignments to configuration class fields.

The second level of validation is post-completion validation. Certain validations don’t make sense until a document is fully “complete”. We don’t want these validations to apply all of the time, because it would make building up a document from scratch a real pain. For instance, we might have to do things in the right order to keep from throwing exceptions, etc.

All of these post-completion validations are encapsulated in the Config.validate method. This method can be called at any time by a client, and will always be called immediately after creating a Config object from XML data and before exporting a Config object to XML. This way, we get decent ease-of-use but we also don’t accept or emit invalid configuration files.

The Config.validate implementation actually takes two passes to completely validate a configuration document. The first pass at validation is to ensure that the proper sections are filled into the document. There are default requirements, but the caller has the opportunity to override these defaults.

The second pass at validation ensures that any filled-in section contains valid data. Any section which is not set to None is validated according to the rules for that section (see below).

Reference Validations

No validations.

Extensions Validations

The list of actions may be either None or an empty list [] if desired. Each extended action must include a name, a module and a function. Then, an extended action must include either an index or dependency information. Which one is required depends on which order mode is configured.

Options Validations

All fields must be filled in except the rsh command. The rcp and rsh commands are used as default values for all remote peers. Remote peers can also rely on the backup user as the default remote user name if they choose.

Peers Validations

Local peers must be completely filled in, including both name and collect directory. Remote peers must also fill in the name and collect directory, but can leave the remote user and rcp command unset. In this case, the remote user is assumed to match the backup user from the options section and rcp command is taken directly from the options section.

Collect Validations

The target directory must be filled in. The collect mode, archive mode and ignore file are all optional. The list of absolute paths to exclude and patterns to exclude may be either None or an empty list [] if desired.

Each collect directory entry must contain an absolute path to collect, and then must either be able to take collect mode, archive mode and ignore file configuration from the parent CollectConfig object, or must set each value on its own. The list of absolute paths to exclude, relative paths to exclude and patterns to exclude may be either None or an empty list [] if desired. Any list of absolute paths to exclude or patterns to exclude will be combined with the same list in the CollectConfig object to make the complete list for a given directory.

Stage Validations

The target directory must be filled in. There must be at least one peer (remote or local) between the two lists of peers. A list with no entries can be either None or an empty list [] if desired.

If a set of peers is provided, this configuration completely overrides configuration in the peers configuration section, and the same validations apply.

Store Validations

The device type and drive speed are optional, and all other values are required (missing booleans will be set to defaults, which is OK).

The image writer functionality in the writer module is supposed to be able to handle a device speed of None. Any caller which needs a “real” (non-None) value for the device type can use DEFAULT_DEVICE_TYPE, which is guaranteed to be sensible.

Purge Validations

The list of purge directories may be either None or an empty list [] if desired. All purge directories must contain a path and a retain days value.

Module Attributes

CedarBackup3.config.DEFAULT_DEVICE_TYPE

The default device type

CedarBackup3.config.DEFAULT_MEDIA_TYPE

The default media type

CedarBackup3.config.VALID_DEVICE_TYPES

List of valid device types

CedarBackup3.config.VALID_MEDIA_TYPES

List of valid media types

CedarBackup3.config.VALID_COLLECT_MODES

List of valid collect modes

CedarBackup3.config.VALID_COMPRESS_MODES

List of valid compress modes

CedarBackup3.config.VALID_ARCHIVE_MODES

List of valid archive modes

CedarBackup3.config.VALID_ORDER_MODES

List of valid extension order modes

author

Kenneth J. Pronovici <pronovic@ieee.org>

Module Contents

CedarBackup3.config.logger
CedarBackup3.config.DEFAULT_DEVICE_TYPE = cdwriter
CedarBackup3.config.DEFAULT_MEDIA_TYPE = cdrw-74
CedarBackup3.config.VALID_DEVICE_TYPES = ['cdwriter', 'dvdwriter']
CedarBackup3.config.VALID_CD_MEDIA_TYPES = ['cdr-74', 'cdrw-74', 'cdr-80', 'cdrw-80']
CedarBackup3.config.VALID_DVD_MEDIA_TYPES = ['dvd+r', 'dvd+rw']
CedarBackup3.config.VALID_MEDIA_TYPES
CedarBackup3.config.VALID_COLLECT_MODES = ['daily', 'weekly', 'incr']
CedarBackup3.config.VALID_ARCHIVE_MODES = ['tar', 'targz', 'tarbz2']
CedarBackup3.config.VALID_COMPRESS_MODES = ['none', 'gzip', 'bzip2']
CedarBackup3.config.VALID_ORDER_MODES = ['index', 'dependency']
CedarBackup3.config.VALID_BLANK_MODES = ['daily', 'weekly']
CedarBackup3.config.VALID_BYTE_UNITS
CedarBackup3.config.VALID_FAILURE_MODES = ['none', 'all', 'daily', 'weekly']
CedarBackup3.config.REWRITABLE_MEDIA_TYPES = ['cdrw-74', 'cdrw-80', 'dvd+rw']
CedarBackup3.config.ACTION_NAME_REGEX = ^[a-z0-9]*$
class CedarBackup3.config.ByteQuantity(quantity=None, units=None)

Bases: object

Class representing a byte quantity.

A byte quantity has both a quantity and a byte-related unit. Units are maintained using the constants from util.py. If no units are provided, UNIT_BYTES is assumed.

The quantity is maintained internally as a string so that issues of precision can be avoided. It really isn’t possible to store a floating point number here while being able to losslessly translate back and forth between XML and object representations. (Perhaps the Python 2.4 Decimal class would have been an option, but I originally wanted to stay compatible with Python 2.3.)

Even though the quantity is maintained as a string, the string must be in a valid floating point positive number. Technically, any floating point string format supported by Python is allowble. However, it does not make sense to have a negative quantity of bytes in this context.

quantity
units
bytes
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of Python 2-style compare operator.

__lt__(other)

Less-than operator, implemented in terms of Python 2-style compare operator.

__gt__(other)

Greater-than operator, implemented in terms of Python 2-style compare operator.

__cmp__(other)

Python 2-style comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.ActionDependencies(beforeList=None, afterList=None)

Bases: object

Class representing dependencies associated with an extended action.

Execution ordering for extended actions is done in one of two ways: either by using index values (lower index gets run first) or by having the extended action specify dependencies in terms of other named actions. This class encapsulates the dependency information for an extended action.

The following restrictions exist on data in this class:

  • Any action name must be a non-empty string matching ACTION_NAME_REGEX

beforeList
afterList
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.ActionHook(action=None, command=None)

Bases: object

Class representing a hook associated with an action.

A hook associated with an action is a shell command to be executed either before or after a named action is executed.

The following restrictions exist on data in this class:

  • The action name must be a non-empty string matching ACTION_NAME_REGEX

  • The shell command must be a non-empty string.

The internal before and after instance variables are always set to False in this parent class.

action
command
before
after
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.PreActionHook(action=None, command=None)

Bases: ActionHook

Class representing a pre-action hook associated with an action.

A hook associated with an action is a shell command to be executed either before or after a named action is executed. In this case, a pre-action hook is executed before the named action.

The following restrictions exist on data in this class:

  • The action name must be a non-empty string consisting of lower-case letters and digits.

  • The shell command must be a non-empty string.

The internal before instance variable is always set to True in this class.

__repr__()

Official string representation for class instance.

class CedarBackup3.config.PostActionHook(action=None, command=None)

Bases: ActionHook

Class representing a pre-action hook associated with an action.

A hook associated with an action is a shell command to be executed either before or after a named action is executed. In this case, a post-action hook is executed after the named action.

The following restrictions exist on data in this class:

  • The action name must be a non-empty string consisting of lower-case letters and digits.

  • The shell command must be a non-empty string.

The internal before instance variable is always set to True in this class.

__repr__()

Official string representation for class instance.

class CedarBackup3.config.BlankBehavior(blankMode=None, blankFactor=None)

Bases: object

Class representing optimized store-action media blanking behavior.

The following restrictions exist on data in this class:

  • The blanking mode must be a one of the values in VALID_BLANK_MODES

  • The blanking factor must be a positive floating point number

blankMode
blankFactor
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.ExtendedAction(name=None, module=None, function=None, index=None, dependencies=None)

Bases: object

Class representing an extended action.

Essentially, an extended action needs to allow the following to happen:

exec("from %s import %s" % (module, function))
exec("%s(action, configPath")" % function)

The following restrictions exist on data in this class:

  • The action name must be a non-empty string consisting of lower-case letters and digits.

  • The module must be a non-empty string and a valid Python identifier.

  • The function must be an on-empty string and a valid Python identifier.

  • If set, the index must be a positive integer.

  • If set, the dependencies attribute must be an ActionDependencies object.

name
module
function
index
dependencies
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.CommandOverride(command=None, absolutePath=None)

Bases: object

Class representing a piece of Cedar Backup command override configuration.

The following restrictions exist on data in this class:

  • The absolute path must be absolute

Note: Lists within this class are “unordered” for equality comparisons.

command
absolutePath
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.CollectFile(absolutePath=None, collectMode=None, archiveMode=None)

Bases: object

Class representing a Cedar Backup collect file.

The following restrictions exist on data in this class:

absolutePath
collectMode
archiveMode
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.CollectDir(absolutePath=None, collectMode=None, archiveMode=None, ignoreFile=None, absoluteExcludePaths=None, relativeExcludePaths=None, excludePatterns=None, linkDepth=None, dereference=False, recursionLevel=None)

Bases: object

Class representing a Cedar Backup collect directory.

The following restrictions exist on data in this class:

  • Absolute paths must be absolute

  • The collect mode must be one of the values in VALID_COLLECT_MODES.

  • The archive mode must be one of the values in VALID_ARCHIVE_MODES.

  • The ignore file must be a non-empty string.

For the absoluteExcludePaths list, validation is accomplished through the util.AbsolutePathList list implementation that overrides common list methods and transparently does the absolute path validation for us.

Note: Lists within this class are “unordered” for equality comparisons.

absolutePath
collectMode
archiveMode
ignoreFile
linkDepth
dereference
recursionLevel
absoluteExcludePaths
relativeExcludePaths
excludePatterns
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.PurgeDir(absolutePath=None, retainDays=None)

Bases: object

Class representing a Cedar Backup purge directory.

The following restrictions exist on data in this class:

  • The absolute path must be an absolute path

  • The retain days value must be an integer >= 0.

absolutePath
retainDays
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.LocalPeer(name=None, collectDir=None, ignoreFailureMode=None)

Bases: object

Class representing a Cedar Backup peer.

The following restrictions exist on data in this class:

  • The peer name must be a non-empty string.

  • The collect directory must be an absolute path.

  • The ignore failure mode must be one of the values in VALID_FAILURE_MODES.

name
collectDir
ignoreFailureMode
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.RemotePeer(name=None, collectDir=None, remoteUser=None, rcpCommand=None, rshCommand=None, cbackCommand=None, managed=False, managedActions=None, ignoreFailureMode=None)

Bases: object

Class representing a Cedar Backup peer.

The following restrictions exist on data in this class:

  • The peer name must be a non-empty string.

  • The collect directory must be an absolute path.

  • The remote user must be a non-empty string.

  • The rcp command must be a non-empty string.

  • The rsh command must be a non-empty string.

  • The cback command must be a non-empty string.

  • Any managed action name must be a non-empty string matching ACTION_NAME_REGEX

  • The ignore failure mode must be one of the values in VALID_FAILURE_MODES.

name
collectDir
remoteUser
rcpCommand
rshCommand
cbackCommand
managed
managedActions
ignoreFailureMode
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.ReferenceConfig(author=None, revision=None, description=None, generator=None)

Bases: object

Class representing a Cedar Backup reference configuration.

The reference information is just used for saving off metadata about configuration and exists mostly for backwards-compatibility with Cedar Backup 1.x.

author
revision
description
generator
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.ExtensionsConfig(actions=None, orderMode=None)

Bases: object

Class representing Cedar Backup extensions configuration.

Extensions configuration is used to specify “extended actions” implemented by code external to Cedar Backup. For instance, a hypothetical third party might write extension code to collect database repository data. If they write a properly-formatted extension function, they can use the extension configuration to map a command-line Cedar Backup action (i.e. “database”) to their function.

The following restrictions exist on data in this class:

  • If set, the order mode must be one of the values in VALID_ORDER_MODES

  • The actions list must be a list of ExtendedAction objects.

orderMode
actions
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.OptionsConfig(startingDay=None, workingDir=None, backupUser=None, backupGroup=None, rcpCommand=None, overrides=None, hooks=None, rshCommand=None, cbackCommand=None, managedActions=None)

Bases: object

Class representing a Cedar Backup global options configuration.

The options section is used to store global configuration options and defaults that can be applied to other sections.

The following restrictions exist on data in this class:

  • The working directory must be an absolute path.

  • The starting day must be a day of the week in English, i.e. "monday", "tuesday", etc.

  • All of the other values must be non-empty strings if they are set to something other than None.

  • The overrides list must be a list of CommandOverride objects.

  • The hooks list must be a list of ActionHook objects.

  • The cback command must be a non-empty string.

  • Any managed action name must be a non-empty string matching ACTION_NAME_REGEX

startingDay
workingDir
backupUser
backupGroup
rcpCommand
rshCommand
cbackCommand
overrides
hooks
managedActions
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

addOverride(command, absolutePath)

If no override currently exists for the command, add one. :param command: Name of command to be overridden :param absolutePath: Absolute path of the overrridden command

replaceOverride(command, absolutePath)

If override currently exists for the command, replace it; otherwise add it. :param command: Name of command to be overridden :param absolutePath: Absolute path of the overrridden command

class CedarBackup3.config.PeersConfig(localPeers=None, remotePeers=None)

Bases: object

Class representing Cedar Backup global peer configuration.

This section contains a list of local and remote peers in a master’s backup pool. The section is optional. If a master does not define this section, then all peers are unmanaged, and the stage configuration section must explicitly list any peer that is to be staged. If this section is configured, then peers may be managed or unmanaged, and the stage section peer configuration (if any) completely overrides this configuration.

The following restrictions exist on data in this class:

  • The list of local peers must contain only LocalPeer objects

  • The list of remote peers must contain only RemotePeer objects

Note: Lists within this class are “unordered” for equality comparisons.

localPeers
remotePeers
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

hasPeers()

Indicates whether any peers are filled into this object. :returns: Boolean true if any local or remote peers are filled in, false otherwise

class CedarBackup3.config.CollectConfig(targetDir=None, collectMode=None, archiveMode=None, ignoreFile=None, absoluteExcludePaths=None, excludePatterns=None, collectFiles=None, collectDirs=None)

Bases: object

Class representing a Cedar Backup collect configuration.

The following restrictions exist on data in this class:

  • The target directory must be an absolute path.

  • The collect mode must be one of the values in VALID_COLLECT_MODES.

  • The archive mode must be one of the values in VALID_ARCHIVE_MODES.

  • The ignore file must be a non-empty string.

  • Each of the paths in absoluteExcludePaths must be an absolute path

  • The collect file list must be a list of CollectFile objects.

  • The collect directory list must be a list of CollectDir objects.

For the absoluteExcludePaths list, validation is accomplished through the util.AbsolutePathList list implementation that overrides common list methods and transparently does the absolute path validation for us.

For the collectFiles and collectDirs list, validation is accomplished through the util.ObjectTypeList list implementation that overrides common list methods and transparently ensures that each element has an appropriate type.

Note: Lists within this class are “unordered” for equality comparisons.

targetDir
collectMode
archiveMode
ignoreFile
absoluteExcludePaths
excludePatterns
collectFiles
collectDirs
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.StageConfig(targetDir=None, localPeers=None, remotePeers=None)

Bases: object

Class representing a Cedar Backup stage configuration.

The following restrictions exist on data in this class:

  • The target directory must be an absolute path

  • The list of local peers must contain only LocalPeer objects

  • The list of remote peers must contain only RemotePeer objects

Note: Lists within this class are “unordered” for equality comparisons.

targetDir
localPeers
remotePeers
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

hasPeers()

Indicates whether any peers are filled into this object. :returns: Boolean true if any local or remote peers are filled in, false otherwise

class CedarBackup3.config.StoreConfig(sourceDir=None, mediaType=None, deviceType=None, devicePath=None, deviceScsiId=None, driveSpeed=None, checkData=False, warnMidnite=False, noEject=False, checkMedia=False, blankBehavior=None, refreshMediaDelay=None, ejectDelay=None)

Bases: object

Class representing a Cedar Backup store configuration.

The following restrictions exist on data in this class:

  • The source directory must be an absolute path.

  • The media type must be one of the values in VALID_MEDIA_TYPES.

  • The device type must be one of the values in VALID_DEVICE_TYPES.

  • The device path must be an absolute path.

  • The SCSI id, if provided, must be in the form specified by validateScsiId.

  • The drive speed must be an integer >= 1

  • The blanking behavior must be a BlankBehavior object

  • The refresh media delay must be an integer >= 0

  • The eject delay must be an integer >= 0

Note that although the blanking factor must be a positive floating point number, it is stored as a string. This is done so that we can losslessly go back and forth between XML and object representations of configuration.

sourceDir
mediaType
deviceType
devicePath
deviceScsiId
driveSpeed
checkData
checkMedia
warnMidnite
noEject
blankBehavior
refreshMediaDelay
ejectDelay
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.PurgeConfig(purgeDirs=None)

Bases: object

Class representing a Cedar Backup purge configuration.

The following restrictions exist on data in this class:

  • The purge directory list must be a list of PurgeDir objects.

For the purgeDirs list, validation is accomplished through the util.ObjectTypeList list implementation that overrides common list methods and transparently ensures that each element is a PurgeDir.

Note: Lists within this class are “unordered” for equality comparisons.

purgeDirs
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

class CedarBackup3.config.Config(xmlData=None, xmlPath=None, validate=True)

Bases: object

Class representing a Cedar Backup XML configuration document.

The Config class is a Python object representation of a Cedar Backup XML configuration file. It is intended to be the only Python-language interface to Cedar Backup configuration on disk for both Cedar Backup itself and for external applications.

The object representation is two-way: XML data can be used to create a Config object, and then changes to the object can be propogated back to disk. A Config object can even be used to create a configuration file from scratch programmatically.

This class and the classes it is composed from often use Python’s property construct to validate input and limit access to values. Some validations can only be done once a document is considered “complete” (see module notes for more details).

Assignments to the various instance variables must match the expected type, i.e. reference must be a ReferenceConfig. The internal check uses the built-in isinstance function, so it should be OK to use subclasses if you want to.

If an instance variable is not set, its value will be None. When an object is initialized without using an XML document, all of the values will be None. Even when an object is initialized using XML, some of the values might be None because not every section is required.

Note: Lists within this class are “unordered” for equality comparisons.

reference
extensions
options
peers
collect
stage
store
purge
__repr__()

Official string representation for class instance.

__str__()

Informal string representation for class instance.

__eq__(other)

Equals operator, implemented in terms of original Python 2 compare operator.

__lt__(other)

Less-than operator, implemented in terms of original Python 2 compare operator.

__gt__(other)

Greater-than operator, implemented in terms of original Python 2 compare operator.

__cmp__(other)

Original Python 2 comparison operator. Lists within this class are “unordered” for equality comparisons. :param other: Other object to compare to

Returns

-1/0/1 depending on whether self is <, = or > other

extractXml(xmlPath=None, validate=True)

Extracts configuration into an XML document.

If xmlPath is not provided, then the XML document will be returned as a string. If xmlPath is provided, then the XML document will be written to the file and None will be returned.

Unless the validate parameter is False, the Config.validate method will be called (with its default arguments) against the configuration before extracting the XML. If configuration is not valid, then an XML document will not be extracted.

Note: It is strongly suggested that the validate option always be set to True (the default) unless there is a specific need to write an invalid configuration file to disk.

Parameters

  • xmlPath (Absolute path to a file) – Path to an XML file to create on disk

  • validate (Boolean true/false) – Validate the document before extracting it

Returns

XML string data or None as described above

Raises

  • ValueError – If configuration within the object is not valid

  • IOError – If there is an error writing to the file

  • OSError – If there is an error writing to the file

validate(requireOneAction=True, requireReference=False, requireExtensions=False, requireOptions=True, requireCollect=False, requireStage=False, requireStore=False, requirePurge=False, requirePeers=False)

Validates configuration represented by the object.

This method encapsulates all of the validations that should apply to a fully “complete” document but are not already taken care of by earlier validations. It also provides some extra convenience functionality which might be useful to some people. The process of validation is laid out in the Validation section in the class notes (above).

Parameters

  • requireOneAction – Require at least one of the collect, stage, store or purge sections

  • requireReference – Require the reference section

  • requireExtensions – Require the extensions section

  • requireOptions – Require the options section

  • requirePeers – Require the peers section

  • requireCollect – Require the collect section

  • requireStage – Require the stage section

  • requireStore – Require the store section

  • requirePurge – Require the purge section

Raises

ValueError – If one of the validations fails

CedarBackup3.config.readByteQuantity(parent, name)

Read a byte size value from an XML document.

A byte size value is an interpreted string value. If the string value ends with “MB” or “GB”, then the string before that is interpreted as megabytes or gigabytes. Otherwise, it is intepreted as bytes.

Parameters

  • parent – Parent node to search beneath

  • name – Name of node to search for

Returns

ByteQuantity parsed from XML document

CedarBackup3.config.addByteQuantityNode(xmlDom, parentNode, nodeName, byteQuantity)

Adds a text node as the next child of a parent, to contain a byte size.

If the byteQuantity is None, then the node will be created, but will be empty (i.e. will contain no text node child).

The size in bytes will be normalized. If it is larger than 1.0 GB, it will be shown in GB (“1.0 GB”). If it is larger than 1.0 MB (“1.0 MB”), it will be shown in MB. Otherwise, it will be shown in bytes (“423413”).

Parameters

  • xmlDom – DOM tree as from impl.createDocument()

  • parentNode – Parent node to create child for

  • nodeName – Name of the new container node

  • byteQuantity – ByteQuantity object to put into the XML document

Returns

Reference to the newly-created node