: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 ``XmlElementImpl`` and adds it as a child. :param tag: XML tag. :param attrib: XML attributes ``{key, value}``. :returns: A XmlElementImpl. .. py:method:: attr(key, default=None) Finds the value for a given key in the ``XmlElementImpl``. :param key: Key of the attribute. :param default: The default return. :returns: The vale of the key, If the key is not found the default is returned. .. py:method:: children() Returns the children of the current ``XmlElementImpl``. .. 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) Returns the first element in the current element. :param paths: Path as ``tag/tag2/tag3`` to the Element to search in. :returns: Returns the first found 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=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. .. 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: Path as ``tag/tag2/tag3`` to the Element to collect texts from. :param 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. .. py:method:: textlist(*paths, deep=False) Collects texts from child-elements. :param paths: Path as ``tag/tag2/tag3`` to the Element to collect texts from. :param 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. .. py:method:: textof(*paths) Returns the text of a given child-element. :param paths: Path as ``tag/tag2/tag3`` to the Element. :returns: The text of the element. .. py:method:: to_dict() Creates a dictionary from an XmlElement object. .. py:method:: to_list(fold_tags=True, remove_namespaces=False) Parse an XML element into a list of arguments. :param fold_tags: If true, folds nested tag names into ``parent/child`` names. :param remove_namespaces: If true, removes all namespaces. .. py:method:: 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. :param extra_namespaces: Extra namespaces to add to the document. :param compact_whitespace: Remove all whitespace outside of tags and elements. :param remove_namespaces: Remove all namespace references. :param with_namespace_declarations: Include the namespace declarations. :param with_schema_locations: Include schema locations. :param with_xml_declaration: Include the xml declaration. :returns: An XML string.