Metadata-Version: 2.4
Name: xdocument
Version: 1.3.0
Summary: A high-level abstraction layer for creating and editing XML documents.
Author-email: John Bolkcom <johnbolk6502@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/johnbolk/xdocument.git
Keywords: XML,DOM
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: defusedxml>=0.7.1
Dynamic: license-file

**A high-level abstraction layer for creating 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**](https://pypi.org/project/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: https://github.com/johnbolk/xdocument.git**

## 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.
