Metadata-Version: 2.4
Name: tentags
Version: 0.1.1
Summary: Advanced Table Markdown for HTML & Excel spreadsheets with rich styling and multi-cell merge grids using 10 core tags.
Author-email: Zhandos Mambetali <zhandos.mambetali@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://pycells.com
Project-URL: Documentation, https://pycells.com/tentags
Project-URL: Repository, https://github.com/Jandos77/tentags
Project-URL: Issues, https://github.com/Jandos77/tentags/issues
Keywords: html,excel,xlsx,table,generator,spreadsheet,pycells,tags,parser
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == "excel"
Requires-Dist: et_xmlfile>=2.0.0; extra == "excel"
Provides-Extra: dev
Requires-Dist: openpyxl>=3.1.0; extra == "dev"
Requires-Dist: et_xmlfile>=2.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# TenTags 🏷️

<p align="center">
  <a href="https://pycells.com">
    <img src="https://pycells.com/assets/img/tentags_logo.png" width="600" alt="TenTags logo">
  </a>
</p>

[![PyPI version](https://img.shields.io/pypi/v/tentags.svg)](https://pypi.org/project/tentags/)
[![Python versions](https://img.shields.io/pypi/pyversions/tentags.svg)](https://pypi.org/project/tentags/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**TenTags** is a standalone, zero-dependency **Advanced Table Markdown** library for Python. It turns compact, expressive string formulas into pixel-perfect **HTML** and native **Excel (`.xlsx`)** spreadsheets using **10 core structural and styling tags**.

### 💡 Why TenTags? (Advanced Markdown for Tables)

Standard Markdown (`| A | B |`) is notoriously rigid when it comes to tables: it cannot merge complex cell grids across rows (`rowspan`) or columns (`colspan`), it lacks background fills and typography controls, and it cannot compile directly to native Excel spreadsheets.

**TenTags** bridges this gap. Think of it as **next-generation Table Markdown** that gives you:
- 🔀 **Advanced 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=>`).
- 📊 **Native Excel Export**: Directly compiles your markup into styled, production-ready `.xlsx` files with exact `openpyxl` grid merges (`ws.merge_cells`), font weights, text alignments, and pattern fills.
- ⚡ **Zero Core Dependencies**: Pure Python runtime (`xml.etree.ElementTree`) that tokenizes and parses at lightning speed.

---

## 📦 Installation

Install from PyPI via pip:

```bash
pip install tentags
```

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

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

---

## 🚀 Quickstart

```python
import tentags

# Define a table expression with custom border color, background fill, and tags
formula = '2,2,1,"#0f172a","solid",0,40, data(Header 1, <b>Header 2</b>; <color=red><i>Red Italic</i></color>, <bg=#e2e8f0>Gray Cell</bg>)'

# 1. Direct rendering to HTML string
html = tentags.render(formula)
print(html)

# 2. Parsing to intermediate TableModel
model = tentags.parse(formula)
print(f"Rows: {model.rows}, Cols: {model.cols}, Border: {model.border_color}")

# 3. Render TableModel to Excel (.xlsx) file
tentags.render_xlsx(model, "styled_report.xlsx")
```

---

## 🎨 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`)**:

```python
import tentags

# Define an advanced 4x4 styled financial performance grid
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>, None, None, None;
    <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:

| Department / Header | Revenue | Expenses | Net Profit |
| :--- | :---: | :---: | :---: |
| **Q3 Financial Performance Dashboard** *(Merged across 4 columns (`colspan=4`), 18px Bold, White text, Dark Slate `#1e293b` background)* | — | — | — |
| **Department** *(Left aligned, Light Gray `#f1f5f9` BG)* | **Revenue** *(Centered, Bold)* | **Expenses** *(Centered, Bold)* | **Net Profit** *(Centered, Bold)* |
| Engineering *(Left aligned)* | $240,000 *(Right aligned)* | $180,000 *(Right aligned)* | **+$60,000** *(Right aligned, Bold, Green `#dcfce7` BG, Dark Green text)* |
| Sales & Marketing *(Left aligned)* | $310,000 *(Right aligned)* | $210,000 *(Right aligned)* | **+$100,000** *(Right aligned, Bold, Green `#dcfce7` BG, Dark Green text)* |

---

## 📊 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>`), and classic Microsoft Excel color palettes (`#1F4E78`, `#DDEBF7`, `#E2EFDA`, `#FFF2CC`):

```python
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, None, None, None, None</cm></b></color></bg></fs>;
    <bg=#DDEBF7><b><rm><center>Category</center></rm></b></bg>, <bg=#DDEBF7><b><cm><center>Q1 & Q2 Allocation</center>, None</cm></b></bg>, <bg=#DDEBF7><b><cm><center>Q3 & Q4 Allocation</center>, None</cm></b></bg>;
    <bg=#DDEBF7><b><rm>None</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>, None</cm></b></color></bg>, <bg=#E2EFDA><color=#375623><b><cm><right>"+$215,000"</right>, None</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`):

<p align="center">
  <img src="https://pycells.com/assets/img/example.png" alt="TenTags Excel Matrix Output" width="750">
</p>

Notice how `None` is passed in slots that get swallowed by an adjacent cell's `<cm>` horizontal merge or `<rm>` vertical merge. When opened in Microsoft Excel or rendered in HTML, the boundaries cleanly dissolve into unified multi-cell headers and summary blocks!

---

## 🏷️ 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>, 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`):

```bash
python test_library.py
```

---

## 📄 License

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