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

Type Config

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.

Method Summary
  __init__(self, xmlData, xmlPath, validate)
Initializes a configuration object.
  __repr__(self)
Official string representation for class instance.
  __str__(self)
Informal string representation for class instance.
  __cmp__(self, other)
Definition of equals operator for this class.
  extractXml(self, xmlPath, validate)
Extracts configuration into an XML document.
  validate(self, requireOneAction, requireReference, requireExtensions, requireOptions, requireCollect, requireStage, requireStore, requirePurge)
Validates configuration represented by the object.
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value

Property Summary
  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.

Instance Method Details

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

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 - XML data representing configuration.
           (type=String data.)
xmlPath - Path to an XML file on disk.
           (type=Absolute path to a file on disk.)
validate - Validate the document after parsing it.
           (type=Boolean true/false.)
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:
__builtin__.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)

Official string representation for class instance.
Overrides:
__builtin__.object.__repr__

__str__(self)
(Informal representation operator)

Informal string representation for class instance.
Overrides:
__builtin__.object.__str__

__cmp__(self, other)
(Comparison operator)

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)

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 - Path to an XML file to create on disk.
           (type=Absolute path to a file.)
validate - Validate the document before extracting it.
           (type=Boolean true/false.)
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.

Notes:

  • This function is not particularly fast. This is most noticable when running the regression tests, where the 30 or so extract-related tests take nearly 6 seconds on my Duron 850 (over half the total config-related test time). However, I think the performance is adequate for our purposes.
  • 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)

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.
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.

Property Details

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.

Generated by Epydoc 2.1 on Mon Sep 4 13:49:32 2006 http://epydoc.sf.net