Nodes & Filters¶

Comment¶

class delb.nodes.CommentNode(content: str)[source]¶

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

This class implements delb.typing.CommentNodeType.

Parameters:: content – The comment’s content a.k.a. text.

Attributes:

`content`	The comment's text.
`depth`	The depth (or level) of the node in its tree.
`document`	The `delb.Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`full_text`	The concatenated contents of all text node descendants in document order.
`index`	The node's index within the parent's collection of child nodes.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to iterate over related node:

`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.

Methods:

`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.
`clone`	Creates a new node of the same type with duplicated contents.
`detach`	Removes the node from its tree.
`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.
`iterate_ancestors`	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.
`replace_with`	Removes the node and places the given one in its tree location.
`serialize`	Returns a string that contains the serialization of the node.
`xpath`	Queries the tree with an XPath expression with this node as initial context node.

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

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 delb.tag() function that are used to derive TextNode respectively TagNode instances from.

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

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) → CommentNode[source]¶

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

Parameters:: deep – Clones the whole subtree if True.
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) → Self¶

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 delb.Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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. When this property is read the currently set default filters are applied. The value None is returned for node without parents and when themself are not matching the filters.

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter, include_descendants: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_descendants – Also yields descendants of the staring node. This deviates from the XPath definition of the following axes.

Returns:

A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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, include_ancestors: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_ancestors – Also yields ancestor nodes / tag nodes that were started earlier in the stream. This deviates from the XPath definition of the preceding axis.

Returns:

A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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 parent: ParentNodeType | None¶

The node’s parent or None.

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

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 delb.tag() function that is used to derive a delb.nodes.TextNode respectively delb.nodes.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: TypeAliasForwardRef('delb.typing.NamespaceDeclarations') | None = None, newline: str | None = None) → str¶

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

Parameters:

format_options – An instance of delb.FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. If not provided the node’s namespace will serve as default namespace. 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: TypeAliasForwardRef('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. If not provided the node’s namespace will serve as default, mapped to an empty prefix.

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.nodes.ProcessingInstructionNode(target: str, content: str)[source]¶

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

This class implements delb.typing.ProcessingInstructionNodeType.

Parameters:

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

Node content properties:

target

The processing instruction's target.

Attributes:

`content`	The processing instruction's text.
`depth`	The depth (or level) of the node in its tree.
`document`	The `delb.Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`full_text`	The concatenated contents of all text node descendants in document order.
`index`	The node's index within the parent's collection of child nodes.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to iterate over related node:

`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.

Methods:

`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.
`clone`	Creates a new node of the same type with duplicated contents.
`detach`	Removes the node from its tree.
`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.
`iterate_ancestors`	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.
`replace_with`	Removes the node and places the given one in its tree location.
`serialize`	Returns a string that contains the serialization of the node.
`xpath`	Queries the tree with an XPath expression with this node as initial context node.

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType'), ...]¶

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) → ProcessingInstructionNode[source]¶

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

Parameters:: deep – Clones the whole subtree if True.
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) → Self¶

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 delb.Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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¶

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter, include_descendants: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_descendants – Also yields descendants of the staring node. This deviates from the XPath definition of the following axes.

Returns:

A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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, include_ancestors: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_ancestors – Also yields ancestor nodes / tag nodes that were started earlier in the stream. This deviates from the XPath definition of the preceding axis.

Returns:

A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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 parent: ParentNodeType | None¶

The node’s parent or None.

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

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: TypeAliasForwardRef('delb.typing.NamespaceDeclarations') | None = None, newline: str | None = None) → str¶

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

Parameters:

format_options – An instance of delb.FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. If not provided the node’s namespace will serve as default namespace. 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: TypeAliasForwardRef('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. If not provided the node’s namespace will serve as default, mapped to an empty prefix.

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.nodes.TagNode(local_name: str, attributes: _AttributesData | dict[AttributeAccessor, str] | TagAttributes | None = None, namespace: str | None = None, children: Iterable[NodeSource] = ())[source]¶

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

This class implements delb.typing.TagNodeType.

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.

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:

namespace

The node's namespace.

Node content properties:

attributes

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

Attributes:

`depth`	The depth (or level) of the node in its tree.
`document`	The `delb.Document` instance that the node is associated with or `None`.
`first_child`	The node's first child node.
`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.
`index`	The node's index within the parent's collection of child nodes.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`local_name`	The node's name.
`location_path`	An unambiguous XPath location path that points to this node from its tree root.
`parent`	The node's parent or `None`.
`universal_name`	The node's qualified name in Clark notation.

Methods to query the tree:

css_select

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

Methods:

`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.
`clone`	Creates a new node of the same type with duplicated contents.
`detach`	Removes the node from its tree.
`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_or_create_by_xpath`	Fetches a single node that is locatable by the provided XPath expression.
`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.
`insert_children`	Inserts one or more child nodes.
`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.
`merge_text_nodes`	Merges all consecutive text nodes in the subtree into one.
`parse`	This method has been replaced by `delb.parse_tree()`.
`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.
`replace_with`	Removes the node and places the given one in its tree location.
`serialize`	Returns a string that contains the serialization of the node.
`xpath`	Queries the tree with an XPath expression with this node as initial context node.

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType'), ...][source]¶

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[TypeAliasForwardRef('delb.typing.XMLNodeType'), ...]¶

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 = TagNode("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 = {"": "http://namespace"}
>>> node = TagNode(
...     "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 = TagNode("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) → delb.typing.TagNodeType[source]¶

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

Parameters:: deep – Clones the whole subtree if True.
Returns:: A copy of the node.

css_select(expression: str, namespaces: TypeAliasForwardRef('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 not provided the node’s namespace will serve as default, mapped to an empty prefix.

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) → Self[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 delb.Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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: TypeAliasForwardRef('delb.typing.NamespaceDeclarations') | None = None) → delb.typing.TagNodeType[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 – A mapping of prefixes that are used in the expression to namespaces. If not provided the node’s namespace will serve as default, mapped to an empty prefix.

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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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: TypeAliasForwardRef('delb.typing.XMLNodeType') | 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¶

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

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[ParentNodeType]¶

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[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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, include_descendants: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_descendants – Also yields descendants of the staring node. This deviates from the XPath definition of the following axes.

Returns:

A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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, include_ancestors: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_ancestors – Also yields ancestor nodes / tag nodes that were started earlier in the stream. This deviates from the XPath definition of the preceding axis.

Returns:

A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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: TypeAliasForwardRef('delb.typing.XMLNodeType') | None¶

The node’s last child node.

property last_descendant: TypeAliasForwardRef('delb.typing.XMLNodeType') | 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(deep: bool = False)¶: Merges all consecutive text nodes in the subtree into one. Text nodes without content are dropped.

property namespace: str¶

The node’s namespace. An empty string represents an empty namespace.

property parent: ParentNodeType | None¶

The node’s parent or None.

static parse(text, parser_options)[source]¶: This method has been replaced by delb.parse_tree().

prepend_children(*node: delb.typing.XMLNodeType, clone: bool = False) → tuple[TypeAliasForwardRef('delb.typing.XMLNodeType'), ...]¶

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) → Self¶

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: TypeAliasForwardRef('delb.typing.NamespaceDeclarations') | None = None, newline: str | None = None) → str[source]¶

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

Parameters:

format_options – An instance of delb.FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. If not provided the node’s namespace will serve as default namespace. 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: TypeAliasForwardRef('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. If not provided the node’s namespace will serve as default, mapped to an empty prefix.

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(qualified_name: delb.typing.QualifiedName, value: str)[source]¶

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

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

property namespace: str¶: 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.nodes.TextNode(text: str | TextNode)[source]¶

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

This class implements delb.typing.TextNodeType.

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.

Attributes:

`content`	The node's text content.
`depth`	The depth (or level) of the node in its tree.
`document`	The `delb.Document` instance that the node is associated with or `None`.
`first_child`	The node's first child.
`full_text`	The concatenated contents of all text node descendants in document order.
`index`	The node's index within the parent's collection of child nodes.
`last_child`	The node's last child node.
`last_descendant`	The node's last descendant.
`parent`	The node's parent or `None`.

Methods to iterate over related node:

`iterate_children`	A generator iterator that yields nothing.
`iterate_descendants`	A generator iterator that yields nothing.

Methods:

`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.
`clone`	Creates a new node of the same type with duplicated contents.
`detach`	Removes the node from its tree.
`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.
`iterate_ancestors`	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.
`replace_with`	Removes the node and places the given one in its tree location.
`serialize`	Returns a string that contains the serialization of the node.
`xpath`	Queries the tree with an XPath expression with this node as initial context node.

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType'), ...]¶

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) → delb.typing.TextNodeType[source]¶

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

Parameters:: deep – Clones the whole subtree if True.
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) → Self¶

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 delb.Document instance that the node is associated with or None.

fetch_following(*filter: delb.typing.Filter) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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) → TypeAliasForwardRef('delb.typing.XMLNodeType') | 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¶

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

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[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_descendants(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

A generator iterator that yields nothing.

iterate_following(*filter: delb.typing.Filter, include_descendants: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_descendants – Also yields descendants of the staring node. This deviates from the XPath definition of the following axes.

Returns:

A generator iterator that yields the following nodes in document order.

iterate_following_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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, include_ancestors: bool = True) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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.
include_ancestors – Also yields ancestor nodes / tag nodes that were started earlier in the stream. This deviates from the XPath definition of the preceding axis.

Returns:

A generator iterator that yields the previous nodes in document order.

iterate_preceding_siblings(*filter: delb.typing.Filter) → Iterator[TypeAliasForwardRef('delb.typing.XMLNodeType')]¶

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 parent: ParentNodeType | None¶

The node’s parent or None.

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

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: TypeAliasForwardRef('delb.typing.NamespaceDeclarations') | None = None, newline: str | None = None) → str¶

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

Parameters:

format_options – An instance of delb.FormatOptions can be provided to configure formatting.
namespaces – A mapping of prefixes to namespaces. If not provided the node’s namespace will serve as default namespace. 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: TypeAliasForwardRef('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. If not provided the node’s namespace will serve as default, mapped to an empty prefix.

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.

Parsing¶

delb.parse_tree(data: delb.typing.InputStream, options: ParserOptions | None = None, *, base_url: str | None = None) → delb.typing.XMLNodeType[source]¶: Parses the provided input to a single node.

delb.parse_nodes(data: InputStream, options: ParserOptions | None = None, *, base_url: str | None = None) → Iterator[XMLNodeType][source]¶: Parses the provided input data to a sequence of nodes.

Filters¶

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

Default filters¶

delb.filters.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 delb.nodes.TagNode.iterate_children(). Mind that they also affect a node’s index property as well as indexed access to child nodes and properties like nodes.delb.TagNode.first_child.

>>> 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.filters.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.filters.is_comment_node(node: delb.typing.XMLNodeType) → bool[source]¶: A node filter that matches delb.typing.CommentNodeType instances.

delb.filters.is_processing_instruction_node(node: delb.typing.XMLNodeType) → bool[source]¶: A node filter that matches delb.typing.ProcessingInstructionNodeType instances.

delb.filters.is_tag_node(node: delb.typing.XMLNodeType) → bool[source]¶: A node filter that matches delb.typing.TagNodeType instances.

delb.filters.is_text_node(node: delb.typing.XMLNodeType) → bool[source]¶: A node filter that matches delb.typing.TextNodeType instances.

delb.filters.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.