pl2html 0.4.0__tar.gz → 0.5.0__tar.gz

{pl2html-0.4.0 → pl2html-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pl2html
-Version: 0.4.0
+Version: 0.5.0
 Summary: Add your description here
 Requires-Dist: polars>=1.42.1
 Requires-Python: >=3.14
@@ -40,7 +40,7 @@ By default, `pl2html` infers datatypes to securely render human-readable tables.
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 
 df = pl.DataFrame(
     {
@@ -78,7 +78,7 @@ Output:
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 from pl2html import formats as fmt
 
 df = pl.DataFrame(
@@ -107,7 +107,7 @@ Instead of embedding hacky structural HTML tags in your data, use the `attrs` pa
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 from pl2html.styles import data_color, rank_color
 
 df = pl.DataFrame(
@@ -167,7 +167,7 @@ Output (github may override table colors, but they are there):
 
 The library is explicitly divided into three decoupled layers:
 
-### 1. Core Compiler (`__init__.py`)
+### 1. Core Compiler (`compiler.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:

{pl2html-0.4.0 → pl2html-0.5.0}/README.md

@@ -31,7 +31,7 @@ By default, `pl2html` infers datatypes to securely render human-readable tables.
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 
 df = pl.DataFrame(
     {
@@ -69,7 +69,7 @@ Output:
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 from pl2html import formats as fmt
 
 df = pl.DataFrame(
@@ -98,7 +98,7 @@ Instead of embedding hacky structural HTML tags in your data, use the `attrs` pa
 
 ```python
 import polars as pl
-from pl2html import to_html
+from pl2html.compiler import to_html
 from pl2html.styles import data_color, rank_color
 
 df = pl.DataFrame(
@@ -158,7 +158,7 @@ Output (github may override table colors, but they are there):
 
 The library is explicitly divided into three decoupled layers:
 
-### 1. Core Compiler (`__init__.py`)
+### 1. Core Compiler (`compiler.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:

pl2html-0.5.0/pl2html/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.5.0'

pl2html-0.4.0/pl2html/__init__.py → pl2html-0.5.0/pl2html/compiler.py

@@ -10,8 +10,6 @@ from polars import (
     when as _when,
 )
 
-__version__ = '0.4.0'
-
 
 def _escape_polars_string(col_name: str) -> _Expr:
     """
@@ -126,10 +124,53 @@ def to_html(
     *,
     attrs: dict[str, dict[str, _Expr]] | None = None,
     exclude_columns: list[str] | None = None,
+    formatters: _Expr | list[_Expr] | None = None,
 ) -> str:
-    """
-    Compiles a Polars DataFrame safely into an HTML string layout.
-    Accepts structural custom attributes mappings to handle layout modifications natively.
+    """Compiles a Polars DataFrame safely into an HTML string layout.
+
+    Accepts structural custom attribute mappings to handle layout modifications
+    and cell styling natively.
+
+    Args:
+        df: The source Polars DataFrame or LazyFrame containing the data.
+        attrs: A dictionary mapping column names to cell attributes (e.g., style,
+            class). The inner dictionary values can be raw Polars expressions that
+            evaluate dynamically based on the column values.
+        exclude_columns: A list of column names to omit from the rendered HTML table.
+        formatters: A single Polars expression or a list of expressions used to
+            format column values into display strings (e.g., using `fmt_number`).
+
+    Returns:
+        A raw HTML string representation of the styled and formatted table.
+
+    Note on Formatters Execution Order:
+        Usually, formatting expressions can be applied directly to the DataFrame
+        via `.with_columns()` before calling `to_html`. However, if your `attrs`
+        contain expressions that require numerical operations on data values (such
+        as computing percentage ranks or maximum thresholds via `rank_color`),
+        pre-formatting will convert those columns into `String` types too early and
+        cause downstream calculation panics (e.g., string division errors).
+
+        By passing your formatting expressions to the `formatters` parameter
+        instead, `to_html` guarantees they are scheduled to execute *after* the
+        numerical style attributes have been safely resolved against the raw data.
+
+    Example:
+        >>> import polars as pl
+        >>> from pl2html import to_html
+        >>> from pl2html.formats import fmt_number
+        >>>
+        >>> df = pl.DataFrame({"sprd": [10.0, 50.0, 100.0]})
+        >>>
+        >>> # A style rule that requires the column to remain numeric (Float64)
+        >>> attrs = {"sprd": {"style": pl.col("sprd") / pl.col("sprd").max()}}
+        >>>
+        >>> # Safe execution: styles are computed first, then text formatting is applied
+        >>> html = to_html(
+        ...     df,
+        ...     attrs=attrs,
+        ...     formatters=fmt_number(columns=["sprd"], decimals=2)
+        ... )
     """
     lf = df.lazy() if isinstance(df, _DataFrame) else df
 
@@ -139,19 +180,51 @@ def to_html(
     schema = lf.collect_schema()
     visible_columns = [c for c in schema.names() if c not in exclude_columns]
 
-    cell_expressions = []
+    # === STEP 1: RESOLVE MATH/STYLE EXPRESSIONS ON NUMERIC DATA FIRST ===
+    # If there are style expressions, evaluate them into static string literals
+    # before applying the text formatters.
+    style_selects = []
+    style_maps = {}
+
+    for col_name, styles in attrs.items():
+        if col_name in visible_columns and 'style' in styles:
+            expr_key = f'__style_{col_name}'
+            style_selects.append(styles['style'].alias(expr_key))
+            style_maps[col_name] = expr_key
+
+    if style_selects:
+        # Collect just the evaluated style values using the numeric dataframe state
+        df = lf.collect()
+        lf = df.lazy()
+        resolved_styles_df = df.select(style_selects)
+
+        # Replace the lazy expressions in attrs with concrete string series expressions
+        new_attrs = {}
+        for col_name, styles in attrs.items():
+            new_attrs[col_name] = styles.copy()
+            if col_name in style_maps:
+                # Inject the pre-calculated style vector back as a harmless literal expression
+                new_attrs[col_name]['style'] = _lit(
+                    resolved_styles_df.get_column(style_maps[col_name])
+                )
+        attrs = new_attrs
 
-    # 2. Map structural cell loops
+    # === STEP 2: APPLY FORMATTERS TO CONVERT COLUMNS TO STRINGS ===
+    if formatters is not None:
+        if isinstance(formatters, _Expr):
+            formatters = [formatters]
+        lf = lf.with_columns(formatters)
+
+    # === STEP 3: BUILD HTML CELLS (Now 100% safe from string division errors!) ===
+    cell_expressions = []
     for c in visible_columns:
-        cell_expressions.append(_build_cell_expr(c, schema[c], attrs))
+        cell_expressions.append(
+            _build_cell_expr(c, lf.collect_schema()[c], attrs)
+        )
 
-    # 3. Concatenate columns horizontally into rows
     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)
 
-    # 5. Execute the query graph and pull out the raw python string directly
     return (
         lf.select(row_expr.alias('html_row'))
         .select(

{pl2html-0.4.0 → pl2html-0.5.0}/pl2html/formats.py

@@ -30,111 +30,98 @@ def _multicolumn(func):
 _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}',
-    n_sigfig: int | None = None,
-    force_sign: bool = False,
-) -> _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
+def _apply_compact_scaling(
+    val: _Expr, compact: bool, compact_system: str
+) -> tuple[_Expr, _Expr]:
+    """Handles logic block 1: Extracts compact suffix rules and scales values down."""
+    if not compact:
+        return val, _lit('')
 
     abs_val = val.abs()
+    log10_expr = _when(abs_val > 0).then(abs_val.log10()).otherwise(_lit(0.0))
+    thousands_exponent = (log10_expr / 3.0).floor().cast(_Int32) * 3
 
-    # 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('')
+    # Force exponent to 0 for fractional numbers (< 1.0)
+    thousands_exponent = (
+        _when(thousands_exponent < 0)
+        .then(_lit(0))
+        .otherwise(thousands_exponent)
+    )
+
+    system_chars = (
+        ('k', 'M', 'G', 'T')
+        if compact_system == 'engineering'
+        else ('K', 'M', 'B', 'T')
+    )
+
+    suffix_chain = (
+        _when(thousands_exponent == 3)
+        .then(_lit(system_chars[0]))
+        .when(thousands_exponent == 6)
+        .then(_lit(system_chars[1]))
+        .when(thousands_exponent == 9)
+        .then(_lit(system_chars[2]))
+        .when(thousands_exponent == 12)
+        .then(_lit(system_chars[3]))
+        .otherwise(_lit(''))
+    )
+
+    divisor = _lit(10.0).pow(thousands_exponent.cast(_Float64))
+    return val / divisor, suffix_chain
+
+
+def _compute_dynamic_precision(
+    val_scaled: _Expr, decimals: int, n_sigfig: int | None
+) -> tuple[_Expr, _Expr | int]:
+    """Handles logic block 2: Computes precision bounds safely avoiding non-finite floats, preserving nulls."""
+
+    # FIX: Explicitly target only NaN and Infinity, leaving nulls untouched
+    is_anomaly = val_scaled.is_nan() | val_scaled.is_infinite()
+    safe_val = _when(is_anomaly).then(_lit(0.0)).otherwise(val_scaled)
 
-    # 2. Dynamic Precision Handling (Significant Figures vs Fixed Decimals)
     if n_sigfig is not None:
         if n_sigfig < 1:
             raise ValueError('n_sigfig must be a positive integer >= 1')
 
-        # Round natively using Polars' built-in significant figures feature
-        rounded = val_scaled.round_sig_figs(n_sigfig)
+        rounded = safe_val.round_sig_figs(n_sigfig)
         abs_rounded = rounded.abs()
 
-        # Determine the number of dynamic decimal places needed for padding per row
         log10_expr = (
             _when(abs_rounded > 0)
             .then(abs_rounded.log10())
             .otherwise(_lit(0.0))
         )
-        # decimals required = n_sigfig - 1 - floor(log10(x))
         dynamic_decimals = (_lit(n_sigfig - 1) - log10_expr.floor()).cast(
             _Int32
         )
-        # Ensure we don't try to pad negative decimal places for large numbers
         dynamic_decimals = (
             _when(dynamic_decimals < 0)
             .then(_lit(0))
             .otherwise(dynamic_decimals)
         )
     else:
-        # Fallback to standard fixed decimal logic
-        epsilon = (
-            _when(val_scaled >= 0).then(_lit(1e-9)).otherwise(_lit(-1e-9))
-        )
-        rounded = (val_scaled + epsilon).round(decimals)
+        epsilon = _when(safe_val >= 0).then(_lit(1e-9)).otherwise(_lit(-1e-9))
+        rounded = (safe_val + epsilon).round(decimals)
         dynamic_decimals = _lit(decimals)
 
-    # 3. Component Extraction & Alignment
+    return rounded, dynamic_decimals
+
+
+def _extract_and_align_components(
+    rounded: _Expr,
+    decimals: int,
+    n_sigfig: int | None,
+    dynamic_decimals: _Expr | int,
+    use_seps: bool,
+) -> _Expr:
+    """Handles logic blocks 3 & 4: Cuts string tokens cleanly."""
+    # Since rounded is calculated from safe_val above, it contains no NaN/inf here.
+    # The .cast(_Int64) is now completely safe from panicking!
     int_part = rounded.cast(_Int64).abs().cast(_String)
     full_str = rounded.abs().cast(_String)
 
-    raw_frac = (
-        _when(full_str.str.contains(r'\.'))
-        .then(full_str.str.split('.').list.get(1))
-        .otherwise(_lit(''))
-    )
+    raw_frac = full_str.str.extract(r'\.(.*)', 1).fill_null(_lit(''))
 
-    # Use native Python string multiplication inside _lit()
     pad_len = n_sigfig if n_sigfig is not None else decimals
     frac_part = (
         _when(dynamic_decimals > 0)
@@ -142,7 +129,6 @@ def fmt_number(
         .otherwise(_lit(''))
     )
 
-    # 4. Constructing Base Number String
     if use_seps:
         int_part = (
             int_part.str.reverse()
@@ -151,19 +137,56 @@ def fmt_number(
             .str.reverse()
         )
 
-    base_num_str = (
+    return (
         _when(dynamic_decimals > 0)
         .then(int_part + _lit('.') + frac_part)
         .otherwise(int_part)
     )
+
+
+@_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}',
+    n_sigfig: int | None = None,
+    force_sign: bool = False,
+) -> _Expr:
+    """
+    Highly optimized, native Polars numeric formatter matching great_tables features.
+    Runs entirely in the parallel Rust engine without dropping into Python row loops.
+    """
+    col_name = columns if isinstance(columns, str) else str(columns)
+    val = _col(columns)
+    if scale_by != 1.0:
+        val = val * scale_by
+
+    # --- HELPER ORCHESTRATION ---
+    val_scaled, suffix_chain = _apply_compact_scaling(
+        val, compact, compact_system
+    )
+    rounded, dynamic_decimals = _compute_dynamic_precision(
+        val_scaled, decimals, n_sigfig
+    )
+    base_num_str = _extract_and_align_components(
+        rounded, decimals, n_sigfig, dynamic_decimals, use_seps
+    )
     base_num_str = base_num_str + suffix_chain
 
+    # --- PATTERN PARSING ---
     prefix, suffix = '', ''
     if pattern != '{x}':
         parts = pattern.split('{x}')
         if len(parts) == 2:
             prefix, suffix = parts[0], parts[1]
 
+    # --- STANDARD EXPRESSION GENERATION ---
     if accounting:
         formatted_expr = (
             _when(val < 0)
@@ -175,7 +198,6 @@ def fmt_number(
                 + _lit(')')
             )
             .otherwise(
-                # If force_sign is True, explicitly prepend '+' to positive values
                 _lit('+' if force_sign else '')
                 + _lit(prefix)
                 + base_num_str
@@ -186,13 +208,22 @@ def fmt_number(
         formatted_expr = (
             _when(val < 0)
             .then(_lit('-') + _lit(prefix) + base_num_str + _lit(suffix))
-            # Handle zero explicitly if you don't want a sign on exactly 0.0
             .when((val == 0) | (not force_sign))
             .then(_lit(prefix) + base_num_str + _lit(suffix))
             .otherwise(_lit('+') + _lit(prefix) + base_num_str + _lit(suffix))
         )
 
-    return formatted_expr
+    # --- CRUCIAL FIX: NON-FINITE GLOBAL GUARD MASK ---
+    # Intercepts expression evaluation to bypass Int64 panics on NaN and Infinity tokens
+    final_guarded_expr = (
+        _when(val.is_nan())
+        .then(_lit('NaN'))
+        .when(val.is_infinite())
+        .then(_when(val < 0).then(_lit('-inf')).otherwise(_lit('inf')))
+        .otherwise(formatted_expr)
+    )
+
+    return final_guarded_expr.alias(col_name)
 
 
 @_multicolumn

{pl2html-0.4.0 → pl2html-0.5.0}/pyproject.toml

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