Queries with XPath & CSS

delb allows querying of nodes with CSS selector and XPath expressions. CSS selectors are converted to XPath expressions with a third-party library before evaluation and they are only supported as far as their computed XPath equivalents are supported by delb’s very own XPath implementation.

This implementation is not fully compliant with one of the W3C’s XPath specifications. It mostly covers the XPath 1.0 specs, but focuses on the querying via path expressions with simple constraints while it omits a broad employment of computations (that’s what programming languages are for) and has therefore these intended deviations from that standard:

• Default namespaces can be addressed in node and attribute names, by simply using no prefix.

• The attribute and namespace axes are not supported in location steps (see also below).

• In predicates only the attribute axis can be used in its abbreviated form (@name).

• Path evaluations within predicates are not available.

• Only these predicate functions are provided and tested:

  • boolean

  • concat

  • contains

  • last

  • not

  • position

  • starts-with

  • text

    • Behaves as if deployed as a single step location path that only tests for the node type text. Hence it returns the contents of the context node’s first child node that is a text node or an empty string when there is none.

  • Please refrain from extension requests without a proper, concrete implementation proposal.

If you’re accustomed to retrieve attribute values with XPath expressions, employ the functionality of the higher programming language at hand like this:

>>> [x.attributes["target"] for x in root.xpath("//foo")
...  if "target" in x.attributes ]  

Instead of:

>>> root.xpath("//foo/@target")  

See _delb.plugins.PluginManager.register_xpath_function() regarding the use of custom functions.

class _delb.xpath.EvaluationContext(node: NodeBase, position: int, size: int, namespaces: Namespaces)

Instances of this class are passed to XPath functions in order to pass contextual information.

namespaces: Namespaces

A mapping of prefixes to namespaces that is used in the whole evaluation.

node: NodeBase

The node that is evaluated.

position: int

The node’s position within all nodes that matched a location step’s node test in order of the step’s axis’ direction. The first position is 1.

size: int

The number of all nodes that matched a location step’s node test.

class _delb.xpath.QueryResults(results: Iterable[delb.NodeBase])

A container with the the results of a CSS selector or XPath query with some helpers for better readable Python expressions.

as_list() → list[delb.NodeBase]

The contained nodes as a new list.

property as_tuple: tuple[delb.NodeBase, ...]

The contained nodes in a tuple.

filtered_by(*filters: delb.typing.Filter) → QueryResults

Returns another QueryResults instance that contains all nodes filtered by the provided filter s.

property first: delb.NodeBase | None

The first node from the results or None if there are none.

in_document_order() → QueryResults

Returns another QueryResults instance where the contained nodes are sorted in document order.

property last: delb.NodeBase | None

The last node from the results or None if there are none.

property size: int

The amount of contained nodes.