Dominate

2.9.1 · active · verified Sat Apr 11

Dominate is a Python library (current version 2.9.1) for creating and manipulating HTML documents using an elegant DOM API. It allows developers to write HTML pages concisely in pure Python, eliminating the need for a separate template language. The library is actively maintained with a regular release cadence.

Warnings

gotcha Newline characters (`\n`) in Python strings are not automatically converted to HTML `<br>` tags when inserted into Dominate elements. You must explicitly add `<br/>` tags or use `dominate.util.text` if you intend for newlines to be preserved visually in the rendered HTML, or `p` tags for paragraphs.
Fix: Use `dominate.tags.br()` for explicit line breaks or wrap text in appropriate block-level elements like `p()`. For raw text that should not be escaped and contains newlines, consider inserting it with `dominate.util.text()` into a `<pre>` tag or similar.
gotcha When adding attributes to HTML tags, Python keywords (e.g., `class`, `for`) must be escaped with an underscore, like `_class='my-class'` or `_for='my-label'` to avoid syntax errors.
Fix: Prefix Python reserved keywords used as HTML attributes with an underscore (e.g., `_class`, `_for`).
breaking Version 2.9.1 introduced support for `dominate` to work in async contexts. While this is an enhancement, improper use of `dominate` elements or context managers within `async` functions without awaiting where necessary could lead to unexpected behavior or runtime errors in `asyncio` applications.
Fix: When using `dominate` within asynchronous code, ensure that any operations that might block the event loop are handled appropriately. If a `dominate` component is designed to be an `async` context manager or interact with `async` resources, ensure `await` is used correctly with `__aenter__` and `__aexit__` (though `dominate` itself does not inherently require `await` for its core DOM manipulation, new integrations might).
gotcha When reusing tag instances (e.g., creating a tag and then adding content to it multiple times in different contexts), be aware of Dominate's context management. If a tag instance is created outside a `with` block and then used inside multiple `with` blocks, its content might be duplicated or not appear where expected.
Fix: When using `with` statements, each `with` block implicitly adds created elements to the current context. If you intend to build up a single element incrementally, add content directly to its `.add()` method or `+=` operator, or ensure the instance is correctly managed within a single `with` context for its children.

Install

pip install dominate Install stable version

Imports

document
```
from dominate.document import document
```
Used to create a full HTML document structure.
tags
```
from dominate import tags
```
Commonly imported as 'tags' to access HTML elements like tags.html, tags.body, tags.h1, etc.
html
```
from dominate.tags import html, body, h1
```
Direct import of specific tags for convenience.
text
```
from dominate.util import text
```
Useful for inserting raw text that should not be further escaped or parsed as HTML.

Quickstart

This quickstart demonstrates creating a basic HTML document, adding elements to the head and body, nesting elements using `with` statements, and adding attributes including custom data attributes. It also shows how to explicitly add line breaks and handle raw text, highlighting a common 'gotcha' with newlines.

from dominate.document import document
from dominate.tags import html, head, body, h1, p, a, div, br
from dominate.util import text

doc = document(title='My Awesome Page')

with doc.head:
    a(href='https://example.com', _class='link-style', data_info='example') << 'Example Link'

with doc.body:
    h1('Hello, Dominate!')
    p('This is a paragraph created with Python.')
    with div(id='container'):
        p('Another paragraph inside a div.')
        p('Line one.')
        br()
        p('Line two with explicit break.')
        p('Raw text with newline:\n')
        text('This text should appear on a new line after the explicit break.')

# Render the document to an HTML string
html_output = doc.render()
print(html_output)

# Example of rendering with pretty printing off
# print(doc.render(pretty=False))

view raw JSON →