Generate HTML, the Pythonic way

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

fvoron

These details have not been verified by PyPI

Project description

Markupflow

Generate HTML, the Pythonic way

Documentation: https://frankie567.github.io/markupflow/

Source Code: https://github.com/frankie567/markupflow

Quickstart

Installation

Install markupflow using pip:

pip install markupflow

Or with uv:

uv add markupflow

Basic Usage

Here's a simple example to generate an HTML document:

from markupflow import Document

# Create a document
doc = Document()

# Build your HTML structure
with doc.tag("html", lang="en"):
    with doc.tag("head"):
        with doc.tag("title"):
            doc.text("My Page")
    with doc.tag("body"):
        with doc.h1():
            doc.text("Hello, World!")
        with doc.p(class_="intro"):
            doc.text("Welcome to markupflow!")

# Get the HTML output
html = doc.render()
print(html)

This generates:

<html lang="en"><head><title>My Page</title></head><body><h1>Hello, World!</h1><p class="intro">Welcome to markupflow!</p></body></html>

Features

Tag Shortcuts

Markupflow provides shortcuts for common HTML tags:

from markupflow import Document

doc = Document()

with doc.html(lang="en"):
    with doc.head():
        with doc.title():
            doc.text("Shortcuts Example")
    with doc.body():
        with doc.h1(id="main-title"):
            doc.text("Main Title")
        with doc.div(class_="container"):
            with doc.p():
                doc.text("First paragraph")
            with doc.p():
                doc.text("Second paragraph")
        # Self-closing tags
        doc.br()
        doc.hr()
        doc.img(src="image.jpg", alt="Example")

print(doc.render())

Dynamic Attributes

Add attributes conditionally using the attr() method:

from markupflow import Document

doc = Document()

user_is_admin = True
show_tooltip = False

with doc.div():
    if user_is_admin:
        doc.attr("class", "admin-panel")
        doc.attr("data-role", "administrator")
    if show_tooltip:
        doc.attr("title", "Admin panel")
    doc.text("Content that changes based on conditions")

print(doc.render())
# Output: <div class="admin-panel" data-role="administrator">Content that changes based on conditions</div>

Dynamic Classes

Add CSS classes conditionally using the classes() method. When classes already exist, new ones are appended:

from markupflow import Document

doc = Document()

is_admin = True
is_active = True
is_highlighted = False

with doc.div(class_="panel"):
    if is_admin:
        doc.classes("admin")
    if is_active:
        doc.classes("active")
    if is_highlighted:
        doc.classes("highlighted")
    doc.text("Panel content")

print(doc.render())
# Output: <div class="panel admin active">Panel content</div>

HTML Escaping

Markupflow automatically escapes content for security:

from markupflow import Document

doc = Document()

with doc.p():
    doc.text("Hello & <world> \"test\"")

print(doc.render())
# Output: <p>Hello &amp; &lt;world&gt; &quot;test&quot;</p>

# For trusted content, use raw()
with doc.div():
    doc.raw("<em>Already escaped</em>")

print(doc.render())
# Output: <div><em>Already escaped</em></div>

Attribute Name Conversion

Python attribute names are automatically converted to HTML format:

from markupflow import Document

doc = Document()

with doc.div(
    class_="container",      # class_ -> class
    data_value="123",        # data_value -> data-value
    aria_label="button"      # aria_label -> aria-label
):
    doc.text("Content")

print(doc.render())
# Output: <div class="container" data-value="123" aria-label="button">Content</div>

Document Reuse

Clear and reuse the same document object:

from markupflow import Document

doc = Document()

# First use
with doc.p():
    doc.text("First content")

html1 = doc.render()

# Clear and reuse
doc.clear()

with doc.h1():
    doc.text("Second content")

html2 = doc.render()

print(html1)  # <p>First content</p>
print(html2)  # <h1>Second content</h1>

Error Handling

Markupflow provides specific exception classes:

from markupflow import Document, MarkupFlowError

doc = Document()

try:
    # This will raise NoTagContextError
    doc.attr("class", "test")
except MarkupFlowError as e:
    print(f"Caught markupflow error: {e}")

try:
    with doc.div():
        doc.text("Content")
        # This will raise TagAlreadyOpenedError
        doc.attr("class", "test")
except MarkupFlowError as e:
    print(f"Caught markupflow error: {e}")

Reusable Components with Fragments

Markupflow supports creating reusable HTML components using the Fragment class. Fragments allow you to define components independently without carrying document instances around.

Creating Finished Fragments

Finished fragments are complete, self-contained HTML components:

from markupflow import Fragment, Document

def alert(message, severity="info"):
    """Create an alert component."""
    fragment = Fragment()
    with fragment.div(class_=f"alert alert-{severity}"):
        fragment.text(message)
    return fragment

def card(title, content):
    """Create a card component."""
    fragment = Fragment()
    with fragment.div(class_="card"):
        with fragment.div(class_="card-header"):
            with fragment.h3():
                fragment.text(title)
        with fragment.div(class_="card-body"):
            fragment.text(content)
    return fragment

# Use fragments in a document
doc = Document()
with doc.tag("body"):
    doc.fragment(alert("Welcome!", "success"))
    doc.fragment(alert("Please note", "warning"))
    doc.fragment(card("Getting Started", "Learn the basics"))

print(doc.render())

Creating Expandable Fragments

Expandable fragments use context managers to allow dynamic content addition:

import contextlib
from markupflow import Fragment, Document

@contextlib.contextmanager
def button(btn_type="button"):
    """Create an expandable button fragment."""
    fragment = Fragment()
    with fragment.button(type=btn_type, class_="btn"):
        yield fragment

@contextlib.contextmanager
def card_with_body(title):
    """Create a card where the body can be filled dynamically."""
    fragment = Fragment()
    with fragment.div(class_="card"):
        with fragment.div(class_="card-header"):
            fragment.text(title)
        with fragment.div(class_="card-body"):
            yield fragment

# Use expandable fragments
doc = Document()
with doc.tag("body"):
    # Button with custom content
    with doc.fragment(button("submit")) as btn:
        btn.text("Submit Form")
    
    # Card with dynamic body content
    with doc.fragment(card_with_body("User Info")) as card_body:
        with card_body.p():
            card_body.text("Name: John Doe")
        with card_body.p():
            card_body.text("Email: john@example.com")

print(doc.render())

Composing Fragments

Fragments can contain other fragments, enabling complex component hierarchies:

from markupflow import Fragment, Document

def icon(name):
    """Create an icon fragment."""
    fragment = Fragment()
    with fragment.span(class_=f"icon icon-{name}"):
        fragment.text(f"[{name}]")
    return fragment

def button_with_icon(text, icon_name):
    """Create a button with an icon."""
    fragment = Fragment()
    with fragment.button(class_="btn"):
        fragment.fragment(icon(icon_name))
        fragment.text(f" {text}")
    return fragment

# Use composed fragments
doc = Document()
with doc.tag("body"):
    doc.fragment(button_with_icon("Save", "save"))
    doc.fragment(button_with_icon("Delete", "trash"))

print(doc.render())

Development

Setup environment

We use uv to manage the development environment and production build, and just to manage command shortcuts. Ensure they are installed on your system.

Run unit tests

You can run all the tests with:

just test

Format the code

Execute the following command to apply linting and check typing:

just lint

Publish a new version

You can bump the version, create a commit and associated tag with one command:

just version patch

just version minor

just version major

Your default Git text editor will open so you can add information about the release.

When you push the tag on GitHub, the workflow will automatically publish it on PyPi and a GitHub release will be created as draft.

Serve the documentation

You can serve the Mkdocs documentation with:

just docs-serve

It'll automatically watch for changes in your code.

License

This project is licensed under the terms of the MIT license.

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

fvoron

These details have not been verified by PyPI

Release history Release notifications | RSS feed

This version

0.0.2

Jan 18, 2026

0.0.1

Jan 17, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markupflow-0.0.2.tar.gz (57.4 kB view details)

Uploaded Jan 18, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

markupflow-0.0.2-py3-none-any.whl (9.8 kB view details)

Uploaded Jan 18, 2026 Python 3

File details

Details for the file markupflow-0.0.2.tar.gz.

File metadata

Download URL: markupflow-0.0.2.tar.gz
Upload date: Jan 18, 2026
Size: 57.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for markupflow-0.0.2.tar.gz
Algorithm	Hash digest
SHA256	`8478e12b91e9e82bf2a26a498e61544b85bdb1377c4537c4a9162fab2ea29e23`
MD5	`db65c7e3ed99530aa07425ef2f5d8159`
BLAKE2b-256	`de45fceb08a4fc99ee4348d642fdee1984bcb3274165bf2c4a38e8c73b699f0d`

See more details on using hashes here.

File details

Details for the file markupflow-0.0.2-py3-none-any.whl.

File metadata

Download URL: markupflow-0.0.2-py3-none-any.whl
Upload date: Jan 18, 2026
Size: 9.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for markupflow-0.0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`702506d20973dc6506cf7a43ae5d21d07dfd87f56467b525878b5ee85d543923`
MD5	`600c767059e9b049360bb3bf3b1d9727`
BLAKE2b-256	`2abaa9083cf0e1812a0d2b96755d9020fc48ae01c2d3052c6eef9d212baadbe0`

See more details on using hashes here.

markupflow 0.0.2

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

Markupflow

Quickstart

Installation

Basic Usage

Features

Tag Shortcuts

Dynamic Attributes

Dynamic Classes

HTML Escaping

Attribute Name Conversion

Document Reuse

Error Handling

Reusable Components with Fragments

Creating Finished Fragments

Creating Expandable Fragments

Composing Fragments

Development

Setup environment

Run unit tests

Format the code

Publish a new version

Serve the documentation

License

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes