# wx.xml.XmlDocument¶

This class holds XML data/document as parsed by XML parser in the root node.

wx.xml.XmlDocument internally uses the expat library which comes with wxWidgets to parse the given stream.

A wx.xml.XmlDocument is in fact a list of wx.xml.XmlNode organised into a structure that reflects the XML tree being represented by the document.

A simple example of using XML classes is:

def ScanDocument():

doc = wx.xml.XmlDocument()
return False

# start processing the XML file
if doc.GetRoot().GetName() != "myroot-node":
return False

# examine prologue
prolog = doc.GetDocumentNode().GetChildren()
while prolog:

if prolog.GetType() == wx.xml.XML_PI_NODE and prolog.GetName() == "target":

# process Process Instruction contents
pi = prolog.GetContent()

# Other code here...

child = doc.GetRoot().GetChildren()
while child:

if child.GetName() == "tag1":

# process text enclosed by tag1/tag1
content = child.GetNodeContent()

# Other code here...

# process attributes of tag1
attrvalue1 = child.GetAttribute("attr1", "default-value")
attrvalue2 = child.GetAttribute("attr2", "default-value")

elif child.GetName() == "tag2":

# process tag2 ...
attrvalue3 = child.GetAttribute("attr3", "default-value")

child = child.GetNext()


Note that if you want to preserve the original formatting of the loaded file including whitespaces and indentation, you need to turn off whitespace-only textnode removal and automatic indentation. For example:

doc = wx.xml.XmlDocument()

# myfile2.xml will be identical to myfile.xml saving it self way:
doc.Save("myfile2.xml", wx.xml.XML_NO_INDENTATION)


Using default parameters, you will get a reformatted document which in general is different from the original loaded content:

doc = wx.xml.XmlDocument()
doc.Save("myfile2.xml")  # myfile2.xml != myfile.xml


wx.xml.XmlDocument can also be used to create documents. The following code gives an example of creating a simple document with two nested element nodes, the second of which has an attribute, and a text node. It also demonstrates how to write the resulting output to a String :

# Create a document and add the root node.
xmlDoc = wx.xml.XmlDocument()

root = wx.xml.XmlNode(None, wx.xml.XML_ELEMENT_NODE, "Root")
xmlDoc.SetRoot(root)

library = wx.xml.XmlNode(root, wx.xml.XML_ELEMENT_NODE, "Library")
name = wx.xml.XmlNode(library, wx.xml.XML_ELEMENT_NODE, "Name")

# Write the output to a string.
stream = io.StringIO()
xmlDoc.Save(stream)


This will produce a document that looks something like the following:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
<Library type="CrossPlatformList">
<Name>wxPython</Name>
</Library>
</Root>


If the root name value of the DOCTYPE is set, either by loading a file with a DOCTYPE declaration or by setting it directly with the SetDoctype member, then a DOCTYPE declaration will be added immediately after the XML declaration.

Note

Ownership is passed to the XML tree as each wx.xml.XmlNode is added to it, and this has two implications. Firstly, the wx.xml.XmlDocument takes responsibility for deleting the node so the user should not delete it; and secondly, a wx.xml.XmlNode must always be created on the heap and never on the stack.

## Class Hierarchy¶

Inheritance diagram for class XmlDocument:

## Methods Summary¶

 __init__ Default constructor. AppendToProlog Appends a Process Instruction or Comment node to the document prologue. DetachDocumentNode Detaches the document node and returns it. DetachRoot Detaches the root entity node and returns it. GetDoctype Returns the DOCTYPE declaration data for the document. GetDocumentNode Returns the document node of the document. GetEOL Returns the output line ending string used for documents. GetFileEncoding Returns encoding of document (may be empty). GetFileType Returns the output line ending format used for documents. GetLibraryVersionInfo Get expat library version information. GetRoot Returns the root element node of the document. GetVersion Returns the version of document. IsOk Returns True if the document has been loaded successfully. Load Parses filename as an xml document and loads its data. Save Saves XML tree creating a file named with given string. SetDoctype Sets the data which will appear in the DOCTYPE declaration when the document is saved. SetDocumentNode Sets the document node of this document. SetFileEncoding Sets the encoding of the file which will be used to save the document. SetFileType Sets the output line ending formats when the document is saved. SetRoot Sets the root element node of this document. SetVersion Sets the version of the XML file which will be used to save the document.

## Class API¶

class wx.xml.XmlDocument(Object)

Possible constructors:

XmlDocument()

XmlDocument(doc)

XmlDocument(filename, encoding="UTF-8")

XmlDocument(stream, encoding="UTF-8")


This class holds XML data/document as parsed by XML parser in the root node.

### Methods¶

__init__(self, *args, **kw)

__init__ (self)

Default constructor.

__init__ (self, doc)

Copy constructor.

Deep copies all the XML tree of the given document.

Parameters

doc (wx.xml.XmlDocument) –

__init__ (self, filename, encoding=”UTF-8”)

Loads the given filename using the given encoding.

See Load .

Parameters
• filename (string) –

• encoding (string) –

__init__ (self, stream, encoding=”UTF-8”)

Loads the XML document from given stream using the given encoding.

See Load .

Parameters

AppendToProlog(self, node)

Appends a Process Instruction or Comment node to the document prologue.

Calling this function will create a prologue or attach the node to the end of an existing prologue.

Parameters

node (wx.xml.XmlNode) –

New in version 2.9.2.

DetachDocumentNode(self)

Detaches the document node and returns it.

The document node will be set to None and thus IsOk will return False after calling this function.

Note that the caller is responsible for deleting the returned node in order to avoid memory leaks.

Return type

wx.xml.XmlNode

New in version 2.9.2.

DetachRoot(self)

Detaches the root entity node and returns it.

After calling this function, the document node will remain together with any prologue nodes, but IsOk will return False since the root entity will be missing.

Note that the caller is responsible for deleting the returned node in order to avoid memory leaks.

Return type

wx.xml.XmlNode

GetDoctype(self)

Returns the DOCTYPE declaration data for the document.

Return type

wx.xml.XmlDoctype

New in version 4.1/wxWidgets-3.1.0.

GetDocumentNode(self)

Returns the document node of the document.

Return type

wx.xml.XmlNode

New in version 2.9.2.

GetEOL(self)

Returns the output line ending string used for documents.

This string is determined by the last call to SetFileType .

Return type

string

New in version 4.1/wxWidgets-3.1.1.

GetFileEncoding(self)

Returns encoding of document (may be empty).

Return type

string

Note

This is the encoding original file was saved in, not the encoding of in-memory representation!

GetFileType(self)

Returns the output line ending format used for documents.

Return type

wx.TextFileType

New in version 4.1/wxWidgets-3.1.1.

static GetLibraryVersionInfo()

Get expat library version information.

Return type

wx.VersionInfo

New in version 2.9.2.

wx.VersionInfo

GetRoot(self)

Returns the root element node of the document.

Return type

wx.xml.XmlNode

GetVersion(self)

Returns the version of document.

This is the value in the < ?xml version=”1.0”?> header of the XML document. If the version attribute was not explicitly given in the header, this function returns an empty string.

Return type

string

IsOk(self)

Returns True if the document has been loaded successfully.

Return type

bool

Load(self, *args, **kw)

Parses filename as an xml document and loads its data.

If flags does not contain wx.xml.XMLDOC_KEEP_WHITESPACE_NODES, then, while loading, all nodes of type XML_TEXT_NODE (see wx.xml.XmlNode) are automatically skipped if they contain whitespaces only.

The removal of these nodes makes the load process slightly faster and requires less memory however makes impossible to recreate exactly the loaded text with a Save call later. Read the initial description of this class for more info.

Returns True on success, False otherwise.

Parameters
• filename (string) –

• encoding (string) –

• flags (int) –

Return type

bool

Like Load but takes the data from given input stream.

Parameters
Return type

bool

Save(self, *args, **kw)

Save (self, filename, indentstep=2)

Saves XML tree creating a file named with given string.

If indentstep is greater than or equal to zero, then, while saving, an automatic indentation is added with steps composed by indentstep spaces.

If indentstep is XML_NO_INDENTATION , then, automatic indentation is turned off.

Parameters
• filename (string) –

• indentstep (int) –

Return type

bool

Save (self, stream, indentstep=2)

Saves XML tree in the given output stream.

See Save(const String&, int) for a description of indentstep.

Parameters
Return type

bool

SetDoctype(self, doctype)

Sets the data which will appear in the DOCTYPE declaration when the document is saved.

Parameters

doctype (wx.xml.XmlDoctype) –

New in version 4.1/wxWidgets-3.1.0.

SetDocumentNode(self, node)

Sets the document node of this document.

Deletes any previous document node. Use DetachDocumentNode and then SetDocumentNode if you want to replace the document node without deleting the old document tree.

Parameters

node (wx.xml.XmlNode) –

New in version 2.9.2.

SetFileEncoding(self, encoding)

Sets the encoding of the file which will be used to save the document.

Parameters

encoding (string) –

SetFileType(self, fileType)

Sets the output line ending formats when the document is saved.

By default Unix file type is used, i.e. a single ASCII LF (10) character is used at the end of lines.

Parameters

fileType (TextFileType) –

New in version 4.1/wxWidgets-3.1.1.

SetRoot(self, node)

Sets the root element node of this document.

Will create the document node if necessary. Any previous root element node is deleted.

Parameters

node (wx.xml.XmlNode) –

SetVersion(self, version)

Sets the version of the XML file which will be used to save the document.

Parameters

version (string) –

### Properties¶

Doctype

DocumentNode

EOL

FileEncoding

FileType

Root

Version