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

This version

0.8.0

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.8.0.tar.gz (13.3 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.8.0-py3-none-any.whl (14.7 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for tagz-0.8.0.tar.gz
Algorithm Hash digest
SHA256 70520b1e782cf9b772d62f65cf6dd05c4e45d3baa50fb97df89e2306d98831e0
MD5 953f979fd80478028604e4c462350894
BLAKE2b-256 e9b3633cfa3e3dcc9221c71a8c4d9b9ecba37be91df0e732085538abd01008e5

See more details on using hashes here.

Provenance

The following attestation bundles were made for tagz-0.8.0.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.8.0-py3-none-any.whl.

File metadata

  • Download URL: tagz-0.8.0-py3-none-any.whl
  • Upload date:
  • Size: 14.7 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.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7391641dd6a000155a407941e3850bc1c752663ee1c350ed8642adfe6d0c9679
MD5 dfa801e344b10ff7d0a611c06870aef8
BLAKE2b-256 5fcb08bde8a2cdae46eae28a056a8882a749409719b4925bcdfaec11291b495c

See more details on using hashes here.

Provenance

The following attestation bundles were made for tagz-0.8.0-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