ramrod.utils Module¶

ramrod.utils.children(node)¶

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.

ramrod.utils.create_new_id(orig_id)¶

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.

ramrod.utils.descendants(node)¶

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.

Parameters:	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.
Returns:	An lxml.etree._Element instance for doc.

ramrod.utils.get_ext_namespace(node)¶

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.

ramrod.utils.get_localname(node)¶

Returns the localname portion the node QName

ramrod.utils.get_namespace(node)¶

Returns the namespace portion of the QName for node.

ramrod.utils.get_node_text(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.

ramrod.utils.get_schemaloc_pairs(node)¶

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.

ramrod.utils.get_type_info(node)¶

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

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

ramrod.utils.get_typed_nodes(root)¶

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

Returns:	A list of etree._Element instances.

ramrod.utils.get_xml_parser()¶

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.

Examples

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

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

ramrod.utils.iterchildren(node)¶

Returns an iterator which yields direct child elements of node.

ramrod.utils.iterdescendants(node)¶

Returns an iterator which yields descendant elements of node.

ramrod.utils.new_id(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.

Example

>>> e = etree.Element('test')
>>> e.attrib['id'] = 'example:non-unique-id'
>>> e.attrib['id']
'example:non-unique-id'
>>> e = new_id(e)
>>> e.attrib['id']
'example:non-unique-id-cleaned-92eaa185-48e2-433e-82ba-a58f692bac32'

ramrod.utils.remove_xml_attribute(node, attr)¶

Removes an attribute from node.

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

ramrod.utils.remove_xml_element(node)¶

Removes node from the parent of node.

ramrod.utils.remove_xml_elements(nodes)¶

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.

ramrod.utils.strip_whitespace(string)¶

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.

Parameters:	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_.

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