Generate HTML, the Pythonic way

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for fvoron from gravatar.com fvoron

Unverified details

These details have not been verified by PyPI
Meta
Classifiers
Report project as malware

Project description

Markupflow

Generate HTML, the Pythonic way

build codecov PyPI version

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>

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}")

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

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for fvoron from gravatar.com fvoron

Unverified details

These details have not been verified by PyPI
Meta
Classifiers

Release history Release notifications | RSS feed

0.0.2

This version

0.0.1

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.1.tar.gz (53.8 kB view details)

Uploaded Source

Built Distribution

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

markupflow-0.0.1-py3-none-any.whl (7.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: markupflow-0.0.1.tar.gz
  • Upload date:
  • Size: 53.8 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.1.tar.gz
Algorithm Hash digest
SHA256 a85ae0772279b525d99a0482e443618c8d3632654cc6f01042b661b656397d3b
MD5 e42570f9679f8b9ad1c2608e008aa741
BLAKE2b-256 260c0d413bb5548b6f1f75085a048aaf0f4fed4d1b64d043f4afdd63fd5f0a1d

See more details on using hashes here.

File details

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

File metadata

  • Download URL: markupflow-0.0.1-py3-none-any.whl
  • Upload date:
  • Size: 7.6 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d53bf664b81b865361a5ed36239e4044981998a11b92168504aed7ffe0a15c7e
MD5 84b1b55f6bb561eedb83b9b33ff020ee
BLAKE2b-256 46537997f988e061e202c9fff73bb618762bb8cc7cdc9a731ba886f6697874c9

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page