API reference

Generated from docstrings and type-hints. The order matches the source so related classes stay together.

tagz (sync)

tagz - a typed HTML builder.

Sync flavour: html, Page, Tag, Fragment, Raw, Style, StyleSheet, ABSENT, parse, TagParser, data_uri, open_data_uri.

Async streaming lives in tagz.aio - same symbol names, async signatures.

class tagz.AbsentAttribute

Bases: object

Sentinel type for ABSENT.

class tagz.Fragment

Bases: Tag

Wrapper-less container - renders children inline with no surrounding tag.

__init__(*_children, _escaped=True)
Parameters:
name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')

Yield ~``chunk_size`` character chunks for streaming into buffered I/O.

Return type:

Iterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

iter_lines(indent_char='\\t')

Yield pretty-printed HTML line by line (no trailing \n).

Return type:

Iterator[str]

Parameters:

indent_char (str)

iter_string(pretty=False)

Yield rendered HTML as small fragments. For streaming, prefer iter_lines() or iter_chunk().

Return type:

Iterator[str]

Parameters:

pretty (bool)

to_string(pretty=False)

Render to a complete HTML string. pretty=True indents and line-breaks.

Return type:

str

Parameters:

pretty (bool)

class tagz.HTML

Bases: HTMLBase

Sync tag factory. html.div and html["div"] return the same TagInstance subclass.

__init__(defaults)
Parameters:

defaults (Mapping[str, Mapping[str, Any]])

class tagz.HTMLBase

Bases: object

Factory machinery for sync/async HTML. Subclasses bind __tag_fabric__.

__init__(defaults)
Parameters:

defaults (Mapping[str, Mapping[str, Any]])

class tagz.Page

Bases: PageBase

Sync HTML5 document.

body: Tag
head: Tag
html: Tag
to_html5(pretty=False)

Render document including PREAMBLE.

Return type:

str

Parameters:

pretty (bool)

PREAMBLE: str = '<!doctype html>\n'

DOCTYPE emitted before <html>. Override for a non-HTML5 doctype.

__init__(body_element=None, head_elements=(), *args, **kwargs)
Parameters:
class tagz.PageBase

Bases: object

<html>/<head>/<body> composition shared by sync and async Page.

Concrete subclasses must define __html__ (the tag factory) and to_html5 (sync or async).

PREAMBLE: str = '<!doctype html>\n'

DOCTYPE emitted before <html>. Override for a non-HTML5 doctype.

__init__(body_element=None, head_elements=(), *args, **kwargs)
Parameters:
body: TagBase
head: TagBase
html: TagBase
class tagz.Raw

Bases: Fragment

Wrapper-less verbatim content. No escaping - use only with trusted input (XSS risk otherwise).

__init__(content)
Parameters:

content (str)

name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')

Yield ~``chunk_size`` character chunks for streaming into buffered I/O.

Return type:

Iterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

iter_lines(indent_char='\\t')

Yield pretty-printed HTML line by line (no trailing \n).

Return type:

Iterator[str]

Parameters:

indent_char (str)

iter_string(pretty=False)

Yield rendered HTML as small fragments. For streaming, prefer iter_lines() or iter_chunk().

Return type:

Iterator[str]

Parameters:

pretty (bool)

to_string(pretty=False)

Render to a complete HTML string. pretty=True indents and line-breaks.

Return type:

str

Parameters:

pretty (bool)

class tagz.Style

Bases: dict[str, Any]

CSS declaration block. Underscores in keys map to hyphens; declarations are sorted by key.

__init__(*args, **kwargs)
Parameters:
classmethod __new__(*args, **kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values
class tagz.StyleSheet

Bases: dict[str | tuple[str, …], Style]

Selector → Style mapping. Tuple keys render as a comma-separated selector list.

__init__(*args, **kwargs)
classmethod __new__(*args, **kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values
class tagz.Tag

Bases: TagBase

Sync HTML element. Sync sibling of tagz.aio.Tag.

to_string(pretty=False)

Render to a complete HTML string. pretty=True indents and line-breaks.

Return type:

str

Parameters:

pretty (bool)

iter_string(pretty=False)

Yield rendered HTML as small fragments. For streaming, prefer iter_lines() or iter_chunk().

Return type:

Iterator[str]

Parameters:

pretty (bool)

iter_lines(indent_char='\\t')

Yield pretty-printed HTML line by line (no trailing \n).

Return type:

Iterator[str]

Parameters:

indent_char (str)

iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')

Yield ~``chunk_size`` character chunks for streaming into buffered I/O.

Return type:

Iterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
__init__(_tag_name, *_children, classes=(), _void=False, _escaped=True, **attributes)
Parameters:
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
class tagz.TagBase

Bases: object

Data + internal helpers shared by sync and async tags.

The public render API lives on the concrete tagz.Tag (sync) and tagz.aio.Tag (async) - keeping it off the base avoids a Liskov override conflict between sync and async signatures.

__init__(_tag_name, *_children, classes=(), _void=False, _escaped=True, **attributes)
Parameters:
name: str
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
children: list[TagBase | str | Callable[[], TagBase | str]]
property classes: Set[str]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

class tagz.TagInstance

Bases: Tag

Base for factory-produced element classes (html.div → TagDiv).

__init__(*_children, classes=(), **attributes)
Parameters:
name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')

Yield ~``chunk_size`` character chunks for streaming into buffered I/O.

Return type:

Iterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

iter_lines(indent_char='\\t')

Yield pretty-printed HTML line by line (no trailing \n).

Return type:

Iterator[str]

Parameters:

indent_char (str)

iter_string(pretty=False)

Yield rendered HTML as small fragments. For streaming, prefer iter_lines() or iter_chunk().

Return type:

Iterator[str]

Parameters:

pretty (bool)

to_string(pretty=False)

Render to a complete HTML string. pretty=True indents and line-breaks.

Return type:

str

Parameters:

pretty (bool)

class tagz.TagParser

Bases: HTMLParser

Builds Tag objects from HTML strings. Most users should call parse() instead.

__init__()

Initialize and reset this instance.

If convert_charrefs is True (the default), all character references are automatically converted to the corresponding Unicode characters.

Return type:

None

root_elements: list[Tag | str]
stack: list[Tag]
doctype: str | None
handle_starttag(tag, attrs)
Return type:

None

Parameters:
handle_endtag(tag)

Handle closing tag.

Return type:

None

Parameters:

tag (str)

handle_startendtag(tag, attrs)

Handle self-closing/void tag.

Return type:

None

Parameters:
handle_data(data)

Handle text content.

Return type:

None

Parameters:

data (str)

handle_decl(decl)
Return type:

None

Parameters:

decl (str)

get_result()
Return type:

Tag | Fragment | Page

CDATA_CONTENT_ELEMENTS = ('script', 'style')
check_for_whole_start_tag(i)
clear_cdata_mode()
close()

Handle any buffered data.

feed(data)

Feed data to the parser.

Call this as often as you want, with as little or as much text as you want (may include ‘n’).

get_starttag_text()

Return full source of start tag: ‘<…>’.

getpos()

Return current line number and offset.

goahead(end)
handle_charref(name)
handle_comment(data)
handle_entityref(name)
handle_pi(data)
parse_bogus_comment(i, report=1)
parse_comment(i, report=1)
parse_declaration(i)
parse_endtag(i)
parse_html_declaration(i)
parse_marked_section(i, report=1)
parse_pi(i)
parse_starttag(i)
reset()

Reset this instance. Loses all unprocessed data.

set_cdata_mode(elem)
unknown_decl(data)
updatepos(i, j)
tagz.data_uri(data, media_type='application/octet-stream')

Encode bytes as a data: URI.

Return type:

str

Parameters:
tagz.open_data_uri(file_path, media_type=None)

Read a file and encode as a data: URI. media_type is guessed from the extension if omitted.

Return type:

str

Parameters:
tagz.parse(html_string)

Parse HTML. Returns a Tag (single root), Fragment (multiple roots), or Page.

Return type:

Tag | Fragment | Page

Parameters:

html_string (str)

tagz.aio (async)

Mirror of tagz with async render methods. See Async and tagz.

Shared value types (Style, StyleSheet, ABSENT, AbsentAttribute) and sync-only helpers (parse, TagParser, data_uri, open_data_uri) are re-exported as-is — see the tagz section above for their docs.

Async mirror of tagz. Same symbols, async render - change the import line and add await.

Children and attributes may also be coroutines, awaitables, async-def functions, or async iterables. See Async and tagz for the contract.

class tagz.aio.Fragment

Bases: Tag

Async wrapper-less container - children render flat with no surrounding tag.

__init__(*_children, _escaped=True)
Parameters:
name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
async iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

async iter_lines(indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

indent_char (str)

async iter_string(pretty=False)
Return type:

AsyncIterator[str]

Parameters:

pretty (bool)

async to_string(pretty=False)
Return type:

str

Parameters:

pretty (bool)

class tagz.aio.HTML

Bases: HTMLBase

Async tag factory. Sibling of tagz.HTML.

__init__(defaults)
Parameters:

defaults (Mapping[str, Mapping[str, Any]])

class tagz.aio.Page

Bases: PageBase

Async HTML5 document.

body: Tag
head: Tag
html: Tag
async to_html5(pretty=False)
Return type:

str

Parameters:

pretty (bool)

PREAMBLE: str = '<!doctype html>\n'

DOCTYPE emitted before <html>. Override for a non-HTML5 doctype.

__init__(body_element=None, head_elements=(), *args, **kwargs)
Parameters:
class tagz.aio.Raw

Bases: Fragment

Async tagz.Raw - unescaped verbatim content.

__init__(content)
Parameters:

content (str)

name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
async iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

async iter_lines(indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

indent_char (str)

async iter_string(pretty=False)
Return type:

AsyncIterator[str]

Parameters:

pretty (bool)

async to_string(pretty=False)
Return type:

str

Parameters:

pretty (bool)

class tagz.aio.Tag

Bases: TagBase

Async HTML element. Sibling of tagz.Tag; awaits any awaitable, iterates any __aiter__ source.

async to_string(pretty=False)
Return type:

str

Parameters:

pretty (bool)

async iter_string(pretty=False)
Return type:

AsyncIterator[str]

Parameters:

pretty (bool)

async iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

async iter_lines(indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

indent_char (str)

name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
__init__(_tag_name, *_children, classes=(), _void=False, _escaped=True, **attributes)
Parameters:
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
class tagz.aio.TagInstance

Bases: Tag

Async factory base. Sibling of tagz.TagInstance.

__init__(*_children, classes=(), **attributes)
Parameters:
name: str
children: list[TagBase | str | Callable[[], TagBase | str]]
attributes: MutableMapping[str, str | None | Style | Callable[[], str | None | Style | AbsentAttribute]]
append(other)

Append a child. Strings are escaped (unless _escaped=False); callables run at render time.

Return type:

None

Parameters:

other (TagBase | str | Callable[[], TagBase | str])

property classes: Set[str]
async iter_chunk(chunk_size=4096, pretty=False, indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

  • chunk_size (int)

  • pretty (bool)

  • indent_char (str)

async iter_lines(indent_char='\\t')
Return type:

AsyncIterator[str]

Parameters:

indent_char (str)

async iter_string(pretty=False)
Return type:

AsyncIterator[str]

Parameters:

pretty (bool)

async to_string(pretty=False)
Return type:

str

Parameters:

pretty (bool)

tagz.aio.ensure_awaitable(maybe_awaitable)

Coerce a callable, coroutine, or future to an Awaitable.

Sync callables are scheduled via loop.call_soon with a captured contextvars context.

Return type:

Awaitable[TypeVar(R)]

Parameters:

maybe_awaitable (Callable[[...], R] | Future[R] | Coroutine[None, None, R])

tagz.aio.html = <tagz.aio.HTML object>

Async tag factory, sharing tagz.base.HTML_DEFAULTS with the sync factory.