pugixml.pugi.XMLDocument

class pugixml.pugi.XMLDocument

Bases: XMLNode

Document class (DOM tree root).

Methods

`__init__`(self)	Initialize `XMLDocument` as an empty document.
`document_element`(self)	Return the document element.
`load_buffer`(self, contents, size[, options, ...])	Load a document from a buffer.
`load_file`(self, path[, options, encoding])	Load a document from the existing file.
`load_string`(self, contents[, options])	Load a document from a string.
`reset`(args, *kwargs)	Overloaded function.
`save`(self, writer[, indent, flags, encoding])	Save the XML document to writer.
`save_file`(self, path[, indent, flags, encoding])	Save the XML document to a file.

Member Documentation

__init__(self: pugixml.pugi.XMLDocument) → None: Initialize XMLDocument as an empty document.

document_element(self: pugixml.pugi.XMLDocument) → pugixml.pugi.XMLNode

Return the document element.

Returns:: The element whose parent is this document, or empty node if nothing exists.

load_buffer(self: pugixml.pugi.XMLDocument, contents: str | bytes, size: SupportsInt | SupportsIndex, options: SupportsInt | SupportsIndex = pugixml.pugi.PARSE_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → pugixml.pugi.XMLParseResult

Load a document from a buffer.

The existing document tree is destroyed.

Parameters:

contents – A document to parse.
size – The contents size in bytes.
options – The parsing options.
encoding – The input encoding.

Returns:

The result of the operation.

Examples

>>> from urllib.request import urlopen
>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> with urlopen('http://example.com/large.xml') as f:
...     contents = f.read()
...     doc.load_buffer(contents, len(contents))

load_file(self: pugixml.pugi.XMLDocument, path: os.PathLike | str | bytes, options: SupportsInt | SupportsIndex = pugixml.pugi.PARSE_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → pugixml.pugi.XMLParseResult

Load a document from the existing file.

The existing document tree is destroyed.

Parameters:

path – The path of the document to parse.
options – The parsing options.
encoding – The input encoding.

Returns:

The result of the operation.

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_file('tree.xml', pugi.PARSE_DEFAULT | pugi.PARSE_DECLARATION | pugi.PARSE_COMMENTS)

load_string(self: pugixml.pugi.XMLDocument, contents: str, options: SupportsInt | SupportsIndex = pugixml.pugi.PARSE_DEFAULT) → pugixml.pugi.XMLParseResult

Load a document from a string.

No encoding conversions are applied.

The existing document tree is destroyed.

Parameters:

contents – A document to parse.
options – The parsing options.

Returns:

The result of the operation.

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child/></node>')

reset(*args, **kwargs)

Overloaded function.

reset(self: pugixml.pugi.XMLDocument) -> None

Remove all nodes.
reset(self: pugixml.pugi.XMLDocument, proto: pugixml.pugi.XMLDocument) -> None

Remove all nodes, then copies the entire contents of the specified document.

Parameters:: proto – The XML document to copy.

save(self: pugixml.pugi.XMLDocument, writer: pugixml.pugi.XMLWriter, indent: str = '\t', flags: SupportsInt | SupportsIndex = pugixml.pugi.FORMAT_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → None

Save the XML document to writer.

Semantics is slightly different from XMLNode.print(), see documentation for details.

Parameters:

writer – The writer object which implements XMLWriter interface.
indent – The indentation character(s).
flags – The output options.
encoding – The output encoding.

See also

XMLNode.print() XMLWriter

Examples

A simple example of saving an XML document to a file:

>>> from pugixml import pugi
>>> class FileWriter(pugi.XMLWriter):
...     def __init__(self, path) -> None:
...         super().__init__()
...         self._file = open(path, 'wb')
...     def close(self) -> None:
...         self._file.close()
...     def write(self, data: bytes, size: int) -> None:
...         self._file.write(data)

>>> from contextlib import closing
>>> doc = pugi.XMLDocument()
>>> doc.append_child('node')
>>> with closing(FileWriter('tree.xml')) as writer:
...     doc.save(writer)

save_file(self: pugixml.pugi.XMLDocument, path: os.PathLike | str | bytes, indent: str = '\t', flags: SupportsInt | SupportsIndex = pugixml.pugi.FORMAT_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → bool

Save the XML document to a file.

Parameters:

path – The path to save the XML document.
indent – The indentation character(s).
flags – The output options.
encoding – The output encoding.

Returns:

True if the saving was successful, False otherwise.