xdocument 1.3.4

A high-level abstraction layer for creating, reading, and editing XML documents.

This high-level abstraction layer is implemented by using wrapper classes for the standard xml.dom.minidom library and the defusedxml package. There are two wrapper classes :

• XDocument - A defined class for creating, loading, and saving an XML document.
• XElement - A defined class which represents an XML document element.

The XDocument and XElement classes provide a concise, tree structure hierarchy for the XML document. Every XML document has a single root element. The root element can have multiple child elements. Each child element can have its own children, and so on and so forth. With the exception of comments, the XML document is composed entirely of elements. The following is a depiction of the XML document structure:

  <root>
    <child>
      <grand_child>
        <great_grand_child/>
      </grand_child>
    </child>
  </root>

The XDocument class provides all the functionality needed for creating a new XML document, loading the XML document from a file, and saving the XML document to a file. When loading from an existing file, this class uses the defusedxml.minidom.parse() function to generate a 'safe' XML document from the file. When saving the XML document to a file, the information is written in a human-readable format which depicts the tree structure hierarchy of the XML document.

Every element of the XML document is an instance of the XElement class. In addition to child elements, every element can have multiple attributes as well as a text value. This class provides a wide range of methods for adding, modifying, and removing elements in the XML document.

Documentation

Full documentation for the XDocument and XElement classes can be found at the GitHub HomePage

Quick Examples

Example #1

A bare minimum implementation the xdocument package would be:

from xdocument import XDocument

XDocument('Blank.xml')

Running this script produces a file named "Blank.xml", and the text content of this file is:

<?xml version="1.0" encoding="utf-8"?>
<XDocument/>

Initially, the "Blank.xml" file does not exist, so the XDocument constructor creates a new blank XML document (with only the root element) and saves it to a file named "Blank.xml". The default root name is "XDocument".

When the script is run again, the XDocument constructor will load the existing "Blank.xml" file as the XML document. It does not save the XML document back to the "Blank.xml" file.

Example #2

This example demonstrates how to populate an XML document with child elements.

from xdocument import XDocument

document = XDocument('Simple.xml', 'Root', 'A Simple XML Document')
if document.root.first_child is None:
    child = document.root.add('Child', 'Attrib', 'Value')
    child.add('GrandChild').value = 'Text'
    document.save()

As before, the XDocument constructor will create a new XML document and save it to a file named "Simple.xml". The two additional parameter values provide an optional name for the root element and the text field for an optional XML document comment.

The if statement checks for a newly created XML document. The root property of the XDocument class is the root element of the XML document. When the XML document is newly created, the root element has no children, and its first_child property will evaluate to None.

Moving inside the if statement code block, the first statement calls the root element's add() method. This method creates a new element named "Child", assigns it an attribute (optional), and makes it a child of the root element. This method also returns a reference to the newly created child element. In the second statement, a grandchild element is generated by calling the child element's add() method, and the value property of the grandchild is assigned a string value. The third statement saves the modified XML document to the "Simple.xml" file.

Running this script produces a file named "Simple.xml", and the text content of this file is:

<?xml version="1.0" encoding="utf-8"?>
<!--A Simple XML Document-->
<Root>
  <Child Attrib="Value">
    <GrandChild>Text</GrandChild>
  </Child>
</Root>

When the script is run again, the XDocument constructor will load the existing "Simple.xml" file as an XML document. The XML document's root element will now have a child element, and the if statement's code block will not be executed. An easy way to demonstrate this, is to append an else statement and its associated code block to the end of the previous script. The statements in this code block will be executed when there is an existing "Simple.xml" file. The following addition to the previous script will allow it to read and print both the attribute value of the Child element and the text value of the GrandChild element:

from xdocument import XDocument

document = XDocument('Simple.xml', 'Root', 'A Simple XML Document')
if document.root.first_child is None:
    child = document.root.add('Child', 'Attrib', 'Value')
    child.add('GrandChild').value = 'Text'
    document.save()
# -----------------------------------------------------------------
else:  # Read and print the contents of the XML document
    child = document.root.first_child
    print(f"Attribute Value = {child.read_attribute('Attrib')}")
    print(f"GrandChild Value = {child.read_child('GrandChild')}")

The reader is encouraged to make changes to the "Simple.xml" file by carefully editing the attribute value of the Child element (the quotation marks are required) and/or the text value of the GrandChild element. The reader should save these changes to the "Simple.xml" file and then run the script again to observe the results. In the event that these changes result in a file that cannot be successfully loaded; simply delete the "Simple.xml" file, and run the script to recreate the original "Simple.xml" file.