htmy Documentation

htmy is an async, pure-Python server-side rendering engine designed to allow HTML generation using Python instead of a custom templating language.

Key Capabilities

• Async-first: Optimized for modern async tools and supports Async HTML streaming for improved Time to First Byte (TTFB).
• React-like Context: Supports context to avoid prop-drilling.
• Component Model: Supports both sync and async function components using decorator syntax.
• HTML/XML Support: Includes all baseline HTML tags, supports native HTML/XML documents with dynamic formatting, and provides slot rendering without custom syntax.
• Extensibility: Built-in support for Markdown, Jinja templates, and async JSON-based internationalization.
• Developer Experience: Fully-typed, unopinionated (works with any CSS/JS framework), and features automatic property-name conversion (snake_case to kebab-case).
• Error Handling: Includes a built-in ErrorBoundary component for graceful error management.
• Compatibility: Works with Trio (via AnyIO) and can wrap other templating libraries.

A component factory is a function that accepts arguments and returns a Component. Unlike full components, factories are evaluated immediately when called.

Advantages:

• Simplicity.
• Better performance (the renderer receives a smaller, pre-resolved component tree).

Limitations:

• Cannot be async (they are called from sync code).
• No access to the rendering Context.
• Cannot act as context providers.
• Immediately evaluated (can be undesirable for very large trees).

Important Note on Sequences: If a factory returns a sequence of components (like a list), you must ensure it is correctly passed to the parent. For example, passing list[list[ComponentType]] to a parent is invalid; you must unpack the list or use a Fragment to ensure the parent receives a flat list[ComponentType].

def heading(text: str) -> Component:
    return html.h1(text)

def section(title: str, text: str) -> Component:
    # This is a factory that returns a component tree immediately
    return html.div(
        heading(title), 
        html.p(text)
    )

htmy allows you to include custom XML-like tags directly within your markdown files. These tags can be mapped to full htmy components via an etree.ETreeConverter.

When a tag like <PostInfo author="John" /> is encountered in markdown, the converter looks for a mapping for PostInfo. If mapped to a class, the class's __init__ method must accept arguments that match the XML attributes.

# markdown file (post.md):
# <PostInfo author="John" published_at="1971-10-11" />

# component definition:
class PostInfo:
    def __init__(self, author: str, published_at: str) -> None:
        self.author = author
        self.published_at = published_at

    def htmy(self, context: Context) -> Component:
        return html.p("By ", html.strong(self.author), " at ", html.em(self.published_at), ".")

# converter configuration:
md_converter = etree.ETreeConverter({
    "PostInfo": PostInfo,
})

The Context (a Mapping) is managed by the renderer and allows you to share data with an entire component subtree.

Context Providers

Any component that implements a htmy_context() -> Context method acts as a provider. This method returns a dictionary of data that will be merged into the context for all child components.

Context Consumers

Components can access the context via the context: Context argument in their htmy method or function signature. You can retrieve specific data using the class or key as a lookup.

from htmy import Component, Context, Renderer, component, html

class UserContext:
    def __init__(self, *children, username: str, theme: str):
        self._children = children
        self.username = username
        self.theme = theme

    def htmy_context(self) -> Context:
        return {UserContext: self}

    def htmy(self, context: Context) -> Component:
        return self._children

    @classmethod
    def from_context(cls, context: Context) -> "UserContext":
        return context[cls]

@component
def welcome_page(text: str, context: Context) -> Component:
    user = UserContext.from_context(context)
    return html.html(html.body(html.h1(text, user.username), data_theme=user.theme))

# Usage:
# page = UserContext(welcome_page("Hello "), username="John", theme="dark")
# await Renderer().render(page)

To use internationalization in htmy, you need to follow two main steps:

1. Create translation resources: Use plain JSON files organized by locale. For example, to support English, create a folder structure like locale/en/page/ and add a hello.json file containing your translation strings.
2. Initialize and provide the I18n instance: Create an I18n instance pointing to your locale folder and include it in the rendering context using i18n.to_context() when calling the Renderer.

Translation strings can use Python format syntax (e.g., {name}) which can be automatically populated via keyword arguments in the get method.

from pathlib import Path
from htmy.i18n import I18n

# 1. Create translation resources (e.g., locale/en/page/hello.json)
# Content: { "message": "Hey {name}" }

# 2. Initialize I18n and provide it to the context
base_folder = Path(__file__).parent
i18n = I18n(base_folder / "locale" / "en")

# When rendering:
# rendered = await Renderer().render(Component(), i18n.to_context())