0
# Dominate
1
2
Dominate is a Python library for creating and manipulating HTML documents using an elegant DOM API. It allows you to write HTML pages in pure Python very concisely, which eliminates the need to learn another template language, and lets you take advantage of the more powerful features of Python.
3
4
## Package Information
5
6
- **Package Name**: dominate
7
- **Language**: Python
8
- **Installation**: `pip install dominate`
9
- **Supported Python Versions**: 3.4+
10
11
## Core Imports
12
13
```python
14
import dominate
15
from dominate.tags import *
16
```
17
18
For specific modules:
19
20
```python
21
from dominate import document
22
from dominate.tags import div, p, a, html_tag
23
from dominate.svg import svg, circle, rect
24
from dominate.util import text, raw, escape
25
from dominate.dom_tag import dom_tag, attr, get_current
26
```
27
28
## Basic Usage
29
30
```python
31
import dominate
32
from dominate.tags import *
33
34
# Create a complete HTML document
35
doc = dominate.document(title='My Website')
36
37
# Add content using context managers
38
with doc.head:
39
link(rel='stylesheet', href='style.css')
40
script(type='text/javascript', src='script.js')
41
42
with doc:
43
with div(id='header'):
44
h1('Welcome to My Site')
45
nav(
46
ul(
47
li(a('Home', href='/')),
48
li(a('About', href='/about')),
49
li(a('Contact', href='/contact'))
50
)
51
)
52
53
with div(cls='content'):
54
p('This is the main content area.')
55
p('Dominate makes HTML generation easy!')
56
57
print(doc)
58
```
59
60
## Architecture
61
62
Dominate follows a hierarchical DOM-like structure:
63
64
- **`dom_tag`**: Base class for all HTML elements providing core functionality
65
- **`html_tag`**: Extends `dom_tag` with HTML-specific features and DOM Level 1 Core API
66
- **`document`**: Complete HTML document container with head, body, and metadata management
67
- **Context Manager Support**: All elements can be used with Python's `with` statement
68
- **Decorator Support**: Elements can be used as decorators for functions
69
- **Threading/Async Safe**: Proper context isolation for concurrent usage
70
71
The library supports both imperative element creation and declarative context-based composition, making it suitable for both simple HTML generation and complex template systems.
72
73
## Capabilities
74
75
### Document Creation
76
77
Complete HTML document management with automatic structure generation, metadata handling, and section organization (header, main, footer).
78
79
```python { .api }
80
class document(html):
81
def __init__(self, title='Dominate', doctype='<!DOCTYPE html>', *args, **kwargs): ...
82
@property
83
def title(self) -> str: ...
84
@title.setter
85
def title(self, value: str): ...
86
def add(self, *args): ...
87
```
88
89
[Document Management](./document.md)
90
91
### HTML Elements
92
93
All HTML5 elements as Python classes with full attribute support, context manager integration, and proper rendering. Includes semantic elements, forms, tables, media, and interactive elements.
94
95
```python { .api }
96
class html_tag(dom_tag):
97
def __init__(self, *args, **kwargs): ...
98
99
# Semantic elements
100
def html(*args, **kwargs): ...
101
def head(*args, **kwargs): ...
102
def body(*args, **kwargs): ...
103
def div(*args, **kwargs): ...
104
def p(*args, **kwargs): ...
105
def a(*args, **kwargs): ...
106
107
# Form elements
108
def form(*args, **kwargs): ...
109
def input_(*args, **kwargs): ...
110
def button(*args, **kwargs): ...
111
def select(*args, **kwargs): ...
112
113
# Table elements
114
def table(*args, **kwargs): ...
115
def tr(*args, **kwargs): ...
116
def td(*args, **kwargs): ...
117
def th(*args, **kwargs): ...
118
```
119
120
[HTML Elements](./html-elements.md)
121
122
### SVG Graphics
123
124
SVG elements for vector graphics creation with automatic attribute name conversion (underscore to dash) and support for shapes, paths, gradients, filters, and animations.
125
126
```python { .api }
127
class svg_tag(html_tag):
128
@staticmethod
129
def clean_attribute(attribute): ...
130
131
def svg(*args, **kwargs): ...
132
def circle(*args, **kwargs): ...
133
def rect(*args, **kwargs): ...
134
def path(*args, **kwargs): ...
135
def g(*args, **kwargs): ...
136
def text(*args, **kwargs): ...
137
def linearGradient(*args, **kwargs): ...
138
def filter(*args, **kwargs): ...
139
```
140
141
[SVG Graphics](./svg.md)
142
143
### DOM Manipulation
144
145
Core DOM tree manipulation with element creation, attribute management, content addition/removal, searching, and rendering with customizable formatting.
146
147
```python { .api }
148
class dom_tag:
149
def __init__(self, *args, **kwargs): ...
150
def add(self, *args): ...
151
def remove(self, obj): ...
152
def clear(self): ...
153
def get(self, tag=None, **kwargs): ...
154
def set_attribute(self, key, value): ...
155
def render(self, indent=' ', pretty=True, xhtml=False): ...
156
def __enter__(self): ...
157
def __exit__(self, type, value, traceback): ...
158
159
def attr(*args, **kwargs): ...
160
def get_current(default=None): ...
161
```
162
163
[DOM Manipulation](./dom-manipulation.md)
164
165
### Utility Functions
166
167
Text processing utilities for HTML escaping, URL encoding, raw HTML insertion, file inclusion, and specialized container elements for advanced layouts.
168
169
```python { .api }
170
def escape(data, quote=True): ...
171
def unescape(data): ...
172
def url_escape(data): ...
173
def url_unescape(data): ...
174
def raw(s): ...
175
def include(f): ...
176
177
class container(dom_tag): ...
178
class text(dom_tag):
179
def __init__(self, _text, escape=True): ...
180
class lazy(dom_tag):
181
def __init__(self, func, *args, **kwargs): ...
182
```
183
184
[Utilities](./utilities.md)
185
186
## Types
187
188
```python { .api }
189
# Base types
190
class dom_tag:
191
is_single: bool # Self-closing tag
192
is_pretty: bool # Pretty print content
193
is_inline: bool # Inline rendering
194
attributes: dict
195
children: list
196
parent: dom_tag | None
197
198
class html_tag(dom_tag): ...
199
200
class document(html_tag):
201
doctype: str
202
head: html_tag
203
body: html_tag
204
title_node: html_tag
205
header: container
206
main: container
207
footer: container
208
209
# Utility types
210
class container(dom_tag): ...
211
class text(dom_tag):
212
escape: bool
213
text: str
214
class lazy(dom_tag):
215
func: callable
216
args: tuple
217
kwargs: dict
218
```