Version: 2.5.0

sdv.utils Module

sdv.utils.children(node)

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

sdv.utils.descendants(node)

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

sdv.utils.get_document_namespaces(doc)

Returns namespace dictionary for all the namespaces declared in the input doc.

Parameters:doc – A read()-able XML document or etree node.

sdv.utils.get_etree_root(doc)

Returns an instance of lxml.etree._Element for the given doc 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. Returns:An lxml.etree._Element instance for doc. Raises:ValidationError – If doc cannot be found or is not a well-formed XML document.

sdv.utils.get_namespace(node)

Returns the namespace for which node falls under.

Parameters:node – An etree node.

sdv.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.

sdv.utils.get_target_ns(doc)

Returns the value of the targetNamespace attribute found on doc.

Returns:

The value of the targetNamespace attribute found at the root of doc.

Raises:

• KeyError – If doc does not contain a targetNamespace attribute.
• ValidationError – If doc cannot be found or is not a well-formed XML document.

sdv.utils.get_type_ns(doc, typename)

Returns the namespace associated with the xsi:type typename found in the XML document doc.

Parameters:

• doc – An XML document. This can be a filename, file-like object, etree._Element, or etree._ElementTree instance.
• typename – The xsi:type value for a given vocabulary instance.

sdv.utils.get_xml_files(files, recursive=False)

Returns a list of files to validate from files. If a member of files is a directory, its children with a .xml extension will be added to the return value.

Parameters:

• files – A list of file paths and/or directory paths.
• recursive – If true, this will descend into any subdirectories of input directories.

Returns:

A list of file paths to validate.

sdv.utils.get_xml_parser(encoding=None)

Returns the global XML parser object. If no global XML parser has been set, one will be created and then returned.

Parameters:encoding – The expected encoding of input documents. By default, an attempt will be made to determine the input document encoding. Returns:The global XML parser object.

sdv.utils.has_content(node)

Returns True if the node has children or text nodes.

Note

This will ignore whitespace and XML comments.

sdv.utils.has_tzinfo(timestamp)

Returns True if the timestamp includes timezone or UTC offset information.

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

Allows you to ignore exceptions cleanly using context managers. This exists in Python 3.4 as contextlib.suppress().

sdv.utils.is_cybox(doc)

Attempts to determine if the input doc is a CybOX XML instance document. If the root-level element falls under a namespace which starts with http://cybox.mitre.org or http://docs.oasis-open.org/cti/ns/cybox, this will return True.

sdv.utils.is_element(node)

Returns True if node is an etree._Element instance.

sdv.utils.is_equal_timestamp(ts1, ts2)

Returns True if the timestamps ts1 and ts2 are equal.

Parameters:

• ts1 – Timestamp string/datetime or etree Element node with ‘timestamp’ attribute.
• ts2 – Timestamp string/datetime or etree Element node with ‘timestamp’ attribute.

sdv.utils.is_iterable(x)

Returns True if x is an iterable collection.

Note

This will return False if x is a string type.

sdv.utils.is_leaf(node)

Returns True if node has no element children.

sdv.utils.is_qname(string)

Returns True if string is a valid QName.

sdv.utils.is_stix(doc)

Attempts to determine if the input doc is a STIX XML instance document. If the root-level element falls under a namespace which starts with http://stix.mitre.org or http://docs.oasis-open.org/cti/ns/stix, this will return True.

sdv.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’

sdv.utils.is_xml(fn)

Returns True if the input filename fn ends with an XML extension.

sdv.utils.iterchildren(node)

Returns an iterator which yields direct child elements of node.

sdv.utils.iterdescendants(node)

Returns an iterator which yields descendant elements of node.

sdv.utils.leaves(tree)

Returns an iterable collection of leaf nodes under tree.

sdv.utils.list_xml_files(directory, recursive=False)

Returns a list of file paths for XML files contained within dir_.

Parameters:

• dir – A path to a directory.
• recursive – If True, this function will descend into all subdirectories.

Returns:

A list of XML file paths directly under dir_.

sdv.utils.localname(node)

Returns the localname for an etree Element node.

sdv.utils.namespace(node)

Returns the namespace for an etree Element node.

sdv.utils.parse_timestamp(value)

Attempts to parse value into an instance of datetime.datetime. If value is None, this function will return None.

Parameters:value – A timestamp. This can be a string or datetime.datetime value.

sdv.utils.remove_all(list_, items)

Removes all items from the list_.

sdv.utils.remove_version_prefix(version)

Strips the ‘stix-‘ prefix from a version number string so it can be compared with older version strings which do not have the prefix.

sdv.utils.set_xml_parser(parser)

Set the XML parser to use internally. This should be an instance of lxml.etree.XMLParser.

Note

Setting parser to an object that is not an instance lxml.etree.XMLParser may result in undesired behaviors.

Parameters:parser – An etree parser.

sdv.utils.strip_whitespace(string)

Returns a copy of string with all whitespace removed.

sdv.utils.union(selectors)

Returns a selector which is a union of the input selectors.

Parameters:selectors – A list of XSLT/XPath selectors. Returns:A new selector string.