HTML Navigation in Python

Aspose.HTML for Python via .NET represents an HTML document as a Document Object Model (DOM) tree. After loading an HTMLDocument, Python code can move between related nodes, inspect elements, evaluate XPath expressions, or select elements with CSS selectors.

Use direct DOM properties such as first_child and next_sibling when the node position is known. Use evaluate() for XPath expressions and query_selector_all() for matching by tag, class, ID, attribute, or element relationship.

HTML DOM Navigation APIs

The aspose.html.dom module provides the Document, Node, and Element types used to inspect a document tree. These APIs follow the node relationships defined by the WHATWG DOM Standard.

Node properties can return element, text, or comment nodes. Element-specific properties skip non-element nodes.

API	Result
first_child and last_child	The first or last child node, including text and comment nodes
next_sibling and previous_sibling	The adjacent sibling node
child_nodes	All child nodes
first_element_child and last_element_child	The first or last child element
children	Child elements without text or comment nodes
get_element_by_id()	The element with the specified unique ID
get_elements_by_tag_name()	Elements with the specified tag name

For DOM modification methods, attributes, inner_html, and text_content, see Edit HTML Documents in Python.

Navigate the HTML DOM Tree

The first example creates two <span> elements separated by a whitespace text node. It demonstrates that sibling navigation visits the text node as well as the elements.

To navigate adjacent HTML nodes:

1. Load or create an HTMLDocument.
2. Choose a starting node through the document body or another parent node.
3. Use child and sibling properties to move through adjacent DOM nodes.
4. Inspect each returned node and read its content or other required properties.

# Navigate the HTML DOM in Python

import aspose.html as ah

# Define the HTML content
html_code = "<span>Hello,</span> <span>World!</span>"

# Navigate between sibling nodes
with ah.HTMLDocument(html_code, ".") as document:
    element = document.body.first_child
    print(element.text_content)

    element = element.next_sibling
    print(element.text_content)

    element = element.next_sibling
    print(element.text_content)

Inspect HTML Elements

Use element traversal properties when whitespace and other non-element nodes should be skipped. The following example loads html_file.html and follows the element structure defined by the Element Traversal specification.

To inspect HTML elements:

1. Load the source HTML file into an HTMLDocument.
2. Access the root element through document_element.
3. Use element traversal properties to move between parent and child elements.
4. Inspect the tag names, text, or other properties of the selected elements.

# Navigate and inspect an HTML document in Python

import os
import aspose.html as ah

# Prepare the input path
data_dir = "data"
document_path = os.path.join(data_dir, "html_file.html")

# Navigate through the HTML element tree
with ah.HTMLDocument(document_path) as document:
    element = document.document_element
    print(element.tag_name)

    element = element.last_element_child
    print(element.tag_name)

    element = element.first_element_child
    print(element.tag_name)
    print(element.text_content)

Select HTML Nodes with XPath

XPath selects nodes by document structure, attributes, and relationships. Aspose.HTML exposes the DOM XPath workflow through document.evaluate(), which returns an XPathResult of the requested type.

The example evaluates //*[@class='happy']//span, which selects descendant <span> elements under elements whose class attribute is exactly happy.

To select HTML nodes with XPath:

1. Load or create the HTML document that contains the target nodes.
2. Define an XPath expression for the required structure or conditions.
3. Pass the expression and an appropriate context node to evaluate().
4. Request XPathResultType.ANY.
5. Call iterate_next() until every matching node has been processed.
6. Read the text_content of each selected node.

# Select HTML nodes with XPath in Python

import aspose.html as ah
import aspose.html.dom.xpath as hxpath

# Define the HTML content
html_code = """
    <div class='happy'>
        <div>
            <span>Hello,</span>
        </div>
    </div>
    <p class='happy'>
        <span>World!</span>
    </p>
"""

# Select <span> nodes inside elements with the happy class
with ah.HTMLDocument(html_code, ".") as document:
    result = document.evaluate(
        "//*[@class='happy']//span",
        document,
        None,
        hxpath.XPathResultType.ANY,
        None
    )

    node = result.iterate_next()
    while node is not None:
        print(node.text_content)
        node = result.iterate_next()

Select HTML Elements with CSS Selectors

CSS selectors provide concise matching by tag name, class, ID, attribute, and relationship. Use query_selector() to return the first matching element or query_selector_all() to return a NodeList containing every match.

The example uses #catalog article.product[data-status='available'] h2 to select <h2> elements from available products in the catalog. The expression combines an ID selector, an element and class selector, an attribute selector, and descendant relationships.

To select HTML elements with a CSS selector:

1. Load or create the HTML document that contains the target elements.
2. Define a CSS selector for the required tags, classes, attributes, or relationships.
3. Pass the selector to query_selector_all().
4. Iterate through the returned NodeList and process each matching node.

# Select HTML elements using a CSS selector in Python

import aspose.html as ah

# Define the HTML content
html_code = """
<section id="catalog">
    <article class="product" data-status="available">
        <h2>HTML Editor</h2>
    </article>
    <article class="product" data-status="unavailable">
        <h2>PDF Converter</h2>
    </article>
    <article class="product" data-status="available">
        <h2>Image Converter</h2>
    </article>
</section>
"""

# Select headings for available products
selector = "#catalog article.product[data-status='available'] h2"

with ah.HTMLDocument(html_code, ".") as document:
    elements = document.query_selector_all(selector)

    for heading in elements:
        print(heading.text_content)

The selector excludes the unavailable product and produces the following output:

HTML Editor
Image Converter

Choose an HTML Navigation Method

Method	Best suited for
Direct node navigation	Moving between known parents, children, or siblings while preserving text and comment nodes
Element traversal	Moving between elements while skipping whitespace, text, and comment nodes
XPath	Selecting nodes with structural paths, attribute tests, and relationship conditions
CSS selectors	Matching elements with familiar tag, class, ID, attribute, and combinator syntax

Common HTML Navigation Issues

Issue	Cause and recommended action
first_child returns a text node	Whitespace between tags is represented by a DOM text node. Use first_element_child when only an element is required.
XPath returns no nodes	The expression does not match the loaded DOM. Inspect the available elements and attributes, then test a simpler expression.
query_selector_all() returns an empty NodeList	The selector does not match the document or uses the wrong class, ID, attribute, or relationship. Verify the loaded HTML and selector syntax.
Element-specific code receives another node type	Direct node navigation can return text or comment nodes. Check the node type or use element traversal properties.

FAQ

What is the difference between Node and Element navigation?

Node navigation includes element, text, and comment nodes. Element traversal properties return only elements, which is useful when formatting whitespace should not affect the traversal logic.

Should I use XPath or CSS selectors?

Use CSS selectors for familiar matching by tag, class, ID, or attribute. Use XPath when selection depends on document hierarchy, node relationships, or path expressions.

Does query_selector_all() return one element or multiple elements?

query_selector_all() returns a NodeList containing all matching elements. Use query_selector() when only the first matching element is required.

Other Platforms

• HTML Navigation in C# – navigate HTML with DOM properties, XPath, CSS selectors, and filtered traversal in Aspose.HTML for .NET.
• HTML Navigation in Java – traverse nodes and select HTML elements with XPath and CSS selectors in Aspose.HTML for Java.

Related Articles

• Data Extraction in Python – choose a workflow for inspecting HTML or extracting files and resources.
• Extract Links from HTML in Python – collect anchor text and href values from selected parts of the DOM.
• Edit HTML Documents in Python – create, modify, and remove DOM elements, attributes, text, and CSS.
• Save File from URL in Python – download a resource after obtaining its URL from an HTML element.
• Extract Images from Website in Python – locate image elements and save their resources locally.
• Extract SVG from Website in Python – extract inline SVG markup and external SVG files.