API reference

class hyperscribe.DocWriter(writer: TextIO)

Write escaped HTML fragments to any object with a write(str) method.

tags: _TagBuilder

Tags by name, as in doc.tags.div, or doc.tags["my-element"].

voids: _Voids

Void elements by name, as in doc.voids.br().

property parts: tuple[DocWriter, _TagBuilder, _Voids]

Return the writer, its tags and its void elements, for unpacking.

doc, t, v = DocWriter(output).parts gives short local names.

__call__(value: LiteralString | SafeStr | SupportsHTML | int | float | Template) → None

Write trusted content verbatim, preserving the current indentation.

Strings with non-literal provenance must be passed to escape(). Objects implementing __html__ contribute their trusted HTML string; literal strings and primitive numeric values are also written verbatim. Tag content, as in doc.tags.p(...), is handled the same way.

inline() → AbstractContextManager[None]

Suppress line breaks and indentation for the markup written in the block.

The block is indented and ends its line like any other tag, so with doc.inline(), doc.tags.div: renders the whole div on one line. Blocks may be nested; formatting resumes once the outermost one exits.

tag(name: str, /, **attrs: LiteralString | SafeStr | SupportsHTML | int | float | bool | None | dict[str, AttributeValue] | Template) → _TagBuilder

Return a tag with any name and attributes.

Equivalent to doc.tags[name](**attrs), which should be used instead.

void_tag(name: str, /, **attrs: LiteralString | SafeStr | SupportsHTML | int | float | bool | None | dict[str, AttributeValue] | Template) → None

Write a void element such as <br> or <img> on its own line.

Equivalent to doc.voids[name](**attrs), which should be used instead.

comment(text: str) → None

Write an HTML comment on its own line.

The text is written as given, so it must not be able to end the comment early. A ValueError is raised if it contains --.

write_raw(value: str) → None

Write unescaped text to the document, bypassing the escaping logic.

text(value: object) → None

Write escaped text to the document on its own line.

Values that are not strings are converted with str.

hyperscribe.escape(value: str) → SafeStr

Escape &, <, > and quotes so the text can be written as HTML.

Quotes are escaped as well, so the result is safe in text and in attribute values.

hyperscribe.escape_silent(value: str | None) → SafeStr

Like escape(), but write None as an empty string.

Use it for optional values, such as a field that may be missing in some data, where an empty result is what the page should show.

hyperscribe.trust(value: str) → SafeStr

Mark a string as safe to write as HTML, without escaping it.

Only use it for content that cannot contain untrusted input.

hyperscribe.SafeStr

A string that is safe to write as HTML, returned by escape() and trust().

It only exists for type checkers; at runtime it is a plain str. Attribute values are escaped as usual, whatever their type.

hyperscribe.TrustedContent

Represent a union type

E.g. for int | str

hyperscribe.AttributeValue

Represent a union type

E.g. for int | str

Tag objects

tags is a tag builder, and voids looks up void element builders. They are documented here because they appear in the signatures above, but you normally do not create them yourself.

class hyperscribe._TagBuilder(_doc: DocWriter, _openings: tuple[str, ...], _closings: tuple[str, ...], _children: dict[str, _TagBuilder] | None = None)

Represent a chain of tags, usable directly or with attributes supplied by a call.

Builders are immutable, so they can be cached and nested inside themselves.

__getattr__(name: str) → _TagBuilder

Return a builder for a nested tag, such as main in doc.body.main.

__getitem__(name: str) → _TagBuilder

Return a builder for a nested tag, as in doc.div["x-y"].

__call__(**attrs: LiteralString | SafeStr | SupportsHTML | int | float | bool | None | dict[str, AttributeValue] | Template) → _TagBuilder

__call__(content: LiteralString | SafeStr | SupportsHTML | int | float | Template, /, **attrs: LiteralString | SafeStr | SupportsHTML | int | float | bool | None | dict[str, AttributeValue] | Template) → None

Write a leaf element when given content, else return a builder.

Attributes are added to the innermost tag, after any it was given by an earlier call. The content is handled like that of DocWriter.__call__(): it is written verbatim, so a string that is not a literal has to go through escape() first. None is rejected with a TypeError instead of being mistaken for missing content.

class hyperscribe._Voids(_doc: DocWriter, _builders: dict[str, ~hyperscribe._VoidBuilder]=<factory>)

Look up void elements by name, as in doc.voids.br().

__getattr__(name: str) → _VoidBuilder

Return the void element with this name, such as img.

__getitem__(name: str) → _VoidBuilder

Return the void element with any name, as in doc.voids["x-y"].

class hyperscribe._VoidBuilder(_doc: DocWriter, _opening: str)

Write a void element, such as <br>, on its own line when called.

__call__(**attrs: LiteralString | SafeStr | SupportsHTML | int | float | bool | None | dict[str, AttributeValue] | Template) → None

Write the element with the given attributes.

Void elements have no content and no closing tag, so there is nothing to pass as content or to enter as a context manager.