Package CedarBackup2 :: Module xmlutil
[hide private]
[frames] | no frames]

Module xmlutil

source code

Provides general XML-related functionality.

What I'm trying to do here is abstract much of the functionality that directly accesses the DOM tree. This is not so much to "protect" the other code from the DOM, but to standardize the way it's used. It will also help extension authors write code that easily looks more like the rest of Cedar Backup.


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

Classes [hide private]
  Serializer
XML serializer class.
Functions [hide private]
 
createInputDom(xmlData, name='cb_config')
Creates a DOM tree based on reading an XML string.
source code
 
createOutputDom(name='cb_config')
Creates a DOM tree used for writing an XML document.
source code
 
serializeDom(xmlDom, indent=3)
Serializes a DOM tree and returns the result in a string.
source code
 
isElement(node)
Returns True or False depending on whether the XML node is an element node.
source code
 
readChildren(parent, name)
Returns a list of nodes with a given name immediately beneath the parent.
source code
 
readFirstChild(parent, name)
Returns the first child with a given name immediately beneath the parent.
source code
 
readStringList(parent, name)
Returns a list of the string contents associated with nodes with a given name immediately beneath the parent.
source code
 
readString(parent, name)
Returns string contents of the first child with a given name immediately beneath the parent.
source code
 
readInteger(parent, name)
Returns integer contents of the first child with a given name immediately beneath the parent.
source code
 
readBoolean(parent, name)
Returns boolean contents of the first child with a given name immediately beneath the parent.
source code
 
addContainerNode(xmlDom, parentNode, nodeName)
Adds a container node as the next child of a parent node.
source code
 
addStringNode(xmlDom, parentNode, nodeName, nodeValue)
Adds a text node as the next child of a parent, to contain a string.
source code
 
addIntegerNode(xmlDom, parentNode, nodeName, nodeValue)
Adds a text node as the next child of a parent, to contain an integer.
source code
 
addBooleanNode(xmlDom, parentNode, nodeName, nodeValue)
Adds a text node as the next child of a parent, to contain a boolean.
source code
 
readLong(parent, name)
Returns long integer contents of the first child with a given name immediately beneath the parent.
source code
 
readFloat(parent, name)
Returns float contents of the first child with a given name immediately beneath the parent.
source code
 
addLongNode(xmlDom, parentNode, nodeName, nodeValue)
Adds a text node as the next child of a parent, to contain a long integer.
source code
 
_encodeText(text, encoding) source code
 
_translateCDATAAttr(characters)
Handles normalization and some intelligence about quoting.
source code
 
_translateCDATA(characters, encoding='UTF-8', prev_chars='', markupSafe=0) source code
Variables [hide private]
  TRUE_BOOLEAN_VALUES = ['Y', 'y']
List of boolean values in XML representing True.
  FALSE_BOOLEAN_VALUES = ['N', 'n']
List of boolean values in XML representing False.
  VALID_BOOLEAN_VALUES = ['Y', 'y', 'N', 'n']
List of valid boolean values in XML.
  logger = logging.getLogger("CedarBackup2.log.xml")
  __package__ = 'CedarBackup2'
Function Details [hide private]

createInputDom(xmlData, name='cb_config')

source code 

Creates a DOM tree based on reading an XML string.

Parameters:
  • name - Assumed base name of the document (root node name).
Returns:
Tuple (xmlDom, parentNode) for the parsed document
Raises:
  • ValueError - If the document can't be parsed.

createOutputDom(name='cb_config')

source code 

Creates a DOM tree used for writing an XML document.

Parameters:
  • name - Base name of the document (root node name).
Returns:
Tuple (xmlDom, parentNode) for the new document

serializeDom(xmlDom, indent=3)

source code 

Serializes a DOM tree and returns the result in a string.

Parameters:
  • xmlDom - XML DOM tree to serialize
  • indent - Number of spaces to indent, as an integer
Returns:
String form of DOM tree, pretty-printed.

readChildren(parent, name)

source code 

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)

source code 

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.

readStringList(parent, name)

source code 

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.

readString(parent, name)

source code 

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.

readInteger(parent, name)

source code 

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.

readBoolean(parent, name)

source code 

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.

addContainerNode(xmlDom, parentNode, nodeName)

source code 

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.

addStringNode(xmlDom, parentNode, nodeName, nodeValue)

source code 

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.

addIntegerNode(xmlDom, parentNode, nodeName, nodeValue)

source code 

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.

addBooleanNode(xmlDom, parentNode, nodeName, nodeValue)

source code 

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.

readLong(parent, name)

source code 

Returns long 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:
Long 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.

readFloat(parent, name)

source code 

Returns float 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:
Float 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 float value.

addLongNode(xmlDom, parentNode, nodeName, nodeValue)

source code 

Adds a text node as the next child of a parent, to contain a long 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.

_encodeText(text, encoding)

source code 

Copyright: This code, prior to customization, was part of the PyXML codebase, and before that was part of the 4DOM suite developed by Fourthought, Inc. It its original form, it was attributed to Martin v. Löwis and was Copyright (c) 2000 Fourthought Inc, USA; All Rights Reserved.

_translateCDATAAttr(characters)

source code 

Handles normalization and some intelligence about quoting.

Copyright: This code, prior to customization, was part of the PyXML codebase, and before that was part of the 4DOM suite developed by Fourthought, Inc. It its original form, it was Copyright (c) 2000 Fourthought Inc, USA; All Rights Reserved.

_translateCDATA(characters, encoding='UTF-8', prev_chars='', markupSafe=0)

source code 

Copyright: This code, prior to customization, was part of the PyXML codebase, and before that was part of the 4DOM suite developed by Fourthought, Inc. It its original form, it was Copyright (c) 2000 Fourthought Inc, USA; All Rights Reserved.