Package CedarBackup2 :: Module config :: Class Config
[hide private]
[frames] | no frames]

Class Config

source code

object --+
         |
        Config

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.

Instance Methods [hide private]
 
__init__(self, xmlData=None, xmlPath=None, validate=True)
Initializes a configuration object.
source code
 
__repr__(self)
Official string representation for class instance.
source code
 
__str__(self)
Informal string representation for class instance.
source code
 
__cmp__(self, other)
Definition of equals operator for this class.
source code
 
extractXml(self, xmlPath=None, validate=True)
Extracts configuration into an XML document.
source code
 
validate(self, requireOneAction=True, requireReference=False, requireExtensions=False, requireOptions=True, requireCollect=False, requireStage=False, requireStore=False, requirePurge=False, requirePeers=False)
Validates configuration represented by the object.
source code
 
_getReference(self)
Property target used to get the reference configuration value.
source code
 
_setReference(self, value)
Property target used to set the reference configuration value.
source code
 
_getExtensions(self)
Property target used to get the extensions configuration value.
source code
 
_setExtensions(self, value)
Property target used to set the extensions configuration value.
source code
 
_getOptions(self)
Property target used to get the options configuration value.
source code
 
_setOptions(self, value)
Property target used to set the options configuration value.
source code
 
_getPeers(self)
Property target used to get the peers configuration value.
source code
 
_setPeers(self, value)
Property target used to set the peers configuration value.
source code
 
_getCollect(self)
Property target used to get the collect configuration value.
source code
 
_setCollect(self, value)
Property target used to set the collect configuration value.
source code
 
_getStage(self)
Property target used to get the stage configuration value.
source code
 
_setStage(self, value)
Property target used to set the stage configuration value.
source code
 
_getStore(self)
Property target used to get the store configuration value.
source code
 
_setStore(self, value)
Property target used to set the store configuration value.
source code
 
_getPurge(self)
Property target used to get the purge configuration value.
source code
 
_setPurge(self, value)
Property target used to set the purge configuration value.
source code
 
_parseXmlData(self, xmlData)
Internal method to parse an XML string into the object.
source code
 
_extractXml(self)
Internal method to extract configuration into an XML string.
source code
 
_validateContents(self)
Validates configuration contents per rules discussed in module documentation.
source code
 
_validateReference(self)
Validates reference configuration.
source code
 
_validateExtensions(self)
Validates extensions configuration.
source code
 
_validateOptions(self)
Validates options configuration.
source code
 
_validatePeers(self)
Validates peers configuration per rules in _validatePeerList.
source code
 
_validateCollect(self)
Validates collect configuration.
source code
 
_validateStage(self)
Validates stage configuration.
source code
 
_validateStore(self)
Validates store configuration.
source code
 
_validatePurge(self)
Validates purge configuration.
source code
 
_validatePeerList(self, localPeers, remotePeers)
Validates the set of local and remote peers.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Static Methods [hide private]
 
_parseReference(parentNode)
Parses a reference configuration section.
source code
 
_parseExtensions(parentNode)
Parses an extensions configuration section.
source code
 
_parseOptions(parentNode)
Parses a options configuration section.
source code
 
_parsePeers(parentNode)
Parses a peers configuration section.
source code
 
_parseCollect(parentNode)
Parses a collect configuration section.
source code
 
_parseStage(parentNode)
Parses a stage configuration section.
source code
 
_parseStore(parentNode)
Parses a store configuration section.
source code
 
_parsePurge(parentNode)
Parses a purge configuration section.
source code
 
_parseExtendedActions(parentNode)
Reads extended actions data from immediately beneath the parent.
source code
 
_parseExclusions(parentNode)
Reads exclusions data from immediately beneath the parent.
source code
 
_parseOverrides(parentNode)
Reads a list of CommandOverride objects from immediately beneath the parent.
source code
 
_parseHooks(parentNode)
Reads a list of ActionHook objects from immediately beneath the parent.
source code
 
_parseCollectFiles(parentNode)
Reads a list of CollectFile objects from immediately beneath the parent.
source code
 
_parseCollectDirs(parentNode)
Reads a list of CollectDir objects from immediately beneath the parent.
source code
 
_parsePurgeDirs(parentNode)
Reads a list of PurgeDir objects from immediately beneath the parent.
source code
 
_parsePeerList(parentNode)
Reads remote and local peer data from immediately beneath the parent.
source code
 
_parseDependencies(parentNode)
Reads extended action dependency information from a parent node.
source code
 
_parseBlankBehavior(parentNode)
Reads a single BlankBehavior object from immediately beneath the parent.
source code
 
_addReference(xmlDom, parentNode, referenceConfig)
Adds a <reference> configuration section as the next child of a parent.
source code
 
_addExtensions(xmlDom, parentNode, extensionsConfig)
Adds an <extensions> configuration section as the next child of a parent.
source code
 
_addOptions(xmlDom, parentNode, optionsConfig)
Adds a <options> configuration section as the next child of a parent.
source code
 
_addPeers(xmlDom, parentNode, peersConfig)
Adds a <peers> configuration section as the next child of a parent.
source code
 
_addCollect(xmlDom, parentNode, collectConfig)
Adds a <collect> configuration section as the next child of a parent.
source code
 
_addStage(xmlDom, parentNode, stageConfig)
Adds a <stage> configuration section as the next child of a parent.
source code
 
_addStore(xmlDom, parentNode, storeConfig)
Adds a <store> configuration section as the next child of a parent.
source code
 
_addPurge(xmlDom, parentNode, purgeConfig)
Adds a <purge> configuration section as the next child of a parent.
source code
 
_addExtendedAction(xmlDom, parentNode, action)
Adds an extended action container as the next child of a parent.
source code
 
_addOverride(xmlDom, parentNode, override)
Adds a command override container as the next child of a parent.
source code
 
_addHook(xmlDom, parentNode, hook)
Adds an action hook container as the next child of a parent.
source code
 
_addCollectFile(xmlDom, parentNode, collectFile)
Adds a collect file container as the next child of a parent.
source code
 
_addCollectDir(xmlDom, parentNode, collectDir)
Adds a collect directory container as the next child of a parent.
source code
 
_addLocalPeer(xmlDom, parentNode, localPeer)
Adds a local peer container as the next child of a parent.
source code
 
_addRemotePeer(xmlDom, parentNode, remotePeer)
Adds a remote peer container as the next child of a parent.
source code
 
_addPurgeDir(xmlDom, parentNode, purgeDir)
Adds a purge directory container as the next child of a parent.
source code
 
_addDependencies(xmlDom, parentNode, dependencies)
Adds a extended action dependencies to parent node.
source code
 
_buildCommaSeparatedString(valueList)
Creates a comma-separated string from a list of values.
source code
 
_addBlankBehavior(xmlDom, parentNode, blankBehavior)
Adds a blanking behavior container as the next child of a parent.
source code
Properties [hide private]
  reference
Reference configuration in terms of a ReferenceConfig object.
  extensions
Extensions configuration in terms of a ExtensionsConfig object.
  options
Options configuration in terms of a OptionsConfig object.
  collect
Collect configuration in terms of a CollectConfig object.
  stage
Stage configuration in terms of a StageConfig object.
  store
Store configuration in terms of a StoreConfig object.
  purge
Purge configuration in terms of a PurgeConfig object.
  peers
Peers configuration in terms of a PeersConfig object.

Inherited from object: __class__

Method Details [hide private]

__init__(self, xmlData=None, xmlPath=None, validate=True)
(Constructor)

source code 

Initializes a configuration object.

If you initialize the object without passing either xmlData or xmlPath, then configuration will be empty and will be invalid until it is filled in properly.

No reference to the original XML data or original path is saved off by this class. Once the data has been parsed (successfully or not) this original information is discarded.

Unless the validate argument is False, the Config.validate method will be called (with its default arguments) against configuration after successfully parsing any passed-in XML. Keep in mind that even if validate is False, it might not be possible to parse the passed-in XML document if lower-level validations fail.

Parameters:
  • xmlData (String data.) - XML data representing configuration.
  • xmlPath (Absolute path to a file on disk.) - Path to an XML file on disk.
  • validate (Boolean true/false.) - Validate the document after parsing it.
Raises:
  • ValueError - If both xmlData and xmlPath are passed-in.
  • ValueError - If the XML data in xmlData or xmlPath cannot be parsed.
  • ValueError - If the parsed configuration document is not valid.
Overrides: object.__init__

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

__repr__(self)
(Representation operator)

source code 

Official string representation for class instance.

Overrides: object.__repr__

__str__(self)
(Informal representation operator)

source code 

Informal string representation for class instance.

Overrides: object.__str__

__cmp__(self, other)
(Comparison operator)

source code 

Definition of equals operator for this class. Lists within this class are "unordered" for equality comparisons.

Parameters:
  • other - Other object to compare to.
Returns:
-1/0/1 depending on whether self is <, = or > other.

extractXml(self, xmlPath=None, validate=True)

source code 

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.

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.

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.

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

source code 

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.

_setReference(self, value)

source code 

Property target used to set the reference configuration value. If not None, the value must be a ReferenceConfig object.

Raises:
  • ValueError - If the value is not a ReferenceConfig

_setExtensions(self, value)

source code 

Property target used to set the extensions configuration value. If not None, the value must be a ExtensionsConfig object.

Raises:
  • ValueError - If the value is not a ExtensionsConfig

_setOptions(self, value)

source code 

Property target used to set the options configuration value. If not None, the value must be an OptionsConfig object.

Raises:
  • ValueError - If the value is not a OptionsConfig

_setPeers(self, value)

source code 

Property target used to set the peers configuration value. If not None, the value must be an PeersConfig object.

Raises:
  • ValueError - If the value is not a PeersConfig

_setCollect(self, value)

source code 

Property target used to set the collect configuration value. If not None, the value must be a CollectConfig object.

Raises:
  • ValueError - If the value is not a CollectConfig

_setStage(self, value)

source code 

Property target used to set the stage configuration value. If not None, the value must be a StageConfig object.

Raises:
  • ValueError - If the value is not a StageConfig

_setStore(self, value)

source code 

Property target used to set the store configuration value. If not None, the value must be a StoreConfig object.

Raises:
  • ValueError - If the value is not a StoreConfig

_setPurge(self, value)

source code 

Property target used to set the purge configuration value. If not None, the value must be a PurgeConfig object.

Raises:
  • ValueError - If the value is not a PurgeConfig

_parseXmlData(self, xmlData)

source code 

Internal method to parse an XML string into the object.

This method parses the XML document into a DOM tree (xmlDom) and then calls individual static methods to parse each of the individual configuration sections.

Most of the validation we do here has to do with whether the document can be parsed and whether any values which exist are valid. We don't do much validation as to whether required elements actually exist unless we have to to make sense of the document (instead, that's the job of the validate method).

Parameters:
  • xmlData (String data) - XML data to be parsed
Raises:
  • ValueError - If the XML cannot be successfully parsed.

_parseReference(parentNode)
Static Method

source code 

Parses a reference configuration section.

We read the following fields:

  author         //cb_config/reference/author
  revision       //cb_config/reference/revision
  description    //cb_config/reference/description
  generator      //cb_config/reference/generator
Parameters:
  • parentNode - Parent node to search beneath.
Returns:
ReferenceConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseExtensions(parentNode)
Static Method

source code 

Parses an extensions configuration section.

We read the following fields:

  orderMode            //cb_config/extensions/order_mode

We also read groups of the following items, one list element per item:

  name                 //cb_config/extensions/action/name
  module               //cb_config/extensions/action/module
  function             //cb_config/extensions/action/function
  index                //cb_config/extensions/action/index
  dependencies         //cb_config/extensions/action/depends

The extended actions are parsed by _parseExtendedActions.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
ExtensionsConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseOptions(parentNode)
Static Method

source code 

Parses a options configuration section.

We read the following fields:

  startingDay    //cb_config/options/starting_day
  workingDir     //cb_config/options/working_dir
  backupUser     //cb_config/options/backup_user
  backupGroup    //cb_config/options/backup_group
  rcpCommand     //cb_config/options/rcp_command
  rshCommand     //cb_config/options/rsh_command
  cbackCommand   //cb_config/options/cback_command
  managedActions //cb_config/options/managed_actions

The list of managed actions is a comma-separated list of action names.

We also read groups of the following items, one list element per item:

  overrides      //cb_config/options/override
  hooks          //cb_config/options/hook

The overrides are parsed by _parseOverrides and the hooks are parsed by _parseHooks.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
OptionsConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parsePeers(parentNode)
Static Method

source code 

Parses a peers configuration section.

We read groups of the following items, one list element per item:

  localPeers     //cb_config/stage/peer
  remotePeers    //cb_config/stage/peer

The individual peer entries are parsed by _parsePeerList.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
StageConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseCollect(parentNode)
Static Method

source code 

Parses a collect configuration section.

We read the following individual fields:

  targetDir            //cb_config/collect/collect_dir
  collectMode          //cb_config/collect/collect_mode
  archiveMode          //cb_config/collect/archive_mode
  ignoreFile           //cb_config/collect/ignore_file

We also read groups of the following items, one list element per item:

  absoluteExcludePaths //cb_config/collect/exclude/abs_path
  excludePatterns      //cb_config/collect/exclude/pattern
  collectFiles         //cb_config/collect/file
  collectDirs          //cb_config/collect/dir

The exclusions are parsed by _parseExclusions, the collect files are parsed by _parseCollectFiles, and the directories are parsed by _parseCollectDirs.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
CollectConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseStage(parentNode)
Static Method

source code 

Parses a stage configuration section.

We read the following individual fields:

  targetDir      //cb_config/stage/staging_dir

We also read groups of the following items, one list element per item:

  localPeers     //cb_config/stage/peer
  remotePeers    //cb_config/stage/peer

The individual peer entries are parsed by _parsePeerList.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
StageConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseStore(parentNode)
Static Method

source code 

Parses a store configuration section.

We read the following fields:

  sourceDir         //cb_config/store/source_dir
  mediaType         //cb_config/store/media_type
  deviceType        //cb_config/store/device_type
  devicePath        //cb_config/store/target_device
  deviceScsiId      //cb_config/store/target_scsi_id
  driveSpeed        //cb_config/store/drive_speed
  checkData         //cb_config/store/check_data
  checkMedia        //cb_config/store/check_media
  warnMidnite       //cb_config/store/warn_midnite
  noEject           //cb_config/store/no_eject

Blanking behavior configuration is parsed by the _parseBlankBehavior method.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
StoreConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parsePurge(parentNode)
Static Method

source code 

Parses a purge configuration section.

We read groups of the following items, one list element per item:

  purgeDirs     //cb_config/purge/dir

The individual directory entries are parsed by _parsePurgeDirs.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
PurgeConfig object or None if the section does not exist.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseExtendedActions(parentNode)
Static Method

source code 

Reads extended actions data from immediately beneath the parent.

We read the following individual fields from each extended action:

  name           name
  module         module
  function       function
  index          index
  dependencies   depends

Dependency information is parsed by the _parseDependencies method.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of extended actions.
Raises:
  • ValueError - If the data at the location can't be read

_parseExclusions(parentNode)
Static Method

source code 

Reads exclusions data from immediately beneath the parent.

We read groups of the following items, one list element per item:

  absolute    exclude/abs_path
  relative    exclude/rel_path
  patterns    exclude/pattern

If there are none of some pattern (i.e. no relative path items) then None will be returned for that item in the tuple.

This method can be used to parse exclusions on both the collect configuration level and on the collect directory level within collect configuration.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
Tuple of (absolute, relative, patterns) exclusions.

_parseOverrides(parentNode)
Static Method

source code 

Reads a list of CommandOverride objects from immediately beneath the parent.

We read the following individual fields:

  command                 command
  absolutePath            abs_path
Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of CommandOverride objects or None if none are found.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseHooks(parentNode)
Static Method

source code 

Reads a list of ActionHook objects from immediately beneath the parent.

We read the following individual fields:

  action                  action
  command                 command
Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of ActionHook objects or None if none are found.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseCollectFiles(parentNode)
Static Method

source code 

Reads a list of CollectFile objects from immediately beneath the parent.

We read the following individual fields:

  absolutePath            abs_path
  collectMode             mode I{or} collect_mode
  archiveMode             archive_mode

The collect mode is a special case. Just a mode tag is accepted, but we prefer collect_mode for consistency with the rest of the config file and to avoid confusion with the archive mode. If both are provided, only mode will be used.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of CollectFile objects or None if none are found.
Raises:
  • ValueError - If some filled-in value is invalid.

_parseCollectDirs(parentNode)
Static Method

source code 

Reads a list of CollectDir objects from immediately beneath the parent.

We read the following individual fields:

  absolutePath            abs_path
  collectMode             mode I{or} collect_mode
  archiveMode             archive_mode
  ignoreFile              ignore_file
  linkDepth               link_depth
  dereference             dereference
  recursionLevel          recursion_level

The collect mode is a special case. Just a mode tag is accepted for backwards compatibility, but we prefer collect_mode for consistency with the rest of the config file and to avoid confusion with the archive mode. If both are provided, only mode will be used.

We also read groups of the following items, one list element per item:

  absoluteExcludePaths    exclude/abs_path
  relativeExcludePaths    exclude/rel_path
  excludePatterns         exclude/pattern

The exclusions are parsed by _parseExclusions.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of CollectDir objects or None if none are found.
Raises:
  • ValueError - If some filled-in value is invalid.

_parsePurgeDirs(parentNode)
Static Method

source code 

Reads a list of PurgeDir objects from immediately beneath the parent.

We read the following individual fields:

  absolutePath            <baseExpr>/abs_path
  retainDays              <baseExpr>/retain_days
Parameters:
  • parentNode - Parent node to search beneath.
Returns:
List of PurgeDir objects or None if none are found.
Raises:
  • ValueError - If the data at the location can't be read

_parsePeerList(parentNode)
Static Method

source code 

Reads remote and local peer data from immediately beneath the parent.

We read the following individual fields for both remote and local peers:

  name        name
  collectDir  collect_dir

We also read the following individual fields for remote peers only:

  remoteUser     backup_user
  rcpCommand     rcp_command
  rshCommand     rsh_command
  cbackCommand   cback_command
  managed        managed
  managedActions managed_actions

Additionally, the value in the type field is used to determine whether this entry is a remote peer. If the type is "remote", it's a remote peer, and if the type is "local", it's a remote peer.

If there are none of one type of peer (i.e. no local peers) then None will be returned for that item in the tuple.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
Tuple of (local, remote) peer lists.
Raises:
  • ValueError - If the data at the location can't be read

_parseDependencies(parentNode)
Static Method

source code 

Reads extended action dependency information from a parent node.

We read the following individual fields:

  runBefore   depends/run_before
  runAfter    depends/run_after

Each of these fields is a comma-separated list of action names.

The result is placed into an ActionDependencies object.

If the dependencies parent node does not exist, None will be returned. Otherwise, an ActionDependencies object will always be created, even if it does not contain any actual dependencies in it.

Parameters:
  • parentNode - Parent node to search beneath.
Returns:
ActionDependencies object or None.
Raises:
  • ValueError - If the data at the location can't be read

_parseBlankBehavior(parentNode)
Static Method

source code 

Reads a single BlankBehavior object from immediately beneath the parent.

We read the following individual fields:

  blankMode     blank_behavior/mode
  blankFactor   blank_behavior/factor
Parameters:
  • parentNode - Parent node to search beneath.
Returns:
BlankBehavior object or None if none if the section is not found
Raises:
  • ValueError - If some filled-in value is invalid.

_extractXml(self)

source code 

Internal method to extract configuration into an XML string.

This method assumes that the internal validate method has been called prior to extracting the XML, if the caller cares. No validation will be done internally.

As a general rule, fields that are set to None will be extracted into the document as empty tags. The same goes for container tags that are filled based on lists - if the list is empty or None, the container tag will be empty.

_addReference(xmlDom, parentNode, referenceConfig)
Static Method

source code 

Adds a <reference> configuration section as the next child of a parent.

We add the following fields to the document:

  author         //cb_config/reference/author
  revision       //cb_config/reference/revision
  description    //cb_config/reference/description
  generator      //cb_config/reference/generator

If referenceConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • referenceConfig - Reference configuration section to be added to the document.

_addExtensions(xmlDom, parentNode, extensionsConfig)
Static Method

source code 

Adds an <extensions> configuration section as the next child of a parent.

We add the following fields to the document:

  order_mode     //cb_config/extensions/order_mode

We also add groups of the following items, one list element per item:

  actions        //cb_config/extensions/action

The extended action entries are added by _addExtendedAction.

If extensionsConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • extensionsConfig - Extensions configuration section to be added to the document.

_addOptions(xmlDom, parentNode, optionsConfig)
Static Method

source code 

Adds a <options> configuration section as the next child of a parent.

We add the following fields to the document:

  startingDay    //cb_config/options/starting_day
  workingDir     //cb_config/options/working_dir
  backupUser     //cb_config/options/backup_user
  backupGroup    //cb_config/options/backup_group
  rcpCommand     //cb_config/options/rcp_command
  rshCommand     //cb_config/options/rsh_command
  cbackCommand   //cb_config/options/cback_command
  managedActions //cb_config/options/managed_actions

We also add groups of the following items, one list element per item:

  overrides      //cb_config/options/override
  hooks          //cb_config/options/pre_action_hook
  hooks          //cb_config/options/post_action_hook

The individual override items are added by _addOverride. The individual hook items are added by _addHook.

If optionsConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • optionsConfig - Options configuration section to be added to the document.

_addPeers(xmlDom, parentNode, peersConfig)
Static Method

source code 

Adds a <peers> configuration section as the next child of a parent.

We add groups of the following items, one list element per item:

  localPeers     //cb_config/peers/peer
  remotePeers    //cb_config/peers/peer

The individual local and remote peer entries are added by _addLocalPeer and _addRemotePeer, respectively.

If peersConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • peersConfig - Peers configuration section to be added to the document.

_addCollect(xmlDom, parentNode, collectConfig)
Static Method

source code 

Adds a <collect> configuration section as the next child of a parent.

We add the following fields to the document:

  targetDir            //cb_config/collect/collect_dir
  collectMode          //cb_config/collect/collect_mode
  archiveMode          //cb_config/collect/archive_mode
  ignoreFile           //cb_config/collect/ignore_file

We also add groups of the following items, one list element per item:

  absoluteExcludePaths //cb_config/collect/exclude/abs_path
  excludePatterns      //cb_config/collect/exclude/pattern
  collectFiles         //cb_config/collect/file
  collectDirs          //cb_config/collect/dir

The individual collect files are added by _addCollectFile and individual collect directories are added by _addCollectDir.

If collectConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • collectConfig - Collect configuration section to be added to the document.

_addStage(xmlDom, parentNode, stageConfig)
Static Method

source code 

Adds a <stage> configuration section as the next child of a parent.

We add the following fields to the document:

  targetDir      //cb_config/stage/staging_dir

We also add groups of the following items, one list element per item:

  localPeers     //cb_config/stage/peer
  remotePeers    //cb_config/stage/peer

The individual local and remote peer entries are added by _addLocalPeer and _addRemotePeer, respectively.

If stageConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • stageConfig - Stage configuration section to be added to the document.

_addStore(xmlDom, parentNode, storeConfig)
Static Method

source code 

Adds a <store> configuration section as the next child of a parent.

We add the following fields to the document:

  sourceDir         //cb_config/store/source_dir
  mediaType         //cb_config/store/media_type
  deviceType        //cb_config/store/device_type
  devicePath        //cb_config/store/target_device
  deviceScsiId      //cb_config/store/target_scsi_id
  driveSpeed        //cb_config/store/drive_speed
  checkData         //cb_config/store/check_data
  checkMedia        //cb_config/store/check_media
  warnMidnite       //cb_config/store/warn_midnite
  noEject           //cb_config/store/no_eject
  refreshMediaDelay //cb_config/store/refresh_media_delay
  ejectDelay        //cb_config/store/eject_delay

Blanking behavior configuration is added by the _addBlankBehavior method.

If storeConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • storeConfig - Store configuration section to be added to the document.

_addPurge(xmlDom, parentNode, purgeConfig)
Static Method

source code 

Adds a <purge> configuration section as the next child of a parent.

We add the following fields to the document:

  purgeDirs     //cb_config/purge/dir

The individual directory entries are added by _addPurgeDir.

If purgeConfig is None, then no container will be added.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • purgeConfig - Purge configuration section to be added to the document.

_addExtendedAction(xmlDom, parentNode, action)
Static Method

source code 

Adds an extended action container as the next child of a parent.

We add the following fields to the document:

  name           action/name
  module         action/module
  function       action/function
  index          action/index
  dependencies   action/depends

Dependencies are added by the _addDependencies method.

The <action> node itself is created as the next child of the parent node. This method only adds one action node. The parent must loop for each action in the ExtensionsConfig object.

If action is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • action - Purge directory to be added to the document.

_addOverride(xmlDom, parentNode, override)
Static Method

source code 

Adds a command override container as the next child of a parent.

We add the following fields to the document:

  command                 override/command
  absolutePath            override/abs_path

The <override> node itself is created as the next child of the parent node. This method only adds one override node. The parent must loop for each override in the OptionsConfig object.

If override is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • override - Command override to be added to the document.

_addHook(xmlDom, parentNode, hook)
Static Method

source code 

Adds an action hook container as the next child of a parent.

The behavior varies depending on the value of the before and after flags on the hook. If the before flag is set, it's a pre-action hook, and we'll add the following fields:

  action                  pre_action_hook/action
  command                 pre_action_hook/command

If the after flag is set, it's a post-action hook, and we'll add the following fields:

  action                  post_action_hook/action
  command                 post_action_hook/command

The <pre_action_hook> or <post_action_hook> node itself is created as the next child of the parent node. This method only adds one hook node. The parent must loop for each hook in the OptionsConfig object.

If hook is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • hook - Command hook to be added to the document.

_addCollectFile(xmlDom, parentNode, collectFile)
Static Method

source code 

Adds a collect file container as the next child of a parent.

We add the following fields to the document:

  absolutePath            dir/abs_path
  collectMode             dir/collect_mode
  archiveMode             dir/archive_mode

Note that for consistency with collect directory handling we'll only emit the preferred collect_mode tag.

The <file> node itself is created as the next child of the parent node. This method only adds one collect file node. The parent must loop for each collect file in the CollectConfig object.

If collectFile is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • collectFile - Collect file to be added to the document.

_addCollectDir(xmlDom, parentNode, collectDir)
Static Method

source code 

Adds a collect directory container as the next child of a parent.

We add the following fields to the document:

  absolutePath            dir/abs_path
  collectMode             dir/collect_mode
  archiveMode             dir/archive_mode
  ignoreFile              dir/ignore_file
  linkDepth               dir/link_depth
  dereference             dir/dereference
  recursionLevel          dir/recursion_level

Note that an original XML document might have listed the collect mode using the mode tag, since we accept both collect_mode and mode. However, here we'll only emit the preferred collect_mode tag.

We also add groups of the following items, one list element per item:

  absoluteExcludePaths    dir/exclude/abs_path
  relativeExcludePaths    dir/exclude/rel_path
  excludePatterns         dir/exclude/pattern

The <dir> node itself is created as the next child of the parent node. This method only adds one collect directory node. The parent must loop for each collect directory in the CollectConfig object.

If collectDir is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • collectDir - Collect directory to be added to the document.

_addLocalPeer(xmlDom, parentNode, localPeer)
Static Method

source code 

Adds a local peer container as the next child of a parent.

We add the following fields to the document:

  name                peer/name
  collectDir          peer/collect_dir
  ignoreFailureMode   peer/ignore_failures

Additionally, peer/type is filled in with "local", since this is a local peer.

The <peer> node itself is created as the next child of the parent node. This method only adds one peer node. The parent must loop for each peer in the StageConfig object.

If localPeer is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • localPeer - Purge directory to be added to the document.

_addRemotePeer(xmlDom, parentNode, remotePeer)
Static Method

source code 

Adds a remote peer container as the next child of a parent.

We add the following fields to the document:

  name                peer/name
  collectDir          peer/collect_dir
  remoteUser          peer/backup_user
  rcpCommand          peer/rcp_command
  rcpCommand          peer/rcp_command
  rshCommand          peer/rsh_command
  cbackCommand        peer/cback_command
  ignoreFailureMode   peer/ignore_failures
  managed             peer/managed
  managedActions      peer/managed_actions

Additionally, peer/type is filled in with "remote", since this is a remote peer.

The <peer> node itself is created as the next child of the parent node. This method only adds one peer node. The parent must loop for each peer in the StageConfig object.

If remotePeer is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • remotePeer - Purge directory to be added to the document.

_addPurgeDir(xmlDom, parentNode, purgeDir)
Static Method

source code 

Adds a purge directory container as the next child of a parent.

We add the following fields to the document:

  absolutePath            dir/abs_path
  retainDays              dir/retain_days

The <dir> node itself is created as the next child of the parent node. This method only adds one purge directory node. The parent must loop for each purge directory in the PurgeConfig object.

If purgeDir is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • purgeDir - Purge directory to be added to the document.

_addDependencies(xmlDom, parentNode, dependencies)
Static Method

source code 

Adds a extended action dependencies to parent node.

We add the following fields to the document:

  runBefore      depends/run_before
  runAfter       depends/run_after

If dependencies is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • dependencies - ActionDependencies object to be added to the document

_buildCommaSeparatedString(valueList)
Static Method

source code 

Creates a comma-separated string from a list of values.

As a special case, if valueList is None, then None will be returned.

Parameters:
  • valueList - List of values to be placed into a string
Returns:
Values from valueList as a comma-separated string.

_addBlankBehavior(xmlDom, parentNode, blankBehavior)
Static Method

source code 

Adds a blanking behavior container as the next child of a parent.

We add the following fields to the document:

  blankMode    blank_behavior/mode
  blankFactor  blank_behavior/factor

The <blank_behavior> node itself is created as the next child of the parent node.

If blankBehavior is None, this method call will be a no-op.

Parameters:
  • xmlDom - DOM tree as from createOutputDom.
  • parentNode - Parent that the section should be appended to.
  • blankBehavior - Blanking behavior to be added to the document.

_validateContents(self)

source code 

Validates configuration contents per rules discussed in module documentation.

This is the second pass at validation. It ensures that any filled-in section contains valid data. Any sections which is not set to None is validated per the rules for that section, laid out in the module documentation (above).

Raises:
  • ValueError - If configuration is invalid.

_validateReference(self)

source code 

Validates reference configuration. There are currently no reference-related validations.

Raises:
  • ValueError - If reference configuration is invalid.

_validateExtensions(self)

source code 

Validates extensions configuration.

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, if the order mode is None or "index", an index is required; and if the order mode is "dependency", dependency information is required.

Raises:
  • ValueError - If reference configuration is invalid.

_validateOptions(self)

source code 

Validates options configuration.

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.

Raises:
  • ValueError - If reference configuration is invalid.

_validatePeers(self)

source code 

Validates peers configuration per rules in _validatePeerList.

Raises:
  • ValueError - If peers configuration is invalid.

_validateCollect(self)

source code 

Validates collect configuration.

The target directory must be filled in. The collect mode, archive mode, ignore file, and recursion level 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.

Raises:
  • ValueError - If collect configuration is invalid.

_validateStage(self)

source code 

Validates stage configuration.

The target directory must be filled in, and the peers are also validated.

Peers are only required in this section if the peers configuration section is not filled in. However, if any peers are filled in here, they override the peers configuration and must meet the validation criteria in _validatePeerList.

Raises:
  • ValueError - If stage configuration is invalid.

_validateStore(self)

source code 

Validates store configuration.

The device type, drive speed, and blanking behavior are optional. All other values are required. Missing booleans will be set to defaults.

If blanking behavior is provided, then both a blanking mode and a blanking factor are required.

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.

This is also where we make sure that the media type -- which is already a valid type -- matches up properly with the device type.

Raises:
  • ValueError - If store configuration is invalid.

_validatePurge(self)

source code 

Validates purge configuration.

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.

Raises:
  • ValueError - If purge configuration is invalid.

_validatePeerList(self, localPeers, remotePeers)

source code 

Validates the set of local and remote peers.

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.

Parameters:
  • localPeers - List of local peers
  • remotePeers - List of remote peers
Raises:
  • ValueError - If stage configuration is invalid.

Property Details [hide private]

reference

Reference configuration in terms of a ReferenceConfig object.

Get Method:
_getReference(self) - Property target used to get the reference configuration value.
Set Method:
_setReference(self, value) - Property target used to set the reference configuration value.

extensions

Extensions configuration in terms of a ExtensionsConfig object.

Get Method:
_getExtensions(self) - Property target used to get the extensions configuration value.
Set Method:
_setExtensions(self, value) - Property target used to set the extensions configuration value.

options

Options configuration in terms of a OptionsConfig object.

Get Method:
_getOptions(self) - Property target used to get the options configuration value.
Set Method:
_setOptions(self, value) - Property target used to set the options configuration value.

collect

Collect configuration in terms of a CollectConfig object.

Get Method:
_getCollect(self) - Property target used to get the collect configuration value.
Set Method:
_setCollect(self, value) - Property target used to set the collect configuration value.

stage

Stage configuration in terms of a StageConfig object.

Get Method:
_getStage(self) - Property target used to get the stage configuration value.
Set Method:
_setStage(self, value) - Property target used to set the stage configuration value.

store

Store configuration in terms of a StoreConfig object.

Get Method:
_getStore(self) - Property target used to get the store configuration value.
Set Method:
_setStore(self, value) - Property target used to set the store configuration value.

purge

Purge configuration in terms of a PurgeConfig object.

Get Method:
_getPurge(self) - Property target used to get the purge configuration value.
Set Method:
_setPurge(self, value) - Property target used to set the purge configuration value.

peers

Peers configuration in terms of a PeersConfig object.

Get Method:
_getPeers(self) - Property target used to get the peers configuration value.
Set Method:
_setPeers(self, value) - Property target used to set the peers configuration value.