Hypermedia

A fully typed Python HTML Renderer with a focus on composability of elements. All html tags available with autocompletion for all the tags attributes. A perfect companion for htmx and ships with FastAPI integration.

Showcase

pythonfull(user="John Doe").dump()partial().dump()

views/index.py

def base() -> Element:  # (1)
    """Your base html document. Written once. Reused anywhere."""
    return Html(
        Head(slot="head"),
        Body(
            Header(slot="header"),
            Main(slot="content"),
            Footer(slot="footer"),
        ),
    )


def user_header(user: str):
    return Div(user, Button("log out", hx_post="/logout"))


def partial() -> Element:
    return Div(H1("Welcome"), Paragraph("Lorem ipsum..."))


def full(user: str | None) -> Element:
    html = base()

    # add title:
    html.extend("head", Title("Welcome to test.com"))

    # If user is logged in add user header
    if user:
        html.extend("header", user_header(user))

    # Extend with index content
    html.extend(
        "content",
        partial(),
    )

    return html

This function is usually placed in commons.py or similar since it will be used by all view files.

<html>

<head>
    <title>Welcome to test.com</title>
</head>

<body>
    <header>
        <!-- (1) -->
        <div>John Doe<button hx-post='/logout'>log out</button></div>
    </header>
    <main>
        <!-- (2) -->
        <div>
            <h1>Welcome</h1>
            <p>Lorem ipsum...</p>
        </div>
    </main>
    <footer></footer>
</body>

</html>

Base was extended with result from user_header(user: str) function because a user was logged in!
This part is rendered by the partial() function.

<div>
    <h1>Welcome</h1>
    <p>Lorem ipsum...</p>
</div>

Why use Hypermedia

If the above example intrigues you then that should be more than enough to give hypermedia a go.

Other reasons for hypermedia:

You need to create html with Python
You want to create html snippets and weave them together.
You think HTMX makes a lot of sense.
Html attributes? yes. Every html element have autocompletion for their specific attributes.
Jinja? tired of not being able to use your types and models? hypermedia never leaves python land, so you keep it all!
You want to make a website with FastAPI - hypermedia ships with special decorator for FastAPI

Goal

To make it easy to write a webapplication in python.

Why

This was just the way we wanted to write html with python. We didn't want to have jinja files were we lost all typing and autocompletion from our python project. And we felt that existing solutions didn't do composability the way we wanted to do it. Especially with regards to working with htmx with partials and full pages.

Contributing

Add issues, ask good questions. Come with good suggestions <3

check the contibuting section

Installation

Package is on pypi. Use pip, poetry or uv to install

pip install hypermedia

poetry add hypermedia

uv add hypermedia

What to do next? head over to the quickstart section!