A lightweight, type-safe Python library for building and parsing HTML documents programmatically without templates

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for mosquito from gravatar.com mosquito

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Dmitry Orlov
  • Tags builder , dom , generator , html , markup , parser , streaming , template , type-safe
  • Requires: Python <4, >=3.10
Classifiers
Report project as malware

Project description

tests Coveralls Latest Version python wheel Python Versions license

tagz

A lightweight, type-safe Python library for building and parsing HTML documents programmatically without templates.

📚 Full documentation: https://mosquito.github.io/tagz/

Overview

tagz lets you construct HTML using pure Python code with a clean, intuitive API. No template engines, no DSLs — just Python functions and objects that map directly to HTML elements.

Key Features:

  • Programmatic HTML construction — build documents using Python objects and methods
  • HTML parser — parse existing HTML strings back into manipulable Tag objects
  • Type-safe — full mypy support with comprehensive type annotations
  • Streaming support — memory-efficient rendering with iter_lines(), iter_chunk(), and iter_string()
  • Automatic escaping — XSS protection enabled by default
  • CSS helpers — built-in Style and StyleSheet objects
  • Fragments and raw — group elements without wrapper tags, or splice in pre-rendered HTML
  • Page objects — high-level API for complete HTML documents with DOCTYPE support

Installation

pip install tagz

or with uv:

uv add tagz

Requires Python 3.10+.

Quick start

from tagz import Page, StyleSheet, Style, html


page = Page(
    lang="en",
    body_element=html.body(
        html.h1("Hello"),
        html.div(
            html.strong("world"),
        ),
        html.a(
            "example link",
            html.i("with italic text"),
            href="https://example.com/"
        ),
    ),
    head_elements=(
        html.meta(charset="utf-8"),
        html.meta(name="viewport", content="width=device-width, initial-scale=1"),
        html.title("tagz example page"),
        html.link(href="/static/css/bootstrap.min.css", rel="stylesheet"),
        html.script(src="/static/js/bootstrap.bundle.min.js"),
        html.style(
            StyleSheet({
                "body": Style(padding="0", margin="0"),
                (".container", ".container-fluid"): Style(transition="opacity 600ms ease-in"),
            })
        )
    ),
)

# `pretty=False` is the fast path; pretty=True produces human-readable output.
output = page.to_html5(pretty=True)
assert output.startswith("<!doctype html>")
assert "<strong>" in output

The pretty-printed output looks like:

<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8"/>
		<meta content="width=device-width, initial-scale=1" name="viewport"/>
		<title>
			tagz example page
		</title>
		<link href="/static/css/bootstrap.min.css" rel="stylesheet"/>
		<script src="/static/js/bootstrap.bundle.min.js">
		</script>
		<style>
			body {margin: 0; padding: 0;}
			.container, .container-fluid {transition: opacity 600ms ease-in;}
		</style>
	</head>
	<body>
		<h1>
			Hello
		</h1>
		<div>
			<strong>
				world
			</strong>
		</div>
		<a href="https://example.com/">
			example link
			<i>
				with italic text
			</i>
		</a>
	</body>
</html>

Where to next?

The full documentation is organised in the Diátaxis style:

  • Tutorials — guided lessons that take you from zero to a working page, parser, or streamed document.
  • How-to guides — recipe-style answers to specific problems (streaming, callables, async data, data: URIs, CSV → table, …).
  • Reference — the full API surface with type signatures.
  • Explanation — design rationale: escaping model, callables and laziness, why there's no async render path.

Feature highlights

Feature Read more
Callable children & attributes How-to: lazy children
Conditional attributes via ABSENT How-to: conditional attributes
Boolean attributes (checked, disabled, …) How-to: boolean attributes
Custom / non-standard tag names How-to: custom tags
Fragments and unescaped Raw content How-to: fragments vs raw
Inline style= and <style> blocks How-to: inline & embedded CSS
Streaming to file / socket / ASGI How-to: stream to a socket
data: URIs for inline binary data How-to: embed binary data
Pre-resolving async data How-to: prefetch async data
Serving HTML fragments to htmx (aiohttp) How-to: htmx + aiohttp — full demo in examples/htmx-asyncio
Parsing existing HTML Tutorial: parse and modify

License

MIT — see LICENSE.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for mosquito from gravatar.com mosquito

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Dmitry Orlov
  • Tags builder , dom , generator , html , markup , parser , streaming , template , type-safe
  • Requires: Python <4, >=3.10
Classifiers

Release history Release notifications | RSS feed

0.8.2

0.8.0

This version

0.7.3

0.7.2

0.7.1

0.6.2

0.6.0

0.5.1

0.5.0

0.4.0

0.3.2

0.3.1

0.3.0

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.3

0.1.2

0.1.1

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tagz-0.7.3.tar.gz (12.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tagz-0.7.3-py3-none-any.whl (12.0 kB view details)

Uploaded Python 3

File details

Details for the file tagz-0.7.3.tar.gz.

File metadata

  • Download URL: tagz-0.7.3.tar.gz
  • Upload date:
  • Size: 12.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for tagz-0.7.3.tar.gz
Algorithm Hash digest
SHA256 0fd68f07749869cbc65417fe2ef228e66f97ef995e8e0d97ff705ea7cc0d787b
MD5 89a71534902f6e3b7675fabd9e4c9b55
BLAKE2b-256 772b22399da3b4225529be8138602197f8d6802d987dd4a959982456317ef267

See more details on using hashes here.

Provenance

The following attestation bundles were made for tagz-0.7.3.tar.gz:

Publisher: publish.yml on mosquito/tagz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tagz-0.7.3-py3-none-any.whl.

File metadata

  • Download URL: tagz-0.7.3-py3-none-any.whl
  • Upload date:
  • Size: 12.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for tagz-0.7.3-py3-none-any.whl
Algorithm Hash digest
SHA256 7f37b70dcda7087b775530ba0d4fa02b4c2f726cac3a5771af1816e351a66c62
MD5 a748dc2edd38462bf05bfc663e583cd9
BLAKE2b-256 022b222b3d94a805713dd84be8d8342e6e5b119bb72219fd69ab04d097fce703

See more details on using hashes here.

Provenance

The following attestation bundles were made for tagz-0.7.3-py3-none-any.whl:

Publisher: publish.yml on mosquito/tagz

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page