CedarBackup2.config.Config

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.