xcheck — XML validation tools

The xcheck module contains classes for validating XML elements. It uses the ElementTree interface.

The Master Class

xcheck defines the structure of an XML-Data node, and validates XML-Data nodes.

class xcheck.XCheck(name[, **kwargs])

This is the default XCheck object that can handle attributes and children. All other checkers are subclasses of XCheck.

Parameters:

• name (string) – This is the name of the XML element tag.
• min_occurs (int) – Minimum number of times this element can occur. To make an element optional set this to 0. If the checker represents an XML attribute, use required instead. (default = 1)
• max_occurs (int) – Maximum number of times this element can occur. (default = 1)
• error (Exception) – The default error for this checker, assuming some other, more logical, error is thrown. (defaut = XCheckError)
• children (list) – A list of check objects. This list can be populated with the :meth:’add_child` method. (default = [] )
• check_children (bool) – Default behavior for checking children of an XML node.
• ordered (bool) – If true, the children listed in the checker should match the order of the XML node being checked. If false, then the order will not matter.
• attributes (dict) – A dictionary of attributes for the checker. This dictionary can be populated with the add_attribute() method.
• required (bool) – Only applies to checkers for XML attributes. (default=True)
• unique (bool) – Only applies to attributes.
• helpstr (str) – A short descriptor of the checker. This is useful for introspection or GUI applications.

Note

There is an interface for XCheck written in wxPython. It will be released in 2013. This will use the required and helpstr attributes

Deprecated since version The: check_children paramater will most likely be removed in future versions.

XCheck objects have the following properties:

name(read-only)

Returns the name of the checker.

has_children

Returns true if there are children present in the validator

has_attributes

Returs true if the xcheck object expects attributes

Creation Methods

XCheck objects have the following methods useful in creation:

xcheck.add_child(children)

add a list of child objects to the expected children raises an error if any child object is not an instance of an XCheck class

If passing a list, unpack it:

>>>x = XCheck('test')
>>>kids = [XCheck('a'), XCheck('b'), XCheck('c')]
>>>x.addchildren(*kids)

xcheck.add_children(children)

This is an alias for addchild. The same rules apply

xcheck.add_attribute(attributes)

Adds expected attributes to the xcheck object.

If passing a list, unpack it.

xcheck.is_att(tag)

returns True if the tag represents an attribute in the checker object

Usage Methods

The following methods are useful when using the xcheck-derived objects.

xcheck.to_dict(node)

Creates a dictionar representing the node

xcheck.has_attribute(tag)

Returns True if one of the checker’s attributes matches ‘tag’.

xcheck.has_child(tag)

Returns True if one of the checker’s children attributes matches ‘tag’.

xcheck.get(tag)

Returns the attribute or child checker object

xcheck.dict_key(tag)

Returns an XMLPath dotted with the attribute (if needed).

xcheck.path_to(tag)

Returns an (XMLPath, attribute) tuple to the given tag.

xcheck.xpath_to(tag)

Returns a formatted xpath string.

Node Manipulation Methods

The following methods allow an XCheck object to manipulate nodes.

xcheck.insert_node(parent, child)

Takes a node and inserts a child node, based on the organiziational rules of the checker.

Parameters:child (parent,) – ElementTree.Elements to manipulate

Warning

Only works on first-generation children of the checker!

xcheck.sort_children(parent, child_name, sortkey[, reverse=False])

Sorts children of a node according to sortkey.

Parameters:

• parent – ElementTree.Element
• child_name – string
• sortkey – passed to a call to sorted()
• reverse – passet to a call to sorted()

xcheck.to_definition_node()

Creates an ElementTree.Element that represents the checker tree, not data that can be checked by the checker.

see load_checker() for more information on the definition node.

Calling a Checker

Calling an xcheck object validates whatever is passed to it:

• a simple data type (integer, float)
• a data-equivalent string ()
• an ElementTree.Element object
• an XML-formatted string

xcheck.__call__(item[, check_children, normalize, verbose, as_string])

Validates the data

Parameters:

• check_children (bool) – overrides the instance attribuet for the current call.
• normalize (bool) – returns a normalized value intstead of True or False
• verbose (boolean) – prints a report as the checker processes
• as_string (boolean) – return a string representation of the checked value instead of the normalized value.

Note

The normalize and as_string parameters do nothing with XCheck objects. They are useful for the subclasses.

Note

The verbose parameter will be relpaced in future, relying on the logging module.

__call__ helper methods

XCheck classes are callable, and rely on two helper methods. For more information and examples, see Rolling your own.

xcheck.check_content(item)

Checks the item against the checker’s rules (either an attribute value or node text) and returns a boolean value.

This method can also raise an error. Errors should be consistent with Python. See Errors for more information.

xcheck.nomalize_content(item)

Uses the checker’s normalization rules without checking the validity of the item being normalized.