phoenix_title 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()
    if not doc.Load("myfile.xml"):
        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()
doc.Load("myfile.xml", "UTF-8", wx.xml.XMLDOC_KEEP_WHITESPACE_NODES)

# 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.Load("myfile.xml")
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)

# Add some XML.
library = wx.xml.XmlNode(root, wx.xml.XML_ELEMENT_NODE, "Library")
library.AddAttribute("type", "CrossPlatformList")
name = wx.xml.XmlNode(library, wx.xml.XML_ELEMENT_NODE, "Name")
name.AddChild(wx.xml.XmlNode(wx.xml.XML_TEXT_NODE, "", "wxPython"))

# 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 Class Hierarchy

Inheritance diagram for class XmlDocument:

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


api 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)

overload Overloaded Implementations:



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

See also

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)

overload Overloaded Implementations:



Load (self, filename, encoding=”UTF-8”, flags=XMLDOC_NONE)

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



Load (self, stream, encoding=”UTF-8”, flags=XMLDOC_NONE)

Like Load but takes the data from given input stream.

Parameters
Return type

bool





Save(self, *args, **kw)

overload Overloaded Implementations:



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

See GetDoctype and SetDoctype



DocumentNode

See GetDocumentNode and SetDocumentNode



EOL

See GetEOL



FileEncoding

See GetFileEncoding and SetFileEncoding



FileType

See GetFileType and SetFileType



Root

See GetRoot and SetRoot



Version

See GetVersion and SetVersion