Version: 1.2.0

ramrod.utils Module


Returns an iterable collection of etree Element nodes that are direct children of node.

ramrod.utils.copy_xml_element(node, tag=None)

Returns a copy of node. The copied node will be renamed to tag if tag is not None.


Creates a new ID from orig_id by appending ‘-cleaned-‘ and a UUID4 string to the end of the orig_id value.

Returns:An ID string.

Returns a list of etree Element nodes that are descendants of node.

ramrod.utils.get_etree_root(doc, make_copy=False)

Returns an instance of lxml.etree._Element for the given input.

  • doc – The input XML document. Can be an instance of lxml.etree._Element, lxml.etree._ElementTree, a file-like object, or a string filename.
  • make_copy – If True, a copy.deepcopy() of the root node will be returned.

An lxml.etree._Element instance for doc.


Returns the namespace which contains the type definition for the node. The type definition is specified by the xsi:type attribute which is formatted as [alias]:[type name].

This method splits the xsi:type attribute value into an alias and a type name and performs a namespace lookup for the alias.

Parameters:node – An instance of lxml.etree._Element which contains an xsi:type attribute.
Returns:The namespace for the type defintion of this node.
Raises:KeyError – if the node does not contain an xsi:type attribute.

Returns the localname portion the node QName


Returns the namespace portion of the QName for node.


Returns the text for a etree _Element node. If the node contains CDATA information, the text will be wrapped in an etree.CDATA instance.

Returns:If the node contains a <![CDATA[]]> block, a etree.CDATA instance will be returned. If the node contains children, None. The node text value otherwise.

Parses the xsi:schemaLocation attribute on node.

Returns:A list of (ns, schemaLocation) tuples for the node.
Raises:KeyError – If node does not have an xsi:schemaLocation attribute.

Returns a (ns alias, typename) tuple which is generated from the xsi:type attribute on node.

  • KeyError – If node does not contain an xsi:type attribute.
  • ValueError – If the xsi:type attribute does not have a colon in it.

Finds all nodes under root which have an xsi:type attribute.

Returns:A list of etree._Element instances.

Returns an etree.ETCompatXMLParser instance.

ramrod.utils.ignored(*args, **kwds)

Allows you to ignore exceptions cleanly using context managers. This exists in Python 3.

ramrod.utils.is_version_equal(x, y)

Attempts to determine if the x amd y version numbers are semantically equivalent.


The version strings “2.1.0” and “2.1” represent semantically equivalent versions, despite not being equal strings.

  • x – A string version number. Ex: ‘2.1.0’
  • y – A string version number. Ex: ‘2.1’

Returns an iterator which yields direct child elements of node.


Returns an iterator which yields descendant elements of node.


Assigns a new, unique ID to node by appending ‘-cleaned-‘ and a UUID4 string to the end of the id attribute value of the node.


>>> e = etree.Element('test')
>>> e.attrib['id'] = 'example:non-unique-id'
>>> e.attrib['id']
>>> e = new_id(e)
>>> e.attrib['id']
ramrod.utils.remove_xml_attribute(node, attr)

Removes an attribute from node.

  • node (lxml.etree._Element) – An _Element node.
  • attr – A attribute tag to be removed.
ramrod.utils.remove_xml_attributes(node, attrs)

Removes xml attributes attrs from node.


Removes node from the parent of node.


Removes each node found in nodes from the XML document.

ramrod.utils.replace_xml_element(old, new)

Replaces old node with new in the document which old exists.


Returns a copy of string with its whitespace stripped.

ramrod.utils.validate_version(version, allowed)

Raises a InvalidVersionError if version is not found in allowed.

  • version – A version string.
  • allowed – An iterable collection of version strings.
ramrod.utils.validate_versions(from_, to_, allowed)

Raises a InvalidVersionError if from_ or to_ are not found in allowed or from_ is greater than or equal to to_.

  • from – A version string.
  • to – A version string.
  • allowed – An iterable collection of version strings.