enh: Add nw.format (#3169)

* enh: Add `nw.format`#

* add to stable

* so stable it could drink you under a table

* fixup

* Update narwhals/stable/v1/__init__.py

Co-authored-by: Francesco Bruzzesi <42817048+FBruzzesi@users.noreply.github.com>

* fixup

---------

Co-authored-by: Francesco Bruzzesi <42817048+FBruzzesi@users.noreply.github.com>

Author: MarcoGorelli

docs/api-reference/narwhals.md

@@ -14,6 +14,7 @@ Here are the top-level functions available in Narwhals.
         - concat
         - concat_str
         - exclude
+        - format
         - from_arrow
         - from_dict
         - from_dicts

narwhals/__init__.py

@@ -54,6 +54,7 @@
     concat,
     concat_str,
     exclude,
+    format,
     from_arrow,
     from_dict,
     from_dicts,
@@ -136,6 +137,7 @@
     "dtypes",
     "exceptions",
     "exclude",
+    "format",
     "from_arrow",
     "from_dict",
     "from_dicts",

narwhals/functions.py

@@ -1746,3 +1746,43 @@ def coalesce(
         ),
         ExprMetadata.from_horizontal_op(*flat_exprs),
     )
+
+
+def format(f_string: str, *args: IntoExpr) -> Expr:
+    """Format expressions as a string.
+
+    Arguments:
+        f_string: A string that with placeholders.
+        args: Expression(s) that fill the placeholders.
+
+    Examples:
+        >>> import duckdb
+        >>> import narwhals as nw
+        >>> rel = duckdb.sql("select * from values ('a', 1), ('b', 2), ('c', 3) df(a, b)")
+        >>> df = nw.from_native(rel)
+        >>> df.with_columns(formatted=nw.format("foo_{}_bar_{}", nw.col("a"), "b"))
+        ┌─────────────────────────────────┐
+        |       Narwhals LazyFrame        |
+        |---------------------------------|
+        |┌─────────┬───────┬─────────────┐|
+        |│    a    │   b   │  formatted  │|
+        |│ varchar │ int32 │   varchar   │|
+        |├─────────┼───────┼─────────────┤|
+        |│ a       │     1 │ foo_a_bar_1 │|
+        |│ b       │     2 │ foo_b_bar_2 │|
+        |│ c       │     3 │ foo_c_bar_3 │|
+        |└─────────┴───────┴─────────────┘|
+        └─────────────────────────────────┘
+    """
+    if (n_placeholders := f_string.count("{}")) != len(args):
+        msg = f"number of placeholders should equal the number of arguments. Expected {n_placeholders} arguments, got {len(args)}."
+        raise ValueError(msg)
+
+    exprs = []
+    it = iter(args)
+    for i, s in enumerate(f_string.split("{}")):
+        if i > 0:
+            exprs.append(next(it))
+        if len(s) > 0:
+            exprs.append(lit(s))
+    return concat_str(exprs, separator="")

narwhals/stable/v1/__init__.py

@@ -1175,6 +1175,11 @@ def concat_str(
     )
 
 
+def format(f_string: str, *args: IntoExpr) -> Expr:
+    """Format expressions as a string."""
+    return _stableify(nw.format(f_string, *args))
+
+
 def coalesce(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr:
     return _stableify(nw.coalesce(exprs, *more_exprs))
 
@@ -1412,6 +1417,7 @@ def scan_parquet(
     "dtypes",
     "exceptions",
     "exclude",
+    "format",
     "from_arrow",
     "from_dict",
     "from_dicts",

narwhals/stable/v2/__init__.py

@@ -915,6 +915,16 @@ def concat_str(
     )
 
 
+def format(f_string: str, *args: IntoExpr) -> Expr:
+    """Format expressions as a string.
+
+    Arguments:
+        f_string: A string that with placeholders.
+        args: Expression(s) that fill the placeholders.
+    """
+    return _stableify(nw.format(f_string, *args))
+
+
 def coalesce(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr:
     """Folds the columns from left to right, keeping the first non-null value.
 
@@ -1233,6 +1243,7 @@ def scan_parquet(
     "dtypes",
     "exceptions",
     "exclude",
+    "format",
     "from_arrow",
     "from_dict",
     "from_dicts",

tests/expr_and_series/format_test.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import pandas as pd
+import pytest
+
+import narwhals as nw
+from tests.utils import Constructor, assert_equal_data
+
+
+def test_format(constructor: Constructor) -> None:
+    df = nw.from_native(
+        constructor(
+            {
+                "name": ["bob", "alice", "dodo"],
+                "surname": ["builder", "wonderlander", "extinct"],
+            }
+        )
+    )
+    result = df.select(fmt=nw.format("hello {} {} wassup", "name", nw.col("surname")))
+    expected = {
+        "fmt": [
+            "hello bob builder wassup",
+            "hello alice wonderlander wassup",
+            "hello dodo extinct wassup",
+        ]
+    }
+    assert_equal_data(result, expected)
+    result = df.select(fmt=nw.format("{} {} wassup", "name", nw.col("surname")))
+    expected = {
+        "fmt": ["bob builder wassup", "alice wonderlander wassup", "dodo extinct wassup"]
+    }
+    assert_equal_data(result, expected)
+
+
+def test_format_invalid() -> None:
+    df = nw.from_native(
+        pd.DataFrame(
+            {
+                "name": ["bob", "alice", "dodo"],
+                "surname": ["builder", "wonderlander", "extinct"],
+            }
+        )
+    )
+    with pytest.raises(ValueError, match="Expected 2 arguments, got 1"):
+        df.select(fmt=nw.format("hello {} {} wassup", "name"))

tests/v1_test.py

@@ -73,6 +73,7 @@ def test_toplevel() -> None:
         mean_h=nw_v1.mean_horizontal("a"),
         len=nw_v1.len(),
         concat_str=nw_v1.concat_str(nw_v1.lit("a"), nw_v1.lit("b")),
+        fmt=nw_v1.format("{}", "a"),
         any_h=nw_v1.any_horizontal(nw_v1.lit(True), nw_v1.lit(True)),
         all_h=nw_v1.all_horizontal(nw_v1.lit(True), nw_v1.lit(True)),
         first=nw_v1.nth(0),
@@ -91,6 +92,7 @@ def test_toplevel() -> None:
         "mean_h": [1, 2, 3],
         "len": [3, 3, 3],
         "concat_str": ["ab", "ab", "ab"],
+        "fmt": ["1", "2", "3"],
         "any_h": [True, True, True],
         "all_h": [True, True, True],
         "first": [1, 2, 3],

tests/v2_test.py

@@ -55,6 +55,7 @@ def test_toplevel() -> None:
         mean_h=nw_v2.mean_horizontal("a"),
         len=nw_v2.len(),
         concat_str=nw_v2.concat_str(nw_v2.lit("a"), nw_v2.lit("b")),
+        fmt=nw_v2.format("{}", "a"),
         any_h=nw_v2.any_horizontal(nw_v2.lit(True), nw_v2.lit(True), ignore_nulls=True),
         all_h=nw_v2.all_horizontal(nw_v2.lit(True), nw_v2.lit(True), ignore_nulls=True),
         first=nw_v2.nth(0),
@@ -73,6 +74,7 @@ def test_toplevel() -> None:
         "mean_h": [1, 2, 3],
         "len": [3, 3, 3],
         "concat_str": ["ab", "ab", "ab"],
+        "fmt": ["1", "2", "3"],
         "any_h": [True, True, True],
         "all_h": [True, True, True],
         "first": [1, 2, 3],