gws.lib.xmlx.element

XmlElement implementation.

Source code: gws.lib.xmlx.element

Module Contents

class gws.lib.xmlx.element.XmlElement(tag: str, attrib: dict | None = None, **extra)

Bases: gws.XmlElement

XML element.

attrib

Dictionary of element attributes.

name

Element name (tag without a namespace).

namespaces = []

Namespaces declared on this element (prefix == '' for the default namespace).

tag

Tag name, local or Clark.

tail = ''

Text after this element’s end tag.

text = ''

Text before first subelement.

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

Create a new element and add it as a child.

Names are taken as they are (local or Clark); ID:name resolution is done by tag() only.

Parameters:

  • tag – Tag name, local or Clark.

  • attrib – Attributes.

  • **extra – Additional attributes.

Returns:

The new element.

append(subelement)

Add a child at the end of the list of children.

Parameters:

subelement – The element to add.

children()

Get the children of this element.

Returns:

The list of children. This is the internal list, not a copy.

clear()

Remove the attributes, namespace declarations, children, text and tail of this element.

declare(*namespaces)

Add namespace declarations to this element.

The declarations are written as xmlns attributes on output. Namespaces already declared with the same prefix and URI are skipped.

Parameters:

*namespaces – Namespaces to declare.

extend(elements)

Add children at the end of the list of children.

Parameters:

subelements – The elements to add.

find(path)

Find the first matching subelement.

Parameters:

path – Tag name or path in ElementTree syntax, with local or Clark names.

Returns:

The element, or None if nothing matches.

findall(path)

Find all matching subelements.

Parameters:

path – Tag name or path in ElementTree syntax, with local or Clark names.

Returns:

A list of elements in document order.

findfirst(*paths)

Find the first element that matches one of the given paths.

Parameters:

*paths – Tag names or paths in ElementTree syntax, tried in order.

Returns:

The first match, or None. Without paths, the first child, or None if there are no children.

findtext(path, default='')

Find the text of the first matching subelement.

Parameters:

  • path – Tag name or path in ElementTree syntax, with local or Clark names.

  • default – Value to return if nothing matches.

Returns:

The text of the element, or default.

get(key, default='')

Get an attribute value.

Parameters:

  • key – Attribute name, local or Clark.

  • default – Value to return if the attribute does not exist.

Returns:

The attribute value, or default.

hasattr(key)

Check if an attribute exists.

Parameters:

key – Attribute name, local or Clark.

Returns:

True if the attribute exists.

insert(index, subelement)

Insert a child at the given position.

Parameters:

  • index – Position in the list of children.

  • subelement – The element to insert.

isa(*names)

Check if the local name of this element matches one of the given names, case-insensitively.

Parameters:

*names – Local names.

Returns:

True if the name matches.

items()

Get the attributes.

Returns:

The attributes as (name, value) pairs.

iter(tag=None)

Iterate over this element and all its descendants, depth-first.

Parameters:

tag – Only return elements with this tag; None or * returns all elements.

Returns:

An iterator of elements, starting with this element if it matches.

iterfind(path)

Iterate over all matching subelements.

Parameters:

path – Tag name or path in ElementTree syntax, with local or Clark names.

Returns:

An iterator of elements in document order.

itertext()

Iterate over the text content of this element and its descendants.

Returns:

An iterator of the non-empty texts and tails in document order, without the tail of this element.

keys()

Get the attribute names.

Returns:

The attribute names.

makeelement(tag, attrib)

Create a new element of the same class, as in ElementTree.

The new element is not added to this element.

Parameters:

  • tag – Tag name, local or Clark.

  • attrib – Attributes.

Returns:

A new element.

remove(subelement)

Remove a child.

Parameters:

other – The child to remove.

Raises:

ValueError – If the element is not a child of this element.

require(path)

Find the first matching subelement, which must exist.

Parameters:

path – Tag name or path in ElementTree syntax, with local or Clark names.

Returns:

The element.

Raises:

gws.lib.xmlx.Error – If nothing matches.

set(key, value)

Set an attribute.

Parameters:

  • key – Attribute name, local or Clark.

  • value – Attribute value.

textdict(*paths, deep=False)

Collect texts from subelements, keyed by tag.

Texts are stripped, empty texts are skipped. If several elements have the same tag, the last text wins.

Parameters:

  • *paths – Tag names or paths in ElementTree syntax. Without paths, the direct children are used.

  • deep – If True, also collect texts from all descendants of the found elements.

Returns:

A dict of tags (local or Clark) and texts.

textlist(*paths, deep=False)

Collect texts from subelements.

Texts are stripped, empty texts are skipped.

Parameters:

  • *paths – Tag names or paths in ElementTree syntax. Without paths, the direct children are used.

  • deep – If True, also collect texts from all descendants of the found elements.

Returns:

A list of texts in document order.

textof(*paths)

Get the text of the first matching element that has text.

Parameters:

*paths – Tag names or paths in ElementTree syntax, tried in order.

Returns:

The text, or an empty string if no matching element has text.

to_dict()

Convert the element tree to a dict.

Returns:

A dict with the keys tag, attrib, text, tail and children, where children is a list of such dicts.

to_string(opts=None)

Serialize this element and its subtree.

Parameters:

opts – Serialization options.

Returns:

An XML string.

Raises:

  • gws.lib.xmlx.WriteError – If the tree contains an invalid or prefixed name.

  • gws.lib.xmlx.NamespaceError – If a namespace is unknown, or one prefix is used for different URIs.