TenTags 🏷️

TenTags is a declarative template language and Intermediate Representation (IR) for automated HTML, Excel (.xlsx), and PDF table and document generation.

💡 Why TenTags? (A Language for Programs & AI, Not Manual Editing)

While general markup formats are designed for humans to manually write text, TenTags is designed specifically as a Template DSL for programs, server engines, and AI agents.

Whether you are building backend report pipelines, ERP/CRM accounting modules, invoice generators, or LLM-driven document agents, generating clean TenTags strings via loops and f-strings is orders of magnitude simpler and safer than emitting verbose HTML strings with inline style="" or hundreds of lines of openpyxl / reportlab API calls:

# Programmatically generate high-fidelity reports with dynamic loops and f-strings:
formula = f'''
5,4,1,"#ccc","solid",0,40, data(
    <bg=#1e293b><color=white><b><cm>{report_title}, , , </cm></b></color></bg>;
    {generated_rows_from_db}
)'''

⚙️ Compiler & Data Pipeline Architecture

At its core, TenTags is a unified Intermediate Representation (IR) table compiler. Rather than manually writing long static strings, you generate TenTags formulas dynamically in your Python backend (e.g. from ORM models or database cursors), parse them into a TableModel AST, and compile them to any target format:

   Database / API
         ↓
    ORM / SQL / Objects
         ↓
  f-strings / Templates
         ↓
   TenTags Formula
         ↓
  [ Lexer ➔ Parser ]
         ↓
   TableModel (IR)
      ↙  ↓  ↘
   HTML Excel PDF  [Future: DOCX, SVG, Flutter...]

• 🎯 Target Audience: Backend developers (FastAPI, Django, Flask), ERP/CRM financial engines, automated invoice/receipt generators, and AI/LLM agents.
• 🤖 AI & LLM Native: LLMs generate exact, compact TenTags formulas reliably without CSS layout bugs or Excel/PDF API hallucinations.
• 🔀 Declarative Grid Merges: Effortlessly merge cells rightward across columns (<cm>) and downward across rows (<rm>).
• 🎨 Rich Typography & Styling: Inline control over font size (<fs>), bold (<b>), italic (<i>), alignment (<left>, <center>, <right>), text color (<color=>), and cell fills (<bg=>).
• 📊 Triple Backend Rendering: Directly compile your IR to high-fidelity HTML (render_html), native Excel (.xlsx) (render_xlsx), or vector PDF (.pdf) (render_pdf).
• ⚡ Lightweight & Modular Runtime: Pure Python runtime (xml.etree.ElementTree) for DSL tokenization and HTML rendering. Optional Excel export (openpyxl) and PDF export (reportlab).

⚡ Quick Start: Programmatic Template Generation

TenTags shines when generating formatted tabular documents dynamically from Python objects:

import tentags

# 1. Your raw data source (e.g., query results from database/ORM)
employees = [
    {"name": "Alice Vance", "salary": "$120,000", "dept": "Engineering"},
    {"name": "Bob Miller", "salary": "$95,000", "dept": "Design"},
    {"name": "Charlie R.", "salary": "$110,000", "dept": "Product"}
]

# 2. Define styled header
header = (
    '<fs=16><bg=#1e293b><color=white><b>Name</b></color></bg></fs>, '
    '<fs=16><bg=#1e293b><color=white><b>Salary</b></color></bg></fs>, '
    '<fs=16><bg=#1e293b><color=white><b>Department</b></color></bg></fs>'
)

# 3. Format body rows dynamically
body_rows = ";\n".join(
    f"<b>{e['name']}</b>, <right>{e['salary']}</right>, <bg=#f1f5f9>{e['dept']}</bg>"
    for e in employees
)

# 4. Construct a complete formula with the preamble (rows, columns, borders, stretch, row height)
formula = f'''
{len(employees) + 1},3,1,"#cbd5e1","solid",0,40, data(
    {header};
    {body_rows}
)
'''

# 5. Parse formula into Intermediate Representation (IR)
model = tentags.parse(formula)

# 6. Render to multiple backends
html_table = tentags.render_html(model)
tentags.render_xlsx(model, "Quarter_Report.xlsx")
tentags.render_pdf(model, "Quarter_Report.pdf")

The same parsed model can be rendered as HTML, Excel (.xlsx), or PDF.

⚙️ Formula Structure & Decoupled Presentation (TenTags v0.2.0+)

A TenTags formula consists of the Preamble (which defines global table structure, grid borders, and sizing) followed by either a single Data Block (legacy format), or decoupled Style and Data blocks (recommended for template reuse):

1. Unified Format (Legacy / Simple Tables)

 1   2   3      4         5     6   7
 ──  ──  ──  ───────   ───────  ─  ──
 4 , 4 , 1 ,"#cbd5e1","solid", 0, 45, data(...)

2. Decoupled Template Format (v0.2.0+)

 4 , 4 , 1 ,"#cbd5e1","solid", 0, 45, style(...), data(...)

During compilation, the engine overlays the layout and formatting rules defined in style(...) (alignments, fonts, backgrounds, column/row merges) onto the raw content defined in data(...).

Following these preamble parameters, the formula is completed by either the data(...) block or a pair of style(...) and data(...) blocks, where cells are defined row-by-row, separated by semicolons (;) and columns separated by commas (,).

🏷️ Tags in style(...) and data(...)

TenTags derives its name from the 10 core structural and styling tags supported inside style(...) and data(...) blocks:

Note on Tag Transfer & Empty Elements: Notice how empty elements (such as , , or , ;) are used when adjacent cells are absorbed by a <cm> horizontal merge or <rm> vertical merge. TenTags automatically transfers and preserves all active tags across cell boundaries without requiring explicit None placeholders.

Additional supported tags:

📦 Installation

Install from PyPI via pip:

pip install tentags

For Excel (.xlsx) export, install the optional excel dependency:

pip install tentags[excel]
# or directly: pip install openpyxl

For PDF (.pdf) export, install the optional pdf dependency:

pip install tentags[pdf]
# or directly: pip install reportlab

To install all optional backends at once:

pip install tentags[all]

🎨 Advanced Example: Beautiful Styled Table & Merges

Here is how a single, clean TenTags expression generates an enterprise-grade financial dashboard table featuring merged headers (<cm>), custom font sizing (<fs>), cell background colors (<bg=>), text alignment (<left>, <right>), and custom typography (<b>, <i>, <color=>) across both HTML and Excel (.xlsx):

import tentags

# Define an advanced 4x4 styled financial performance grid using clean empty elements (, ,) inside merges
formula = '''4,4,1,"#cbd5e1","solid",0,45, data(
    <fs=18><bg=#1e293b><color=white><b><cm>Q3 Financial Performance Dashboard, , , , </cm></b></color></bg></fs>;
    <bg=#f1f5f9><b><left>Department</left></b></bg>, <bg=#f1f5f9><b><center>Revenue</center></b></bg>, <bg=#f1f5f9><b><center>Expenses</center></b></bg>, <bg=#f1f5f9><b><center>Net Profit</center></b></bg>;
    <left>Engineering</left>, <right>"$240,000"</right>, <right>"$180,000"</right>, <bg=#dcfce7><color=#166534><b><right>"+$60,000"</right></b></color></bg>;
    <left>Sales & Marketing</left>, <right>"$310,000"</right>, <right>"$210,000"</right>, <bg=#dcfce7><color=#166534><b><right>"+$100,000"</right></b></color></bg>
)'''

# Compile IR once — render to any backend
model = tentags.parse(formula)

# 1. Export to native Excel (.xlsx) with exact fonts, fills & merge_cells
tentags.render_xlsx(model, "Q3_Financial_Dashboard.xlsx")

# 2. Export to vector PDF (.pdf) via ReportLab
tentags.render_pdf(model, "Q3_Financial_Dashboard.pdf")

# 3. Render to responsive HTML string with inline CSS
html_table = tentags.render_html(model)
print(html_table)

📋 Visual Structure & Styling Result:

📊 Excel Matrix Example: Row Merges (<rm>), Column Merges (<cm>) & Colors

To see how TenTags shines as a native Excel spreadsheet generator, here is a 5x5 Enterprise Allocation Matrix utilizing combined row merges (<rm>), multi-column merges (<cm>), clean empty elements ( , , ), and classic Microsoft Excel color palettes (#1F4E78, #DDEBF7, #E2EFDA, #FFF2CC):

import tentags

# Define an Excel matrix with vertical row merges (<rm>) and horizontal column merges (<cm>)
excel_formula = '''5,5,1,"#B0C4DE","solid",0,35, data(
    <fs=16><bg=#1F4E78><color=white><b><cm>2026 Enterprise Budget & Allocation Matrix, , , , </cm></b></color></bg></fs>;
    <bg=#DDEBF7><b><rm><center>Category</center></rm></b></bg>, <bg=#DDEBF7><b><cm><center>Q1 & Q2 Allocation, </center></cm></b></bg>, <bg=#DDEBF7><b><cm><center>Q3 & Q4 Allocation, </center></cm></b></bg>;
    <bg=#DDEBF7><b><rm> </rm></b></bg>, <bg=#F2F2F2><b><center>Hardware</center></b></bg>, <bg=#F2F2F2><b><center>Software</center></b></bg>, <bg=#F2F2F2><b><center>Hardware</center></b></bg>, <bg=#F2F2F2><b><center>Software</center></b></bg>;
    <bg=#FFF2CC><b><left>R&D Division</left></b></bg>, <right>"$150,000"</right>, <right>"$85,000"</right>, <right>"$120,000"</right>, <right>"$95,000"</right>;
    <bg=#E2EFDA><color=#375623><b><left>Total Budget</left></b></color></bg>, <bg=#E2EFDA><color=#375623><b><cm><right>"$235,000", </right></cm></b></color></bg>, <bg=#E2EFDA><color=#375623><b><cm><right>"+$215,000", </right></cm></b></color></bg>
)'''

# Compile IR once — export to all three backends
model = tentags.parse(excel_formula)

# Export to native Excel (.xlsx)
tentags.render_xlsx(model, "Enterprise_Budget_Matrix.xlsx")

# Export to vector PDF (.pdf)
tentags.render_pdf(model, "Enterprise_Budget_Matrix.pdf")

🗓️ Visual Spreadsheet Grid Structure (A1:E5):

🛠️ API Reference

Module Constants & Metadata

• tentags.__version__: Library version string (e.g., '2.0.3').
• tentags.version_info: Version tuple for checking compatibility (e.g., (2, 0, 3)).
• tentags.__author__: Author name ('Zhandos Mambetali').
• tentags.__license__: Project license ('Apache-2.0').
• tentags.__homepage__: Link to home website ('https://tentags.org').
• tentags.__url__: Canonical library URL ('https://tentags.org').
• tentags.__copyright__: Copyright notice ('Copyright (c) 2026 Zhandos Mambetali').

Diagnostic & Utility Helpers

tentags.info() -> None

Prints the package version, author, license, website, Python version, and availability of the HTML, PDF, and XLSX renderers.

tentags.features() -> dict

Checks the availability of optional rendering backends. Returns a dictionary:

{
    "html": True,
    "pdf": True,   # True if reportlab is installed
    "xlsx": True   # True if openpyxl is installed
}

tentags.validate(formula: str) -> dict

Syntactically checks a TenTags formula's layout configuration and markup tag balance. Returns a status dictionary:

• Success: {"status": "ok", "message": "Syntax OK"}
• Failure: {"status": "error", "message": "Missing closing tag </b>..."}

tentags.demo(name: str = "dashboard") -> None

Generates an HTML demo in the current directory and XLSX/PDF files when the corresponding optional backends are installed. Supported templates: 'dashboard', 'invoice', 'table'. Example:

import tentags
tentags.demo("invoice") # Generates HTML, XLSX, and PDF invoices on the fly

Core API Functions

tentags.render(preamble_or_formula, style=None, data=None, context=None) -> str

Renders either a complete formula or decoupled preamble, style, and data blocks to a <table>...</table> HTML string.

• preamble_or_formula: A complete formula such as 'rows, cols, border_width, "border_color", "border_style", stretch, cell_height, data(...)', or a preamble used with style and data.
• style: Optional style(...) block for decoupled rendering.
• data: Optional data(...) block for decoupled rendering.
• context: Optional dictionary of variable names and their replacement values ({'VarName': 'Value'}).

tentags.parse(formula: str, context: dict = None) -> TableModel

Parses the formula into a structured TableModel instance containing 2D cell grids (CellDesc), BorderFlags, and styles without generating HTML.

tentags.compile(preamble, style, data, context: dict = None) -> TableModel

Builds a TableModel from decoupled preamble, style, and data blocks. Each block may be a TenTags string or a parsed cell grid.

tentags.render_html(model: TableModel) -> str

Renders a previously parsed TableModel instance into an HTML string.

tentags.render_xlsx(model: TableModel, filepath_or_stream) -> None

Exports a TableModel directly to an Excel .xlsx file using openpyxl. Applies openpyxl.styles.Font (bold, italic, color), openpyxl.styles.PatternFill (background color), and openpyxl.styles.Border according to the table formula. Requires pip install tentags[excel].

tentags.render_pdf(model: TableModel, filepath_or_stream) -> None

Exports a TableModel directly to a vector PDF file using ReportLab. Translates IR coordinates, merged cell regions (SPAN), background fills (BACKGROUND), fonts, alignments, and border grids into native ReportLab TableStyle commands. Automatically selects portrait or landscape page orientation based on column count. Requires pip install tentags[pdf].

🗂️ Multi-Table Rendering (v1.1.0+)

TenTags supports assembling and rendering multiple independent tables into a single output file (HTML Grid, Multi-Sheet or Stacked Excel workbook, or Multi-Page PDF report). This is highly useful for generating comprehensive reports where you want to reuse preambles and styling templates across different datasets.

Each table is defined as a dictionary containing its components:

table_definition = {
    "preamble": "3, 4, 1, #1977ff, solid-1, 0, 40",  # Optional: table structure and borders
    "style": "style(<bg=white><center>...</center></bg>)",  # Optional: styling layout template
    "data": "data(Item, Qty; Wood, 10; Metal, 5)", # Required: table content
    "title": "Materials Summary",              # Optional: display title for PDF and stacked Excel
    "sheet_name": "Materials"                  # Optional: Worksheet name for Excel sheets mode
}

Example: Assembling a Multi-Table Report

import tentags

# Define reusable templates
common_preamble = '4, 4, 1, #1977ff, solid-1, 0, 40'
common_style = '''style(
    <bg=#1e293b><color=white><b><cm> , , , </cm></b></color></bg>;
    <bg=#e2e8f0><b><left></left></b></bg>, <bg=#e2e8f0><b><center></center></b></bg>, <bg=#e2e8f0><b><right></right></b></bg>, <bg=#e2e8f0><b><right></right></b></bg>;
    <left></left>, <center></center>, <right></right>, <right></right>;
    <left></left>, <center></center>, <right></right>, <right></right>
)'''

# Define distinct datasets
data_materials = 'data(Materials Report, , , ; Item, Qty, Price, Total; Wood, 10, 150, 1500; Metal, 5, 300, 1500)'
data_tools = 'data(Tools Report, , , ; Tool, Qty, Condition, Status; Hammer, 2, New, Active; Drill, 1, Used, Active)'

# Assemble reports list
report_tables = [
    {
        "preamble": common_preamble,
        "style": common_style,
        "data": data_materials,
        "title": "Materials Summary Report",
        "sheet_name": "Materials"
    },
    {
        "preamble": common_preamble,
        "style": common_style,
        "data": data_tools,
        "title": "Tools Inventory Report",
        "sheet_name": "Tools"
    }
]

# 1. Compile to a multi-page PDF document
tentags.multitable_pdf(report_tables, "combined_report.pdf", page_size="A4", orientation="portrait", page_break_after_each=True)

# 2. Export to a single Excel workbook (each table on a separate sheet)
tentags.multitable_xlsx(report_tables, "combined_sheets.xlsx", mode="sheets")

# 3. Export to a single Excel workbook (tables stacked vertically on one sheet with gaps)
tentags.multitable_xlsx(report_tables, "combined_stacked.xlsx", mode="stacked", gap=3)

# 4. Generate an HTML 2-column Grid layout
html_grid = tentags.multitable_html(report_tables, layout="grid", cols=2, gap="30px")

Multi-Table API Reference

tentags.multitable_html(tables: list, layout: str = "vertical", cols: int = 1, gap: str = "24px", full_page: bool = False, context: dict = None) -> str

Assembles and renders multiple tables into a single HTML container string.

• layout: 'vertical' (stacked) or 'grid' (using CSS Grid).
• cols: Number of columns in CSS Grid (only applicable when layout='grid').
• gap: CSS spacing between tables (e.g., '20px', '1.5rem').
• full_page: If True, wraps the output in a complete HTML document with <html> and <body> tags.

tentags.multitable_xlsx(tables: list, filepath_or_stream, mode: str = "sheets", gap: int = 3, show_titles: bool = True, context: dict = None) -> None

Assembles and renders multiple tables into a single Excel .xlsx workbook.

• mode: 'sheets' (creates a separate Worksheet for each table) or 'stacked' (renders all tables vertically on a single sheet).
• gap: Number of empty rows between stacked tables (only applicable when mode='stacked').
• show_titles: If True, renders the optional table title in bold above each table (only applicable when mode='stacked').

tentags.multitable_pdf(tables: list, filepath_or_stream, page_size: str = "letter", orientation: str = "portrait", page_break_after_each: bool = True, margins: tuple = (36, 36, 36, 36), context: dict = None) -> None

Assembles and renders multiple tables into a single PDF document.

• page_size: 'letter' or 'A4'.
• orientation: 'portrait' or 'landscape'.
• page_break_after_each: If True, places a page break after each table so they start on a fresh page.
• margins: Page margins tuple (left, right, top, bottom) in points (default: (36, 36, 36, 36)).

🔌 Web Framework & Template Integrations (v2.0.0+)

TenTags comes with built-in integrations for popular Python web engines under tentags.contrib and Django package structures.

1. Django Template Tags

If tentags is added to INSTALLED_APPS in your Django settings.py, Django will automatically discover the template tags.

In your HTML template:

{% load tentags %}

<!-- Block tag (supports short {% tt %} alias as well) -->
{% tt %}
2, 1, 1, "black", "solid-1", 0, 50,
data(
    Item, Quantity;
    {{ product.name }}, {{ product.qty }}
)
{% endtt %}

<!-- Inline tag -->
{% tentags_inline formula_string %}

2. Jinja2 / Flask / FastAPI

TenTags provides a Jinja2 Extension (TenTagsExtension) and global helper function (tentags).

FastAPI Integration

FastAPI integration is optional. Install FastAPI and Jinja2 in the application that uses TenTags; use an ASGI server such as Uvicorn to run that application:

pip install fastapi jinja2 "uvicorn[standard]"

from fastapi.templating import Jinja2Templates
from tentags.contrib.fastapi import register_templates

templates = Jinja2Templates(directory="templates")
register_templates(templates)

Flask Integration

from flask import Flask
from tentags.contrib.flask import init_app

app = Flask(__name__)
init_app(app)

In your Jinja2 Templates:

<!-- Block Tag -->
{% tt %}
2, 2, 3, "blue", "solid", 0, 50,
data(
    A, B;
    C, D
)
{% endtt %}

<!-- Inline Function -->
{{ tentags('2, 2, 3, "blue", "solid", 0, 50, data(A, B; C, D)') }}

🧪 Running Tests

To run the standalone test suite:

python -m pytest

Generated output files include:

• test_output.html — Summary HTML report of all rendered tables
• test_output.xlsx — Basic Excel table
• test_style_output.xlsx — Excel with styling tags
• Q3_Financial_Dashboard.xlsx / .pdf — Financial dashboard in Excel and PDF
• Enterprise_Budget_Matrix.xlsx / .pdf — Enterprise budget matrix in Excel and PDF

PDF files require pip install tentags[pdf] (ReportLab).

📄 License

Licensed under the Apache License 2.0. Copyright (c) 2026 Zhandos Mambetali.