ElementTree

Lightweight XML support for Larky.

XML is an inherently hierarchical data format, and the most natural way to represent it is with a tree. This module has two classes for this purpose:

  • ElementTree represents the whole XML document as a tree.

  • Element represents a single node in this tree.

Interactions with the whole document (reading and writing to/from files) are usually done on the ElementTree level. Interactions with a single XML element and its sub-elements are done on the Element level. Element is a flexible container object designed to store hierarchical data structures in memory. It can be described as a cross between a list and a dictionary. Each Element has a number of properties associated with it:

  • tag: a string containing the element's name.

  • text: a string containing the element's text content.

  • tail: a string containing additional data, such as whitespace.

  • attributes: a Python dictionary storing the element's attributes.

And a number of child elements stored in a Python sequence. To create an element instance, use the Element constructor, or the SubElement factory function. You can also use the ElementTree class to wrap an element structure and convert it to and from XML.

ElementTree.Comment(text=None)

Comment element factory. This function creates a special element which the standard serializer serializes as an XML comment.

Parameters:

  • text - string containing the comment string.

ElementTree.Element(tag, attrib=None, **extra)

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.

Example form: <tag attrib>text<child/>…</tag>tail.

Parameters:

  • tag - the element name.

  • attrib - optional dictionary containing element attributes.

  • extra - additional element attributes given as keyword arguments.

ElementTree.PI(target, text=None)

Processing Instruction element factory. This function creates a special element which the standard serializer serializes as an XML comment.

Parameters:

  • target - string containing the processing instruction.

  • text - string containing the processing instruction contents, if any.

ElementTree.ParseError(code, position, msg='')

An error when parsing an XML document.

Parameters:

  • code - the specific exception code.

  • position - the line and column of the error.

ElementTree.ProcessingInstruction(target, text=None)

Processing Instruction element factory. This function creates a special element which the standard serializer serializes as an XML comment.

Parameters:

  • target - string containing the processing instruction.

  • text - string containing the processing instruction contents, if any.

ElementTree.QName(text_or_uri, tag=None)

Qualified name wrapper. This class can be used to wrap a QName attribute value in order to get proper namespace handing on output.

Parameters:

  • text_or_uri - string containing the QName value either in the form {uri}local, or if the tag argument is given, the URI part of a QName. :param tag: optional argument which if given, will make the first argument (text_or_uri) be interpreted as a URI, and this argument (tag) be interpreted as a local name.

ElementTree.SubElement(parent, tag, attrib=None, **extra)

Subelement factory which creates an element instance, and appends it to an existing parent. The element tag, attribute names, and attribute values can be either bytes or Unicode strings.

Parameters:

  • parent - parent element.

  • tag - subelements name.

  • attrib - optional directory containing element attributes

  • extra - additional attributes given as keyword arguments.

ElementTree.TreeBuilder(element_factory=None, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False, **options)

Generic element structure builder. This builder converts a sequence of start, data, and end method calls to a well-formed element structure. You can use this class to build an element structure using a custom XML parser, or a parser for some other XML-like format.

Parameters:

  • element_factory - optional element factory which is called to create new Element instances, as necessary.

  • comment_factory - factory to create comments to be used instead of the standard factory.

  • insert_comments - false (the default), comments will not be inserted into the tree.

  • pi_factory - factory to create processing instructions to be used instead of the standard factory.

  • insert_pis - if false (the default), processing instructions will not be inserted into the tree.

ElementTree.XML(text, parser=None)

Parse XML document from string constant. This function can be used to embed “XML Literals” in Python code.

Parameters:

  • text - string containing XML data.

  • parser - optional parser instance, defaulting to the standard XMLParser.

Returns: Element instance.

ElementTree.XMLID(text, parser=None)

Parse XML document from string constant for its IDs.

Parameters:

  • text - string containing XML data.

  • parser - optional parser instance, defaulting to the standard XMLParser.

Returns: (Element, dict) tuple, in which the dict maps element id:s to elements.

ElementTree.XMLParser(html=0, target=None, encoding=None)

Element structure builder for XML source data based on the expat parser.

Parameters:

  • html - predefined HTML entities (not supported currently).

  • target - optional target object which defaults to an instance of the standard TreeBuilder class, encoding is an optional encoding string which if given, overrides the encoding specified in the XML file.

ElementTree.dump(elem)

Write element tree or element structure to sys.stdout. This function should be used for debugging only.

Parameters:

  • elem - either an ElementTree, or a single Element. The exact output format is implementation dependent. In this version, it's written as an ordinary XML file.

ElementTree.fromstring(text, parser=None)

Parse XML document from string constant. This function can be used to embed “XML Literals” in Python code.

Parameters:

  • text - string containing XML data

  • parser - optional parser instance, defaulting to the standard XMLParser.

Returns: Element instance.

ElementTree.fromstringlist(sequence, parser=None)

Parse XML document from sequence of string fragments.

Parameters:

  • sequence - is a list of other sequence.

  • parser - optional parser instance, defaulting to the standard XMLParser.

Returns: Element instance.

ElementTree.iselement(element)

Checks if an object appears to be a valid element object or if element appears to be an Element. :param element: element to check.

ElementTree.iterparse(source, events=None, parser=None)

Incrementally parse XML document into ElementTree. This class also reports what's going on to the user based on the events it is initialized with. The supported events are the strings “start”, “end”, “start-ns” and “end-ns” (the “ns” events are used to get detailed namespace information). If events is omitted, only “end” events are reported.

Parameters:

  • source - filename or file object containing XML data.

  • events - list of events to report back.

  • parser - optional parser instance.

Returns: iterator providing (event, elem) pairs.

ElementTree.parse(source, parser=None, tree_factory=<function ElementTree>)

Parse XML document into element tree.

Example:

f = StringIO('<doc><one>One</one><two>Two</two>hm<three>Three</three></doc>')
parser = SimpleXMLTreeBuilder.TreeBuilder()
doc = ElementTree.parse(f, parser=parser, tree_factory=ElementTree.ElementTree)
root = doc.getroot()
operator.getitem(root, 0).tag
'one'
operator.getitem(root, 1).tag
'two'
operator.getitem(root, 2).tag
'three'
f = StringIO('<doc level="A"><one updated="Y">One</one><two updated="N">Two</two>hm<three>Three</three></doc>')
doc = ElementTree.parse(f, parser=parser, tree_factory=ElementTree.ElementTree)
root = doc.getroot()
root.findall("./one")[0].tag
'one'
root.findall("./one")[0].text
'One'
root.findall(".")[0].attrib['level']
'A'

Parameters:

  • source - filename or file object containing XML data.

  • parser - optional parser instance defaulting to XMLParser.

Returns: ElementTree instance.

ElementTree.register_namespace(prefix, uri)

Register a namespace prefix. The registry is global, and any existing mapping for either the given prefix or the namespace URI will be removed. ValueError is raised if prefix is reserved or is invalid.

Parameters:

  • prefix - namespace prefix.

  • uri - namespace uri. Tags and attributes in this namespace will be serialized with prefix if possible.

ElementTree.tostring(element, encoding='us-ascii', method='xml', xml_declaration=None, default_namespace=None, short_empty_elements=True, pretty_print=False, with_comments=False, exclusive=False)

Generate string representation of XML element. All subelements are included.

Parameters:

  • element - an Element instance, encoding is an optional output encoding defaulting to US-ASCII.

  • method - optional output which can be one of “xml” (default), “html”, “text” or “c14n”.

  • encoding - if “unicode”, a string is returned. Otherwise a bytestring is returned.

Returns: encoded string containing the XML data.

PreviousdictsNextenum

Last updated