pl2html 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pl2html
-Version: 0.2.0
+Version: 0.4.0
 Summary: Add your description here
 Requires-Dist: polars>=1.42.1
 Requires-Python: >=3.14
@@ -51,10 +51,8 @@ df = pl.DataFrame(
 )
 
 # Compiles safely to a Polars LazyFrame containing the HTML output
-html_lazy = to_html(df)
+html_table_string = to_html(df)
 
-# Collect and extract the compiled string
-html_table_string = html_lazy.collect().item()
 print(html_table_string)
 ```
 
@@ -101,7 +99,7 @@ df_f = df.with_columns(
     fmt.sub_zero("status_code", zero_text="OK")
 )
 
-html = to_html(df_f).collect().item()
+html = to_html(df_f)
 ```
 
 ### 3. Advanced Styling via Native Attributes (`attrs`)
@@ -141,7 +139,7 @@ styles.update(
     )
 )
 
-html_table = to_html(df, attrs=styles).collect().item()
+html_table = to_html(df, attrs=styles)
 ```
 
 Output (github may override table colors, but they are there):
@@ -205,3 +203,12 @@ Generates structural Polars expression payloads mapped to specific HTML style at
 .str.replace_all('"', '"')
 .str.replace_all("'", ''')
 ```
+
+### Design Inspiration & Why This Library Exists
+
+Most of the API design and formatting parameters in this library are heavily inspired by [great-tables](https://posit-dev.github.io/great-tables/reference/). If you are looking for detailed descriptions or conceptual overviews of specific formatting arguments, the `great-tables` reference documentation serves as an excellent companion guide. 
+
+However, this library was born out of distinct architectural and environment constraints:
+
+* **Zero Overhead Styling:** While `great-tables` is incredibly feature-rich, it often produces dense HTML styles and boilerplate structures that were unnecessary for the target use cases. This library optimizes for minimal, highly clean HTML output.
+* **Modern Python Compatibility (Py 3.14+):** `great-tables` pulls in heavy external dependencies, including binary wheels like `multimark`. At the time of development, these dependencies did not support Python 3.14 (see [multimark #3](https://github.com/posit-dev/multimark/issues/3)). To unblock workflows and maintain an ultra-lightweight, future-proof stack with zero complex binary dependencies, this native, Rust-backed Polars formatter was built from the ground up.

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

@@ -42,10 +42,8 @@ df = pl.DataFrame(
 )
 
 # Compiles safely to a Polars LazyFrame containing the HTML output
-html_lazy = to_html(df)
+html_table_string = to_html(df)
 
-# Collect and extract the compiled string
-html_table_string = html_lazy.collect().item()
 print(html_table_string)
 ```
 
@@ -92,7 +90,7 @@ df_f = df.with_columns(
     fmt.sub_zero("status_code", zero_text="OK")
 )
 
-html = to_html(df_f).collect().item()
+html = to_html(df_f)
 ```
 
 ### 3. Advanced Styling via Native Attributes (`attrs`)
@@ -132,7 +130,7 @@ styles.update(
     )
 )
 
-html_table = to_html(df, attrs=styles).collect().item()
+html_table = to_html(df, attrs=styles)
 ```
 
 Output (github may override table colors, but they are there):
@@ -196,3 +194,12 @@ Generates structural Polars expression payloads mapped to specific HTML style at
 .str.replace_all('"', '"')
 .str.replace_all("'", ''')
 ```
+
+### Design Inspiration & Why This Library Exists
+
+Most of the API design and formatting parameters in this library are heavily inspired by [great-tables](https://posit-dev.github.io/great-tables/reference/). If you are looking for detailed descriptions or conceptual overviews of specific formatting arguments, the `great-tables` reference documentation serves as an excellent companion guide. 
+
+However, this library was born out of distinct architectural and environment constraints:
+
+* **Zero Overhead Styling:** While `great-tables` is incredibly feature-rich, it often produces dense HTML styles and boilerplate structures that were unnecessary for the target use cases. This library optimizes for minimal, highly clean HTML output.
+* **Modern Python Compatibility (Py 3.14+):** `great-tables` pulls in heavy external dependencies, including binary wheels like `multimark`. At the time of development, these dependencies did not support Python 3.14 (see [multimark #3](https://github.com/posit-dev/multimark/issues/3)). To unblock workflows and maintain an ultra-lightweight, future-proof stack with zero complex binary dependencies, this native, Rust-backed Polars formatter was built from the ground up.

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

@@ -10,7 +10,7 @@ from polars import (
     when as _when,
 )
 
-__version__ = '0.2.0'
+__version__ = '0.4.0'
 
 
 def _escape_polars_string(col_name: str) -> _Expr:
@@ -126,7 +126,7 @@ def to_html(
     *,
     attrs: dict[str, dict[str, _Expr]] | None = None,
     exclude_columns: list[str] | None = None,
-) -> _LazyFrame:
+) -> str:
     """
     Compiles a Polars DataFrame safely into an HTML string layout.
     Accepts structural custom attributes mappings to handle layout modifications natively.
@@ -151,8 +151,14 @@ def to_html(
     # 4. Generate wrappers and frame the query graph
     html_header, html_footer = _build_html_skeleton(visible_columns)
 
-    return lf.select(row_expr.alias('html_row')).select(
-        (html_header + _col('html_row').str.join('\n') + html_footer).alias(
-            'html_table'
+    # 5. Execute the query graph and pull out the raw python string directly
+    return (
+        lf.select(row_expr.alias('html_row'))
+        .select(
+            (
+                html_header + _col('html_row').str.join('\n') + html_footer
+            ).alias('html_table')
         )
+        .collect()
+        .item()
     )

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

@@ -17,12 +17,10 @@ from polars import (
 # --- 0. Decorator to cleanly support single or multiple columns ---
 def _multicolumn(func):
     @_wraps(func)
-    def wrapper(columns: str | _Iterable[str], *args, **kwargs):
+    def wrapper(*, columns: str | _Iterable[str], **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 func(columns=columns, **kwargs)
+        return [func(columns=col, **kwargs).alias(col) for col in columns]
 
     return wrapper
 
@@ -34,6 +32,7 @@ _Columns = str | list[str]
 
 @_multicolumn
 def fmt_number(
+    *,
     columns: _Columns,
     decimals: int = 2,
     scale_by: float = 1.0,
@@ -42,6 +41,8 @@ def fmt_number(
     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.
@@ -90,38 +91,71 @@ def fmt_number(
         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)
+    # 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')
 
-    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()
-            )
+        # Round natively using Polars' built-in significant figures feature
+        rounded = val_scaled.round_sig_figs(n_sigfig)
+        abs_rounded = rounded.abs()
 
-        base_num_str = int_part + _lit('.') + frac_part
+        # 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:
-        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()
-            )
+        # 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)
+        dynamic_decimals = _lit(decimals)
+
+    # 3. Component Extraction & Alignment
+    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(''))
+    )
+
+    # 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)
+        .then((raw_frac + _lit('0' * pad_len)).str.slice(0, dynamic_decimals))
+        .otherwise(_lit(''))
+    )
+
+    # 4. Constructing Base Number String
+    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 = (
+        _when(dynamic_decimals > 0)
+        .then(int_part + _lit('.') + frac_part)
+        .otherwise(int_part)
+    )
     base_num_str = base_num_str + suffix_chain
 
     prefix, suffix = '', ''
@@ -140,13 +174,22 @@ def fmt_number(
                 + _lit(suffix)
                 + _lit(')')
             )
-            .otherwise(_lit(prefix) + base_num_str + _lit(suffix))
+            .otherwise(
+                # If force_sign is True, explicitly prepend '+' to positive values
+                _lit('+' if force_sign else '')
+                + _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))
+            # 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
@@ -154,7 +197,11 @@ def fmt_number(
 
 @_multicolumn
 def fmt_percent(
-    columns: _Columns, decimals: int = 2, use_seps: bool = True
+    *,
+    columns: _Columns,
+    decimals: int = 2,
+    use_seps: bool = True,
+    force_sign: bool = False,
 ) -> _Expr:
     """Formats columns as percentages, multiplying by 100 automatically."""
     return fmt_number(
@@ -163,16 +210,19 @@ def fmt_percent(
         scale_by=100.0,
         use_seps=use_seps,
         pattern='{x}%',
+        force_sign=force_sign,
     )
 
 
 @_multicolumn
 def fmt_currency(
+    *,
     columns: _Columns,
     symbol: str = '$',
     decimals: int = 2,
     use_seps: bool = True,
     accounting: bool = True,
+    force_sign: bool = False,
 ) -> _Expr:
     """Formats columns as localized currency values."""
     return fmt_number(
@@ -181,11 +231,13 @@ def fmt_currency(
         use_seps=use_seps,
         accounting=accounting,
         pattern=f'{symbol}{{x}}',
+        force_sign=force_sign,
     )
 
 
 @_multicolumn
 def fmt_scientific(
+    *,
     columns: _Columns,
     decimals: int = 2,
     scale_by: float = 1.0,
@@ -259,6 +311,7 @@ def fmt_scientific(
 
 @_multicolumn
 def fmt_bytes(
+    *,
     columns: _Columns,
     standard: _Literal['decimal', 'binary'] = 'decimal',
     decimals: int = 1,
@@ -375,6 +428,7 @@ def fmt_bytes(
 
 @_multicolumn
 def fmt_tf(
+    *,
     columns: _Columns,
     tf_style: _Literal[
         'true-false',
@@ -439,12 +493,12 @@ def fmt_tf(
 
 
 @_multicolumn
-def sub_missing(columns: _Columns, missing_text: str = '—') -> _Expr:
+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:
+def sub_zero(*, columns: _Columns, zero_text: str = '—') -> _Expr:
     return (
         _when(_col(columns) == 0)
         .then(_lit(zero_text))
@@ -454,6 +508,7 @@ def sub_zero(columns: _Columns, zero_text: str = '—') -> _Expr:
 
 @_multicolumn
 def fmt_integer(
+    *,
     columns: _Columns,
     scale_by: float = 1.0,
     compact: bool = False,
@@ -461,6 +516,7 @@ def fmt_integer(
     use_seps: bool = True,
     accounting: bool = False,
     pattern: str = '{x}',
+    force_sign: bool = False,
 ) -> _Expr:
     """Highly optimized native Polars integer formatter wrapper."""
     return fmt_number(
@@ -472,4 +528,5 @@ def fmt_integer(
         use_seps=use_seps,
         accounting=accounting,
         pattern=pattern,
+        force_sign=force_sign,
     )

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

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