Package CedarBackup2 :: Module config

[show private | hide private]

Module CedarBackup2.config

Provides configuration-related objects.

Summary

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

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

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

This module also contains a set of very general XML-parsing and writing functions that third-party extensions can use to simplify the job of parsing and writing their own configuration.

External Python Libraries

This class is one of the few pieces of code in the CedarBackup2 package that requires functionality outside of the Python 2.3 standard library. It depends on the XPath functionality provided by the PyXML product in the xml.xpath package.

The PyXML XPath library is not very fast. This is particularly noticable when reading lists of things with the XPath [n] syntax. Because of this, the code below jumps through some performance-improvement hoops that would normally not be required when using a faster library.

Backwards Compatibility

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

XML Configuration Structure

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

An XML configuration file is composed of seven sections:

reference: specifies reference information about the file (author, revision, etc)
extensions: specifies mappings to Cedar Backup extensions (external code)
options: specifies global configuration options
collect: specifies configuration related to the collect action
stage: specifies configuration related to the stage action
store: specifies configuration related to the store action
purge: specifies configuration related to the purge action

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

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

Unicode vs. String Data

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

Validation

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

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

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

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

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

Reference Validations

No validations.

Extensions Validations

The list of actions may be either None or an empty list [] if desired. Each extended action must include a name, a module and a function. The index value is optional.

Options Validations

All fields must be filled in. The rcp command is used as a default value for all remote peers in the staging section. Remote peers can also rely on the backup user as the default remote user name if they choose.

Collect Validations

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

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

Stage Validations

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

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.

Store Validations

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

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

Purge Validations

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

Author: Kenneth J. Pronovici <pronovic@ieee.org>

Classes
`ExtendedAction`	Class representing an extended action.
`CollectDir`	Class representing a Cedar Backup collect directory.
`PurgeDir`	Class representing a Cedar Backup purge directory.
`LocalPeer`	Class representing a Cedar Backup peer.
`RemotePeer`	Class representing a Cedar Backup peer.
`ReferenceConfig`	Class representing a Cedar Backup reference configuration.
`ExtensionsConfig`	Class representing Cedar Backup extensions configuration.
`OptionsConfig`	Class representing a Cedar Backup global options configuration.
`CollectConfig`	Class representing a Cedar Backup collect configuration.
`StageConfig`	Class representing a Cedar Backup stage configuration.
`StoreConfig`	Class representing a Cedar Backup store configuration.
`PurgeConfig`	Class representing a Cedar Backup purge configuration.
`Config`	Class representing a Cedar Backup XML configuration document.

Function Summary
	`addBooleanNode(xmlDom, parentNode, nodeName, nodeValue)` Adds a text node as the next child of a parent, to contain a boolean.
	`addContainerNode(xmlDom, parentNode, nodeName)` Adds a container node as the next child of a parent node.
	`addIntegerNode(xmlDom, parentNode, nodeName, nodeValue)` Adds a text node as the next child of a parent, to contain an integer.
	`addStringNode(xmlDom, parentNode, nodeName, nodeValue)` Adds a text node as the next child of a parent, to contain a string.
	`readBoolean(parent, name)` Returns boolean contents of the first child with a given name immediately beneath the parent.
	`readChildren(parent, name)` Returns a list of nodes with a given name immediately beneath the parent.
	`readFirstChild(parent, name)` Returns the first child with a given name immediately beneath the parent.
	`readInteger(parent, name)` Returns integer contents of the first child with a given name immediately beneath the parent.
	`readString(parent, name)` Returns string contents of the first child with a given name immediately beneath the parent.
	`readStringList(parent, name)` Returns a list of the string contents associated with nodes with a given name immediately beneath the parent.

Variable Summary
`list`	`TRUE_BOOLEAN_VALUES`: List of boolean values in XML representing `True`.
`list`	`FALSE_BOOLEAN_VALUES`: List of boolean values in XML representing `False`.
`list`	`VALID_BOOLEAN_VALUES`: List of valid boolean values in XML.
`str`	`DEFAULT_DEVICE_TYPE`: The default device type.
`str`	`DEFAULT_MEDIA_TYPE`: The default media type.
`list`	`VALID_DEVICE_TYPES`: List of valid device types.
`list`	`VALID_MEDIA_TYPES`: List of valid media types.
`list`	`VALID_COLLECT_MODES`: List of valid collect modes.
`list`	`VALID_ARCHIVE_MODES`: List of valid archive modes.
`list`	`VALID_COMPRESS_MODES`: List of valid compress modes.

Function Details

addBooleanNode(xmlDom, parentNode, nodeName, nodeValue)

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

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

Boolean True, or anything else interpreted as True by Python, will be converted to a string "Y". Anything else will be converted to a string "N". The result is added to the document via addStringNode.

Parameters:: xmlDom - DOM tree as from impl.createDocument().; parentNode - Parent node to create child for.; nodeName - Name of the new container node.; nodeValue - The value to put into the node.

Returns:: Reference to the newly-created node.

addContainerNode(xmlDom, parentNode, nodeName)

Adds a container node as the next child of a parent node.

Parameters:: xmlDom - DOM tree as from impl.createDocument().; parentNode - Parent node to create child for.; nodeName - Name of the new container node.

Returns:: Reference to the newly-created node.

addIntegerNode(xmlDom, parentNode, nodeName, nodeValue)

Adds a text node as the next child of a parent, to contain an integer.

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

The integer will be converted to a string using "%d". The result will be added to the document via addStringNode.

Parameters:: xmlDom - DOM tree as from impl.createDocument().; parentNode - Parent node to create child for.; nodeName - Name of the new container node.; nodeValue - The value to put into the node.

Returns:: Reference to the newly-created node.

addStringNode(xmlDom, parentNode, nodeName, nodeValue)

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

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

Parameters:: xmlDom - DOM tree as from impl.createDocument().; parentNode - Parent node to create child for.; nodeName - Name of the new container node.; nodeValue - The value to put into the node.

Returns:: Reference to the newly-created node.

readBoolean(parent, name)

Returns boolean contents of the first child with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node.

The string value of the node must be one of the values in VALID_BOOLEAN_VALUES.

Parameters:: parent - Parent node to search beneath.; name - Name of node to search for.

Returns:: Boolean contents of node or None if no matching nodes are found.

Raises:: ValueError - If the string at the location can't be converted to a boolean.

readChildren(parent, name)

Returns a list of nodes with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node.

Underneath, we use the Python getElementsByTagName method, which is pretty cool, but which (surprisingly?) returns a list of all children with a given name below the parent, at any level. We just prune that list to include only children whose parentNode matches the passed-in parent.

Parameters:: parent - Parent node to search beneath.; name - Name of nodes to search for.

Returns:: List of child nodes with correct parent, or an empty list if no matching nodes are found.

readFirstChild(parent, name)

Returns the first child with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node.

Parameters:: parent - Parent node to search beneath.; name - Name of node to search for.

Returns:: First properly-named child of parent, or None if no matching nodes are found.

readInteger(parent, name)

Returns integer contents of the first child with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node.

Parameters:: parent - Parent node to search beneath.; name - Name of node to search for.

Returns:: Integer contents of node or None if no matching nodes are found.

Raises:: ValueError - If the string at the location can't be converted to an integer.

readString(parent, name)

Returns string contents of the first child with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node. We assume that string contents of a given node belong to the first TEXT_NODE child of that node.

Parameters:: parent - Parent node to search beneath.; name - Name of node to search for.

Returns:: String contents of node or None if no matching nodes are found.

readStringList(parent, name)

Returns a list of the string contents associated with nodes with a given name immediately beneath the parent.

By "immediately beneath" the parent, we mean from among nodes that are direct children of the passed-in parent node.

First, we find all of the nodes using readChildren, and then we retrieve the "string contents" of each of those nodes. The returned list has one entry per matching node. We assume that string contents of a given node belong to the first TEXT_NODE child of that node. Nodes which have no TEXT_NODE children are not represented in the returned list.

Parameters:: parent - Parent node to search beneath.; name - Name of node to search for.

Returns:: List of strings as described above, or None if no matching nodes are found.

Variable Details

TRUE_BOOLEAN_VALUES

List of boolean values in XML representing True.

Type:: list
Value:: ['Y', 'y']

FALSE_BOOLEAN_VALUES

List of boolean values in XML representing False.

Type:: list
Value:: ['N', 'n']

VALID_BOOLEAN_VALUES

List of valid boolean values in XML.

Type:: list
Value:: ['Y', 'y', 'N', 'n']

DEFAULT_DEVICE_TYPE

The default device type.

Type:: str
Value:: 'cdwriter'

DEFAULT_MEDIA_TYPE

The default media type.

Type:: str
Value:: 'cdrw-74'

VALID_DEVICE_TYPES

List of valid device types.

Type:: list
Value:: ['cdwriter']

VALID_MEDIA_TYPES

List of valid media types.

Type:: list
Value:: ['cdr-74', 'cdrw-74', 'cdr-80', 'cdrw-80']

VALID_COLLECT_MODES

List of valid collect modes.

Type:: list
Value:: ['daily', 'weekly', 'incr']

VALID_ARCHIVE_MODES

List of valid archive modes.

Type:: list
Value:: ['tar', 'targz', 'tarbz2']

VALID_COMPRESS_MODES

List of valid compress modes.

Type:: list
Value:: ['none', 'gzip', 'bzip2']

Generated by Epydoc 2.1 on Fri Apr 22 15:56:16 2005

http://epydoc.sf.net