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

caseInsensitive = False

Element is case-insensitive.

lcName

Element name (tag without a namespace) in lower case.

name

Element name (tag without a namespace).

tail

Text after this element’s end tag, but before the next sibling element’s start tag. This is either a string or the value None. Note that if there was no text, this attribute may be either None or an empty string, depending on the parser.

text

Text before first subelement. This is either a string or the value None. Note that if there is no text, this attribute may be either None or the empty string, depending on the parser.

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

Creates a new element and adds it as a child.

Parameters:

• tag – XML tag.

• attrib – XML attributes {key, value}.

attr(key, default='')

Alias for ‘get’.

children()

Returns the children of the current element.

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)

Given a list of paths, returns the first matching 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='')

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.

hasattr(key)

Check if an attribute exists.

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 – List of paths to search for.

• deep – If False it only looks into direct children, otherwise search the entire subtree.

Returns:

A dict tag name -> text.

textlist(*paths, deep=False)

Collects texts from child elements.

Parameters:

• paths – List of paths to search for.

• deep – If False it only looks into direct children, otherwise search the entire subtree.

Returns:

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

textof(*paths)

Given a list of paths, returns the text of the first matching element that has text.

to_dict()

Creates a dictionary from an XmlElement object.

to_list(opts=None)

Parse an XML element into a list of arguments (reverse of gws.lib.xmlx.tag).

Parameters:

opts – XML options for serialization.

to_string(opts=None)

Converts the Element object to a string.

Parameters:

opts – XML options for serialization.

Returns:

An XML string.