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

This version

0.8.2

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.2.tar.gz (13.4 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.2-py3-none-any.whl (14.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: tagz-0.8.2.tar.gz
  • Upload date:
  • Size: 13.4 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.2.tar.gz
Algorithm Hash digest
SHA256 1ad3c47ff296079951eab9a53050bb5874a8d9481150534479d8eafa0a141649
MD5 f30ab4dd9ace08a2ac4faa232ecc5f60
BLAKE2b-256 ff1fc43d6554d98f6a7037aa5f898903259ca42ec3d565e7287794aaa4e506ad

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: tagz-0.8.2-py3-none-any.whl
  • Upload date:
  • Size: 14.8 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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 255ec249863bafee4bca5de2887c154d507770e0c866d2cf04a0715edcec7a5b
MD5 d184cba4245e67fcf64b401bea6f7899
BLAKE2b-256 ae80d9bc0729dea0d5d0eeb23663311a04b767ce792eebce488f5d6cc95238c7

See more details on using hashes here.

Provenance

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