Implement GT.pipe() and GT.pipes()

docs/_quarto.yml

@@ -174,6 +174,13 @@ quartodoc:
       contents:
         - GT.save
         - GT.as_raw_html
+    - title: Pipeline
+      desc: >
+        Sometimes, you might want to programmatically manipulate the table while still benefiting
+        from the chained API that **Great Tables** offers. `pipe()` is designed to tackle this
+        issue.
+      contents:
+        - GT.pipe
     - title: Value formatting functions
       desc: >
         If you have single values (or lists of them) in need of formatting, we have a set of

great_tables/_pipe.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Any
+
+if TYPE_CHECKING:
+    from .gt import GT
+
+
+def pipe(self: "GT", func: Callable[..., "GT"], *args: Any, **kwargs: Any) -> "GT":
+    """
+    Provide a structured way to chain a function for a GT object.
+
+    This function accepts a function that receives a GT object along with optional positional and
+    keyword arguments, returning a GT object. This allows users to easily integrate a function
+    into the chained API offered by **Great Tables**.
+
+    Parameters
+    ----------
+    func
+        A function that receives a GT object along with optional positional and keyword arguments,
+        returning a GT object.
+
+    *args
+        Optional positional arguments to be passed to the function.
+
+    **kwargs
+        Optional keyword arguments to be passed to the function.
+
+    Returns
+    -------
+    gt
+        A GT object.
+
+    Examples:
+    ------
+    Let's use the `name`, `land_area_km2`, and `density_2021` columns of the `towny` dataset to
+    create a table. First, we'll demonstrate using two consecutive calls to the `.tab_style()`
+    method to highlight the maximum value of the `land_area_km2` column with `"lightgray"` and the
+    maximum value of the `density_2021` column with `"lightblue"`.
+
+    ```{python}
+    import polars as pl
+    from great_tables import GT, loc, style
+    from great_tables.data import towny
+
+
+    towny_mini = pl.from_pandas(towny).head(10)
+
+    (
+        GT(
+            towny_mini[["name", "land_area_km2", "density_2021"]],
+            rowname_col="name",
+        )
+        .tab_style(
+            style=style.fill(color="lightgray"),
+            locations=loc.body(
+                columns="land_area_km2",
+                rows=pl.col("land_area_km2").eq(pl.col("land_area_km2").max()),
+            ),
+        )
+        .tab_style(
+            style=style.fill(color="lightblue"),
+            locations=loc.body(
+                columns="density_2021",
+                rows=pl.col("density_2021").eq(pl.col("density_2021").max()),
+            ),
+        )
+    )
+    ```
+
+    Next, we'll demonstrate how to achieve the same result using the `.pipe()` method to
+    programmatically style each column.
+
+    ```{python}
+    columns = ["land_area_km2", "density_2021"]
+    colors = ["lightgray", "lightblue"]
+
+
+    def tbl_style(gtbl: GT, columns: list[str], colors: list[str]) -> GT:
+        for column, color in zip(columns, colors):
+            gtbl = gtbl.tab_style(
+                style=style.fill(color=color),
+                locations=loc.body(columns=column, rows=pl.col(column).eq(pl.col(column).max())),
+            )
+        return gtbl
+
+
+    (
+        GT(
+            towny_mini[["name", "land_area_km2", "density_2021"]],
+            rowname_col="name",
+        ).pipe(tbl_style, columns, colors)
+    )
+    ```
+    """
+    return func(self, *args, **kwargs)

great_tables/gt.py

@@ -11,6 +11,7 @@
 from great_tables._boxhead import cols_align, cols_label
 from great_tables._data_color import data_color
 from great_tables._export import as_raw_html, save
+from great_tables._pipe import pipe
 from great_tables._formats import (
     fmt,
     fmt_bytes,
@@ -255,6 +256,8 @@ def __init__(
     save = save
     as_raw_html = as_raw_html
 
+    pipe = pipe
+
     # -----
 
     def _repr_html_(self):

tests/test_pipe.py

@@ -0,0 +1,37 @@
+import polars as pl
+from great_tables import GT, loc, style
+
+
+def test_pipe():
+    columns = ["x", "y"]
+    colors = ["lightgray", "lightblue"]
+    df = pl.DataFrame(dict(zip(columns, [[1, 2, 3], [3, 2, 1]])))
+
+    gt1 = (
+        GT(df)
+        .tab_style(
+            style=style.fill(color=colors[0]),
+            locations=loc.body(
+                columns=columns[0], rows=pl.col(columns[0]).eq(pl.col(columns[0]).max())
+            ),
+        )
+        .tab_style(
+            style=style.fill(color=colors[1]),
+            locations=loc.body(
+                columns=columns[1], rows=pl.col(columns[1]).eq(pl.col(columns[1]).max())
+            ),
+        )
+    )
+
+    def tbl_style(gtbl: GT, columns: list[str], colors: list[str]) -> GT:
+        for column, color in zip(columns, colors):
+            gtbl = gtbl.tab_style(
+                style=style.fill(color=color),
+                locations=loc.body(columns=column, rows=pl.col(column).eq(pl.col(column).max())),
+            )
+        return gtbl
+
+    gt2 = GT(df).pipe(tbl_style, columns, colors)  # check *args
+    gt3 = GT(df).pipe(tbl_style, columns=columns, colors=colors)  # check **kwargs
+
+    assert gt1._styles == gt2._styles == gt3._styles