:tocdepth: 3 :py:mod:`gws.lib.xmlx.element` ============================== .. py:module:: gws.lib.xmlx.element .. autoapi-nested-parse:: XmlElement implementation. **Source code:** :source:`gws.lib.xmlx.element` Module Contents --------------- .. py:class:: XmlElementImpl(tag, attrib=None, **extra) Bases: :py:obj:`xml.etree.ElementTree.Element`, :py:obj:`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: text...tail .. py:attribute:: caseInsensitive :value: False Element is case-insensitive. .. py:attribute:: lcName Element name (tag without a namespace) in lower case. .. py:attribute:: name Element name (tag without a namespace). .. py:attribute:: 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. .. py:attribute:: 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. .. py:method:: add(tag, attrib=None, **extra) Creates a new element and adds it as a child. :param tag: XML tag. :param attrib: XML attributes ``{key, value}``. .. py:method:: attr(key, default='') Alias for 'get'. .. py:method:: children() Returns the children of the current element. .. py:method:: 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. .. py:method:: 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. .. py:method:: findfirst(*paths) Given a list of paths, returns the first matching element. .. py:method:: 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. .. py:method:: 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. .. py:method:: hasattr(key) Check if an attribute exists. .. py:method:: 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. .. py:method:: 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. .. py:method:: textdict(*paths, deep=False) Collects texts from child elements. :param paths: List of paths to search for. :param deep: If ``False`` it only looks into direct children, otherwise search the entire subtree. :returns: A dict tag name -> text. .. py:method:: textlist(*paths, deep=False) Collects texts from child elements. :param paths: List of paths to search for. :param 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. .. py:method:: textof(*paths) Given a list of paths, returns the text of the first matching element that has text. .. py:method:: to_dict() Creates a dictionary from an XmlElement object. .. py:method:: to_list(opts=None) Parse an XML element into a list of arguments (reverse of `gws.lib.xmlx.tag`). :param opts: XML options for serialization. .. py:method:: to_string(opts=None) Converts the Element object to a string. :param opts: XML options for serialization. :returns: An XML string.