API Reference¶

exception minihtml.CircularReferenceError¶: Raised when a circular reference between elements is detected.

class minihtml.Component(callback: Callable[[Slots], Node | HasNodes], slots: Slots)¶

An instance of a component.

To fill the default slot, use the component as a context manager.

To fill a slot by name, use the slot() method.

slot(slot: str | None = None) → Iterator[None]¶

Parameters:: slot – The slot name, or None to refer to the default slot.

Context manager to add content to a slot. Nodes created within the context will be added to the slot.

class minihtml.ComponentWrapper(impl: Callable[[Concatenate[Slots, P]], Node | HasNodes], slots: Sequence[str], default: str | None, styles: Sequence[Node] | None = None, scripts: Sequence[Node] | None = None)¶

Wraps a component implementation.

Decorating a function with the @component decorator replaces the function with a ComponentWrapper.

class minihtml.Element¶: Base class for elements.

class minihtml.ElementEmpty(tag: str, *, inline: bool = False, omit_end_tag: bool)¶: An empty element.

class minihtml.ElementNonEmpty(tag: str, *, inline: bool = False)¶: An element that can have content.

class minihtml.Fragment(*content: Node | HasNodes | str)¶

A collection of nodes without a parent element.

Use the fragment() function to create fragments.

class minihtml.Node¶: Base class for text nodes and elements.

class minihtml.Prototype¶: Base class for element prototypes.

class minihtml.PrototypeEmpty(tag: str, *, inline: bool, omit_end_tag: bool)¶

A prototype for emtpy elements.

Use the make_prototype() function to create new prototypes.

class minihtml.PrototypeNonEmpty(tag: str, *, inline: bool)¶

A prototype for elements that can have content.

Use the make_prototype() function to create new prototypes.

class minihtml.Slots(slots: Sequence[str], default: str | None)¶

Object to interact with slots from the inside of a component.

is_filled(slot: str | None = None) → bool¶

Returns whether or not the slot has been filled.

Parameters:: slot – The slot name, or None to refer to the default slot.

slot(slot: str | None = None) → SlotContext¶

Insert the contents of a given slot.

Parameters:: slot – The slot name, or None to refer to the default slot.

When used as a context manager, nodes created within the context will be inserted if the slot has not been filled (default content).

class minihtml.Template(callback: Callable[[], list[Node]])¶

The result of calling a function decorated with @template.

render(*, doctype: bool = True) → str¶

Render the template and return a string.

Parameters:: doctype – Whether or not to prepend the doctype declaration <!doctype html> to the output.

class minihtml.Text(s: str, escape: bool = True)¶

A text node.

Use the text() and safe() functions to create text nodes.

Decorator to create a component.

Parameters:

slots – A list of slot names. When omitted, the component will have one default unnamed slot.
default – One of the names in slots that should be the default slot. When slots is set but not default, the component’s slots always have to be referred to by name.
style – Associate one or more style nodes with the component.
script – Associate one or more script nodes with the component.

When called, the decorated function receives a Slots object as its first argument.

minihtml.component_scripts() → ResourceWrapper¶

Placeholder element for component scripts.

Can only be used in code called from a function decorated with @template. Inserts the script nodes collected from all components used in the current template.

minihtml.component_styles() → ResourceWrapper¶

Placeholder element for component styles.

Can only be used in code called from a function decorated with @template. Inserts the style nodes collected from all components used in the current template.

minihtml.fragment(*content: Node | HasNodes | str) → Fragment¶

Create a fragment.

A fragment is a collection of nodes without a parent element.

When called inside an element context, adds the fragment contents to the parent element.

minihtml.make_prototype(tag: str, *, inline: bool = False) → PrototypeNonEmpty¶

minihtml.make_prototype(tag: str, *, inline: bool = False, empty: Literal[False]) → PrototypeNonEmpty

minihtml.make_prototype(tag: str, *, inline: bool = False, empty: Literal[True], omit_end_tag: bool = False) → PrototypeEmpty

Factory function to create a new element prototype.

Parameters:

tag – The tag name.
inline – Whether or not the element is an inline (True) or block element (False).
empty – Whether or not the element is allowed to have content.
omit_end_tag – When empty=True, whether or not the end tag should be omitted when rendering.

Returns:

An element prototype.

minihtml.safe(s: str) → Text¶

Create a text node with HTML escaping disabled.

When called inside an element context, adds text content to the parent element.

minihtml.template() → Callable[[Callable[[P], Node | HasNodes]], Callable[[P], Template]]¶

minihtml.template(layout: ComponentWrapper[...]) → Callable[[Callable[[Concatenate[Component, P]], None]], Callable[[P], Template]]

Decorator to create a template.

Parameters:: layout – A component to use as the layout for the template. The layout must have a default slot.

When layout is used, the decorated function will be executed within the context of the layout component when the template is rendered. All elements created in the function body will be added to the default slot of the component. The function will receive the component as the first positional argument, and should return None.

When layout is not used, the function should return the content to be rendered.

The template will collect and deduplicate the style and script nodes of all components used within the template (including the layout component). These nodes can be inserted into the document by using the component_styles() and component_scripts() placeholders.

minihtml.text(s: str) → Text¶

Create a text node.

When called inside an element context, adds text content to the parent element.