gws.lib.xmlx.element

XmlElement implementation.

Source code: gws.lib.xmlx.element

Module Contents

class gws.lib.xmlx.element.XmlElementImpl(tag, attrib=None, **extra)

Bases: xml.etree.ElementTree.Element, gws.XmlElement

An XML element.

This class is the reference implementation of the Element interface.

An element’s length is its number of subelements. That means if you want to check if an element is truly empty, you should check BOTH its length AND its text attribute.

The element tag, attribute names, and attribute values can be either bytes or strings.

tag is the element name. attrib is an optional dictionary containing element attributes. extra are additional element attributes given as keyword arguments.

Example form:

<tag attrib>text<child/>…</tag>tail

add(tag, attrib=None, **extra)

Creates a new XmlElementImpl and adds it as a child.

Parameters:

  • tag – XML tag.

  • attrib – XML attributes {key, value}.

Returns:

A XmlElementImpl.

attr(key, default=None)

Finds the value for a given key in the XmlElementImpl.

Parameters:

  • key – Key of the attribute.

  • default – The default return.

Returns:

The vale of the key, If the key is not found the default is returned.

children()

Returns the children of the current XmlElementImpl.

find(path, namespaces=None)

Find first matching element by tag name or path.

path is a string having either an element tag or an XPath, namespaces is an optional mapping from namespace prefix to full name.

Return the first matching element, or None if no element was found.

findall(path, namespaces=None)

Find all matching subelements by tag name or path.

path is a string having either an element tag or an XPath, namespaces is an optional mapping from namespace prefix to full name.

Returns list containing all matching elements in document order.

findfirst(*paths)

Returns the first element in the current element.

Parameters:

paths – Path as tag/tag2/tag3 to the Element to search in.

Returns:

Returns the first found element.

findtext(path, default=None, namespaces=None)

Find text for first matching element by tag name or path.

path is a string having either an element tag or an XPath, default is the value to return if the element was not found, namespaces is an optional mapping from namespace prefix to full name.

Return text content of first matching element, or default value if none was found. Note that if an element is found having no text content, the empty string is returned.

get(key, default=None)

Get element attribute.

Equivalent to attrib.get, but some implementations may handle this a bit more efficiently. key is what attribute to look for, and default is what to return if the attribute was not found.

Returns a string containing the attribute value, or the default if attribute was not found.

iter(tag=None)

Create tree iterator.

The iterator loops over the element and all subelements in document order, returning all elements with a matching tag.

If the tree structure is modified during iteration, new or removed elements may or may not be included. To get a stable set, use the list() function on the iterator, and loop over the resulting list.

tag is what tags to look for (default is to return all elements)

Return an iterator containing all the matching elements.

iterfind(path, namespaces=None)

Find all matching subelements by tag name or path.

path is a string having either an element tag or an XPath, namespaces is an optional mapping from namespace prefix to full name.

Return an iterable yielding all matching elements in document order.

textdict(*paths, deep=False)

Collects texts from child-elements.

Parameters:

  • paths – Path as tag/tag2/tag3 to the Element to collect texts from.

  • deep – If False it only looks into direct children, otherwise it searches for texts in the complete children-tree.

Returns:

A dict containing all the text from the child-elements.

textlist(*paths, deep=False)

Collects texts from child-elements.

Parameters:

  • paths – Path as tag/tag2/tag3 to the Element to collect texts from.

  • deep – If False it only looks into direct children, otherwise it searches for texts in the complete children-tree.

Returns:

A list containing all the text from the child-elements.

textof(*paths)

Returns the text of a given child-element.

Parameters:

paths – Path as tag/tag2/tag3 to the Element.

Returns:

The text of the element.

to_dict()

Creates a dictionary from an XmlElement object.

to_list(fold_tags=True, remove_namespaces=False)

Parse an XML element into a list of arguments.

Parameters:

  • fold_tags – If true, folds nested tag names into parent/child names.

  • remove_namespaces – If true, removes all namespaces.

to_string(extra_namespaces=None, compact_whitespace=False, remove_namespaces=False, with_namespace_declarations=False, with_schema_locations=False, with_xml_declaration=False)

Converts the Element object to a string.

Parameters:

  • extra_namespaces – Extra namespaces to add to the document.

  • compact_whitespace – Remove all whitespace outside of tags and elements.

  • remove_namespaces – Remove all namespace references.

  • with_namespace_declarations – Include the namespace declarations.

  • with_schema_locations – Include schema locations.

  • with_xml_declaration – Include the xml declaration.

Returns:

An XML string.