pugixml.pugi ¶

set_value(*args, **kwargs)¶

Overloaded function.

set_value(self: pugixml.pugi.XMLAttribute, value: str) -> bool

Set the attribute value.
set_value(self: pugixml.pugi.XMLAttribute, value: str, size: int) -> bool

Set the attribute value with the specified length.
set_value(self: pugixml.pugi.XMLAttribute, value: bool) -> bool

Set the attribute value as a boolean (True or False).
set_value(self: pugixml.pugi.XMLAttribute, value: float) -> bool

Set the attribute value as a number [DBL_MIN, DBL_MAX].
set_value(self: pugixml.pugi.XMLAttribute, value: float, precision: int) -> bool

Set the attribute value as a number with the specified precision [DBL_MIN, DBL_MAX].
set_value(self: pugixml.pugi.XMLAttribute, value: int) -> bool

Set the attribute value as a number [LLONG_MIN, LLONG_MAX].
set_value(self: pugixml.pugi.XMLAttribute, value: int) -> bool

Set the attribute value as a number [0, ULLONG_MAX].

Parameters:

value (Union[str, bool, float, int]) – The attribute value to set.
size (int) – The length of the attribute value as a string.
precision (int) – The precision of the attribute value as a floating point number.

Returns:

False if attribute is empty or there is not enough memory.

Return type:

value(self: pugixml.pugi.XMLAttribute) → str¶

Return the attribute value.

Returns:: The attribute value, or the empty string if attribute is empty.
Return type:: str

See also

as_string()

class pugixml.pugi.XMLAttributeIterator¶

Bases: pybind11_object

A collection of attributes.

See also

XMLNode.attributes()

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: pugixml.pugi.XMLAttributeIterator, index: int) -> pugixml.pugi.XMLAttribute

Return the attribute at the specified index from the collection.
__getitem__(self: pugixml.pugi.XMLAttributeIterator, slice: slice) -> list[pugixml.pugi.XMLAttribute]

Return a list of attributes at the specified slice from the collection.

Parameters:

index (int) – An index to specify position.
slice (slice) – A slice object to specify range.

Returns:

The attribute(s) at the specified index/slice from the collection.

Return type:

Union[XMLAttribute, List[XMLAttribute]]

__iter__(self: pugixml.pugi.XMLAttributeIterator) → pugixml.pugi.XMLAttributeIterator¶

Return itself.

Returns:: self.
Return type:: XMLAttributeIterator

__len__(self: pugixml.pugi.XMLAttributeIterator) → int¶

Return the collection size.

Returns:: The collection size.
Return type:: int

__next__(self: pugixml.pugi.XMLAttributeIterator) → pugixml.pugi.XMLAttribute¶

Return the next attribute from the collection.

Returns:: The next attribute from the collection.
Return type:: XMLAttribute

class pugixml.pugi.XMLAttributeStruct¶

Bases: pybind11_object

The internal object of the attribute.

__eq__(self: pugixml.pugi.XMLAttributeStruct, other: pugixml.pugi.XMLAttributeStruct) → bool¶

Return self == other.

Parameters:: other (XMLAttributeStruct) – The internal object of the attribute to compare.
Returns:: The result of comparing pointers of the internal objects.
Return type:: bool

__ne__(self: pugixml.pugi.XMLAttributeStruct, other: pugixml.pugi.XMLAttributeStruct) → bool¶

Return self != other.

Parameters:: other (XMLAttributeStruct) – The internal object of the attribute to compare.
Returns:: The result of comparing pointers of the internal objects.
Return type:: bool

class pugixml.pugi.XMLDocument¶

Bases: XMLNode

Document class (DOM tree root).

__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 not exists.
Return type:: XMLNode

load_buffer(self: pugixml.pugi.XMLDocument, contents: Union[str, bytes], size: int, options: int = 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 (Union[str, bytes]) – A document to parse.
size (int) – The contents size in bytes.
options (int) – The parsing options.
encoding (XMLEncoding) – The input encoding.

Returns:

The result of the operation.

Return type:

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, options: int = 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 (os.PathLike) – The path-like object of the document to parse.
options (int) – The parsing options.
encoding (XMLEncoding) – The input encoding.

Returns:

The result of the operation.

Return type:

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: int = 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 (str) – A document to parse.
options (int) – The parsing options.

Returns:

The result of the operation.

Return type:

XMLNode.print(), XMLWriter

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 (XMLDocument) – The XML document to copy.

save(self: pugixml.pugi.XMLDocument, writer: pugixml.pugi.XMLWriter, indent: str = '\t', flags: int = 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 (XMLWriter) – The writer object which implements XMLWriter interface.
indent (str) – The indentation character(s).
flags (int) – The output options.
encoding (XMLEncoding) – The output encoding.

See also

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, indent: str = '\t', flags: int = pugixml.pugi.FORMAT_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → bool¶

Save the XML document to a file.

Parameters:

path (os.PathLike) – The path-like object to save the XML document.
indent (str) – The indentation character(s).
flags (int) – The output options.
encoding (XMLEncoding) – The output encoding.

Returns:

True if the saving was successful, False otherwise.

Return type:

class pugixml.pugi.XMLEncoding¶

Bases: pybind11_object

These flags determine the encoding of input/output data for XML document.

Members:

ENCODING_AUTO : Auto-detect input encoding using BOM or ‘<’ / ‘<?’ detection; use UTF8 if BOM is not found.

ENCODING_UTF8 : UTF8 encoding.

ENCODING_UTF16_LE : Little-endian UTF16.

ENCODING_UTF16_BE : Big-endian UTF16.

ENCODING_UTF16 : UTF16 with native endianness.

ENCODING_UTF32_LE : Little-endian UTF32.

ENCODING_UTF32_BE : Big-endian UTF32.

ENCODING_UTF32 : UTF32 with native endianness.

ENCODING_WCHAR : The same encoding wchar_t has (either UTF16 or UTF32).

ENCODING_LATIN1 : ISO-8859-1 encoding (also known as Latin-1).

class pugixml.pugi.XMLNamedNodeIterator¶

Bases: pybind11_object

A collection of nodes specified by name.

See also

XMLNode.children()

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: pugixml.pugi.XMLNamedNodeIterator, index: int) -> pugixml.pugi.XMLNode

Return the node at the specified index from the collection.
__getitem__(self: pugixml.pugi.XMLNamedNodeIterator, slice: slice) -> list[pugixml.pugi.XMLNode]

Return a list of nodes at the specified slice from the collection.

Parameters:

index (int) – An index to specify position.
slice (slice) – A slice object to specify range.

Returns:

The node(s) at the specified index/slice from the collection.

Return type:

Union[XMLNode, List[XMLNode]]

__iter__(self: pugixml.pugi.XMLNamedNodeIterator) → pugixml.pugi.XMLNamedNodeIterator¶

Return itself.

Returns:: self.
Return type:: XMLNamedNodeIterator

__len__(self: pugixml.pugi.XMLNamedNodeIterator) → int¶

Return the collection size.

Returns:: The collection size.
Return type:: int

__next__(self: pugixml.pugi.XMLNamedNodeIterator) → pugixml.pugi.XMLNode¶

Return the next node from the collection.

Returns:: The next node from collection.
Return type:: XMLNode

class pugixml.pugi.XMLNode¶

Bases: pybind11_object

A light-weight handle for manipulating nodes in DOM tree.

__bool__(self: pugixml.pugi.XMLNode) → bool¶

Determine if this node is not empty.

Returns:: True if node is not empty, False otherwise.
Return type:: bool

__eq__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self == other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__ge__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self >= other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__gt__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self > other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__hash__(self: pugixml.pugi.XMLNode) → int¶

Return the hash value (unique for handles to the same object).

This is equivalent to hash_value().

Returns:: The hash value.
Return type:: int

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: pugixml.pugi.XMLNode) -> None

Initialize XMLNode as an empty node.
__init__(self: pugixml.pugi.XMLNode, p: pugixml.pugi.XMLNodeStruct) -> None

Initialize XMLNode with the internal object.

Parameters:: p (XMLNodeStruct) – The internal object of the node to shallow copy.

__le__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self <= other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__lt__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self < other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__ne__(self: pugixml.pugi.XMLNode, other: pugixml.pugi.XMLNode) → bool¶

Return self != other.

Parameters:: other (XMLNode) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

append_attribute(self: pugixml.pugi.XMLNode, name: str) → pugixml.pugi.XMLAttribute¶

Add a new attribute with the specified name to the end of the list of attributes for this node.

Parameters:: name (str) – The attribute name to add.
Returns:: The attribute added, or empty attribute if error occurs.
Return type:: XMLAttribute

append_buffer(self: pugixml.pugi.XMLNode, contents: Union[str, bytes], size: int, options: int = pugixml.pugi.PARSE_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO) → pugixml.pugi.XMLParseResult¶

Parse a buffer as a fragment of the XML document and appends all nodes as children of the current node.

Parameters:

contents (Union[str, bytes]) – The XML document fragment to parse.
size (int) – The contents size in bytes.
options (int) – The parsing options.
encoding (XMLEncoding) – The input encoding.

Returns:

The result of the operation.

Return type:

append_child(*args, **kwargs)¶

Overloaded function.

append_child(self: pugixml.pugi.XMLNode, node_type: pugixml.pugi.XMLNodeType = <XMLNodeType.NODE_ELEMENT: 2>) -> pugixml.pugi.XMLNode

Add a new node with the specified node type to the end of the list of children.
append_child(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNode

Add a new node with the specified name to the end of the list of children.

Parameters:

node_type (XMLNodeType) – The node type to add.
name (str) – The node name to add.

Returns:

The node added, or empty node if error occurs.

Return type:

find_child(), find_node()

append_copy(*args, **kwargs)¶

Overloaded function.

append_copy(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLAttribute) -> pugixml.pugi.XMLAttribute

Add a copy of attribute proto to the end of the list of attributes for this node.
append_copy(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Add a copy of node proto to the end of the list of children.

Parameters:: proto (Union[XMLAttribute, XMLNode]) – The attribute or node to add after copying.
Returns:: The attribute/node added, or empty attribute/node if error occurs.
Return type:: Union[XMLAttribute, XMLNode]

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> node = doc.append_child('node')
>>> attr1 = node.append_attribute('attr1')
>>> attr1.set_value(1)
>>> attr2 = node.append_copy(attr1)
>>> attr1 != attr2  # True
>>> attr2.set_name('attr2')
>>> doc.print(pugi.PrintWriter())
<node attr1="1" attr2="1"/>

append_move(self: pugixml.pugi.XMLNode, moved: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Move the specified node as the last child of this node.

Parameters:: moved (XMLNode) – The node to move.
Returns:: The node moved, or empty node if error occurs.
Return type:: XMLNode

attribute(*args, **kwargs)¶

Overloaded function.

attribute(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLAttribute

Return the attribute with the specified name for this node.
attribute(self: pugixml.pugi.XMLNode, name: str, hint: pugixml.pugi.XMLAttribute) -> pugixml.pugi.XMLAttribute

Return the attribute with the specified name and hint for this node.

Parameters:

name (str) – The attribute name to find.
hint (XMLAttribute) – The attribute to start searching for in the attribute list of this node. If the attribute specified by name is found in the attribute list, hint is updated with the next attribute after the one found, or with an empty attribute if not found.

Returns:

The first attribute found, or empty attribute if not exists.

Return type:

XMLAttribute

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node attr1="1" attr2="2" attr3="3" />')
>>> node = doc.child('node')
>>> hint = pugi.XMLAttribute()
>>> node.attribute('attr2', hint).name()
'attr2'
>>> hint.name()
'attr3'
>>> node.attribute('attr1', hint).name()
'attr1'
>>> hint.name()
'attr2'
>>> node.attribute('attr3', hint).name()
'attr3'
>>> hint.empty()
True

attributes(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLAttributeIterator¶

Return an iterator of attributes for this node.

Returns:: A new iterator of attributes.
Return type:: XMLAttributeIterator

child(self: pugixml.pugi.XMLNode, name: str) → pugixml.pugi.XMLNode¶

Return a child node with the specified name.

Parameters:: name (str) – The node name to find.
Returns:: The first node found, or empty node if not exists.
Return type:: XMLNode

child_value(*args, **kwargs)¶

Overloaded function.

child_value(self: pugixml.pugi.XMLNode) -> str

Return the value of the first child node with node type NODE_PCDATA or NODE_CDATA.
child_value(self: pugixml.pugi.XMLNode, name: str) -> str

Return the value of the child node with the specified name.

Parameters:: name (str) – The node name to find.
Returns:: The value of the child node specified by name, the value of the first child node with node type NODE_PCDATA or NODE_CDATA, or the empty string if not exists.
Return type:: str

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child1>value1</child1><child3><![CDATA[value3]]></child3>value4</node>')
>>> doc.child_value('node')
'value4'
>>> doc.child('node').child_value()
'value4'
>>> doc.child('node').child_value('child1')
'value1'
>>> doc.child('node').child_value('child3')
'value3'

children(*args, **kwargs)¶

Overloaded function.

children(self: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNodeIterator

Return an iterator of children.
children(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNamedNodeIterator

Return an iterator of children with the specified name.

Parameters:: name (str) – The node name to find.
Returns:: A new iterator of children.
Return type:: Union[XMLNodeIterator, XMLNamedNodeIterator]

empty(self: pugixml.pugi.XMLNode) → bool¶

Determine if this node is empty.

Returns:: True if node is empty, False otherwise.
Return type:: bool

find_attribute(self: pugixml.pugi.XMLNode, pred: Callable[[pugixml.pugi.XMLAttribute], bool]) → pugixml.pugi.XMLAttribute¶

Find the attribute using predicate.

Parameters:: pred (Callable[[XMLAttribute], bool]) – The function to find attribute.
Returns:: The first attribute for which predicate returned True.
Return type:: XMLAttribute

See also

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node attr1="0" attr2="1"/>')
>>> doc.child('node').find_attribute(lambda x: x.as_int() > 0).name()
'attr2'
>>> doc.child('node').find_attribute(lambda x: x.as_int() <= 0).name()
'attr1'

find_child(self: pugixml.pugi.XMLNode, pred: Callable[[pugixml.pugi.XMLNode], bool]) → pugixml.pugi.XMLNode¶

Find the child node using predicate.

Parameters:: pred (Callable[[XMLNode], bool]) – The function to find child node.
Returns:: The first child for which predicate returned True.
Return type:: XMLNode

See also

find_attribute(), find_node()

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child1/><child2/></node>')
>>> doc.find_child(lambda x: x.name().startswith('child')).empty()
True
>>> doc.child('node').find_child(lambda x: x.name().startswith('child')).name()
'child1'

find_child_by_attribute(*args, **kwargs)¶

Overloaded function.

find_child_by_attribute(self: pugixml.pugi.XMLNode, name: str, attr_name: str, attr_value: str) -> pugixml.pugi.XMLNode

Find the child node with the specified node name, attribute name, and attribute value.
find_child_by_attribute(self: pugixml.pugi.XMLNode, attr_name: str, attr_value: str) -> pugixml.pugi.XMLNode

Find the child node with the specified attribute name and attribute value.

Parameters:

name (str) – The node name to find.
attr_name (str) – The attribute name to find.
attr_value (str) – The attribute value to find.

Returns:

The first child found, or empty node if not exists.

Return type:

find_attribute(), find_child()

find_node(self: pugixml.pugi.XMLNode, pred: Callable[[pugixml.pugi.XMLNode], bool]) → pugixml.pugi.XMLNode¶

Find the node from subtree using predicate.

Parameters:: pred (Callable[[XMLNode], bool]) – The function to find node from subtree.
Returns:: The first node from subtree (depth-first), for which predicate returned True.
Return type:: XMLNode

See also

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child1/><child2/></node>')
>>> doc.find_node(lambda x: x.name().startswith('child')).name()
'child1'
>>> doc.child('node').find_node(lambda x: x.name().startswith('child')).name()
'child1'

first_attribute(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLAttribute¶

Return the first attribute in the list of attributes for this node.

Returns:: The attribute found, or empty attribute if not exists.
Return type:: XMLAttribute

See also

last_attribute()

first_child(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Return the first child node.

Returns:: The first child node, or empty node if not exists.
Return type:: XMLNode

See also

last_child()

first_element_by_path(self: pugixml.pugi.XMLNode, path: str, delimiter: str = '/') → pugixml.pugi.XMLNode¶

Search for a node by path consisting of node names and ‘.’ or ‘..’ elements.

Parameters:

path (str) – The path to search for the node.
delimiter (str) – The path separator.

Returns:

The first node found, or empty node if not exists.

Return type:

See also

path()

hash_value(self: pugixml.pugi.XMLNode) → int¶

Return the hash value (unique for handles to the same object).

Returns:: The hash value.
Return type:: int

insert_attribute_after(self: pugixml.pugi.XMLNode, name: str, attr: pugixml.pugi.XMLAttribute) → pugixml.pugi.XMLAttribute¶

Insert a new attribute with the specified name after attr in the list of attributes for this node.

Parameters:

name (str) – The attribute name to insert.
attr (XMLAttribute) – The attribute in the attribute list for this node.

Returns:

The attribute inserted, or empty attribute if error occurs.

Return type:

XMLAttribute

insert_attribute_before(self: pugixml.pugi.XMLNode, name: str, attr: pugixml.pugi.XMLAttribute) → pugixml.pugi.XMLAttribute¶

Insert a new attribute with the specified name before attr in the list of attributes for this node.

Parameters:

name (str) – The attribute name to insert.
attr (XMLAttribute) – The attribute in the attribute list for this node.

Returns:

The attribute inserted, or empty attribute if error occurs.

Return type:

XMLAttribute

insert_child_after(*args, **kwargs)¶

Overloaded function.

insert_child_after(self: pugixml.pugi.XMLNode, node_type: pugixml.pugi.XMLNodeType, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a new node with the specified node type after node in the list of children.
insert_child_after(self: pugixml.pugi.XMLNode, name: str, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a new node with the specified name after node in the list of children.

Parameters:

node_type (XMLNodeType) – The node type to insert.
name (str) – The node name to insert.
node (XMLNode) – The node in the children list.

Returns:

The node inserted, or empty node if error occurs.

Return type:

insert_child_before(*args, **kwargs)¶

Overloaded function.

insert_child_before(self: pugixml.pugi.XMLNode, node_type: pugixml.pugi.XMLNodeType, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a new node with the specified node type before node in the list of children.
insert_child_before(self: pugixml.pugi.XMLNode, name: str, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a new node with the specified name before node in the list of children.

Parameters:

node_type (XMLNodeType) – The node type to insert.
name (str) – The node name to insert.
node (XMLNode) – The node in the children list.

Returns:

The node inserted, or empty node if error occurs.

Return type:

insert_copy_after(*args, **kwargs)¶

Overloaded function.

insert_copy_after(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLAttribute, attr: pugixml.pugi.XMLAttribute) -> pugixml.pugi.XMLAttribute

Insert a copy of attribute proto after attr in the list of attributes for this node.
insert_copy_after(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLNode, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a copy of node proto after node in the list of children.

Parameters:

proto (Union[XMLAttribute, XMLNode]) – The attribute or node to insert after copying.
attr (XMLAttribute) – The attribute in the attribute list of this node.
node (XMLNode) – The node in the children list.

Returns:

The attribute/node inserted, or empty attribute/node if error occurs.

Return type:

Union[XMLAttribute, XMLNode]

insert_copy_before(*args, **kwargs)¶

Overloaded function.

insert_copy_before(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLAttribute, attr: pugixml.pugi.XMLAttribute) -> pugixml.pugi.XMLAttribute

Insert a copy of attribute proto before attr in the list of attributes for this node.
insert_copy_before(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLNode, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Insert a copy of node proto before node in the list of children.

Parameters:

proto (Union[XMLAttribute, XMLNode]) – The attribute or node to insert after copying.
attr (XMLAttribute) – The attribute in the attribute list of this node.
node (XMLNode) – The node in the children list.

Returns:

The attribute/node inserted, or empty attribute/node if error occurs.

Return type:

Union[XMLAttribute, XMLNode]

insert_move_after(self: pugixml.pugi.XMLNode, moved: pugixml.pugi.XMLNode, node: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Move the specified node after node in the list of children.

Parameters:

moved (XMLNode) – The node to move.
node (XMLNode) – The node in the children list.

Returns:

The node moved, or empty node if error occurs.

Return type:

insert_move_before(self: pugixml.pugi.XMLNode, moved: pugixml.pugi.XMLNode, node: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Move the specified node before node in the list of children.

Parameters:

moved (XMLNode) – The node to move.
node (XMLNode) – The node in the children list.

Returns:

The node moved, or empty node if error occurs.

Return type:

first_element_by_path()

internal_object(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNodeStruct¶

Return the internal object.

Returns:: The internal object of this node.
Return type:: XMLNodeStruct

last_attribute(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLAttribute¶

Return the last attribute in the list of attributes for this node.

Returns:: The attribute found, or empty attribute if not exists.
Return type:: XMLAttribute

See also

first_attribute()

last_child(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Return the last child node.

Returns:: The last child node, or empty node if not exists.
Return type:: XMLNode

See also

first_child()

name(self: pugixml.pugi.XMLNode) → str¶

Return the node name.

Returns:: The node name, or the empty string if node is empty or it has no name.
Return type:: str

next_sibling(*args, **kwargs)¶

Overloaded function.

next_sibling(self: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Return the next sibling node in the document tree.
next_sibling(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNode

Return the next sibling node with the specified name in the document tree.

Parameters:: name (str) – The name of the target node.
Returns:: The node found, or empty node if not exists.
Return type:: XMLNode

See also

previous_sibling()

offset_debug(self: pugixml.pugi.XMLNode) → int¶

Return the node offset in the parsed file/string for debugging purposes.

Returns:: The offset to node’s data from the beginning of XML buffer. For more information on parsing offsets, see parsing error handling documentation.
Return type:: int

parent(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Return the parent node.

Returns:: The parent node, or empty node if not exists.
Return type:: XMLNode

path(self: pugixml.pugi.XMLNode, delimiter: str = '/') → str¶

Return the absolute node path from the root as a text string.

Parameters:: delimiter (str) – The path separator.
Returns:: A path string.
Return type:: str

See also

prepend_attribute(self: pugixml.pugi.XMLNode, name: str) → pugixml.pugi.XMLAttribute¶

Add a new attribute with the specified name to the top of the list of attributes for this node.

Parameters:: name (str) – The attribute name to add.
Returns:: The attribute added, or empty attribute if error occurs.
Return type:: XMLAttribute

prepend_child(*args, **kwargs)¶

Overloaded function.

prepend_child(self: pugixml.pugi.XMLNode, node_type: pugixml.pugi.XMLNodeType = <XMLNodeType.NODE_ELEMENT: 2>) -> pugixml.pugi.XMLNode

Add a new node with the specified node type to the top of the list of children.
prepend_child(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNode

Add a new node with the specified name to the top of the list of children.

Parameters:

node_type (XMLNodeType) – The node type to add.
name (str) – The node name to add.

Returns:

The node added, or empty node if error occurs.

Return type:

XMLDocument.save(), XMLWriter

prepend_copy(*args, **kwargs)¶

Overloaded function.

prepend_copy(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLAttribute) -> pugixml.pugi.XMLAttribute

Add a copy of attribute proto to the top of the list of attributes for this node.
prepend_copy(self: pugixml.pugi.XMLNode, proto: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Add a copy of node proto to the top of the list of children.

Parameters:: proto (Union[XMLAttribute, XMLNode]) – The attribute or node to add after copying.
Returns:: The attribute/node added, or empty attribute/node if error occurs.
Return type:: Union[XMLAttribute, XMLNode]

prepend_move(self: pugixml.pugi.XMLNode, moved: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Move the specified node as the first child of this node.

Parameters:: moved (XMLNode) – The node to move.
Returns:: The node moved, or empty node if error occurs.
Return type:: XMLNode

previous_sibling(*args, **kwargs)¶

Overloaded function.

previous_sibling(self: pugixml.pugi.XMLNode) -> pugixml.pugi.XMLNode

Return the previous sibling node in the document tree.
previous_sibling(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNode

Return the previous sibling node with the specified name in the document tree.

Parameters:: name (str) – The name of the target node.
Returns:: The node found, or empty node if not exists.
Return type:: XMLNode

See also

next_sibling()

print(self: pugixml.pugi.XMLNode, writer: pugixml.pugi.XMLWriter, indent: str = '\t', flags: int = pugixml.pugi.FORMAT_DEFAULT, encoding: pugixml.pugi.XMLEncoding = pugixml.pugi.ENCODING_AUTO, depth: int = 0) → None¶

Save a single subtree to writer.

See documentation for details.

Parameters:

writer (XMLWriter) – The writer object which implements XMLWriter interface.
indent (str) – The indentation character(s).
flags (int) – The output options.
encoding (XMLEncoding) – The output encoding.
depth (int) – The number of node’s depth.

See also

Examples

>>> from pugixml import pugi
>>> class SimpleWriter(pugi.XMLWriter):
...     def __init__(self) -> None:
...         super().__init__()
...         self._data = b''
...     def getvalue(self) -> bytes:
...         return self._data
...     def write(self, data: bytes, size: int) -> None:
...         self._data += data

>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child1 a1="v1"><child2 a2="v2"/></child1></node>')
>>> writer = SimpleWriter()
>>> doc.print(writer, encoding=pugi.ENCODING_UTF32_BE)
>>> writer.getvalue().decode('utf-32be')
'<node>\n\t<child1 a1="v1">\n\t\t<child2 a2="v2" />\n\t</child1>\n</node>\n'
>>> writer = SimpleWriter()
>>> doc.child('node').first_child().print(writer, encoding=pugi.ENCODING_UTF32_BE)
>>> writer.getvalue().decode('utf-32be')
'<child1 a1="v1">\n\t<child2 a2="v2" />\n</child1>\n'

remove_attribute(*args, **kwargs)¶

Overloaded function.

remove_attribute(self: pugixml.pugi.XMLNode, attr: pugixml.pugi.XMLAttribute) -> bool

Remove the attribute with the specified attr from the list of attributes for this node.
remove_attribute(self: pugixml.pugi.XMLNode, name: str) -> bool

Remove the attribute with the specified name from the list of attributes for this node.

Parameters:

attr (XMLAttribute) – The attribute to remove.
name (str) – The attribute name to remove.

Returns:

False if node is empty, attr is empty, attribute to be removed is not in the attribute list, or there is not enough memory.

Return type:

remove_attributes(self: pugixml.pugi.XMLNode) → bool¶

Remove all attributes from the node.

Returns:: False if node is empty or there is not enough memory.
Return type:: bool

remove_child(*args, **kwargs)¶

Overloaded function.

remove_child(self: pugixml.pugi.XMLNode, node: pugixml.pugi.XMLNode) -> bool

Remove the child node specified by node and its entire subtree (including all descendant nodes and attributes) from the document.
remove_child(self: pugixml.pugi.XMLNode, name: str) -> bool

Remove the child node specified by name and its entire subtree (including all descendant nodes and attributes) from the document.

Parameters:

node (XMLNode) – The node to remove.
name (str) – The node name to remove.

Returns:

False if node is empty, node is empty, node to be removed is not in the children list, or there is not enough memory.

Return type:

remove_children(self: pugixml.pugi.XMLNode) → bool¶

Remove all child nodes of the node.

Returns:: False if node is empty or there is not enough memory.
Return type:: bool

root(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNode¶

Return the root of DOM tree this node belongs to.

Returns:: The root node, or empty node if not exists.
Return type:: XMLNode

select_node(*args, **kwargs)¶

Overloaded function.

select_node(self: pugixml.pugi.XMLNode, query: str, variables: pugixml.pugi.XPathVariableSet = None) -> pugixml.pugi.XPathNode

Select a single node by evaluating XPath expression with variables.

This is equivalent to select_nodes(query, variables).first().
select_node(self: pugixml.pugi.XMLNode, query: pugixml.pugi.XPathQuery) -> pugixml.pugi.XPathNode

Select a single node by evaluating XPath expression.

This is equivalent to select_nodes(query).first().

Parameters:

query (Union[str, XPathQuery]) – The XPath expression.
variables (Optional[XPathVariableSet]) – The variables in query.

Returns:

The first XPath node in the document order that matches the XPath expression, or empty XPath node if node is empty or XPath expression does not match anything.

Return type:

XPathNode

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><head id="1"/><foo id="2"/><foo id="3"/><tail id="4"/></node>')
>>> node = doc.select_node('//*[@id="2"]')
>>> bool(node)
True
>>> node.node().print(pugi.PrintWriter())
<foo id="2" />
>>> varset = pugi.XPathVariableSet()
>>> var = varset.add('id', pugi.XPATH_TYPE_NUMBER)
>>> var.set(3)
>>> node = doc.select_node('//*[@id=string($id)]', varset)
>>> bool(node)
True
>>> node.node().print(pugi.PrintWriter())
<foo id="3" />
>>> var.set(5)
>>> node = doc.select_node('//*[@id=string($id)]', varset)
>>> bool(node)
False

select_nodes(*args, **kwargs)¶

Overloaded function.

select_nodes(self: pugixml.pugi.XMLNode, query: str, variables: pugixml.pugi.XPathVariableSet = None) -> pugixml.pugi.XPathNodeSet

Select the node set by evaluating XPath expression with variables.
select_nodes(self: pugixml.pugi.XMLNode, query: pugixml.pugi.XPathQuery) -> pugixml.pugi.XPathNodeSet

Select the node set by evaluating XPath expression.

Parameters:

query (Union[str, XPathQuery]) – The XPath expression.
variables (Optional[XPathVariableSet]) – The variables in query.

Returns:

The XPath node set in the document order that matches the XPath expression, or empty XPath node set if node is empty or XPath expression does not match anything.

Return type:

XPathNodeSet

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><head id="1"/><foo id="2"/><foo id="3"/><tail id="4"/></node>')
>>> varset = pugi.XPathVariableSet()
>>> var = varset.add('name', pugi.XPATH_TYPE_STRING)
>>> query = pugi.XPathQuery('//*[local-name()=$name]', varset)
>>> var.set('foo')
>>> ns = doc.select_nodes(query)
>>> ns.size()
2
>>> ns[0].node().print(pugi.PrintWriter())
<foo id="2" />
>>> ns[1].node().print(pugi.PrintWriter())
<foo id="3" />
>>> var.set('tail')
>>> ns = doc.select_nodes(query)
>>> ns.size()
1
>>> ns[0].node().print(pugi.PrintWriter())
<tail id="4" />

set_name(*args, **kwargs)¶

Overloaded function.

set_name(self: pugixml.pugi.XMLNode, name: str) -> bool

Set the node name.
set_name(self: pugixml.pugi.XMLNode, name: str, size: int) -> bool

Set the node name with the specified length.

Parameters:

name (str) – The node name to set.
size (int) – The length of the node name.

Returns:

False if node is empty, there is not enough memory, or node can not have name.

Return type:

set_value(*args, **kwargs)¶

Overloaded function.

set_value(self: pugixml.pugi.XMLNode, value: str) -> bool

Set the node value.
set_value(self: pugixml.pugi.XMLNode, value: str, size: int) -> bool

Set the node value with the specified length.

Parameters:

value (str) – The node value to set.
size (int) – The length of the value.

Returns:

False if node is empty, there is not enough memory, or node can not have value.

Return type:

text(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLText¶

Return the text object for the current node.

Returns:: The text object.
Return type:: XMLText

traverse(self: pugixml.pugi.XMLNode, walker: pugixml.pugi.XMLTreeWalker) → bool¶

Traverse subtree recursively with XMLTreeWalker.

First, traverse() calls XMLTreeWalker.begin() with the traversal root as its arguments. Then, XMLTreeWalker.for_each() is called for all nodes in the traversal subtree in depth first order, excluding the traversal root, with the node as its arguments. Finally, XMLTreeWalker.end() is called with traversal root as its argument. If begin, end, or any of the for_each returns False, the traversal is terminated and False is returned as the traversal result.

See documentation for more details.

Parameters:: walker (XMLTreeWalker) – The walker object which implements XMLTreeWalker interface.
Returns:: False if XMLTreeWalker.begin(), XMLTreeWalker.end(), or any of the XMLTreeWalker.for_each() returns False.
Return type:: bool

Examples

>>> from pugixml import pugi
... class PrintWalker(pugi.XMLTreeWalker):
...     def for_each(self, node: pugi.XMLNode) -> bool:
...         print('%r depth=%d name=%r' % (node.type(), self.depth(), node.name()))
...         return True

>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node><child1><child2/></child1><child3/></node>')
>>> doc.traverse(PrintWalker())
<XMLNodeType.NODE_ELEMENT: 2> depth=0 name='node'
<XMLNodeType.NODE_ELEMENT: 2> depth=1 name='child1'
<XMLNodeType.NODE_ELEMENT: 2> depth=2 name='child2'
<XMLNodeType.NODE_ELEMENT: 2> depth=1 name='child3'

type(self: pugixml.pugi.XMLNode) → pugixml.pugi.XMLNodeType¶

Return the node type.

Returns:: The node type.
Return type:: XMLNodeType

value(self: pugixml.pugi.XMLNode) → str¶

Return the node value.

Returns:: The node value, or the empty string if node is empty or it has no value.
Return type:: str

Note

For <node>text</node> value() does not return “text”! Use child_value() or text() methods to access text inside nodes.

class pugixml.pugi.XMLNodeIterator¶

Bases: pybind11_object

A collection of nodes.

See also

XMLNode.children()

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: pugixml.pugi.XMLNodeIterator, index: int) -> pugixml.pugi.XMLNode

Return the node at the specified index from the collection.
__getitem__(self: pugixml.pugi.XMLNodeIterator, slice: slice) -> list[pugixml.pugi.XMLNode]

Return a list of nodes at the specified slice from the collection.

Parameters:

index (int) – An index to specify position.
slice (slice) – A slice object to specify range.

Returns:

The node(s) at the specified index/slice from the collection.

Return type:

Union[XMLNode, List[XMLNode]]

__iter__(self: pugixml.pugi.XMLNodeIterator) → pugixml.pugi.XMLNodeIterator¶

Return itself.

Returns:: self.
Return type:: XMLNodeIterator

__len__(self: pugixml.pugi.XMLNodeIterator) → int¶

Return the collection size.

Returns:: The collection size.
Return type:: int

__next__(self: pugixml.pugi.XMLNodeIterator) → pugixml.pugi.XMLNode¶

Return the next node from the collection.

Returns:: The next node from the collection.
Return type:: XMLNode

class pugixml.pugi.XMLNodeStruct¶

Bases: pybind11_object

The internal object of the node.

__eq__(self: pugixml.pugi.XMLNodeStruct, other: pugixml.pugi.XMLNodeStruct) → bool¶

Return self == other.

Parameters:: other (XMLNodeStruct) – The internal object of the node to compare.
Returns:: The result of comparing pointers of the internal objects.
Return type:: bool

__ne__(self: pugixml.pugi.XMLNodeStruct, other: pugixml.pugi.XMLNodeStruct) → bool¶

Return self != other.

Parameters:: other (XMLNodeStruct) – The internal object of the node to compare.
Returns:: The result of comparing pointers of the internal objects.
Return type:: bool

class pugixml.pugi.XMLNodeType¶

Bases: pybind11_object

Tree node types.

Members:

NODE_NULL : Empty (null) node handle.

NODE_DOCUMENT : A document tree’s absolute root.

NODE_ELEMENT : Element tag, i.e. ‘<node/>’

NODE_PCDATA : Plain character data, i.e. ‘text’

NODE_CDATA : Character data, i.e. ‘<![CDATA[text]]>’

NODE_COMMENT : Comment tag, i.e. ‘<!– text –>’

NODE_PI : Processing instruction, i.e. ‘<?name?>’

NODE_DECLARATION : Document declaration, i.e. ‘<?xml version=”1.0”?>’

NODE_DOCTYPE : Document type declaration, i.e. ‘<!DOCTYPE doc>’

class pugixml.pugi.XMLParseResult¶

Bases: pybind11_object

Parsing result.

__bool__(self: pugixml.pugi.XMLParseResult) → bool¶

Determine if the parsing result is not an error (status == STATUS_OK).

Returns:: True if the parsing result is not an error, False otherwise.
Return type:: bool

__init__(self: pugixml.pugi.XMLParseResult) → None¶: Initialize XMLParseResult.

description(self: pugixml.pugi.XMLParseResult) → str¶

Return an error description.

Returns:: An error description.
Return type:: str

property encoding¶

The source document encoding.

Type:: XMLEncoding

property offset¶

The last parsed offset.

Type:: int

property status¶

The parsing status.

Type:: XMLParseStatus

class pugixml.pugi.XMLParseStatus¶

Bases: pybind11_object

Parsing status, returned as part of XMLParseResult object.

Members:

STATUS_OK : No error.

STATUS_FILE_NOT_FOUND : File was not found during XMLDocument.load_file().

STATUS_IO_ERROR : Error reading from file/stream.

STATUS_OUT_OF_MEMORY : Could not allocate memory.

STATUS_INTERNAL_ERROR : Internal error occurred.

STATUS_UNRECOGNIZED_TAG : Parser could not determine tag type.

STATUS_BAD_PI : Parsing error occurred while parsing document declaration/processing instruction.

STATUS_BAD_COMMENT : Parsing error occurred while parsing comment.

STATUS_BAD_CDATA : Parsing error occurred while parsing CDATA section.

STATUS_BAD_DOCTYPE : Parsing error occurred while parsing document type declaration.

STATUS_BAD_PCDATA : Parsing error occurred while parsing PCDATA section.

STATUS_BAD_START_ELEMENT : Parsing error occurred while parsing start element tag.

STATUS_BAD_ATTRIBUTE : Parsing error occurred while parsing element attribute.

STATUS_BAD_END_ELEMENT : Parsing error occurred while parsing end element tag.

STATUS_END_ELEMENT_MISMATCH : There was a mismatch of start-end tags (closing tag had incorrect name, some tag was not closed or there was an excessive closing tag).

STATUS_APPEND_INVALID_ROOT : Unable to append nodes since root type is not NODE_ELEMENT or NODE_DOCUMENT (exclusive to XMLNode.append_buffer()).

STATUS_NO_DOCUMENT_ELEMENT : Parsing resulted in a document without element nodes.

class pugixml.pugi.XMLText¶

Bases: pybind11_object

A helper for working with text inside PCDATA nodes.

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node/>')
>>> node = doc.child('node')
>>> a = node.append_child('a').append_child(pugi.NODE_CDATA)
>>> a.text().set('foo')
>>> b = node.append_child(pugi.NODE_PCDATA)
>>> b.text().set('bar')
>>> c = node.append_child(pugi.NODE_ELEMENT)
>>> c.set_name('c')
>>> c.text().set('baz')
>>> node.print(pugi.PrintWriter(), indent=' ')
<node>
 <a><![CDATA[foo]]></a>bar<c>baz</c>
</node>

__bool__(self: pugixml.pugi.XMLText) → bool¶

Determine if this object is not empty.

Returns:: True if object is not empty, False otherwise.
Return type:: bool

__init__(self: pugixml.pugi.XMLText) → None¶: Initialize XMLText as an empty text.

as_bool(self: pugixml.pugi.XMLText, default: bool = False) → bool¶

Return the contents as a boolean.

Parameters:: default (bool) – The default value.
Returns:: The contents as a boolean (returns True if first character is in ‘1tTyY’ set), or the default value if conversion did not succeed or object is empty.
Return type:: bool

as_double(self: pugixml.pugi.XMLText, default: float = 0) → float¶

Return the contents as a number [DBL_MIN, DBL_MAX].

Parameters:: default (float) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: float

as_float(self: pugixml.pugi.XMLText, default: float = 0) → float¶

Return the contents as a number [FLT_MIN, FLT_MAX].

Parameters:: default (float) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: float

as_int(self: pugixml.pugi.XMLText, default: int = 0) → int¶

Return the contents as a number [INT_MIN, INT_MAX].

Parameters:: default (int) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: int

as_llong(self: pugixml.pugi.XMLText, default: int = 0) → int¶

Return the contents as a number [LLONG_MIN, LLONG_MAX].

Parameters:: default (int) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: int

as_string(self: pugixml.pugi.XMLText, default: str = '') → str¶

Return the contents.

Parameters:: default (str) – The default value.
Returns:: The contents, or the default value if object is empty.
Return type:: str

as_uint(self: pugixml.pugi.XMLText, default: int = 0) → int¶

Return the contents as a number [0, UINT_MAX].

Parameters:: default (int) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: int

as_ullong(self: pugixml.pugi.XMLText, default: int = 0) → int¶

Return the contents as a number [0, ULLONG_MAX].

Parameters:: default (int) – The default value.
Returns:: The contents as a number, or the default value if conversion did not succeed or object is empty.
Return type:: int

data(self: pugixml.pugi.XMLText) → pugixml.pugi.XMLNode¶

Return the data node (NODE_PCDATA or NODE_CDATA) for this object.

Returns:: The data node for this object.
Return type:: XMLNode

empty(self: pugixml.pugi.XMLText) → bool¶

Determine if this object is empty.

Returns:: True if object is empty, False otherwise.
Return type:: bool

get(self: pugixml.pugi.XMLText) → str¶

Return the contents.

Returns:: The contents, or the empty string if object is empty.
Return type:: str

See also

as_string()

set(*args, **kwargs)¶

Overloaded function.

set(self: pugixml.pugi.XMLText, value: str) -> bool

Set the contents.
set(self: pugixml.pugi.XMLText, value: str, size: int) -> bool

Set the contents with the specified length.
set(self: pugixml.pugi.XMLText, value: bool) -> bool

Set the contents as a boolean (True or False).
set(self: pugixml.pugi.XMLText, value: float) -> bool

Set the contents as a number [DBL_MIN, DBL_MAX].
set(self: pugixml.pugi.XMLText, value: float, precision: int) -> bool

Set the contents as a number with the specified precision [DBL_MIN, DBL_MAX].
set(self: pugixml.pugi.XMLText, value: int) -> bool

Set the contents as a number [LLONG_MIN, LLONG_MAX].
set(self: pugixml.pugi.XMLText, value: int) -> bool

Set the contents as a number [0, ULLONG_MAX].

Parameters:

value (Union[str, bool, float, int]) – The contents to set.
size (int) – The length of the contents as a string.
precision (int) – The precision of the contents as a floating point number.

Returns:

False if object is empty or there is not enough memory.

Return type:

XPathQuery, XPathVariable

class pugixml.pugi.XMLTreeWalker¶

Bases: pybind11_object

Abstract tree walker class.

Important

Do not use XMLTreeWalker directly.
You must override any or all of begin(), end(), and for_each() methods in derived class.

See also

XMLNode.traverse()

__init__(self: pugixml.pugi.XMLTreeWalker) → None¶: Initialize XMLTreeWalker.

begin(self: pugixml.pugi.XMLTreeWalker, node: pugixml.pugi.XMLNode) → bool¶

Called by XMLNode.traverse() at the start of traversal.

Parameters:: node (XMLNode) – The node of traversal root.
Returns:: True if the traverse should continue, False otherwise.
Return type:: bool

depth(self: pugixml.pugi.XMLTreeWalker) → int¶

Return the node’s depth.

Returns:: The depth of current node.
Return type:: int

end(self: pugixml.pugi.XMLTreeWalker, node: pugixml.pugi.XMLNode) → bool¶

Called by XMLNode.traverse() at the end of traversal.

Parameters:: node (XMLNode) – The node of traversal root.
Returns:: True if the traverse should continue, False otherwise.
Return type:: bool

for_each(self: pugixml.pugi.XMLTreeWalker, node: pugixml.pugi.XMLNode) → bool¶

Called by XMLNode.traverse() for all nodes in the traversal subtree except the traversal root, in the depth first order.

Parameters:: node (XMLNode) – The current node in the traversal subtree.
Returns:: True if the traverse should continue, False otherwise.
Return type:: bool

class pugixml.pugi.XMLWriter¶

Bases: pybind11_object

Writer interface for node printing.

See documentation for details.

Important

Do not use XMLWriter directly.
You must override write() method in derived class.

__init__(self: pugixml.pugi.XMLWriter) → None¶: Initialize XMLWriter.

write(self: pugixml.pugi.XMLWriter, data: bytes, size: int) → None¶

Write memory chunk into stream/file/whatever.

Parameters:

data (bytes) – The chunk of data to write.
size (int) – The data size in bytes.

class pugixml.pugi.XPathNode¶

Bases: pybind11_object

XPath node class (either XMLNode or XMLAttribute.)

__bool__(self: pugixml.pugi.XPathNode) → bool¶

Determine if this XPath node is not empty.

Returns:: True if XPath node is not empty, False otherwise.
Return type:: bool

__eq__(*args, **kwargs)¶

Overloaded function.

__eq__(self: pugixml.pugi.XPathNode, other: pugixml.pugi.XPathNode) -> bool

Return self == other.
__eq__(self: pugixml.pugi.XPathNode, other: pugixml.pugi.XMLNode) -> bool

Return self == other.

Parameters:: other (Union[XPathNode, XMLNode]) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: pugixml.pugi.XPathNode) -> None

Initialize XPathNode as an empty XPath node.
__init__(self: pugixml.pugi.XPathNode, node: pugixml.pugi.XMLNode) -> None

Initialize XPathNode with the node.
__init__(self: pugixml.pugi.XPathNode, attribute: pugixml.pugi.XMLAttribute, parent: pugixml.pugi.XMLNode) -> None

Initialize XPathNode with the attribute and its parent node.

Parameters:

node (XMLNode) – The node to evaluate over.
attribute (XMLAttribute) – The attribute to evaluate over.
parent (XMLNode) – The parent node of attribute.

__ne__(*args, **kwargs)¶

Overloaded function.

__ne__(self: pugixml.pugi.XPathNode, other: pugixml.pugi.XPathNode) -> bool

Return self != other.
__ne__(self: pugixml.pugi.XPathNode, other: pugixml.pugi.XMLNode) -> bool

Return self != other.

Parameters:: other (Union[XPathNode, XMLNode]) – The node to compare.
Returns:: The result of comparing pointers of internal objects.
Return type:: bool

attribute(self: pugixml.pugi.XPathNode) → pugixml.pugi.XMLAttribute¶

Return the attribute if any.

Returns:: The attribute if any, empty attribute otherwise.
Return type:: XMLAttribute

node(self: pugixml.pugi.XPathNode) → pugixml.pugi.XMLNode¶

Return the node if any.

Returns:: The node if any, empty node otherwise.
Return type:: XMLNode

parent(self: pugixml.pugi.XPathNode) → pugixml.pugi.XMLNode¶

Return the parent node.

Returns:: The parent of node.
Return type:: XMLNode

class pugixml.pugi.XPathNodeSet¶

Bases: pybind11_object

A fixed-size collection of XPath nodes.

TYPE_SORTED = <Type.TYPE_SORTED: 1>¶

TYPE_SORTED_REVERSE = <Type.TYPE_SORTED_REVERSE: 2>¶

TYPE_UNSORTED = <Type.TYPE_UNSORTED: 0>¶

__getitem__(*args, **kwargs)¶

Overloaded function.

__getitem__(self: pugixml.pugi.XPathNodeSet, index: int) -> pugixml.pugi.XPathNode

Return the XPath node at the specified index from the collection.
__getitem__(self: pugixml.pugi.XPathNodeSet, slice: slice) -> list[pugixml.pugi.XPathNode]

Return a list of XPath nodes at the specified slice from the collection.

Parameters:

index (int) – An index to specify position.
slice (slice) – A slice object to specify range.

Returns:

The XPath node(s) at the specified index/slice from collection.

Return type:

Union[XPathNode, List[XPathNode]]

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: pugixml.pugi.XPathNodeSet) -> None

Initialize XPathNodeSet as an empty collection.
__init__(self: pugixml.pugi.XPathNodeSet, other: pugixml.pugi.XPathNodeSet) -> None

Initialize XPathNodeSet with a copy of the collection.

Parameters:: other (XPathNodeSet) – The collection to copy.

__iter__(self: pugixml.pugi.XPathNodeSet) → Iterator[XPathNode]¶

Return an iterator for this collection of XPath nodes.

Returns:: A new iterator for collection of XPath nodes.
Return type:: Iterator[XPathNode]

__len__(self: pugixml.pugi.XPathNodeSet) → int¶

Return the collection size.

This is equivalent to size().

Returns:: The collection size.
Return type:: int

empty(self: pugixml.pugi.XPathNodeSet) → bool¶

Determine if this collection is empty.

Returns:: True if collection is empty, False otherwise.
Return type:: bool

first(self: pugixml.pugi.XPathNodeSet) → pugixml.pugi.XPathNode¶

Return the first node in the collection by document order.

Returns:: The first node in the collection, or empty node if the collection is empty.
Return type:: XPathNode

size(self: pugixml.pugi.XPathNodeSet) → int¶

Return the collection size.

Returns:: The collection size.
Return type:: int

sort(self: pugixml.pugi.XPathNodeSet, reverse: bool = False) → None¶

Sort the collection in ascending/descending order by document order.

Parameters:: reverse (bool) – If True, sort in descending order.

type(self: pugixml.pugi.XPathNodeSet) → pugixml.pugi.XPathNodeSet.Type¶

Return the collection type.

Returns:: The collection type.
Return type:: XPathNodeSet.Type

class pugixml.pugi.XPathNodeSet.Type¶

Bases: pybind11_object

Collection type.

Members:

TYPE_UNSORTED : Not ordered.

TYPE_SORTED : Sorted by document order (ascending).

TYPE_SORTED_REVERSE : Sorted by document order (descending).

class pugixml.pugi.XPathParseResult¶

Bases: pybind11_object

XPath parsing result.

__bool__(self: pugixml.pugi.XPathParseResult) → bool¶

Determine if the parsing result is not an error (error is None).

Returns:: True if the parsing result is not an error, False otherwise.
Return type:: bool

__init__(self: pugixml.pugi.XPathParseResult) → None¶: Initialize XPathParseResult.

description(self: pugixml.pugi.XPathParseResult) → str¶

Return an error description.

Returns:: An error description.
Return type:: str

property error¶

An error message. (None if no error)

Type:: Optional[str]

property offset¶

The last parsed offset.

Type:: int

class pugixml.pugi.XPathQuery¶

Bases: pybind11_object

A compiled XPath expression object.

Examples

>>> from pugixml import pugi
>>> doc = pugi.XMLDocument()
>>> doc.load_string('<node attr="3"/>')
>>> q = pugi.XPathQuery('node/@attr')
>>> q.evaluate_boolean(doc)
True
>>> q.evaluate_number(doc)
3.0
>>> q.evaluate_string(doc)
'3'
>>> n = q.evaluate_node(doc)
>>> bool(n)
True
>>> n.attribute().name()
'attr'
>>> ns = q.evaluate_node_set(doc)
>>> bool(ns)
True
>>> ns.size()
1
>>> ns[0].attribute().name()
'attr'

__bool__(self: pugixml.pugi.XPathQuery) → bool¶

Determine if this XPath expression is valid.

Returns:: True if XPath expression is valid, False otherwise.
Return type:: bool

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: pugixml.pugi.XPathQuery, query: str, variables: pugixml.pugi.XPathVariableSet = None) -> None

Initialize XPathQuery with the XPath expression and variables.
__init__(self: pugixml.pugi.XPathQuery) -> None

Initialize XPathQuery as an invalid expression.

Parameters:

query (str) – The XPath expression.
variables (Optional[XPathVariableSet]) – The variables in query.

evaluate_boolean(*args, **kwargs)¶

Overloaded function.

evaluate_boolean(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XPathNode) -> bool

Evaluate the expression as a boolean value in the specified context; performs type conversion if necessary.
evaluate_boolean(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XMLNode) -> bool

Evaluate the expression as a boolean value in the specified context; performs type conversion if necessary.

Parameters:: node (Union[XPathNode, XMLNode]) – The node to evaluate over.
Returns:: The value evaluated as a boolean, or False if error occurs.
Return type:: bool

evaluate_node(*args, **kwargs)¶

Overloaded function.

evaluate_node(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XPathNode) -> pugixml.pugi.XPathNode

Evaluate the expression as a node set in the specified context; performs type conversion if necessary.
evaluate_node(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XPathNode

Evaluate the expression as a node set in the specified context; performs type conversion if necessary.

Parameters:: node (Union[XPathNode, XMLNode]) – The node to evaluate over.
Returns:: The first node evaluated as a node set, or empty node if error occurs.
Return type:: XPathNode

See also

XMLNode.select_node()

evaluate_node_set(*args, **kwargs)¶

Overloaded function.

evaluate_node_set(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XPathNode) -> pugixml.pugi.XPathNodeSet

Evaluate the expression as a node set in the specified context; performs type conversion if necessary.
evaluate_node_set(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XMLNode) -> pugixml.pugi.XPathNodeSet

Evaluate the expression as a node set in the specified context; performs type conversion if necessary.

Parameters:: node (Union[XPathNode, XMLNode]) – The node to evaluate over.
Returns:: The value evaluated as a node set, or empty node set if error occurs.
Return type:: XPathNodeSet

See also

XMLNode.select_nodes()

evaluate_number(*args, **kwargs)¶

Overloaded function.

evaluate_number(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XPathNode) -> float

Evaluate the expression as a number in the specified context; performs type conversion if necessary.
evaluate_number(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XMLNode) -> float

Evaluate the expression as a number in the specified context; performs type conversion if necessary.

Parameters:: node (Union[XPathNode, XMLNode]) – The node to evaluate over.
Returns:: The value evaluated as a number, or float('nan') if error occurs.
Return type:: float

evaluate_string(*args, **kwargs)¶

Overloaded function.

evaluate_string(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XPathNode) -> str

Evaluate the expression as a string in the specified context; performs type conversion if necessary.
evaluate_string(self: pugixml.pugi.XPathQuery, node: pugixml.pugi.XMLNode) -> str

Evaluate the expression as a string in the specified context; performs type conversion if necessary.

Parameters:: node (Union[XPathNode, XMLNode]) – The node to evaluate over.
Returns:: The value evaluated as a string, or the empty string if error occurs.
Return type:: str

result(self: pugixml.pugi.XPathQuery) → pugixml.pugi.XPathParseResult¶

Return the parsing result.

Returns:: The parsing result.
Return type:: XPathParseResult

return_type(self: pugixml.pugi.XPathQuery) → pugixml.pugi.XPathValueType¶

Return the return type of the XPath expression.

Returns:: The return type of the XPath expression.
Return type:: XPathValueType

class pugixml.pugi.XPathValueType¶

Bases: pybind11_object

XPath query return type.

Members:

XPATH_TYPE_NONE : Unknown type (query failed to compile).

XPATH_TYPE_NODE_SET : Node set (XPathNodeSet).

XPATH_TYPE_NUMBER : Number.

XPATH_TYPE_STRING : String.

XPATH_TYPE_BOOLEAN : Boolean.

class pugixml.pugi.XPathVariable¶

Bases: pybind11_object

A single XPath variable.

See also

XPathVariableSet

get_boolean(self: pugixml.pugi.XPathVariable) → bool¶

Return the variable value without type conversion.

Returns:: The variable value, or False if variable type does not match.
Return type:: bool

get_node_set(self: pugixml.pugi.XPathVariable) → pugixml.pugi.XPathNodeSet¶

Return the variable value without type conversion.

Returns:: The variable value, or empty node set if variable type does not match.
Return type:: XPathNodeSet

get_number(self: pugixml.pugi.XPathVariable) → float¶

Return the variable value without type conversion.

Returns:: The variable value, or float('nan') if variable type does not match.
Return type:: float

get_string(self: pugixml.pugi.XPathVariable) → str¶

Return the variable value without type conversion.

Returns:: The variable value, or the empty string if variable type does not match.
Return type:: str

name(self: pugixml.pugi.XPathVariable) → str¶

Return the variable name.

Returns:: The variable name.
Return type:: str

set(*args, **kwargs)¶

Overloaded function.

set(self: pugixml.pugi.XPathVariable, value: float) -> bool

Set the variable value as a number [DBL_MIN, DBL_MAX].
set(self: pugixml.pugi.XPathVariable, value: bool) -> bool

Set the variable value as a boolean.
set(self: pugixml.pugi.XPathVariable, value: str) -> bool

Set the variable value as a string.
set(self: pugixml.pugi.XPathVariable, value: pugixml.pugi.XPathNodeSet) -> bool

Set the variable value as the XPath node set.

Parameters:: value (Union[float, bool, str, XPathNodeSet]) – The variable value to set.
Returns:: False if variable type does not match or there is not enough memory.
Return type:: bool

type(self: pugixml.pugi.XPathVariable) → pugixml.pugi.XPathValueType¶

Return the variable type.

Returns:: The variable type.
Return type:: XPathValueType

class pugixml.pugi.XPathVariableSet¶

Bases: pybind11_object

A set of XPath variables.

See also

__init__(self: pugixml.pugi.XPathVariableSet) → None¶: Initialize XPathVariableSet.

add(self: pugixml.pugi.XPathVariableSet, name: str, value_type: pugixml.pugi.XPathValueType) → Optional[pugixml.pugi.XPathVariable]¶

Add a new variable and return it, or return the existing one if the types match.

Parameters:

name (str) – The variable name to add/get.
value_type (XPathValueType) – The variable type to add/get.

Returns:

The variable added or the existing one if the types matches, or None if not exists or there is not enough memory.

Return type:

Optional[XPathVariable]

get(self: pugixml.pugi.XPathVariableSet, name: str) → Optional[pugixml.pugi.XPathVariable]¶

Return the existing variable with the specified name.

Parameters:: name (str) – The variable name to get.
Returns:: The variable if exists, None otherwise.
Return type:: Optional[XPathVariable]

set(*args, **kwargs)¶

Overloaded function.

set(self: pugixml.pugi.XPathVariableSet, name: str, value: float) -> bool

Set the value of an existing variable as a number [DBL_MIN, DBL_MAX].
set(self: pugixml.pugi.XPathVariableSet, name: str, value: bool) -> bool

Set the value of an existing variable as a boolean.
set(self: pugixml.pugi.XPathVariableSet, name: str, value: str) -> bool

Set the value of an existing variable as a string.
set(self: pugixml.pugi.XPathVariableSet, name: str, value: pugixml.pugi.XPathNodeSet) -> bool

Set the value of an existing variable as the XPath node set.

No type conversion is performed.

This is equivalent to add(name, value_type).set(value).

Parameters:

name (str) – The variable name to set.
value (Union[float, bool, str, XPathNodeSet]) – The variable value to set.

Returns:

False if there is no such variable or if types mismatch.

Return type: