Nodes & Filters¶

Comment¶

class delb.CommentNode(etree_element: _Element)[source]¶

The instances of this class represent comment nodes of a tree.

To instantiate new nodes use new_comment_node().

Node properties:

`depth`	The depth (or level) of the node in its tree.
`index`	The node's index within the parent's collection of child nodes or `None` when the node has no parent.
`namespaces`	The prefix to namespace mapping of the node.

Node content properties:

`content`	The comment's text.
`full_text`	The concatenated contents of all text node descendants in document order.

Related document and nodes properties:

`document`	The `Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to query the tree:

xpath

Queries the tree with an XPath expression with this node as initial context node.

Methods to fetch a relative node:

`fetch_following`	Retrieves the next filter matching node on the following axis.
`fetch_following_sibling`	Retrieves the next filter matching node on the following-sibling axis.
`fetch_preceding`	Retrieves the next filter matching node on the preceding axis.
`fetch_preceding_sibling`	Retrieves the next filter matching node on the preceding-sibling axis.

Methods to iterate over related node:

`iterate_ancestors`	Iterator over the filter matching nodes on the ancestor axis.
`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.
`iterate_following`	Iterator over the filter matching nodes on the following axis.
`iterate_following_siblings`	Iterator over the filter matching nodes on the following-sibling axis.
`iterate_preceding`	Iterator over the filter matching nodes on the preceding axis.
`iterate_preceding_siblings`	Iterator over the filter matching nodes on the preceding-sibling axis.

Methods to add nodes to a tree:

`add_following_siblings`	Adds one or more nodes to the right of the node this method is called on.
`add_preceding_siblings`	Adds one or more nodes to the left of the node this method is called on.

Methods to remove a node:

`detach`	Removes the node from its tree.
`replace_with`	Removes the node and places the given one in its tree location.

Methods:

`clone`	Creates a new node of the same type with duplicated contents.
`new_tag_node`	Creates a new `TagNode` instance in the node's context.
`serialize`	Returns a string that contains the serialization of the node.

add_following_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the right of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

The nodes can be concrete instances of any node type or rather abstract descriptions in the form of strings or objects returned from the tag() function that are used to derive TextNode respectively TagNode instances from.

add_preceding_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the left of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

clone(deep: bool = False, quick_and_unsafe: bool | None = None) → _ElementWrappingNode¶

Creates a new node of the same type with duplicated contents.

Parameters:

deep – Clones the whole subtree if True.
quick_and_unsafe – Deprecated.

Returns:

A copy of the node.

property content: str¶

The comment’s text.

property depth: int¶

The depth (or level) of the node in its tree.

detach(retain_child_nodes: bool = False) → _ElementWrappingNode¶

Removes the node from its tree.

Parameters:: retain_child_nodes – Keeps the node’s descendants in the originating tree if True.
Returns:: The removed node.

property document: Document | None¶

The Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following axis.

Parameters:: filter – Any number of filter s.
Returns:: The next node in document order that matches all filters or None.

fetch_following_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the right that matches all filters or None.

fetch_preceding(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding axis.

Parameters:: filter – Any number of filter s.
Returns:: The previous node in document order that matches all filters or None.

fetch_preceding_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the left that matches all filters or None.

first_child = None¶: The node’s first child.

property full_text: str¶

The concatenated contents of all text node descendants in document order.

property index: int | None¶

The node’s index within the parent’s collection of child nodes or None when the node has no parent.

iterate_ancestors(*filter: delb.typing.Filter) → Iterator[TagNode]¶

Iterator over the filter matching nodes on the ancestor axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the ancestor nodes from bottom to top.

iterate_children(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s right.

iterate_preceding(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s left.

last_child = None¶: The node’s last child node.

last_descendant = None¶: The node’s last descendant.

property namespaces: Namespaces¶

The prefix to namespace mapping of the node.

new_tag_node(local_name: str, attributes: dict[AttributeAccessor, str] | None = None, namespace: str | None = None, children: Sequence[str | NodeBase | _TagDefinition] = ()) → TagNode¶

Creates a new TagNode instance in the node’s context.

Parameters:

local_name – The tag name.
attributes – Optional attributes that are assigned to the new node.
namespace – An optional tag namespace. If none is provided, the context node’s namespace is inherited.
children – An optional sequence of objects that will be appended as child nodes. This can be existing nodes, strings that will be inserted as text nodes and in-place definitions of TagNode instances from tag(). The latter will be assigned to the same namespace.

Returns:

The newly created tag node.

property parent: TagNode | None¶

The node’s parent or None.

replace_with(node: delb.typing.NodeSource, clone: bool = False) → delb.NodeBase¶

Removes the node and places the given one in its tree location.

The node can be a concrete instance of any node type or a rather abstract description in the form of a string or an object returned from the tag() function that is used to derive a TextNode respectively TagNode instance from.

Parameters:

node – The replacing node.
clone – A concrete, replacing node is cloned if True.

Returns:

The removed node.

serialize(*, format_options: FormatOptions | None = None, namespaces: delb.typing.NamespaceDeclarations | None = None, newline: str | None = None)¶

Returns a string that contains the serialization of the node. See Serialization for details.

Parameters:

format_options – An instance of FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. These are overriding possible declarations from a parsed serialisat that the document instance stems from. Prefixes for undeclared namespaces are enumerated with the prefix ns.
newline – See io.TextIOWrapper for a detailed explanation of the parameter with the same name.

xpath(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → QueryResults¶

Queries the tree with an XPath expression with this node as initial context node.

Parameters:

expression – A supported XPath 1.0 expression that contains one or more location paths.
namespaces – A mapping of prefixes that are used in the expression to namespaces. The declarations that were used in a document’s source serialisat serve as fallback.

Returns:

All nodes that match the evaluation of the provided XPath expression.

See Queries with XPath & CSS for details on the extent of the XPath implementation.

Processing instruction¶

class delb.ProcessingInstructionNode(etree_element: _Element)[source]¶

The instances of this class represent processing instruction nodes of a tree.

To instantiate new nodes use new_processing_instruction_node().

Node properties:

`depth`	The depth (or level) of the node in its tree.
`index`	The node's index within the parent's collection of child nodes or `None` when the node has no parent.
`namespaces`	The prefix to namespace mapping of the node.

Node content properties:

`content`	The processing instruction's text.
`full_text`	The concatenated contents of all text node descendants in document order.
`target`	The processing instruction's target.

Related document and nodes properties:

`document`	The `Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to query the tree:

xpath

Queries the tree with an XPath expression with this node as initial context node.

Methods to fetch a relative node:

`fetch_following`	Retrieves the next filter matching node on the following axis.
`fetch_following_sibling`	Retrieves the next filter matching node on the following-sibling axis.
`fetch_preceding`	Retrieves the next filter matching node on the preceding axis.
`fetch_preceding_sibling`	Retrieves the next filter matching node on the preceding-sibling axis.

Methods to iterate over related node:

`iterate_ancestors`	Iterator over the filter matching nodes on the ancestor axis.
`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.
`iterate_following`	Iterator over the filter matching nodes on the following axis.
`iterate_following_siblings`	Iterator over the filter matching nodes on the following-sibling axis.
`iterate_preceding`	Iterator over the filter matching nodes on the preceding axis.
`iterate_preceding_siblings`	Iterator over the filter matching nodes on the preceding-sibling axis.

Methods to add nodes to a tree:

`add_following_siblings`	Adds one or more nodes to the right of the node this method is called on.
`add_preceding_siblings`	Adds one or more nodes to the left of the node this method is called on.

Methods to remove a node:

`detach`	Removes the node from its tree.
`replace_with`	Removes the node and places the given one in its tree location.

Methods:

`clone`	Creates a new node of the same type with duplicated contents.
`new_tag_node`	Creates a new `TagNode` instance in the node's context.
`serialize`	Returns a string that contains the serialization of the node.

add_following_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the right of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

add_preceding_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the left of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

clone(deep: bool = False, quick_and_unsafe: bool | None = None) → _ElementWrappingNode¶

Creates a new node of the same type with duplicated contents.

Parameters:

deep – Clones the whole subtree if True.
quick_and_unsafe – Deprecated.

Returns:

A copy of the node.

property content: str¶

The processing instruction’s text.

property depth: int¶

The depth (or level) of the node in its tree.

detach(retain_child_nodes: bool = False) → _ElementWrappingNode¶

Removes the node from its tree.

Parameters:: retain_child_nodes – Keeps the node’s descendants in the originating tree if True.
Returns:: The removed node.

property document: Document | None¶

The Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following axis.

Parameters:: filter – Any number of filter s.
Returns:: The next node in document order that matches all filters or None.

fetch_following_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the right that matches all filters or None.

fetch_preceding(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding axis.

Parameters:: filter – Any number of filter s.
Returns:: The previous node in document order that matches all filters or None.

fetch_preceding_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the left that matches all filters or None.

first_child = None¶: The node’s first child.

property full_text: str¶

The concatenated contents of all text node descendants in document order.

property index: int | None¶

The node’s index within the parent’s collection of child nodes or None when the node has no parent.

iterate_ancestors(*filter: delb.typing.Filter) → Iterator[TagNode]¶

Iterator over the filter matching nodes on the ancestor axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the ancestor nodes from bottom to top.

iterate_children(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s right.

iterate_preceding(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s left.

last_child = None¶: The node’s last child node.

last_descendant = None¶: The node’s last descendant.

property namespaces: Namespaces¶

The prefix to namespace mapping of the node.

new_tag_node(local_name: str, attributes: dict[AttributeAccessor, str] | None = None, namespace: str | None = None, children: Sequence[str | NodeBase | _TagDefinition] = ()) → TagNode¶

Creates a new TagNode instance in the node’s context.

Parameters:

local_name – The tag name.
attributes – Optional attributes that are assigned to the new node.
namespace – An optional tag namespace. If none is provided, the context node’s namespace is inherited.
children – An optional sequence of objects that will be appended as child nodes. This can be existing nodes, strings that will be inserted as text nodes and in-place definitions of TagNode instances from tag(). The latter will be assigned to the same namespace.

Returns:

The newly created tag node.

property parent: TagNode | None¶

The node’s parent or None.

replace_with(node: delb.typing.NodeSource, clone: bool = False) → delb.NodeBase¶

Removes the node and places the given one in its tree location.

Parameters:

node – The replacing node.
clone – A concrete, replacing node is cloned if True.

Returns:

The removed node.

serialize(*, format_options: FormatOptions | None = None, namespaces: delb.typing.NamespaceDeclarations | None = None, newline: str | None = None)¶

Returns a string that contains the serialization of the node. See Serialization for details.

Parameters:

format_options – An instance of FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. These are overriding possible declarations from a parsed serialisat that the document instance stems from. Prefixes for undeclared namespaces are enumerated with the prefix ns.
newline – See io.TextIOWrapper for a detailed explanation of the parameter with the same name.

property target: str¶

The processing instruction’s target.

xpath(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → QueryResults¶

Queries the tree with an XPath expression with this node as initial context node.

Parameters:

expression – A supported XPath 1.0 expression that contains one or more location paths.
namespaces – A mapping of prefixes that are used in the expression to namespaces. The declarations that were used in a document’s source serialisat serve as fallback.

Returns:

All nodes that match the evaluation of the provided XPath expression.

See Queries with XPath & CSS for details on the extent of the XPath implementation.

Tag¶

class delb.TagNode(etree_element: _Element)[source]¶

The instances of this class represent tag node s of a tree, the equivalent of DOM’s elements.

To instantiate new nodes use Document.new_tag_node, TagNode.new_tag_node, TextNode.new_tag_node or new_tag_node().

Some syntactic sugar is baked in:

Attributes and nodes can be tested for membership in a node.

>>> root = Document('<root ham="spam"><child/></root>').root
>>> "ham" in root
True
>>> root.first_child in root
True

Nodes can be copied. Note that this relies on TagNode.clone().

>>> from copy import copy, deepcopy
>>> root = Document("<root>Content</root>").root
>>> print(copy(root))
<root/>
>>> print(deepcopy(root))
<root>Content</root>

Attribute values and child nodes can be obtained, set and deleted with the subscript notation.

>>> root = Document('<root x="y"><child_1/>child_2<child_3/></root>').root
>>> print(root["x"])
y
>>> print(root[0])
<child_1/>
>>> print(root[-1])
<child_3/>
>>> print([str(x) for x in root[1::-1]])
['child_2', '<child_1/>']

How much child nodes has this node anyway?

>>> root = Document("<root><child_1/><child_2/></root>").root
>>> len(root)
2
>>> len(root[0])
0

As seen in the examples above, a tag nodes string representation yields a serialized XML representation of a sub-/tree. See Serialization for details.

Node properties:

`depth`	The depth (or level) of the node in its tree.
`index`	The node's index within the parent's collection of child nodes or `None` when the node has no parent.
`local_name`	The node's name.
`location_path`	An unambiguous XPath location path that points to this node from its tree root.
`namespace`	The node's namespace.
`namespaces`	The prefix to namespace mapping of the node.
`prefix`	The prefix that the node's namespace is currently mapped to.
`universal_name`	The node's qualified name in Clark notation.

Node content properties:

`attributes`	A mapping that can be used to access the node's attributes.
`full_text`	The concatenated contents of all text node descendants in document order.
`id`	This is a shortcut to retrieve and set the `id` attribute in the XML namespace.

Related document and nodes properties:

`document`	The `Document` instance that the node is associated with or `None`.
`first_child`	The node's first child node.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to query the tree:

`css_select`	Queries the tree with a CSS selector expression with this node as initial context node.
`fetch_or_create_by_xpath`	Fetches a single node that is locatable by the provided XPath expression.
`xpath`	Queries the tree with an XPath expression with this node as initial context node.

Methods to fetch a relative node:

`fetch_following`	Retrieves the next filter matching node on the following axis.
`fetch_following_sibling`	Retrieves the next filter matching node on the following-sibling axis.
`fetch_preceding`	Retrieves the next filter matching node on the preceding axis.
`fetch_preceding_sibling`	Retrieves the next filter matching node on the preceding-sibling axis.

Methods to iterate over related node:

`iterate_ancestors`	Iterator over the filter matching nodes on the ancestor axis.
`iterate_children`	Iterator over the filter matching nodes on the child axis.
`iterate_descendants`	Iterator over the filter matching nodes on the ancestor axis.
`iterate_following`	Iterator over the filter matching nodes on the following axis.
`iterate_following_siblings`	Iterator over the filter matching nodes on the following-sibling axis.
`iterate_preceding`	Iterator over the filter matching nodes on the preceding axis.
`iterate_preceding_siblings`	Iterator over the filter matching nodes on the preceding-sibling axis.

Methods to add nodes to a tree:

`add_following_siblings`	Adds one or more nodes to the right of the node this method is called on.
`add_preceding_siblings`	Adds one or more nodes to the left of the node this method is called on.
`append_children`	Adds one or more nodes as child nodes after any existing to the child nodes of the node this method is called on.
`insert_children`	Inserts one or more child nodes.
`prepend_children`	Adds one or more nodes as child nodes before any existing to the child nodes of the node this method is called on.

Methods to remove a node:

`detach`	Removes the node from its tree.
`replace_with`	Removes the node and places the given one in its tree location.

Methods:

`clone`	Creates a new node of the same type with duplicated contents.
`merge_text_nodes`	Merges all consecutive text nodes in the subtree into one.
`new_tag_node`	Creates a new `TagNode` instance in the node's context.
`parse`	Parses the given string or bytes sequence into a new tree.
`serialize`	Returns a string that contains the serialization of the node.

add_following_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the right of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

add_preceding_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the left of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

append_children(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...][source]¶

Adds one or more nodes as child nodes after any existing to the child nodes of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were appended.

property attributes: TagAttributes¶

A mapping that can be used to access the node’s attributes.

>>> node = new_tag_node("node", attributes={"foo": "0", "bar": "0"})
>>> node.attributes
{'foo': '0', 'bar': '0'}
>>> node.attributes.pop("bar")  
<Attribute(bar="0") [0x...]>
>>> node.attributes["foo"] = "1"
>>> node.attributes["peng"] = "1"
>>> print(node)
<node foo="1" peng="1"/>
>>> node.attributes.update({"foo": "2", "zong": "2"})
>>> print(node)
<node foo="2" peng="1" zong="2"/>

Namespaced names are accessed with two-value tuples or a string. The two-value holds the namespace and the local name in that order. A string can either be a fully qualified name in Clark notation or a local name that belongs to the containing node’s namespace.

>>> DefaultStringOptions.namespaces = {None: "http://namespace"}
>>> node = new_tag_node(
...     "node",
...     namespace="http://namespace",
... )
>>> node.attributes.update({("http://namespace", "foo"): "0"})
>>> print(node)
<node xmlns="http://namespace" foo="0"/>
>>> attribute = node.attributes[("http://namespace", "foo")]
>>> node.attributes["foo"] is attribute
True
>>> node.attributes["{http://namespace}foo"] is attribute
True

Attributes behave like strings, but also expose namespace, local name and value for manipulation.

>>> node = new_tag_node("node")
>>> node.attributes["foo"] = "0"
>>> node.attributes["foo"].local_name = "bar"
>>> node.attributes["bar"].namespace = "http://namespace"
>>> node.attributes[("http://namespace", "bar")].value = "X"
>>> print(node)
<node xmlns:ns0="http://namespace" ns0:bar="X"/>
>>> "ref-" + node.attributes[("http://namespace", "bar")].lower()
'ref-x'

clone(deep: bool = False, quick_and_unsafe: bool | None = None) → TagNode[source]¶

Creates a new node of the same type with duplicated contents.

Parameters:

deep – Clones the whole subtree if True.
quick_and_unsafe – Deprecated.

Returns:

A copy of the node.

css_select(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → QueryResults[source]¶

Queries the tree with a CSS selector expression with this node as initial context node.

Parameters:

expression – A CSS selector expression.
namespaces – A mapping of prefixes that are used in the expression to namespaces. If omitted, the node’s definition is used.

Returns:

All nodes that match the evaluation of the provided CSS selector expression.

See Queries with XPath & CSS regarding the extent of the supported grammar.

Namespace prefixes are delimited with a | before a name test, for example div svg|metadata selects all descendants of div named nodes that belong to the default namespace or have no namespace and whose name is metadata and have a namespace that is mapped to the svg prefix.

property depth: int¶

The depth (or level) of the node in its tree.

detach(retain_child_nodes: bool = False) → _ElementWrappingNode[source]¶

Removes the node from its tree.

Parameters:: retain_child_nodes – Keeps the node’s descendants in the originating tree if True.
Returns:: The removed node.

property document: Document | None¶

The Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following axis.

Parameters:: filter – Any number of filter s.
Returns:: The next node in document order that matches all filters or None.

fetch_following_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the right that matches all filters or None.

fetch_or_create_by_xpath(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → TagNode[source]¶

Fetches a single node that is locatable by the provided XPath expression. If the node doesn’t exist, the non-existing branch will be created.

Parameters:

expression – An XPath expression that can unambiguously locate a descending node in a tree that has any state.
namespaces – An optional mapping of prefixes to namespaces. The declarations that were used in a document’s source serialisat serve as fallback.

Returns:

The existing or freshly created node descibed with expression.

These rules are imperative in your endeavour:

All location steps must use the child axis.
Each step needs to provide a name test.
Attribute comparisons against literals are the only allowed predicates.
Multiple attribute comparisons must be joined with the and operator and / or contained in more than one predicate expression.
The logical validity of multiple attribute comparisons isn’t checked. E.g. one could provide foo[@p="her"][@p="him"], but expect an undefined behaviour.

>>> root = Document("<root/>").root
>>> grandchild = root.fetch_or_create_by_xpath(
...     "child[@a='b']/grandchild"
... )
>>> grandchild is root.fetch_or_create_by_xpath(
...     "child[@a='b']/grandchild"
... )
True
>>> str(root)
'<root><child a="b"><grandchild/></child></root>'

fetch_preceding(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding axis.

Parameters:: filter – Any number of filter s.
Returns:: The previous node in document order that matches all filters or None.

fetch_preceding_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the left that matches all filters or None.

property first_child: delb.NodeBase | None¶

The node’s first child node.

property full_text: str¶

The concatenated contents of all text node descendants in document order.

property id: str | None¶

This is a shortcut to retrieve and set the id attribute in the XML namespace. The client code is responsible to pass properly formed id names.

property index: int | None¶

The node’s index within the parent’s collection of child nodes or None when the node has no parent.

insert_children(index: int, *node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...][source]¶

Inserts one or more child nodes.

Parameters:

index – The index at which the first of the given nodes will be inserted, the remaining nodes are added afterwards in the given order.
node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were inserted.

iterate_ancestors(*filter: delb.typing.Filter) → Iterator[TagNode]¶

Iterator over the filter matching nodes on the ancestor axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the ancestor nodes from bottom to top.

iterate_children(*filter: delb.typing.Filter) → Iterator[delb.NodeBase][source]¶

Iterator over the filter matching nodes on the child axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the child nodes of the node.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[delb.NodeBase][source]¶

Iterator over the filter matching nodes on the ancestor axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the descending nodes of the node.

iterate_following(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s right.

iterate_preceding(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s left.

property last_child: delb.NodeBase | None¶

The node’s last child node.

property last_descendant: delb.NodeBase | None¶

The node’s last descendant.

property local_name: str¶

The node’s name.

property location_path: str¶

An unambiguous XPath location path that points to this node from its tree root.

merge_text_nodes()[source]¶: Merges all consecutive text nodes in the subtree into one. Text nodes without content are dropped.

property namespace: str | None¶

The node’s namespace.

property namespaces: Namespaces¶

The prefix to namespace mapping of the node.

new_tag_node(local_name: str, attributes: dict[AttributeAccessor, str] | None = None, namespace: str | None = None, children: Sequence[str | NodeBase | _TagDefinition] = ()) → TagNode[source]¶

Creates a new TagNode instance in the node’s context.

Parameters:

local_name – The tag name.
attributes – Optional attributes that are assigned to the new node.
namespace – An optional tag namespace. If none is provided, the context node’s namespace is inherited.
children – An optional sequence of objects that will be appended as child nodes. This can be existing nodes, strings that will be inserted as text nodes and in-place definitions of TagNode instances from tag(). The latter will be assigned to the same namespace.

Returns:

The newly created tag node.

property parent: TagNode | None¶

The node’s parent or None.

static parse(text: AnyStr, parser_options: ParserOptions | None = None) → TagNode[source]¶

Parses the given string or bytes sequence into a new tree.

Parameters:

text – A serialized XML tree.
parser_options – A delb.ParserOptions class to configure the used parser.

property prefix: str | None¶

The prefix that the node’s namespace is currently mapped to.

prepend_children(*node: delb.NodeBase, clone: bool = False) → tuple[delb.NodeBase, ...][source]¶

Adds one or more nodes as child nodes before any existing to the child nodes of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were prepended.

replace_with(node: delb.typing.NodeSource, clone: bool = False) → delb.NodeBase¶

Removes the node and places the given one in its tree location.

Parameters:

node – The replacing node.
clone – A concrete, replacing node is cloned if True.

Returns:

The removed node.

serialize(*, format_options: FormatOptions | None = None, namespaces: delb.typing.NamespaceDeclarations | None = None, newline: str | None = None)[source]¶

Returns a string that contains the serialization of the node. See Serialization for details.

Parameters:

format_options – An instance of FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. These are overriding possible declarations from a parsed serialisat that the document instance stems from. Prefixes for undeclared namespaces are enumerated with the prefix ns.
newline – See io.TextIOWrapper for a detailed explanation of the parameter with the same name.

property universal_name: str¶

The node’s qualified name in Clark notation.

xpath(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → QueryResults[source]¶

Queries the tree with an XPath expression with this node as initial context node.

Parameters:

expression – A supported XPath 1.0 expression that contains one or more location paths.
namespaces – A mapping of prefixes that are used in the expression to namespaces. The declarations that were used in a document’s source serialisat serve as fallback.

Returns:

All nodes that match the evaluation of the provided XPath expression.

See Queries with XPath & CSS for details on the extent of the XPath implementation.

Tag attribute¶

class delb.nodes.Attribute(attributes: TagAttributes, qualified_name: tuple[str, str])[source]¶

Attribute objects represent tag node’s attributes. See the delb.TagNode.attributes() documentation for capabilities.

property local_name: str¶: The attribute’s local name.

property namespace: str | None¶: The attribute’s namespace

property universal_name: str¶: The attribute’s namespace and local name in Clark notation.

property value: str¶: The attribute’s value.

Text¶

class delb.TextNode(reference_or_text: _Element | str | TextNode, position: int = 0)[source]¶

TextNodes contain the textual data of a document. The class shall not be initialized by client code, just throw strings into the trees.

Instances expose all methods of str except str.index():

>>> node = TextNode("Show us the way to the next whisky bar.")
>>> node.split()
['Show', 'us', 'the', 'way', 'to', 'the', 'next', 'whisky', 'bar.']

Instances can be tested for inequality with other text nodes and strings:

>>> TextNode("ham") == TextNode("spam")
False
>>> TextNode("Patsy") == "Patsy"
True

And they can be tested for substrings:

>>> "Sir" in TextNode("Sir Bedevere the Wise")
True

Attributes that rely to child nodes yield nothing respectively None.

Node properties:

`depth`	The depth (or level) of the node in its tree.
`index`	The node's index within the parent's collection of child nodes or `None` when the node has no parent.
`namespaces`	The prefix to namespace mapping of the node.

Node content properties:

`content`	The node's text content.
`full_text`	The concatenated contents of all text node descendants in document order.

Related document and nodes properties:

`document`	The `Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to query the tree:

xpath

Queries the tree with an XPath expression with this node as initial context node.

Methods to fetch a relative node:

`fetch_following`	Retrieves the next filter matching node on the following axis.
`fetch_following_sibling`	Retrieves the next filter matching node on the following-sibling axis.
`fetch_preceding`	Retrieves the next filter matching node on the preceding axis.
`fetch_preceding_sibling`	Retrieves the next filter matching node on the preceding-sibling axis.

Methods to iterate over related node:

`iterate_ancestors`	Iterator over the filter matching nodes on the ancestor axis.
`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.
`iterate_following`	Iterator over the filter matching nodes on the following axis.
`iterate_following_siblings`	Iterator over the filter matching nodes on the following-sibling axis.
`iterate_preceding`	Iterator over the filter matching nodes on the preceding axis.
`iterate_preceding_siblings`	Iterator over the filter matching nodes on the preceding-sibling axis.

Methods to add nodes to a tree:

`add_following_siblings`	Adds one or more nodes to the right of the node this method is called on.
`add_preceding_siblings`	Adds one or more nodes to the left of the node this method is called on.

Methods to remove a node:

`detach`	Removes the node from its tree.
`replace_with`	Removes the node and places the given one in its tree location.

Methods:

`clone`	Creates a new node of the same type with duplicated contents.
`new_tag_node`	Creates a new `TagNode` instance in the node's context.
`serialize`	Returns a string that contains the serialization of the node.

add_following_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the right of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

add_preceding_siblings(*node: delb.typing.NodeSource, clone: bool = False) → tuple[delb.NodeBase, ...]¶

Adds one or more nodes to the left of the node this method is called on.

Parameters:

node – The node(s) to be added.
clone – Clones the concrete nodes before adding if True.

Returns:

The concrete nodes that were added.

clone(deep: bool = False, quick_and_unsafe: bool | None = None) → delb.NodeBase[source]¶

Creates a new node of the same type with duplicated contents.

Parameters:

deep – Clones the whole subtree if True.
quick_and_unsafe – Deprecated.

Returns:

A copy of the node.

property content: str¶

The node’s text content.

property depth: int¶

The depth (or level) of the node in its tree.

detach(retain_child_nodes: bool = False) → TextNode[source]¶

Removes the node from its tree.

Parameters:: retain_child_nodes – Keeps the node’s descendants in the originating tree if True.
Returns:: The removed node.

property document: Document | None¶

The Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following axis.

Parameters:: filter – Any number of filter s.
Returns:: The next node in document order that matches all filters or None.

fetch_following_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the following-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the right that matches all filters or None.

fetch_preceding(*filter: delb.typing.Filter) → delb.NodeBase | None¶

Retrieves the next filter matching node on the preceding axis.

Parameters:: filter – Any number of filter s.
Returns:: The previous node in document order that matches all filters or None.

fetch_preceding_sibling(*filter: delb.typing.Filter) → delb.NodeBase | None[source]¶

Retrieves the next filter matching node on the preceding-sibling axis.

Parameters:: filter – Any number of filter s.
Returns:: The next sibling to the left that matches all filters or None.

first_child = None¶: The node’s first child.

property full_text: str¶

The concatenated contents of all text node descendants in document order.

property index: int | None¶

The node’s index within the parent’s collection of child nodes or None when the node has no parent.

iterate_ancestors(*filter: delb.typing.Filter) → Iterator[TagNode]¶

Iterator over the filter matching nodes on the ancestor axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the ancestor nodes from bottom to top.

iterate_children(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the following-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s right.

iterate_preceding(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[delb.NodeBase]¶

Iterator over the filter matching nodes on the preceding-sibling axis.

Parameters:: filter – Any number of filter s that a node must match to be yielded.
Returns:: A generator iterator that yields the siblings to the node’s left.

last_child = None¶: The node’s last child node.

last_descendant = None¶: The node’s last descendant.

property namespaces¶

The prefix to namespace mapping of the node.

new_tag_node(local_name: str, attributes: dict[AttributeAccessor, str] | None = None, namespace: str | None = None, children: Sequence[str | NodeBase | _TagDefinition] = ()) → TagNode¶

Creates a new TagNode instance in the node’s context.

Parameters:

local_name – The tag name.
attributes – Optional attributes that are assigned to the new node.
namespace – An optional tag namespace. If none is provided, the context node’s namespace is inherited.
children – An optional sequence of objects that will be appended as child nodes. This can be existing nodes, strings that will be inserted as text nodes and in-place definitions of TagNode instances from tag(). The latter will be assigned to the same namespace.

Returns:

The newly created tag node.

property parent: TagNode | None¶

The node’s parent or None.

replace_with(node: delb.typing.NodeSource, clone: bool = False) → delb.NodeBase¶

Removes the node and places the given one in its tree location.

Parameters:

node – The replacing node.
clone – A concrete, replacing node is cloned if True.

Returns:

The removed node.

serialize(*, format_options: FormatOptions | None = None, namespaces: delb.typing.NamespaceDeclarations | None = None, newline: str | None = None)¶

Returns a string that contains the serialization of the node. See Serialization for details.

Parameters:

format_options – An instance of FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. These are overriding possible declarations from a parsed serialisat that the document instance stems from. Prefixes for undeclared namespaces are enumerated with the prefix ns.
newline – See io.TextIOWrapper for a detailed explanation of the parameter with the same name.

xpath(expression: str, namespaces: delb.typing.NamespaceDeclarations | None = None) → QueryResults¶

Queries the tree with an XPath expression with this node as initial context node.

Parameters:

expression – A supported XPath 1.0 expression that contains one or more location paths.
namespaces – A mapping of prefixes that are used in the expression to namespaces. The declarations that were used in a document’s source serialisat serve as fallback.

Returns:

All nodes that match the evaluation of the provided XPath expression.

See Queries with XPath & CSS for details on the extent of the XPath implementation.

Node constructors¶

delb.new_comment_node(content: str) → CommentNode[source]¶

Creates a new CommentNode.

Parameters:: content – The comment’s content a.k.a. text.
Returns:: The newly created comment node.

delb.new_processing_instruction_node(target: str, content: str) → ProcessingInstructionNode[source]¶

Creates a new ProcessingInstructionNode.

Parameters:

target – The processing instruction’s target name.
content – The processing instruction’s text.

Returns:

The newly created processing instruction node.

delb.new_tag_node(local_name: str, attributes: dict[AttributeAccessor, str] | TagAttributes | None = None, namespace: str | None = None, children: Iterable[NodeSource] = ()) → TagNode[source]¶

Creates a new TagNode instance outside any context. It is preferable to use the method new_tag_node on instances of documents and nodes where the namespace is inherited.

Parameters:

local_name – The tag name.
attributes – Optional attributes that are assigned to the new node.
namespace – An optional tag namespace.
children – An optional iterable of objects that will be appended as child nodes. This can be existing nodes, strings that will be inserted as text nodes and in-place definitions of TagNode instances from tag(). The latter will be assigned to the same namespace.

Returns:

The newly created tag node.

Filters¶

The following implementations are shipped with the library. Also see delb.typing.Filter

Default filters¶

delb.altered_default_filters(*filter: delb.typing.Filter, extend: bool = False)[source]¶

This function can be either used as as context manager or decorator to define a set of default_filters for the encapsuled code block or callable.

Parameters:

filter – The filters to set or append.
extend – Extends the currently active filters with the given ones instead of replacing them.

These are then applied in all operations that allow node filtering, like TagNode.next_node(). Mind that they also affect a node’s index property and indexed access to child nodes.

>>> root = Document(
...     '<root xmlns="foo"><a/><!--x--><b/><!--y--><c/></root>'
... ).root
>>> with altered_default_filters(is_comment_node):
...     print([x.content for x in root.iterate_children()])
['x', 'y']

As the default filters shadow comments and processing instructions by default, use no argument to unset this in order to access all type of nodes.

Contributed filters¶

delb.any_of(*filter: delb.typing.Filter) → delb.typing.Filter[source]¶: A node filter wrapper that matches when any of the given filters is matching, like a boolean or.

delb.is_comment_node(node: delb.NodeBase) → bool[source]¶: A node filter that matches CommentNode instances.

delb.is_processing_instruction_node(node: delb.NodeBase) → bool[source]¶: A node filter that matches ProcessingInstructionNode instances.

delb.is_tag_node(node: delb.NodeBase) → bool[source]¶: A node filter that matches TagNode instances.

delb.is_text_node(node: delb.NodeBase) → bool[source]¶: A node filter that matches TextNode instances.

delb.not_(*filter: delb.typing.Filter) → delb.typing.Filter[source]¶: A node filter wrapper that matches when the given filter is not matching, like a boolean not.