pl2html 0.1.0__tar.gz → 0.2.0__tar.gz

pl2html-0.2.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.3
+Name: pl2html
+Version: 0.2.0
+Summary: Add your description here
+Requires-Dist: polars>=1.42.1
+Requires-Python: >=3.14
+Project-URL: GitHub, https://github.com/5j9/pl2html
+Description-Content-Type: text/markdown
+
+# pl2html
+
+A fast, secure, and zero-dependency HTML engine for Polars. 
+
+`pl2html` compiles Polars `DataFrame` and `LazyFrame` workflows natively into HTML table structures entirely inside the Polars expression engine. By leveraging parallelized Rust memory environments, it bypasses slow Python row loops (`.map_elements`), making it an incredibly lightweight alternative to styling engines like `great_tables` or pandas `.style`.
+
+## Features
+
+* 🚀 **Native Polars Performance**: Runs entirely inside the Polars expression graph. Streamable and lazy-execution friendly.
+* 🛡️ **Injection-Safe by Default**: Automatically neutralizes sequential HTML injection vectors using a lookahead-free, native escaping algorithm.
+* 🎨 **Advanced Formatting Toolkit**: Human-readable display rules for numbers, integers, currencies, percentages, scientific notations, bytes, and booleans running entirely in Rust.
+* ➡️ **Multicolumn Support**: All formatting and substitution functions accept a single column string or an iterable list of columns automatically.
+* 🌗 **Conditional Styling & Color Scales**: Native linear interpolation pipelines to generate multi-segment background color heatmaps by value or percentile rank.
+* 🌌 **Auto-Contrast Accessibility**: Dynamic text foreground switches (`#000000` vs `#FFFFFF`) calculated via WCAG relative luminance algorithms on the fly.
+* 📦 **Afraid of Bloat? Zero Dependencies**: Cleaned of heavy packages like `numpy` or `matplotlib`. It runs entirely on pure Python and Polars.
+
+---
+
+## Installation
+
+```bash
+pip install pl2html
+```
+
+---
+
+## Quick Start
+
+### 1. Basic HTML Rendering with Auto-Escaping
+By default, `pl2html` infers datatypes to securely render human-readable tables. Strings are escaped, and integers/floats automatically get localized thousands separators.
+
+```python
+import polars as pl
+from pl2html import to_html
+
+df = pl.DataFrame(
+    {
+        'company': ["<script>alert('malicious')</script> Corp", 'Acme Inc.'],
+        'revenue': [1420500, -50200],
+        'margin': [0.0451, -0.0512],
+    }
+)
+
+# Compiles safely to a Polars LazyFrame containing the HTML output
+html_lazy = to_html(df)
+
+# Collect and extract the compiled string
+html_table_string = html_lazy.collect().item()
+print(html_table_string)
+```
+
+Output:
+
+<table>
+ <thead>
+  <tr>
+   <th>company</th>
+   <th>revenue</th>
+   <th>margin</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr><td>&lt;script&gt;alert(&#x27;malicious&#x27;)&lt;/script&gt; Corp</td><td>1,420,500</td><td>0.045</td></tr>
+  <tr><td>Acme Inc.</td><td>-50,200</td><td>-0.051</td></tr>
+ </tbody>
+</table>
+
+
+### 2. Rich Data Formatting (Natively Vectorized)
+`pl2html` exposes high-performance formatting expressions designed to prepare columns simultaneously before passing them to `to_html`. Every function natively supports passing lists of multiple columns at once.
+
+```python
+import polars as pl
+from pl2html import to_html
+from pl2html import formats as fmt
+
+df = pl.DataFrame(
+    {
+        "asset_a": [5400600, 2100],
+        "asset_b": [45100000, -850000],
+        "growth": [0.1256, -0.024],
+        "is_active": [True, False],
+        "status_code": [0, 404]
+    }
+)
+
+# Format multiple financial asset columns compactly in one pass using lists
+df_f = df.with_columns(
+    fmt.fmt_integer(["asset_a", "asset_b"], compact=True, compact_system="financial"),
+    fmt.fmt_percent("growth", decimals=1),
+    fmt.fmt_tf("is_active", tf_style="check-mark"),
+    fmt.sub_zero("status_code", zero_text="OK")
+)
+
+html = to_html(df_f).collect().item()
+```
+
+### 3. Advanced Styling via Native Attributes (`attrs`)
+Instead of embedding hacky structural HTML tags in your data, use the `attrs` parameter to inject dynamic CSS attributes purely. Use `data_color` or `rank_color` to construct high-performance heatmaps.
+
+```python
+import polars as pl
+from pl2html import to_html
+from pl2html.styles import data_color, rank_color
+
+df = pl.DataFrame(
+    {
+        'employee': ['Alice', 'Bob', 'Charlie', 'David'],
+        'performance_score': [98.5, 42.0, 81.2, 12.0],
+        'utilization': [0.02, 0.41, 0.78, 0.22],
+    }
+)
+
+styles = {}
+
+# 1. Color Heatmap by Absolute Value (Custom 3-color palette with auto-contrast text)
+styles.update(
+    data_color(
+        column='performance_score',
+        palette=['#ff7675', '#fdcb6e', '#00b894'],
+        auto_contrast=True
+    )
+)
+
+# 2. Color Heatmap by Percentile Rank Order (Continuous interpolation)
+styles.update(
+    rank_color(
+        column='utilization',
+        palette=['#000000', '#FFFFFF'],
+        descending=False,
+        auto_contrast=True
+    )
+)
+
+html_table = to_html(df, attrs=styles).collect().item()
+```
+
+Output (github may override table colors, but they are there):
+
+
+<table>
+ <thead>
+  <tr>
+   <th>employee</th>
+   <th>performance_score</th>
+   <th>utilization</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr><td>Alice</td><td style="background-color: rgb(0,184,148); color: #000000;">98.5</td><td style="background-color: rgb(255,255,255); color: #000000;">0.92</td></tr>
+  <tr><td>Bob</td><td style="background-color: rgb(254,177,112); color: #000000;">42.0</td><td style="background-color: rgb(85,85,85); color: #FFFFFF;">0.41</td></tr>
+  <tr><td>Charlie</td><td style="background-color: rgb(101,192,133); color: #000000;">81.2</td><td style="background-color: rgb(170,170,170); color: #000000;">0.78</td></tr>
+  <tr><td>David</td><td style="background-color: rgb(255,118,117); color: #000000;">12.0</td><td style="background-color: rgb(0,0,0); color: #FFFFFF;">0.22</td></tr>
+ </tbody>
+</table>
+
+---
+
+## Architecture & Module Layout
+
+The library is explicitly divided into three decoupled layers:
+
+### 1. Core Compiler (`__init__.py`)
+Responsible for reading the dataframe schema, iterating horizontally over visible columns, and joining tokens into structural row arrays natively in Rust. 
+* Exposed via `to_html(df, *, attrs=None, exclude_columns=None)`.
+* Automatically assigns high-performance format fallbacks:
+  * `is_integer()`: Applies thousands separator reversals.
+  * `is_float()`: Automatically base-truncates decimal positions and breaks layout chunks smoothly.
+  * *Catchall*: Direct pass through `_escape_polars_string()` to secure against cross-site scripting (XSS).
+
+### 2. Format Expressions (`formats.py`)
+Contains native string-shaping expression generators wrapped in a `@_multicolumn` macro to cleanly display large datasets without dropping into slow Python loops.
+* `fmt_number()` / `fmt_integer()`: Supports precision rounding, thousands separators, accounting parentheses, and financial/engineering compact suffixing (`K`, `M`, `B` vs `k`, `M`, `G`).
+* `fmt_percent()` / `fmt_currency()`: Optimized wrappers handling percentage scaling and currency masking.
+* `fmt_scientific()`: Natively parses mantissas and exponents with flexible styling (`x10n`, `e`, `E`) and forced signs.
+* `fmt_bytes()`: Dynamically maps byte magnitudes to decimal (`kB`, `MB`) or binary (`KiB`, `MiB`) notations.
+* `fmt_tf()`: Transforms booleans to presets (`arrows`, `check-mark`, `circles`) with native `na_val` null overrides.
+* `sub_missing()` / `sub_zero()`: Clean conditional data substitution expressions for nulls and exact zeros.
+
+### 3. Style Utilities (`styles.py`)
+Generates structural Polars expression payloads mapped to specific HTML style attributes.
+* `data_color(column, palette, domain=None, auto_contrast=True)`: Evaluates column boundaries (`.min()` / `.max()`) at evaluation time and maps row values via piece-wise linear RGB interpolation.
+* `rank_color(column, palette, descending=False, auto_contrast=True)`: Replaces absolute numerical scaling with ordinal percentile ranks to smooth out heavily skewed datasets or extreme outliers.
+
+**Every style output returns a clean nested dictionary structure (`{column: {attribute: expression}}`) to feed directly into `to_html(attrs=...)`.**
+
+---
+
+## Security
+
+`pl2html` passes untrusted data arrays through a strict sequential escaping chain natively in Rust:
+```python
+.str.replace_all('&', '&amp;')
+.str.replace_all('<', '&lt;')
+.str.replace_all('>', '&gt;')
+.str.replace_all('"', '&quot;')
+.str.replace_all("'", '&#x27;')
+```

pl2html-0.2.0/README.md

@@ -0,0 +1,198 @@
+# pl2html
+
+A fast, secure, and zero-dependency HTML engine for Polars. 
+
+`pl2html` compiles Polars `DataFrame` and `LazyFrame` workflows natively into HTML table structures entirely inside the Polars expression engine. By leveraging parallelized Rust memory environments, it bypasses slow Python row loops (`.map_elements`), making it an incredibly lightweight alternative to styling engines like `great_tables` or pandas `.style`.
+
+## Features
+
+* 🚀 **Native Polars Performance**: Runs entirely inside the Polars expression graph. Streamable and lazy-execution friendly.
+* 🛡️ **Injection-Safe by Default**: Automatically neutralizes sequential HTML injection vectors using a lookahead-free, native escaping algorithm.
+* 🎨 **Advanced Formatting Toolkit**: Human-readable display rules for numbers, integers, currencies, percentages, scientific notations, bytes, and booleans running entirely in Rust.
+* ➡️ **Multicolumn Support**: All formatting and substitution functions accept a single column string or an iterable list of columns automatically.
+* 🌗 **Conditional Styling & Color Scales**: Native linear interpolation pipelines to generate multi-segment background color heatmaps by value or percentile rank.
+* 🌌 **Auto-Contrast Accessibility**: Dynamic text foreground switches (`#000000` vs `#FFFFFF`) calculated via WCAG relative luminance algorithms on the fly.
+* 📦 **Afraid of Bloat? Zero Dependencies**: Cleaned of heavy packages like `numpy` or `matplotlib`. It runs entirely on pure Python and Polars.
+
+---
+
+## Installation
+
+```bash
+pip install pl2html
+```
+
+---
+
+## Quick Start
+
+### 1. Basic HTML Rendering with Auto-Escaping
+By default, `pl2html` infers datatypes to securely render human-readable tables. Strings are escaped, and integers/floats automatically get localized thousands separators.
+
+```python
+import polars as pl
+from pl2html import to_html
+
+df = pl.DataFrame(
+    {
+        'company': ["<script>alert('malicious')</script> Corp", 'Acme Inc.'],
+        'revenue': [1420500, -50200],
+        'margin': [0.0451, -0.0512],
+    }
+)
+
+# Compiles safely to a Polars LazyFrame containing the HTML output
+html_lazy = to_html(df)
+
+# Collect and extract the compiled string
+html_table_string = html_lazy.collect().item()
+print(html_table_string)
+```
+
+Output:
+
+<table>
+ <thead>
+  <tr>
+   <th>company</th>
+   <th>revenue</th>
+   <th>margin</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr><td>&lt;script&gt;alert(&#x27;malicious&#x27;)&lt;/script&gt; Corp</td><td>1,420,500</td><td>0.045</td></tr>
+  <tr><td>Acme Inc.</td><td>-50,200</td><td>-0.051</td></tr>
+ </tbody>
+</table>
+
+
+### 2. Rich Data Formatting (Natively Vectorized)
+`pl2html` exposes high-performance formatting expressions designed to prepare columns simultaneously before passing them to `to_html`. Every function natively supports passing lists of multiple columns at once.
+
+```python
+import polars as pl
+from pl2html import to_html
+from pl2html import formats as fmt
+
+df = pl.DataFrame(
+    {
+        "asset_a": [5400600, 2100],
+        "asset_b": [45100000, -850000],
+        "growth": [0.1256, -0.024],
+        "is_active": [True, False],
+        "status_code": [0, 404]
+    }
+)
+
+# Format multiple financial asset columns compactly in one pass using lists
+df_f = df.with_columns(
+    fmt.fmt_integer(["asset_a", "asset_b"], compact=True, compact_system="financial"),
+    fmt.fmt_percent("growth", decimals=1),
+    fmt.fmt_tf("is_active", tf_style="check-mark"),
+    fmt.sub_zero("status_code", zero_text="OK")
+)
+
+html = to_html(df_f).collect().item()
+```
+
+### 3. Advanced Styling via Native Attributes (`attrs`)
+Instead of embedding hacky structural HTML tags in your data, use the `attrs` parameter to inject dynamic CSS attributes purely. Use `data_color` or `rank_color` to construct high-performance heatmaps.
+
+```python
+import polars as pl
+from pl2html import to_html
+from pl2html.styles import data_color, rank_color
+
+df = pl.DataFrame(
+    {
+        'employee': ['Alice', 'Bob', 'Charlie', 'David'],
+        'performance_score': [98.5, 42.0, 81.2, 12.0],
+        'utilization': [0.02, 0.41, 0.78, 0.22],
+    }
+)
+
+styles = {}
+
+# 1. Color Heatmap by Absolute Value (Custom 3-color palette with auto-contrast text)
+styles.update(
+    data_color(
+        column='performance_score',
+        palette=['#ff7675', '#fdcb6e', '#00b894'],
+        auto_contrast=True
+    )
+)
+
+# 2. Color Heatmap by Percentile Rank Order (Continuous interpolation)
+styles.update(
+    rank_color(
+        column='utilization',
+        palette=['#000000', '#FFFFFF'],
+        descending=False,
+        auto_contrast=True
+    )
+)
+
+html_table = to_html(df, attrs=styles).collect().item()
+```
+
+Output (github may override table colors, but they are there):
+
+
+<table>
+ <thead>
+  <tr>
+   <th>employee</th>
+   <th>performance_score</th>
+   <th>utilization</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr><td>Alice</td><td style="background-color: rgb(0,184,148); color: #000000;">98.5</td><td style="background-color: rgb(255,255,255); color: #000000;">0.92</td></tr>
+  <tr><td>Bob</td><td style="background-color: rgb(254,177,112); color: #000000;">42.0</td><td style="background-color: rgb(85,85,85); color: #FFFFFF;">0.41</td></tr>
+  <tr><td>Charlie</td><td style="background-color: rgb(101,192,133); color: #000000;">81.2</td><td style="background-color: rgb(170,170,170); color: #000000;">0.78</td></tr>
+  <tr><td>David</td><td style="background-color: rgb(255,118,117); color: #000000;">12.0</td><td style="background-color: rgb(0,0,0); color: #FFFFFF;">0.22</td></tr>
+ </tbody>
+</table>
+
+---
+
+## Architecture & Module Layout
+
+The library is explicitly divided into three decoupled layers:
+
+### 1. Core Compiler (`__init__.py`)
+Responsible for reading the dataframe schema, iterating horizontally over visible columns, and joining tokens into structural row arrays natively in Rust. 
+* Exposed via `to_html(df, *, attrs=None, exclude_columns=None)`.
+* Automatically assigns high-performance format fallbacks:
+  * `is_integer()`: Applies thousands separator reversals.
+  * `is_float()`: Automatically base-truncates decimal positions and breaks layout chunks smoothly.
+  * *Catchall*: Direct pass through `_escape_polars_string()` to secure against cross-site scripting (XSS).
+
+### 2. Format Expressions (`formats.py`)
+Contains native string-shaping expression generators wrapped in a `@_multicolumn` macro to cleanly display large datasets without dropping into slow Python loops.
+* `fmt_number()` / `fmt_integer()`: Supports precision rounding, thousands separators, accounting parentheses, and financial/engineering compact suffixing (`K`, `M`, `B` vs `k`, `M`, `G`).
+* `fmt_percent()` / `fmt_currency()`: Optimized wrappers handling percentage scaling and currency masking.
+* `fmt_scientific()`: Natively parses mantissas and exponents with flexible styling (`x10n`, `e`, `E`) and forced signs.
+* `fmt_bytes()`: Dynamically maps byte magnitudes to decimal (`kB`, `MB`) or binary (`KiB`, `MiB`) notations.
+* `fmt_tf()`: Transforms booleans to presets (`arrows`, `check-mark`, `circles`) with native `na_val` null overrides.
+* `sub_missing()` / `sub_zero()`: Clean conditional data substitution expressions for nulls and exact zeros.
+
+### 3. Style Utilities (`styles.py`)
+Generates structural Polars expression payloads mapped to specific HTML style attributes.
+* `data_color(column, palette, domain=None, auto_contrast=True)`: Evaluates column boundaries (`.min()` / `.max()`) at evaluation time and maps row values via piece-wise linear RGB interpolation.
+* `rank_color(column, palette, descending=False, auto_contrast=True)`: Replaces absolute numerical scaling with ordinal percentile ranks to smooth out heavily skewed datasets or extreme outliers.
+
+**Every style output returns a clean nested dictionary structure (`{column: {attribute: expression}}`) to feed directly into `to_html(attrs=...)`.**
+
+---
+
+## Security
+
+`pl2html` passes untrusted data arrays through a strict sequential escaping chain natively in Rust:
+```python
+.str.replace_all('&', '&amp;')
+.str.replace_all('<', '&lt;')
+.str.replace_all('>', '&gt;')
+.str.replace_all('"', '&quot;')
+.str.replace_all("'", '&#x27;')
+```

{pl2html-0.1.0 → pl2html-0.2.0}/pl2html/__init__.py

@@ -1,9 +1,19 @@
-import polars as pl
-
-__version__ = '0.1.0'
-
-
-def _escape_polars_string(col_name: str) -> pl.Expr:
+from polars import (
+    DataFrame as _DataFrame,
+    DataType as _DataType,
+    Expr as _Expr,
+    LazyFrame as _LazyFrame,
+    String as _String,
+    col as _col,
+    concat_str as _concat_str,
+    lit as _lit,
+    when as _when,
+)
+
+__version__ = '0.2.0'
+
+
+def _escape_polars_string(col_name: str) -> _Expr:
     """
     Escapes a column's string representations for secure HTML compatibility.
     Because standard HTML entities use look-arounds or loops, we can fall back to
@@ -11,8 +21,8 @@ def _escape_polars_string(col_name: str) -> pl.Expr:
     but basic safety replaces characters sequentially.
     """
     return (
-        pl.col(col_name)
-        .cast(pl.String)
+        _col(col_name)
+        .cast(_String)
         .str.replace_all('&', '&')
         .str.replace_all('<', '&lt;')
         .str.replace_all('>', '&gt;')
@@ -21,12 +31,12 @@ def _escape_polars_string(col_name: str) -> pl.Expr:
     )
 
 
-def _format_integer(col_name: str) -> pl.Expr:
+def _format_integer(col_name: str) -> _Expr:
     """Adds thousands separators to integers using look-around-free logic."""
     return (
-        pl.col(col_name)
+        _col(col_name)
         .fill_null(0)
-        .cast(pl.String)
+        .cast(_String)
         .str.reverse()
         .str.replace_all(r'\d{3}', '$0,')
         .str.reverse()
@@ -35,9 +45,9 @@ def _format_integer(col_name: str) -> pl.Expr:
     )
 
 
-def _format_float(col_name: str) -> pl.Expr:
+def _format_float(col_name: str) -> _Expr:
     """Formats floats with 3 decimals and thousands separators."""
-    rounded_str = pl.col(col_name).round(3).cast(pl.String)
+    rounded_str = _col(col_name).round(3).cast(_String)
     int_part = rounded_str.str.split_exact('.', 1).struct.field('field_0')
     dec_part = rounded_str.str.split_exact('.', 1).struct.field('field_1')
 
@@ -50,17 +60,17 @@ def _format_float(col_name: str) -> pl.Expr:
     )
 
     return (
-        pl.when(dec_part.is_not_null() & (dec_part != ''))
-        .then(formatted_int + pl.lit('.') + dec_part)
+        _when(dec_part.is_not_null() & (dec_part != ''))
+        .then(formatted_int + _lit('.') + dec_part)
         .otherwise(formatted_int)
     )
 
 
 def _build_cell_expr(
     col_name: str,
-    dtype: pl.DataType,
-    attrs: dict[str, dict[str, pl.Expr]],
-) -> pl.Expr:
+    dtype: _DataType,
+    attrs: dict[str, dict[str, _Expr]],
+) -> _Expr:
     """
     Applies secure auto-escaping or data formatting overrides, then dynamically
     compiles HTML attributes into a valid single opening <td> tag block.
@@ -81,54 +91,47 @@ def _build_cell_expr(
         for attr_name, val_expr in attrs[col_name].items():
             # If the expression returns null or empty for a specific row, skip writing the attribute
             compiled_attr = (
-                pl.when(val_expr.is_not_null() & (val_expr != ''))
+                _when(val_expr.is_not_null() & (val_expr != ''))
                 .then(
-                    pl.lit(f' {attr_name}="')
-                    + val_expr.cast(pl.String)
-                    + pl.lit('"')
+                    _lit(f' {attr_name}="')
+                    + val_expr.cast(_String)
+                    + _lit('"')
                 )
-                .otherwise(pl.lit(''))
+                .otherwise(_lit(''))
             )
             attr_expr_list.append(compiled_attr)
 
     # Combine attribute strings together
     if attr_expr_list:
-        opening_td = (
-            pl.lit('<td') + pl.concat_str(attr_expr_list) + pl.lit('>')
-        )
+        opening_td = _lit('<td') + _concat_str(attr_expr_list) + _lit('>')
     else:
-        opening_td = pl.lit('<td>')
+        opening_td = _lit('<td>')
 
-    return opening_td + fmt_expr + pl.lit('</td>')
+    return opening_td + fmt_expr + _lit('</td>')
 
 
-def _build_html_skeleton(
-    visible_columns: list[str], add_row_no: bool
-) -> tuple[pl.Expr, pl.Expr]:
+def _build_html_skeleton(visible_columns: list[str]) -> tuple[_Expr, _Expr]:
     header_parts = ['<table>', '  <thead>\n    <tr>']
-    if add_row_no:
-        header_parts.append('      <th>#</th>')
     for c in visible_columns:
         header_parts.append(f'      <th>{c}</th>')
     header_parts.append('    </tr>\n  </thead>\n  <tbody>')
 
-    html_header = pl.lit('\n'.join(header_parts) + '\n')
-    html_footer = pl.lit('\n  </tbody>\n</table>')
+    html_header = _lit('\n'.join(header_parts) + '\n')
+    html_footer = _lit('\n  </tbody>\n</table>')
     return html_header, html_footer
 
 
 def to_html(
-    df: pl.DataFrame | pl.LazyFrame,
+    df: _DataFrame | _LazyFrame,
     *,
-    attrs: dict[str, dict[str, pl.Expr]] | None = None,
+    attrs: dict[str, dict[str, _Expr]] | None = None,
     exclude_columns: list[str] | None = None,
-    add_row_no: bool = True,
-) -> pl.LazyFrame:
+) -> _LazyFrame:
     """
     Compiles a Polars DataFrame safely into an HTML string layout.
     Accepts structural custom attributes mappings to handle layout modifications natively.
     """
-    lf = df.lazy() if isinstance(df, pl.DataFrame) else df
+    lf = df.lazy() if isinstance(df, _DataFrame) else df
 
     exclude_columns = exclude_columns or []
     attrs = attrs or {}
@@ -138,31 +141,18 @@ def to_html(
 
     cell_expressions = []
 
-    # 1. Row Index Element Processing
-    if add_row_no:
-        index_expr = (
-            pl.lit('<td>')
-            + (pl.arange(1, pl.len() + 1).cast(pl.String))
-            + pl.lit('</td>')
-        )
-        cell_expressions.append(index_expr)
-
     # 2. Map structural cell loops
     for c in visible_columns:
         cell_expressions.append(_build_cell_expr(c, schema[c], attrs))
 
     # 3. Concatenate columns horizontally into rows
-    row_expr = (
-        pl.lit('    <tr>') + pl.concat_str(cell_expressions) + pl.lit('</tr>')
-    )
+    row_expr = _lit('    <tr>') + _concat_str(cell_expressions) + _lit('</tr>')
 
     # 4. Generate wrappers and frame the query graph
-    html_header, html_footer = _build_html_skeleton(
-        visible_columns, add_row_no
-    )
+    html_header, html_footer = _build_html_skeleton(visible_columns)
 
     return lf.select(row_expr.alias('html_row')).select(
-        (html_header + pl.col('html_row').str.join('\n') + html_footer).alias(
+        (html_header + _col('html_row').str.join('\n') + html_footer).alias(
             'html_table'
         )
     )

pl2html-0.2.0/pl2html/formats.py

@@ -0,0 +1,475 @@
+from collections.abc import Iterable as _Iterable
+from functools import wraps as _wraps
+from typing import Literal as _Literal
+
+from polars import (
+    Expr as _Expr,
+    Float64 as _Float64,
+    Int32 as _Int32,
+    Int64 as _Int64,
+    String as _String,
+    col as _col,
+    lit as _lit,
+    when as _when,
+)
+
+
+# --- 0. Decorator to cleanly support single or multiple columns ---
+def _multicolumn(func):
+    @_wraps(func)
+    def wrapper(columns: str | _Iterable[str], *args, **kwargs):
+        if isinstance(columns, str):
+            return func(columns, *args, **kwargs)
+        # Automatically alias each expression to its original column name
+        # so Polars knows exactly which column to overwrite/create.
+        return [func(col, *args, **kwargs).alias(col) for col in columns]
+
+    return wrapper
+
+
+# --- 1. Formatter Implementation Block ---
+
+_Columns = str | list[str]
+
+
+@_multicolumn
+def fmt_number(
+    columns: _Columns,
+    decimals: int = 2,
+    scale_by: float = 1.0,
+    compact: bool = False,
+    compact_system: _Literal['financial', 'engineering'] = 'financial',
+    use_seps: bool = True,
+    accounting: bool = False,
+    pattern: str = '{x}',
+) -> _Expr:
+    """
+    Highly optimized, native Polars numeric formatter matching great_tables features.
+    Runs entirely in the parallel Rust engine without dropping into Python row loops.
+    """
+    val = _col(columns)
+    if scale_by != 1.0:
+        val = val * scale_by
+
+    abs_val = val.abs()
+
+    # 1. Extract compact scaling suffix chain if enabled
+    if compact:
+        log10_expr = (
+            _when(abs_val > 0).then(abs_val.log10()).otherwise(_lit(0.0))
+        )
+        thousands_exponent = (log10_expr / 3.0).floor().cast(_Int32) * 3
+
+        if compact_system == 'engineering':
+            suffix_chain = (
+                _when(thousands_exponent == 3)
+                .then(_lit('k'))
+                .when(thousands_exponent == 6)
+                .then(_lit('M'))
+                .when(thousands_exponent == 9)
+                .then(_lit('G'))
+                .when(thousands_exponent == 12)
+                .then(_lit('T'))
+                .otherwise(_lit(''))
+            )
+        else:
+            suffix_chain = (
+                _when(thousands_exponent == 3)
+                .then(_lit('K'))
+                .when(thousands_exponent == 6)
+                .then(_lit('M'))
+                .when(thousands_exponent == 9)
+                .then(_lit('B'))
+                .when(thousands_exponent == 12)
+                .then(_lit('T'))
+                .otherwise(_lit(''))
+            )
+        divisor = _lit(10.0).pow(thousands_exponent.cast(_Float64))
+        val_scaled = val / divisor
+    else:
+        val_scaled = val
+        suffix_chain = _lit('')
+
+    # 2. Handle precision rounding and extract base components natively
+    epsilon = _when(val_scaled >= 0).then(_lit(1e-9)).otherwise(_lit(-1e-9))
+    rounded = (val_scaled + epsilon).round(decimals)
+
+    if decimals > 0:
+        int_part = rounded.cast(_Int64).abs().cast(_String)
+        full_str = rounded.abs().cast(_String)
+        frac_part = (
+            _when(full_str.str.contains(r'\.'))
+            .then(full_str.str.split('.').list.get(1).str.slice(0, decimals))
+            .otherwise(_lit(''))
+        ).str.pad_end(decimals, fill_char='0')
+
+        if use_seps:
+            int_part = (
+                int_part.str.reverse()
+                .str.replace_all(r'(\d{3})', r'${1},')
+                .str.strip_suffix(',')
+                .str.reverse()
+            )
+
+        base_num_str = int_part + _lit('.') + frac_part
+    else:
+        base_num_str = rounded.round(0).cast(_Int64).abs().cast(_String)
+        if use_seps:
+            base_num_str = (
+                base_num_str.str.reverse()
+                .str.replace_all(r'(\d{3})', r'${1},')
+                .str.strip_suffix(',')
+                .str.reverse()
+            )
+
+    base_num_str = base_num_str + suffix_chain
+
+    prefix, suffix = '', ''
+    if pattern != '{x}':
+        parts = pattern.split('{x}')
+        if len(parts) == 2:
+            prefix, suffix = parts[0], parts[1]
+
+    if accounting:
+        formatted_expr = (
+            _when(val < 0)
+            .then(
+                _lit('(')
+                + _lit(prefix)
+                + base_num_str
+                + _lit(suffix)
+                + _lit(')')
+            )
+            .otherwise(_lit(prefix) + base_num_str + _lit(suffix))
+        )
+    else:
+        formatted_expr = (
+            _when(val < 0)
+            .then(_lit('-') + _lit(prefix) + base_num_str + _lit(suffix))
+            .otherwise(_lit(prefix) + base_num_str + _lit(suffix))
+        )
+
+    return formatted_expr
+
+
+@_multicolumn
+def fmt_percent(
+    columns: _Columns, decimals: int = 2, use_seps: bool = True
+) -> _Expr:
+    """Formats columns as percentages, multiplying by 100 automatically."""
+    return fmt_number(
+        columns=columns,
+        decimals=decimals,
+        scale_by=100.0,
+        use_seps=use_seps,
+        pattern='{x}%',
+    )
+
+
+@_multicolumn
+def fmt_currency(
+    columns: _Columns,
+    symbol: str = '$',
+    decimals: int = 2,
+    use_seps: bool = True,
+    accounting: bool = True,
+) -> _Expr:
+    """Formats columns as localized currency values."""
+    return fmt_number(
+        columns=columns,
+        decimals=decimals,
+        use_seps=use_seps,
+        accounting=accounting,
+        pattern=f'{symbol}{{x}}',
+    )
+
+
+@_multicolumn
+def fmt_scientific(
+    columns: _Columns,
+    decimals: int = 2,
+    scale_by: float = 1.0,
+    exp_style: _Literal['x10n', 'e', 'E'] = 'x10n',
+    pattern: str = '{x}',
+    force_sign_m: bool = False,
+    force_sign_n: bool = False,
+) -> _Expr:
+    """Highly optimized scientific notation formatter."""
+    val = _col(columns)
+    if scale_by != 1.0:
+        val = val * scale_by
+
+    abs_val = val.abs()
+    log10_expr = _when(abs_val > 0).then(abs_val.log10()).otherwise(_lit(0.0))
+    exponent = log10_expr.floor().cast(_Int32)
+    exponent = _when(val == 0).then(_lit(0)).otherwise(exponent)
+
+    divisor = _lit(10.0).pow(exponent.cast(_Float64))
+    mantissa = val / divisor
+
+    epsilon = _when(mantissa >= 0).then(_lit(1e-9)).otherwise(_lit(-1e-9))
+    rounded_m = (mantissa + epsilon).round(decimals)
+
+    if decimals > 0:
+        int_m = rounded_m.cast(_Int64).abs().cast(_String)
+        full_str_m = rounded_m.abs().cast(_String)
+        frac_m = (
+            _when(full_str_m.str.contains(r'\.'))
+            .then(full_str_m.str.split('.').list.get(1).str.slice(0, decimals))
+            .otherwise(_lit(''))
+        ).str.pad_end(decimals, fill_char='0')
+        m_str = int_m + _lit('.') + frac_m
+    else:
+        m_str = rounded_m.round(0).cast(_Int64).abs().cast(_String)
+
+    m_str = (
+        _when(val < 0)
+        .then(_lit('-') + m_str)
+        .when((_lit(force_sign_m)) & (val > 0))
+        .then(_lit('+') + m_str)
+        .otherwise(m_str)
+    )
+
+    n_str = exponent.abs().cast(_String)
+    n_str = (
+        _when(exponent < 0)
+        .then(_lit('-') + n_str)
+        .when((_lit(force_sign_n)) & (exponent > 0))
+        .then(_lit('+') + n_str)
+        .otherwise(
+            _when(_lit(force_sign_n)).then(_lit('+') + n_str).otherwise(n_str)
+        )
+    )
+
+    if exp_style == 'x10n':
+        combined = m_str + _lit(' × 10^') + n_str
+    elif exp_style == 'E':
+        combined = m_str + _lit('E') + n_str
+    else:
+        combined = m_str + _lit('e') + n_str
+
+    prefix, suffix = '', ''
+    if pattern != '{x}':
+        parts = pattern.split('{x}')
+        if len(parts) == 2:
+            prefix, suffix = parts[0], parts[1]
+
+    return _lit(prefix) + combined + _lit(suffix)
+
+
+@_multicolumn
+def fmt_bytes(
+    columns: _Columns,
+    standard: _Literal['decimal', 'binary'] = 'decimal',
+    decimals: int = 1,
+    use_seps: bool = True,
+    pattern: str = '{x}',
+    force_sign: bool = False,
+    incl_space: bool = True,
+) -> _Expr:
+    """Highly optimized native bytes formatter."""
+    val = _col(columns)
+    abs_val = val.abs()
+
+    if standard == 'binary':
+        base = 1024.0
+        log_expr = (
+            _when(abs_val > 0).then(abs_val.log(2.0)).otherwise(_lit(0.0))
+        )
+        exponent_idx = (log_expr / 10.0).floor().cast(_Int32)
+        exponent_idx = (
+            _when(exponent_idx < 0).then(_lit(0)).otherwise(exponent_idx)
+        )
+        suffix_chain = (
+            _when(exponent_idx == 0)
+            .then(_lit('B'))
+            .when(exponent_idx == 1)
+            .then(_lit('KiB'))
+            .when(exponent_idx == 2)
+            .then(_lit('MiB'))
+            .when(exponent_idx == 3)
+            .then(_lit('GiB'))
+            .when(exponent_idx == 4)
+            .then(_lit('TiB'))
+            .when(exponent_idx == 5)
+            .then(_lit('PiB'))
+            .otherwise(_lit('B'))
+        )
+    else:
+        base = 1000.0
+        log_expr = (
+            _when(abs_val > 0).then(abs_val.log10()).otherwise(_lit(0.0))
+        )
+        exponent_idx = (log_expr / 3.0).floor().cast(_Int32)
+        exponent_idx = (
+            _when(exponent_idx < 0).then(_lit(0)).otherwise(exponent_idx)
+        )
+        suffix_chain = (
+            _when(exponent_idx == 0)
+            .then(_lit('B'))
+            .when(exponent_idx == 1)
+            .then(_lit('kB'))
+            .when(exponent_idx == 2)
+            .then(_lit('MB'))
+            .when(exponent_idx == 3)
+            .then(_lit('GB'))
+            .when(exponent_idx == 4)
+            .then(_lit('TB'))
+            .when(exponent_idx == 5)
+            .then(_lit('PB'))
+            .otherwise(_lit('B'))
+        )
+
+    divisor = _lit(base).pow(exponent_idx.cast(_Float64))
+    val_scaled = val / divisor
+
+    epsilon = _when(val_scaled >= 0).then(_lit(1e-9)).otherwise(_lit(-1e-9))
+    rounded = (val_scaled + epsilon).round(decimals)
+
+    if decimals > 0:
+        int_part = rounded.cast(_Int64).abs().cast(_String)
+        full_str = rounded.abs().cast(_String)
+        frac_part = (
+            _when(full_str.str.contains(r'\.'))
+            .then(full_str.str.split('.').list.get(1).str.slice(0, decimals))
+            .otherwise(_lit(''))
+        ).str.pad_end(decimals, fill_char='0')
+
+        if use_seps:
+            int_part = (
+                int_part.str.reverse()
+                .str.replace_all(r'(\d{3})', r'${1},')
+                .str.strip_suffix(',')
+                .str.reverse()
+            )
+        base_num_str = int_part + _lit('.') + frac_part
+    else:
+        base_num_str = rounded.round(0).cast(_Int64).abs().cast(_String)
+        if use_seps:
+            base_num_str = (
+                base_num_str.str.reverse()
+                .str.replace_all(r'(\d{3})', r'${1},')
+                .str.strip_suffix(',')
+                .str.reverse()
+            )
+
+    base_num_str = (
+        _when(val < 0)
+        .then(_lit('-') + base_num_str)
+        .when((_lit(force_sign)) & (val > 0))
+        .then(_lit('+') + base_num_str)
+        .otherwise(base_num_str)
+    )
+
+    space = _lit(' ') if incl_space else _lit('')
+    combined = base_num_str + space + suffix_chain
+
+    prefix, suffix = '', ''
+    if pattern != '{x}':
+        parts = pattern.split('{x}')
+        if len(parts) == 2:
+            prefix, suffix = parts[0], parts[1]
+
+    return _lit(prefix) + combined + _lit(suffix)
+
+
+@_multicolumn
+def fmt_tf(
+    columns: _Columns,
+    tf_style: _Literal[
+        'true-false',
+        'yes-no',
+        'up-down',
+        'check-mark',
+        'circles',
+        'squares',
+        'diamonds',
+        'arrows',
+        'triangles',
+        'triangles-lr',
+    ] = 'true-false',
+    pattern: str = '{x}',
+    true_val: str | None = None,
+    false_val: str | None = None,
+    na_val: str | None = None,
+) -> _Expr:
+    """Highly optimized native boolean layout mapper."""
+    style_map = {
+        'true-false': ('true', 'false'),
+        'yes-no': ('yes', 'no'),
+        'up-down': ('up', 'down'),
+        'check-mark': ('✓', '✗'),
+        'circles': ('●', '○'),
+        'squares': ('■', '□'),
+        'diamonds': ('◆', '◇'),
+        'arrows': ('↑', '↓'),
+        'triangles': ('▲', '▼'),
+        'triangles-lr': ('▶', '◀'),
+    }
+
+    preset_true, preset_false = style_map.get(tf_style, ('true', 'false'))
+    final_true = true_val if true_val is not None else preset_true
+    final_false = false_val if false_val is not None else preset_false
+
+    base_expr = (
+        _when(_col(columns))
+        .then(_lit(final_true))
+        .otherwise(_lit(final_false))
+    )
+
+    prefix, suffix = '', ''
+    if pattern != '{x}':
+        parts = pattern.split('{x}')
+        if len(parts) == 2:
+            prefix, suffix = parts[0], parts[1]
+
+    formatted_expr = _lit(prefix) + base_expr + _lit(suffix)
+
+    if na_val is not None:
+        return (
+            _when(_col(columns).is_null())
+            .then(_lit(na_val))
+            .otherwise(formatted_expr)
+        )
+    return (
+        _when(_col(columns).is_null())
+        .then(_lit(None))
+        .otherwise(formatted_expr)
+    )
+
+
+@_multicolumn
+def sub_missing(columns: _Columns, missing_text: str = '—') -> _Expr:
+    return _col(columns).fill_null(_lit(missing_text))
+
+
+@_multicolumn
+def sub_zero(columns: _Columns, zero_text: str = '—') -> _Expr:
+    return (
+        _when(_col(columns) == 0)
+        .then(_lit(zero_text))
+        .otherwise(_col(columns))
+    )
+
+
+@_multicolumn
+def fmt_integer(
+    columns: _Columns,
+    scale_by: float = 1.0,
+    compact: bool = False,
+    compact_system: _Literal['financial', 'engineering'] = 'financial',
+    use_seps: bool = True,
+    accounting: bool = False,
+    pattern: str = '{x}',
+) -> _Expr:
+    """Highly optimized native Polars integer formatter wrapper."""
+    return fmt_number(
+        columns=columns,
+        decimals=0,
+        scale_by=scale_by,
+        compact=compact,
+        compact_system=compact_system,
+        use_seps=use_seps,
+        accounting=accounting,
+        pattern=pattern,
+    )

pl2html-0.2.0/pl2html/styles.py

@@ -0,0 +1,179 @@
+from polars import (
+    Expr as _Expr,
+    Float64 as _Float64,
+    Int32 as _Int32,
+    String as _String,
+    col as _col,
+    len as _len,
+    lit as _lit,
+    when as _when,
+)
+
+
+def _interpolate_segment(
+    norm_val: _Expr,
+    low_hex: str,
+    high_hex: str,
+    seg_start: float,
+    segment_width: float,
+) -> tuple[_Expr, _Expr, _Expr]:
+    """Calculates the dynamic RGB expressions for a specific color segment."""
+    # Parse hex strings into base integer components
+    r1, g1, b1 = (
+        int(low_hex[1:3], 16),
+        int(low_hex[3:5], 16),
+        int(low_hex[5:7], 16),
+    )
+    r2, g2, b2 = (
+        int(high_hex[1:3], 16),
+        int(high_hex[3:5], 16),
+        int(high_hex[5:7], 16),
+    )
+
+    # Compute local advancement factor within this specific segment channel
+    local_factor = (norm_val - seg_start) / segment_width
+
+    # Linear interpolation formula applied directly to Polars Expressions
+    r_expr = (_lit(r1) + (_lit(r2 - r1) * local_factor)).round(0).cast(_Int32)
+    g_expr = (_lit(g1) + (_lit(g2 - g1) * local_factor)).round(0).cast(_Int32)
+    b_expr = (_lit(b1) + (_lit(b2 - b1) * local_factor)).round(0).cast(_Int32)
+
+    return r_expr, g_expr, b_expr
+
+
+def _build_css_expression(
+    r: _Expr, g: _Expr, b: _Expr, auto_contrast: bool
+) -> _Expr:
+    """Stitches RGB expressions into a complete background and foreground style string."""
+    base_style = (
+        _lit('background-color: rgb(')
+        + r.cast(_String)
+        + _lit(',')
+        + g.cast(_String)
+        + _lit(',')
+        + b.cast(_String)
+        + _lit(');')
+    )
+
+    if not auto_contrast:
+        return base_style
+
+    # WCAG Relative Luminance Formula matching standard text accessibility bounds
+    luminance = (
+        (0.2126 * (r / 255.0))
+        + (0.7152 * (g / 255.0))
+        + (0.0722 * (b / 255.0))
+    )
+
+    fg_color = (
+        _when(luminance < 0.45)
+        .then(_lit(' color: #FFFFFF;'))
+        .otherwise(_lit(' color: #000000;'))
+    )
+    return base_style + fg_color
+
+
+def data_color(
+    column: str,
+    palette: list[str],
+    domain: tuple[float, float] | None = None,
+    auto_contrast: bool = True,
+) -> dict[str, dict[str, _Expr]]:
+    """
+    Generates a style attribute expression mapping values in a column to a hex color palette.
+    If domain is None, it dynamically calculates min/max from the column at evaluation time.
+    """
+    if len(palette) < 2:
+        raise ValueError(
+            'Palette must contain at least 2 colors for interpolation.'
+        )
+
+    # 1. Evaluate Data Domain and Normalize Boundaries
+    min_expr = _lit(domain[0]) if domain else _col(column).min()
+    max_expr = _lit(domain[1]) if domain else _col(column).max()
+    range_expr = max_expr - min_expr
+
+    norm_val = (
+        _when(range_expr == 0)
+        .then(_lit(0.0))
+        .otherwise((_col(column) - min_expr) / range_expr)
+    )
+
+    num_segments = len(palette) - 1
+    segment_width = 1.0 / num_segments
+
+    # 2. Build the Initial Segment Boundary Condition
+    r, g, b = _interpolate_segment(
+        norm_val, palette[0], palette[1], 0.0, segment_width
+    )
+    chain = _when(norm_val <= segment_width).then(
+        _build_css_expression(r, g, b, auto_contrast)
+    )
+
+    # 3. Chain Remaining Segments Sequentially
+    for i in range(1, num_segments):
+        seg_start = i * segment_width
+        seg_end = (i + 1) * segment_width
+
+        r, g, b = _interpolate_segment(
+            norm_val, palette[i], palette[i + 1], seg_start, segment_width
+        )
+        chain = chain.when(norm_val <= seg_end).then(
+            _build_css_expression(r, g, b, auto_contrast)
+        )
+
+    return {column: {'style': chain.otherwise(_lit(''))}}
+
+
+def rank_color(
+    column: str,
+    palette: list[str],
+    descending: bool = False,
+    auto_contrast: bool = True,
+) -> dict[str, dict[str, _Expr]]:
+    """
+    Generates a style attribute expression mapping values in a column to a hex color palette
+    based on their ordinal rank rather than their absolute value.
+    """
+    if len(palette) < 2:
+        raise ValueError(
+            'Palette must contain at least 2 colors for interpolation.'
+        )
+
+    # 1. Dynamically compute the ordinal rank (1-indexed) inside Polars
+    # Subtract 1 to make it 0-indexed: [0, n-1]
+    rank_expr = _col(column).rank(method='ordinal', descending=descending) - 1
+
+    # 2. Safely normalize the rank between 0.0 and 1.0 based on dataset size
+    # norm = rank / (total_rows - 1)
+    total_rows_minus_1 = _len().cast(_Float64) - 1.0
+
+    norm_val = (
+        _when(total_rows_minus_1 <= 0)
+        .then(_lit(0.0))
+        .otherwise(rank_expr.cast(_Float64) / total_rows_minus_1)
+    )
+
+    num_segments = len(palette) - 1
+    segment_width = 1.0 / num_segments
+
+    # 3. Reuse our optimized piece-wise interpolation pipeline
+    r, g, b = _interpolate_segment(
+        norm_val, palette[0], palette[1], 0.0, segment_width
+    )
+    chain = _when(norm_val <= segment_width).then(
+        _build_css_expression(r, g, b, auto_contrast)
+    )
+
+    for i in range(1, num_segments):
+        seg_start = i * segment_width
+        seg_end = (i + 1) * segment_width
+
+        r, g, b = _interpolate_segment(
+            norm_val, palette[i], palette[i + 1], seg_start, segment_width
+        )
+        chain = chain.when(norm_val <= seg_end).then(
+            _build_css_expression(r, g, b, auto_contrast)
+        )
+
+    return {column: {'style': chain.otherwise(_lit(''))}}

{pl2html-0.1.0 → pl2html-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'uv_build'
 
 [project]
 name = "pl2html"
-version = "0.1.0"
+version = "0.2.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.14"

pl2html-0.1.0/PKG-INFO

@@ -1,9 +0,0 @@
-Metadata-Version: 2.3
-Name: pl2html
-Version: 0.1.0
-Summary: Add your description here
-Requires-Dist: polars>=1.42.1
-Requires-Python: >=3.14
-Project-URL: GitHub, https://github.com/5j9/pl2html
-Description-Content-Type: text/markdown
-