tentags 0.1.4

A lightweight declarative document markup language and DSL focused on high-fidelity tables and spreadsheet grids.

TenTags 🏷️

TenTags is a lightweight declarative document markup language and DSL focused on generating high-fidelity tables and spreadsheet grids.

💡 Why TenTags?

Traditional table generators and document export tools often require complex boilerplates, rigid APIs, or verbose configurations. They frequently lack declarative multi-cell grid merges across rows (rowspan) and columns (colspan), inline typography controls, and the ability to compile directly into both web layouts and native Excel spreadsheets.

TenTags solves this by providing a clean, expressive domain-specific language (DSL). By combining a custom lexer, tokenizer, and intermediate AST model (TableModel) with dual rendering backends, TenTags gives you:

• 🔀 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>), horizontal alignment (<left>, <center>, <right>), text color (<color=>), and cell fills (<bg=>).
• 📊 Dual Backend Rendering: Compile your markup directly to high-fidelity HTML strings (render_html) or native Excel (.xlsx) spreadsheets (render_xlsx) with faithful openpyxl grid merges (ws.merge_cells) and fills.
• ⚡ Zero Core Dependencies: Pure Python runtime (xml.etree.ElementTree) for DSL parsing and HTML rendering. Optional Excel export via openpyxl.

---

⚡ Quick Code → Result

Write this concise, expressive TenTags formula:

import tentags

formula = '''3,2,1,"#cbd5e1","solid",0,40, data(
    <fs=16><bg=#1e293b><color=white><b><cm><center>Quarter Report, ,</center></cm></b></color></bg></fs>;
    <b>Sales</b>, <right>"$120,000"</right>;
    <b>Marketing</b>, <right>"$80,000"</right>
)'''

# 1. Render directly to high-fidelity HTML string
html_table = tentags.render(formula)

# 2. Or export directly to native Excel (.xlsx)
model = tentags.parse(formula)
tentags.render_xlsx(model, "Quarter_Report.xlsx")

↓ Faithful Visual Output across both HTML & Excel (.xlsx):

Quarter Report (Merged across 2 columns (<cm>), 16px Bold White text, Dark Slate #1e293b fill)	—
Sales (Bold)	$120,000 (Right aligned)
Marketing (Bold)	$80,000 (Right aligned)

---

🏷️ The 10 Tags in data(...)

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

#	Tag / Syntax	Type	Description	Example
1	<fs=...>	Typography	Sets custom font size (font-size in HTML, size in Excel openpyxl).	data(<fs=16>Heading</fs>, Text)
2	<b>...</b>	Typography	Renders cell text in Bold font weight (font-weight: bold).	data(<b>Total</b>, 100)
3	<i>...</i>	Typography	Renders cell text in Italic font style (font-style: italic).	data(<i>Pending</i>, Done)
4	<left>	Alignment	Aligns cell content to the left (text-align: left).	data(<left>Left aligned text)
5	<center>	Alignment	Aligns cell content to the center (text-align: center).	data(<center>Centered text)
6	<right>	Alignment	Aligns cell content to the right (text-align: right).	data(<right>Right aligned $5,000)
7	<color=...>	Text Color	Sets custom HEX or CSS text color (color: ... / font color).	data(<color=#ef4444>Error</color>, OK)
8	<bg=...>	Background Fill	Sets cell background fill color (background-color: ... / PatternFill).	data(<bg=#f8fafc>Summary</bg>, $500)
9	<cm>...</cm>	Column Merge	Merges the cell rightward with adjacent columns (colspan).	data(<cm>Merged Title, ,</cm>; A, B)
10	<rm>...</rm>	Row Merge	Merges the cell downward with rows below it (rowspan).	data(<rm>Date</rm>, Job; , Engineer)

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.

---

📦 Installation

Install from PyPI via pip:

pip install tentags

If you plan to export directly to Excel (.xlsx), install the optional excel dependency:

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

---

🎨 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>
)'''

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

# 2. 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>
)'''

# Export to a native Excel spreadsheet (.xlsx) with true merged regions & fills
model = tentags.parse(excel_formula)
tentags.render_xlsx(model, "Enterprise_Budget_Matrix.xlsx")

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

#	Tag / Syntax	Type	Description	Example
1	<fs=...>	Typography	Sets custom font size (font-size in HTML, size in Excel openpyxl).	data(<fs=16>Heading</fs>, Text)
2	<b>...</b>	Typography	Renders cell text in Bold font weight (font-weight: bold).	data(<b>Total</b>, 100)
3	<i>...</i>	Typography	Renders cell text in Italic font style (font-style: italic).	data(<i>Pending</i>, Done)
4	<left>	Alignment	Aligns cell content to the left (text-align: left).	data(<left>Left aligned text)
5	<center>	Alignment	Aligns cell content to the center (text-align: center).	data(<center>Centered text)
6	<right>	Alignment	Aligns cell content to the right (text-align: right).	data(<right>Right aligned $5,000)
7	<color=...>	Text Color	Sets custom HEX or CSS text color (color: ... / font color).	data(<color=#ef4444>Error</color>, OK)
8	<bg=...>	Background Fill	Sets cell background fill color (background-color: ... / PatternFill).	data(<bg=#f8fafc>Summary</bg>, $500)
9	<cm>...</cm>	Column Merge	Merges the cell rightward with adjacent columns (colspan).	data(<cm>Merged Title</cm>, None; A, B)
10	<rm>...</rm>	Row Merge	Merges the cell downward with rows below it (rowspan).	data(<rm>Date</rm>, Job; <cm>, Engineer)

Note on Tag Transfer: When merging (<cm>, <rm>) or expanding ranges across styled cells (<fs>, <b>, <i>, <color>, <bg>, <left>, <center>, <right>), TenTags automatically transfers and preserves all formatting across cell boundaries in both HTML and Excel outputs.

Dynamic Data Expressions: In addition to the 10 markup tags above, TenTags data(...) supports dynamic line numbering (#), variable context substitution (VarName), CSV URL/file import (csv(...)), and cell range expansion (A1:B3).

---

🛠️ API Reference

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

Parses the input DSL formula string and returns a complete <table>...</table> HTML string.

• formula: String in format 'rows, cols, border_width, "border_color", "border_style", margin, row_height, data(...)'.
• 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.render_html(model: TableModel) -> str

Renders a previously parsed TableModel instance into an HTML string.

tentags.render_xlsx(model: TableModel, output_filename: str) -> 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.

---

🧪 Running Tests

To run the standalone test suite and generate sample visual outputs (test_output.html, test_output.xlsx, test_style_output.xlsx):

python test_library.py

---

📄 License

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