Create and Load HTML Documents in Python

The HTMLDocument class represents an HTML document as a Document Object Model (DOM) tree. The document-tree model and HTML document structure are defined by the WHATWG DOM and HTML Living Standard. You can create an empty document or load HTML from a local file, URL, string, or binary stream and then inspect, edit, save, or convert it.

Use HTMLDocument() to create an empty HTML document. To load existing content, pass a file path or URL to a supported constructor. When loading HTML from a string or stream, also provide a base URI so that relative CSS, images, scripts, and links can be resolved correctly.

Create an HTML Document

Aspose.HTML for Python via .NET creates the standard <html>, <head>, and <body> structure for a new HTMLDocument. You can save that structure immediately or add DOM nodes before saving it.

Create an Empty HTML Document

The following example creates an empty document and saves it as output/document-empty.html:

1. Create the output directory and destination path.
2. Initialize HTMLDocument without constructor arguments.
3. Call save() to write the document to an HTML file.

# Create an empty HTML document in Python

import os
import aspose.html as ah

# Prepare the output path
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
save_path = os.path.join(output_dir, "document-empty.html")

# Create and save an empty HTML document
with ah.HTMLDocument() as document:
    # Work with the document here
    document.save(save_path)

The saved file contains an empty HTML document structure. Add elements to the DOM before calling save() when the file should contain page content.

Create HTML Content with the DOM

This example creates a document, adds a Hello, World! text node to its <body>, and saves output/create-new-document.html:

1. Open a new HTMLDocument with a Python context manager.
2. Create a text node with create_text_node().
3. Append the node to document.body.
4. Save the populated document.

# Create an HTML document in Python using the DOM

import os
import aspose.html as ah

# Prepare the output path
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
document_path = os.path.join(output_dir, "create-new-document.html")

# Create an empty HTML document
with ah.HTMLDocument() as document:
    # Create a text node and add it to the document
    text = document.create_text_node("Hello, World!")
    document.body.append_child(text)

    # Save the HTML document
    document.save(document_path)

Continue with Edit an HTML Document for examples that create elements, set attributes, and modify CSS.

Load HTML from Different Sources

Choose the constructor that matches where the HTML content comes from. A file path or URL identifies an external source, while a string or stream supplies the markup directly.

Load HTML from a File

The following example loads data/document.html and saves it to output/document-edited.html:

1. Build the input and output paths.
2. Load the local file with HTMLDocument(document_path).
3. Make any required DOM changes where indicated in the example.
4. Save the document to the output path.

# Load an HTML file in Python

import os
import aspose.html as ah

# Prepare input and output paths
output_dir = "output"
input_dir = "data"
os.makedirs(output_dir, exist_ok=True)

document_path = os.path.join(input_dir, "document.html")
save_path = os.path.join(output_dir, "document-edited.html")

# Load, process, and save the HTML document
with ah.HTMLDocument(document_path) as document:
    # Work with the document here
    document.save(save_path)

The current example does not modify the DOM; it demonstrates the load-and-save workflow. Add editing operations before document.save() when the output must differ from the source.

Load HTML from a URL

HTMLDocument can load a web page directly from an absolute URL. The constructor performs a synchronous load and processes linked resources required by the document.

The example performs these steps:

1. Pass the web-page URL to HTMLDocument.
2. Access the root element through document_element.
3. Print the serialized HTML through outer_html.

# Load HTML from a URL in Python

import aspose.html as ah

# Load the web page and print its HTML
with ah.HTMLDocument("https://docs.aspose.com/html/files/aspose.html") as document:
    print(document.document_element.outer_html)

This example writes the loaded markup to the console; it does not save an output file. If the page cannot be loaded, the constructor raises a loading error, so production code should handle network and resource-loading failures.

Load HTML from a String

Use an HTMLDocument constructor that accepts HTML markup and a base URI when the source already exists in memory. The base URI determines how relative resource URLs are resolved.

The following example:

1. Defines <p>Hello, World!</p> as a Python string.
2. Creates a document from the string and uses . as the base URI.
3. Saves the result as output/create-html-from-string.html.

# Create an HTML document from a string in Python

import os
import aspose.html as ah

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

# Prepare the output path
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
save_path = os.path.join(output_dir, "create-html-from-string.html")

# Create an HTML document from the string and save it
with ah.HTMLDocument(html_code, ".") as document:
    document.save(save_path)

Load HTML from a Stream

Use io.BytesIO when HTML is already available as bytes and should be loaded without first writing a source file to disk.

The stream example:

1. Encodes the HTML markup as a BytesIO stream.
2. Supplies the stream and base URI to HTMLDocument.
3. Saves the loaded document as output/load-from-stream.html.

# Load HTML from a stream in Python

import os
import io
import aspose.html as ah

# Prepare the output path
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)
save_path = os.path.join(output_dir, "load-from-stream.html")

# Define the base URI for relative resources
base_uri = "."

# Load HTML from a memory stream and save it
with io.BytesIO(b"<p>Hello, World!</p>") as content_stream:
    with ah.HTMLDocument(content_stream, base_uri) as document:
        document.save(save_path)

Load an SVG File in Python

Use SVGDocument from the aspose.html.dom.svg module for standalone SVG content. Like HTML, SVG is exposed through a DOM, but SVG-specific classes and methods belong to the SVG API. The SVG 2 specification defines the SVG document model, elements, and rendering behavior.

Load SVG from a File and Access Its DOM

The following example loads the local load-svg.svg file and reads an attribute from its <circle> element. Download the sample and place it in the data directory before running the code.

1. Save the sample SVG as data/load-svg.svg.
2. Pass the SVG file path to the SVGDocument constructor.
3. Find the <circle> element with get_elements_by_tag_name().
4. Read its fill attribute through the SVG DOM.

# Load an SVG file in Python and access its DOM

import aspose.html.dom.svg as ahsvg

# Load the SVG file and access an element through the DOM
with ahsvg.SVGDocument("data/flower.svg") as document:
    circle = document.get_elements_by_tag_name("circle")[0]
    print(circle.get_attribute("fill"))

The code prints #2F80ED, the fill color defined for the circle. The same DOM can be used to inspect elements, change attributes, or save the modified SVG.

Load SVG from a Stream

Use a stream when SVG markup is already available in memory. The existing example:

1. Defines SVG markup containing a circle with a radius of 40 pixels.
2. Encodes the markup and stores it in a BytesIO stream.
3. Creates SVGDocument with the stream and a base URI.
4. Prints the serialized SVG and saves it as load-from-stream.svg.

# Create an SVG document from a string in Python

import io
import aspose.html.dom.svg as ahsvg

# Define the SVG content
svg_content = "<svg xmlns='http://www.w3.org/2000/svg'><circle cx='50' cy='50' r='40'/></svg>"
base_uri = "."

# Create an SVG document from a memory stream
with io.BytesIO(svg_content.encode("utf-8")) as content_stream:
    with ahsvg.SVGDocument(content_stream, base_uri) as document:
        # Print and save the SVG document
        print(document.document_element.outer_html)
        document.save("load-from-stream.svg")

For additional SVG-specific workflows, see the Aspose.SVG for Python via .NET documentation.

Work with MHTML and EPUB Sources

MHTML stores HTML and associated resources in a web archive, while EPUB packages publication content and resources. These formats are supported as conversion sources, but they are not loaded with an HTMLDocument constructor for DOM editing.

• MHTML Converter – convert an MHTML archive to PDF, XPS, DOCX, or raster images.
• EPUB Converter – convert an EPUB publication to PDF, XPS, DOCX, or raster images.

Common Document Loading Issues

Issue	Likely Cause	Recommended Action
Relative images or styles do not load	The string or stream was created without a suitable base URI.	Pass a base URI that relative resource paths can be resolved against.
Loading from a URL fails	The page or one of its required resources is unavailable or blocked by network settings.	Verify the URL and network access, and handle loading errors in application code.
An empty document contains no visible content	HTMLDocument() creates the document structure but does not add page content.	Create and append elements or text nodes before saving.
MHTML or EPUB cannot be edited with HTMLDocument	These formats use source-specific conversion workflows.	Use the MHTML or EPUB converter for the required output format.

Related Articles

• Working with HTML Documents in Python – choose between document creation, editing, and saving workflows.
• Edit an HTML Document in Python – create and modify elements, attributes, text, and CSS.
• Save an HTML Document in Python – save HTML with linked resources or as MHTML and Markdown.
• Converting Between Formats in Python – select a converter for HTML, SVG, MHTML, EPUB, or Markdown input.
• Aspose.HTML for Python via .NET Examples – browse complete examples and supporting data files.