pugixml.pugi.XMLNode

class pugixml.pugi.XMLNode

Bases: pybind11_object

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

Methods

`__bool__`(self)	Determine if this node is not empty.
`__eq__`(self, other)	Return self == other.
`__ge__`(self, other)	Return self >= other.
`__gt__`(self, other)	Return self > other.
`__hash__`(self)	Return the hash value (unique for handles to the same object).
`__init__`(args, *kwargs)	Overloaded function.
`__le__`(self, other)	Return self <= other.
`__lt__`(self, other)	Return self < other.
`__ne__`(self, other)	Return self != other.
`append_attribute`(self, name)	Add a new attribute with the specified name to the end of the list of attributes for this node.
`append_buffer`(self, contents, size[, ...])	Parse buffer as a fragment of the XML document and append all nodes as children of the current node.
`append_child`(args, *kwargs)	Overloaded function.
`append_copy`(args, *kwargs)	Overloaded function.
`append_move`(self, moved)	Move the specified node as the last child of this node.
`attribute`(args, *kwargs)	Overloaded function.
`attributes`(self)	Return an iterator of attributes for this node.
`child`(self, name)	Return a child node with the specified name.
`child_value`(args, *kwargs)	Overloaded function.
`children`(args, *kwargs)	Overloaded function.
`empty`(self)	Determine if this node is empty.
`ensure_attribute`(self, name)	Return the attribute with the specified name.
`ensure_child`(self, name)	Return the child node with the specified name.
`find_attribute`(self, pred)	Find the attribute using predicate.
`find_child`(self, pred)	Find the child node using predicate.
`find_child_by_attribute`(args, *kwargs)	Overloaded function.
`find_node`(self, pred)	Find the node from subtree using predicate.
`first_attribute`(self)	Return the first attribute in the list of attributes for this node.
`first_child`(self)	Return the first child node.
`first_element_by_path`(self, path[, delimiter])	Search for the node from the path consisting of the node name and "." or "..".
`hash_value`(self)	Return the hash value (unique for handles to the same object).
`insert_attribute_after`(self, name, attr)	Insert a new attribute with the specified name after attr in the list of attributes for this node.
`insert_attribute_before`(self, name, attr)	Insert a new attribute with the specified name before attr in the list of attributes for this node.
`insert_child_after`(args, *kwargs)	Overloaded function.
`insert_child_before`(args, *kwargs)	Overloaded function.
`insert_copy_after`(args, *kwargs)	Overloaded function.
`insert_copy_before`(args, *kwargs)	Overloaded function.
`insert_move_after`(self, moved, node)	Move the specified node after node in the list of child nodes.
`insert_move_before`(self, moved, node)	Move the specified node before node in the list of child nodes.
`internal_object`(self)	Return the internal object.
`last_attribute`(self)	Return the last attribute in the list of attributes for this node.
`last_child`(self)	Return the last child node.
`name`(self)	Return the node name.
`next_sibling`(args, *kwargs)	Overloaded function.
`offset_debug`(self)	Return the node offset in the parsed file or string for debugging purposes.
`parent`(self)	Return the parent node.
`path`(self[, delimiter])	Return the absolute node path from the root as a text string.
`prepend_attribute`(self, name)	Add a new attribute with the specified name to the top of the list of attributes for this node.
`prepend_child`(args, *kwargs)	Overloaded function.
`prepend_copy`(args, *kwargs)	Overloaded function.
`prepend_move`(self, moved)	Move the specified node as the first child of this node.
`previous_sibling`(args, *kwargs)	Overloaded function.
`print`(self, writer[, indent, flags, ...])	Save a single subtree to writer.
`remove_attribute`(args, *kwargs)	Overloaded function.
`remove_attributes`(self)	Remove all attributes from the node.
`remove_child`(args, *kwargs)	Overloaded function.
`remove_children`(self)	Remove all child nodes of the node.
`root`(self)	Return the root of the DOM tree this node belongs to.
`select_node`(args, *kwargs)	Overloaded function.
`select_nodes`(args, *kwargs)	Overloaded function.
`set_name`(args, *kwargs)	Overloaded function.
`set_value`(args, *kwargs)	Overloaded function.
`text`(self)	Return the text object for the current node.
`traverse`(self, walker)	Traverse subtree recursively with `XMLTreeWalker`.
`type`(self)	Return the node type.
`value`(self)	Return the node value.

Member Documentation

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

Determine if this node is not empty.

Returns:: True if this node is not empty, False otherwise.

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

Return self == other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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

Return self >= other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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

Return self > other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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

__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 – The internal object of the node to shallow copy.

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

Return self <= other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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

Return self < other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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

Return self != other.

Parameters:: other – The node to compare.
Returns:: True if the result of comparing the internal objects is true, False otherwise.

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 – The attribute name to add.
Returns:: The attribute added, or an empty attribute if an error occurs.

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

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

Parameters:

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

Returns:

The result of the operation.

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 child nodes.
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 child nodes.

Parameters:

node_type – The node type to add.
name – The node name to add.

Returns:

The node added, or an empty node if an error occurs.

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 child nodes.

Parameters:: proto – The attribute or node to add after copying.
Returns:: The attribute/node added, or an empty attribute/node if an error occurs.

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 – The node to move.
Returns:: The node moved, or an empty node if an error occurs.

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 – The attribute name to find.
hint – 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 an empty attribute if nothing exists.

See also

ensure_attribute()

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.

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

Return a child node with the specified name.

Parameters:: name – The node name to find.
Returns:: The first node found, or an empty node if nothing exists.

See also

ensure_child()

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 – The node name to find.
Returns:: The value of the child node, or an empty string if nothing exists.

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 for child nodes.
children(self: pugixml.pugi.XMLNode, name: str) -> pugixml.pugi.XMLNamedNodeIterator

Return an iterator for child nodes with the specified name.

Parameters:: name – The node name to find.
Returns:: A new iterator for child nodes.

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

Determine if this node is empty.

Returns:: True if the node is empty, False otherwise.

ensure_attribute(self: pugixml.pugi.XMLNode, name: str) → pugixml.pugi.XMLAttribute

Return the attribute with the specified name.

If the attribute with the specified name does not exist, it will be added.

Parameters:: name – The name of the attribute.
Returns:: The attribute with the specified name, or an empty attribute if an error occurs.

See also

attribute()

ensure_child(self: pugixml.pugi.XMLNode, name: str) → pugixml.pugi.XMLNode

Return the child node with the specified name.

If the child node with the specified name does not exist, it will be added as an element.

Parameters:: name – The name of the child node.
Returns:: The child node with the specified name, or an empty node if an error occurs.

See also

child()

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

Find the attribute using predicate.

Parameters:: pred – The function to find attribute.
Returns:: The first attribute for which predicate returned True.

See also

find_child() find_node()

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: collections.abc.Callable[[pugixml.pugi.XMLNode], bool]) → pugixml.pugi.XMLNode

Find the child node using predicate.

Parameters:: pred – The function to find child node.
Returns:: The first child for which predicate returned True.

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 – The node name to find.
attr_name – The attribute name to find.
attr_value – The attribute value to find.

Returns:

The first child found, or an empty node if nothing exists.

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

Find the node from subtree using predicate.

Parameters:: pred – The function to find node from subtree.
Returns:: The first node from subtree (depth-first), for which predicate returned True.

See also

find_attribute() find_child()

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 an empty attribute if nothing exists.

See also

last_attribute()

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

Return the first child node.

Returns:: The first child node, or an empty node if nothing exists.

See also

last_child()

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

Search for the node from the path consisting of the node name and “.” or “..”.

Parameters:

path – The path to search for the node.
delimiter – The path separator.

Returns:

The first node found, or an empty node if nothing exists.

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.

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 – The attribute name to insert.
attr – The attribute in the attribute list for this node.

Returns:

The attribute inserted, or an empty attribute if an error occurs.

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 – The attribute name to insert.
attr – The attribute in the attribute list for this node.

Returns:

The attribute inserted, or an empty attribute if an error occurs.

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 child nodes.
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 child nodes.

Parameters:

node_type – The node type to insert.
name – The node name to insert.
node – The node in the child list.

Returns:

The node inserted, or an empty node if an error occurs.

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 child nodes.
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 child nodes.

Parameters:

node_type – The node type to insert.
name – The node name to insert.
node – The node in the child list.

Returns:

The node inserted, or an empty node if an error occurs.

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 child nodes.

Parameters:

proto – The attribute or node to insert after copying.
attr – The attribute in the attribute list of this node.
node – The node in the child list.

Returns:

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

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 child nodes.

Parameters:

proto – The attribute or node to insert after copying.
attr – The attribute in the attribute list of this node.
node – The node in the child list.

Returns:

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

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 child nodes.

Parameters:

moved – The node to move.
node – The node in the child list.

Returns:

The node moved, or an empty node if an error occurs.

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 child nodes.

Parameters:

moved – The node to move.
node – The node in the child list.

Returns:

The node moved, or an empty node if an error occurs.

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

Return the internal object.

Returns:: The internal object of this node.

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 an empty attribute if nothing exists.

See also

first_attribute()

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

Return the last child node.

Returns:: The last child node, or an empty node if nothing exists.

See also

first_child()

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

Return the node name.

Returns:: The node name, or an empty string if the node is empty or has no name.

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 – The name of the target node.
Returns:: The node found, or an empty node if nothing exists.

See also

previous_sibling()

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

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

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

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

Return the parent node.

Returns:: The parent node, or an empty node if nothing exists.

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

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

Parameters:: delimiter – The path separator.
Returns:: A path string.

See also

first_element_by_path()

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 – The attribute name to add.
Returns:: The attribute added, or an empty attribute if an error occurs.

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 child nodes.
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 child nodes.

Parameters:

node_type – The node type to add.
name – The node name to add.

Returns:

The node added, or an empty node if an error occurs.

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 child nodes.

Parameters:: proto – The attribute or node to add after copying.
Returns:: The attribute/node added, or an empty attribute/node if an error occurs.

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 – The node to move.
Returns:: The node moved, or an empty node if an error occurs.

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 – The name of the target node.
Returns:: The node found, or an empty node if nothing exists.

See also

next_sibling()

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

Save a single subtree to writer.

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.
depth – The number of node’s depth.

See also

XMLDocument.save() XMLWriter

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 – The attribute to remove.
name – The attribute name to remove.

Returns:

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

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

Remove all attributes from the node.

Returns:: False if the node is empty or there is not enough memory.

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 – The node to remove.
name – The node name to remove.

Returns:

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

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

Remove all child nodes of the node.

Returns:: False if the node is empty or there is not enough memory.

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

Return the root of the DOM tree this node belongs to.

Returns:: The root node, or an empty node if nothing exists.

select_node(*args, **kwargs)

Overloaded function.

select_node(self: pugixml.pugi.XMLNode, query: str, variables: pugixml.pugi.XPathVariableSet | None = 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 – The XPath expression.
variables – The variables in query. variables can be None.

Returns:

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

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 = 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 – The XPath expression.
variables – The variables in query. variables can be None

Returns:

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

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: typing.SupportsInt | typing.SupportsIndex) -> bool

Set the node name with the specified length.

Parameters:

name – The node name to set.
size – The length of the node name.

Returns:

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

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: typing.SupportsInt | typing.SupportsIndex) -> bool

Set the node value with the specified length.

Parameters:

value – The node value to set.
size – The length of the value.

Returns:

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

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

Return the text object for the current node.

Returns:: The text object.

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 – The walker object which implements XMLTreeWalker interface.
Returns:: False if XMLTreeWalker.begin(), XMLTreeWalker.end(), or any of the XMLTreeWalker.for_each() returns False.

Examples

>>> from pugixml import pugi
... class PrintWalker(pugi.XMLTreeWalker):
...     def for_each(self, node: pugi.XMLNode) -> bool:
...         print(f'{node.type()!r} depth={self.depth()} name={node.name()!r}')
...         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.

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

Return the node value.

Returns:: The node value, or an empty string if the node is empty or has no value.

Note

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