feat: implement cols_reorder() for flexible column reordering

docs/_quarto.yml

@@ -156,6 +156,7 @@ quartodoc:
         - GT.cols_move
         - GT.cols_move_to_start
         - GT.cols_move_to_end
+        - GT.cols_reorder
         - GT.cols_hide
     - title: Location Targeting and Styling Classes
       desc: >

great_tables/_gt_data.py

@@ -409,7 +409,7 @@ def vars_from_type(self, type: ColInfoTypeEnum) -> list[str]:
     def reorder(self, vars: list[str]) -> Self:
         boxh_vars = [col.var for col in self]
         if set(vars) != set(boxh_vars):
-            raise ValueError("Reordering vars must contain all boxhead vars.")
+            raise ValueError("Column reordering must include all columns in the table.")
 
         new_order = [boxh_vars.index(var) for var in vars]
 

great_tables/_spanners.py

@@ -753,3 +753,58 @@
         curr_boxhead = curr_boxhead._set_column_width(col, width)
 
     return self._replace(_boxhead=curr_boxhead)
+
+
+def cols_reorder(self: GTSelf, columns: SelectExpr) -> GTSelf:
+    """Reordering the columns as specified.
+
+    We can easily reorder columns by specifying `columns`. While this can be done upstream of
+    **Great Tables**, `cols_reorder()` is simpler and reduces the chance of errors. The order of
+    `columns` is preserved.
+
+    Note that all columns specified in `columns` must exist in the table, and the list must contain
+    the same number of columns as the original table.
+
+    Parameters
+    ----------
+    columns
+        The columns to target, specified as a list of column names.
+
+    Returns
+    -------
+    GT
+        The GT object is returned. This is the same object that the method is called on so that we
+        can facilitate method chaining.
+
+    Examples
+    --------
+    Let's use the `exibble` dataset to create a new table.
+    ```{python}
+    from great_tables import GT
+    from great_tables.data import exibble
+
+    gt = GT(exibble)
+    gt
+    ```
+    Suppose you want to move the `fctr` column to the beginning of the table and position the `char`
+    and `num` columns as the last two. While this can be accomplished using `cols_move()`,
+    `cols_move_to_start()`, and `cols_move_to_end()`, **Great Tables** offers a more convenient
+    function: `cols_reorder()`. By passing a list of column names to the `columns=` parameter,
+    the table will be reordered accordingly:
+    ```{python}
+    num_col, char_col, fctr_col, *cols = exibble.columns
+    gt.cols_reorder([fctr_col, *cols, char_col,  num_col])
+    ```
+    """
+
+    if isinstance(columns, str):
+        columns = [columns]
+
+    sel_cols = resolve_cols_c(data=self, expr=columns)
+
+    col_vars = [col.var for col in self._boxhead]
+
+    _validate_sel_cols(sel_cols, col_vars)
+
+    new_boxhead = self._boxhead.reorder(sel_cols)
+    return self._replace(_boxhead=new_boxhead)

great_tables/gt.py

@@ -52,6 +52,7 @@
     cols_move,
     cols_move_to_end,
     cols_move_to_start,
+    cols_reorder,
     cols_width,
     tab_spanner,
 )
@@ -256,6 +257,7 @@ def __init__(
     cols_move = cols_move
     cols_move_to_start = cols_move_to_start
     cols_move_to_end = cols_move_to_end
+    cols_reorder = cols_reorder
     cols_hide = cols_hide
 
     tab_header = tab_header

tests/test_spanners.py

@@ -11,6 +11,7 @@
     cols_move,
     cols_move_to_end,
     cols_move_to_start,
+    cols_reorder,
     empty_spanner_matrix,
     spanners_print_matrix,
     tab_spanner,
@@ -358,6 +359,34 @@ def test_cols_move_to_end_multi_cols(DF, columns):
     assert [col.var for col in new_gt._boxhead] == ["b", "d", "a", "c"]
 
 
+@pytest.mark.parametrize(
+    "DF, columns",
+    [
+        (pd.DataFrame, ["a", "d", "c", "b"]),
+        (pl.DataFrame, pl.col("a", "d", "c", "b")),
+        (pl.DataFrame, [pl.col("a", "d", "c"), "b"]),
+    ],
+)
+def test_cols_reorder(DF, columns):
+    df = DF({"a": [1, 2], "b": [3, 4], "c": [5, 6], "d": [7, 8]})
+    src_gt = GT(df)
+    new_gt = cols_reorder(src_gt, columns=columns)
+    assert [col.var for col in new_gt._boxhead] == ["a", "d", "c", "b"]
+
+
+@pytest.mark.parametrize(
+    "DF, columns",
+    [(pd.DataFrame, ["a", "d"]), (pl.DataFrame, ["a", "d", "c"])],
+)
+def test_cols_reorder_raises(DF, columns):
+    df = DF({"a": [1, 2], "b": [3, 4], "c": [5, 6], "d": [7, 8]})
+    src_gt = GT(df)
+    with pytest.raises(Exception) as exc_info:
+        new_gt = cols_reorder(src_gt, columns=columns)
+
+    assert "Column reordering must include all columns in the table." in exc_info.value.args[0]
+
+
 @pytest.mark.parametrize("DF, columns", [(pd.DataFrame, "c"), (pl.DataFrame, cs.starts_with("c"))])
 def test_cols_hide_single_col(DF, columns):
     df = DF({"a": [1, 2], "b": [3, 4], "c": [5, 6], "d": [7, 8]})