API Reference

declxml is a library for declaratively processing XML documents.

Processors

The declxml library uses processors to define the structure of XML documents. Processors can be divided into two categories: primitive processors and aggregate processors.

Primitive Processors

Primitive processors are used to parse and serialize simple, primitive values. The following module functions are used to construct primitive processors:

declxml.boolean(element_name, attribute=None, required=True, alias=None, default=False, omit_empty=False, hooks=None)[source]

Create a processor for boolean values.

Parameters:
  • element_name – Name of the XML element containing the value. Can also be specified using supported XPath syntax.
  • attribute – If specified, then the value is searched for under the attribute within the element specified by element_name. If not specified, then the value is searched for as the contents of the element specified by element_name.
  • required – Indicates whether the value is required when parsing and serializing.
  • alias – If specified, then this is used as the name of the value when read from XML. If not specified, then the element_name is used as the name of the value.
  • default – Default value to use if the element is not present. This option is only valid if required is specified as False.
  • omit_empty – If True, then Falsey values will be omitted when serializing to XML. Note that Falsey values are never omitted when they are elements of an array. Falsey values can be omitted only when they are standalone elements.
  • hooks – A Hooks object.
Returns:

A declxml processor object.

declxml.floating_point(element_name, attribute=None, required=True, alias=None, default=0.0, omit_empty=False, hooks=None)[source]

Create a processor for floating point values.

See also declxml.boolean()

declxml.integer(element_name, attribute=None, required=True, alias=None, default=0, omit_empty=False, hooks=None)[source]

Create a processor for integer values.

See also declxml.boolean()

declxml.string(element_name, attribute=None, required=True, alias=None, default='', omit_empty=False, strip_whitespace=True, hooks=None)[source]

Create a processor for string values.

Parameters:strip_whitespace – Indicates whether leading and trailing whitespace should be stripped from parsed string values.

See also declxml.boolean()

Aggregate Processors

Aggregate processors are composed of other processors. These processors are used for values such as dictionaries, arrays, and user objects.

declxml.array(item_processor, alias=None, nested=None, omit_empty=False, hooks=None)[source]

Create an array processor that can be used to parse and serialize array data.

XML arrays may be nested within an array element, or they may be embedded within their parent. A nested array would look like:

<root-element>
    <some-element>ABC</some-element>
    <nested-array>
        <array-item>0</array-item>
        <array-item>1</array-item>
    </nested-array>
</root-element>

The corresponding embedded array would look like:

<root-element>
    <some-element>ABC</some-element>
    <array-item>0</array-item>
    <array-item>1</array-item>
</root-element>

An array is considered required when its item processor is configured as being required.

Parameters:
  • item_processor – A declxml processor object for the items of the array.
  • alias – If specified, the name given to the array when read from XML. If not specified, then the name of the item processor is used instead.
  • nested – If the array is a nested array, then this should be the name of the element under which all array items are located. If not specified, then the array is treated as an embedded array. Can also be specified using supported XPath syntax.
  • omit_empty – If True, then nested arrays will be omitted when serializing if they are empty. Only valid when nested is specified. Note that an empty array may only be omitted if it is not itself contained within an array. That is, for an array of arrays, any empty arrays in the outer array will always be serialized to prevent information about the original array from being lost when serializing.
  • hooks – A Hooks object.
Returns:

A declxml processor object.

declxml.dictionary(element_name, children, required=True, alias=None, hooks=None)[source]

Create a processor for dictionary values.

Parameters:
  • element_name – Name of the XML element containing the dictionary value. Can also be specified using supported XPath syntax.
  • children – List of declxml processor objects for processing the children contained within the dictionary.
  • required – Indicates whether the value is required when parsing and serializing.
  • alias – If specified, then this is used as the name of the value when read from XML. If not specified, then the element_name is used as the name of the value.
  • hooks – A Hooks object.
Returns:

A declxml processor object.

declxml.named_tuple(element_name, tuple_type, child_processors, required=True, alias=None, hooks=None)[source]

Create a processor for namedtuple values.

Parameters:tuple_type – The namedtuple type.

See also declxml.dictionary()

declxml.user_object(element_name, cls, child_processors, required=True, alias=None, hooks=None)[source]

Create a processor for user objects.

Parameters:cls – Class object with a no-argument constructor or other callable no-argument object.

See also declxml.dictionary()

Hooks

class declxml.Hooks(after_parse=None, before_serialize=None)[source]

Contains functions to be invoked during parsing and serialization.

A Hooks object contains two functions: after_parse and before_serialize. Both of these functions receive two arguments and should return one value.

As their first argument, both functions will receive a ProcessorStateView object representing the current state of the processor when the function is invoked.

The after_parse function will receive as its second argument the value parsed by the processor from the XML data during parsing. This function must return a value that will be used by the processor as its parse result.

Similarly, the before_serialize function will receive as its second argument the value to be serialized to XML by the processor during serialization. This function must return a value that the processor will serialize to XML.

Both the after_parse and before_serialize functions are optional.

class declxml.ProcessorStateView(processor_state)[source]

Provides an immutable view of the processor state.

locations

Get iterator of the ProcessorLocations visited by the processor.

Represents the current location of the processor in the XML document.

A ProcessorLocation represents a single location of a processor in an XML document. It is a namedtuple with two fields: element_path and array_index. The element_path field contains the path to the element in the XML document relative to the previous location in the list of locations. The array_index field contains the index of the element if it is in an array, otherwise it is None if the element is not in an array.

Returns:Iterator of ProcessorLocation objects.
raise_error(exception_type, message='')[source]

Raise an error with the processor state included in the error message.

Parameters:
  • exception_type – Type of exception to raise
  • message – Error message

Parsing

declxml.parse_from_file(root_processor, xml_file_path, encoding='utf-8')[source]

Parse the XML file using the processor starting from the root of the document.

Parameters:
  • root_processor – Root processor of the XML document.
  • xml_file_path – Path to XML file to parse.
  • encoding – Encoding of the file.
Returns:

Parsed value.

declxml.parse_from_string(root_processor, xml_string)[source]

Parse the XML string using the processor starting from the root of the document.

Parameters:xml_string – XML string to parse.

See also declxml.parse_from_file()

Serialization

declxml.serialize_to_file(root_processor, value, xml_file_path, encoding='utf-8', indent=None)[source]

Serialize the value to an XML file using the root processor.

Parameters:
  • root_processor – Root processor of the XML document.
  • value – Value to serialize.
  • xml_file_path – Path to the XML file to which the serialized value will be written.
  • encoding – Encoding of the file.
  • indent – If specified, then the XML will be formatted with the specified indentation.
declxml.serialize_to_string(root_processor, value, indent=None)[source]

Serialize the value to an XML string using the root processor.

Returns:The serialized XML string.

See also declxml.serialize_to_file()

Exceptions

exception declxml.XmlError[source]

Base error class representing errors processing XML data.

exception declxml.InvalidPrimitiveValue[source]

Represents errors due to invalid primitive values.

exception declxml.InvalidRootProcessor[source]

Represents errors due to invalid root processors.

exception declxml.MissingValue[source]

Represents errors due to missing required values.