pydantic-to-html 0.1.0

A library to convert Pydantic models to HTML

pydantic-to-html

A Python library that automatically converts Pydantic models into structured HTML using safe and semantic defaults.

Overview

pydantic-to-html infers an appropriate HTML structure based on the types of fields in a Pydantic model, including support for nested models, lists, and forms for user input.

Installation

pip install pydantic-to-html

Usage

from pydantic import BaseModel
from pydantic_to_html import render_html

class User(BaseModel):
    name: str
    email: str
    age: int

user = User(name="John Doe", email="[e-mail]", age=30)
html = render_html(user)
print(html)

Features

• ✅ Automatic HTML Conversion – Converts any Pydantic model into a structured HTML representation.
• ✅ Recursive Nesting – Handles nested models and lists of models gracefully.
• ✅ Table-Based Rendering – Uses elements for structured data representation.
• ✅ List Support – Renders lists as
  or
  , depending on the data type.
  1. ✅ Automatic Form Generation – Can generate editable forms with elements.
  2. ✅ Type-Safe Defaults – Uses appropriate form fields based on the Pydantic field type (str, int, bool, datetime, etc.).
  3. ✅ Customizable Themes – Allows passing custom CSS classes or styles.
  4. ✅ HTMX Support – Optionally integrates HTMX for live updates.
  5. ✅ Validation & Constraints – Uses Pydantic field constraints to enforce validation on form inputs.

  API

  def render_html(
      model: BaseModel,
      editable: bool = False,
      theme: str | None = None,
      htmx: bool = False,
      htmx_mode: str = "full",  # "full" | "inline" | "none"
      max_depth: int | None = None,
  ) -> str:
      """Converts a Pydantic model into HTML (table or form)."""
  

  Type Mapping

Pydantic Type	Default HTML Element
str
int
float
bool
datetime
List[str]	Multiple inside
List[Model]	Nested Dict[str, Any] Table (if structured), <ul> otherwise Enum Radio buttons Literal["A", "B"] Dropdown (<select>) HTMX Modes Mode Behavior "none" Static HTML "inline" updates on hx-trigger="change" "full" Whole form auto-submits on change Handling Nested Models & Lists Lists of Primitives (List[str]) → with elements. Lists of Models (List[Model]) → Rendered as nested tables. Dictionaries (Dict[str, Any]) → Rendered as a key-value table if structured, or if unstructured. Nested Pydantic Models → Recursively rendered as nested tables, with a configurable max_depth to limit depth. Validation & Constraints Mapping Min/Max Length (Field(min_length=3, max_length=50)) → minlength="3" maxlength="50" Greater Than (Field(gt=0)) → min="0" Regex Constraints (Field(regex="^[a-z]+$") → pattern="^[a-z]+$" Error Handling for Edge Cases Unsupported Types (bytes, UUID, Callable) UUID → Rendered as str(uuid) bytes → Rendered as "[binary data]" Callable → Rendered as "[function]" Default Factories (Field(default_factory=...)) → Rendered appropriately with their defaults. Roadmap This is our current development roadmap. Contributions are welcome! Phase 1: Basic Rendering Convert flat Pydantic models into tables Support nested models using recursion Support lists as elements Phase 2: Editable Forms Render models as forms with fields Infer input types from field types Handle lists as multiple input fields Phase 3: Advanced Features Add HTMX integration for interactive forms Implement theme support Add validation based on Pydantic constraints Support for complex types (Enum, Literal, etc.) Add custom rendering hooks Phase 4: Optimization & Extras Performance improvements for large models Add support for custom widgets Implement max_depth control for nested models Add accessibility features Comprehensive documentation site License MIT