feat: Add support for {Expr,Series}.str.to_titlecase

docs/api-reference/expr_str.md

@@ -18,6 +18,7 @@
         - to_date
         - to_datetime
         - to_lowercase
+        - to_titlecase
         - to_uppercase
         - zfill
       show_source: false

docs/api-reference/series_str.md

@@ -18,6 +18,7 @@
         - to_date
         - to_datetime
         - to_lowercase
+        - to_titlecase
         - to_uppercase
         - zfill
       show_source: false

narwhals/_arrow/series_str.py

@@ -79,6 +79,9 @@ def to_uppercase(self) -> ArrowSeries:
     def to_lowercase(self) -> ArrowSeries:
         return self.with_native(pc.utf8_lower(self.native))
 
+    def to_titlecase(self) -> ArrowSeries:
+        return self.with_native(pc.utf8_title(self.native))
+
     def zfill(self, width: int) -> ArrowSeries:
         binary_join: Incomplete = pc.binary_join_element_wise
         native = self.native

narwhals/_compliant/any_namespace.py

@@ -100,6 +100,7 @@ def split(self, by: str) -> CompliantT_co: ...
     def to_datetime(self, format: str | None) -> CompliantT_co: ...
     def to_date(self, format: str | None) -> CompliantT_co: ...
     def to_lowercase(self) -> CompliantT_co: ...
+    def to_titlecase(self) -> CompliantT_co: ...
     def to_uppercase(self) -> CompliantT_co: ...
     def zfill(self, width: int) -> CompliantT_co: ...
 

narwhals/_compliant/expr.py

@@ -1156,6 +1156,9 @@ def to_uppercase(self) -> EagerExprT:
     def zfill(self, width: int) -> EagerExprT:
         return self.compliant._reuse_series_namespace("str", "zfill", width=width)
 
+    def to_titlecase(self) -> EagerExprT:
+        return self.compliant._reuse_series_namespace("str", "to_titlecase")
+
 
 class EagerExprStructNamespace(
     EagerExprNamespace[EagerExprT], StructNamespace[EagerExprT], Generic[EagerExprT]

narwhals/_dask/expr_str.py

@@ -113,6 +113,11 @@ def to_lowercase(self) -> DaskExpr:
             lambda expr: expr.str.lower(), "to_lowercase"
         )
 
+    def to_titlecase(self) -> DaskExpr:
+        return self.compliant._with_callable(
+            lambda expr: expr.str.title(), "to_titlecase"
+        )
+
     def zfill(self, width: int) -> DaskExpr:
         return self.compliant._with_callable(
             lambda expr, width: expr.str.zfill(width), "zfill", width=width

narwhals/_duckdb/expr_str.py

@@ -2,11 +2,13 @@
 
 from typing import TYPE_CHECKING
 
-from narwhals._duckdb.utils import F, lit
+from narwhals._duckdb.utils import F, col, concat_str, lit
 from narwhals._sql.expr_str import SQLExprStringNamespace
-from narwhals._utils import not_implemented
+from narwhals._utils import not_implemented, requires
 
 if TYPE_CHECKING:
+    from duckdb import Expression
+
     from narwhals._duckdb.expr import DuckDBExpr
 
 
@@ -27,4 +29,25 @@ def to_date(self, format: str | None) -> DuckDBExpr:
         compliant_expr = self.compliant
         return compliant_expr.cast(compliant_expr._version.dtypes.Date())
 
+    @requires.backend_version((1, 2))
+    def to_titlecase(self) -> DuckDBExpr:
+        from narwhals._duckdb.utils import lambda_expr
+
+        def _to_titlecase(expr: Expression) -> Expression:
+            extract_expr = F(
+                "regexp_extract_all", F("lower", expr), lit(r"[a-z0-9]*[^a-z0-9]*")
+            )
+            elem = col("_")
+            capitalize = lambda_expr(
+                elem,
+                concat_str(
+                    F("upper", F("array_extract", elem, lit(1))),
+                    F("substring", elem, lit(2)),
+                ),
+            )
+            capitalized_expr = F("list_transform", extract_expr, capitalize)
+            return F("list_aggregate", capitalized_expr, lit("string_agg"), lit(""))
+
+        return self.compliant._with_elementwise(_to_titlecase)
+
     replace = not_implemented()

narwhals/_duckdb/utils.py

@@ -5,6 +5,7 @@
 
 import duckdb
 import duckdb.typing as duckdb_dtypes
+from duckdb import Expression
 from duckdb.typing import DuckDBPyType
 
 from narwhals._utils import Version, isinstance_or_issubclass, zip_strict
@@ -13,7 +14,7 @@
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
 
-    from duckdb import DuckDBPyRelation, Expression
+    from duckdb import DuckDBPyRelation
 
     from narwhals._compliant.typing import CompliantLazyFrameAny
     from narwhals._duckdb.dataframe import DuckDBLazyFrame
@@ -50,6 +51,22 @@
 """Alias for `duckdb.FunctionExpression`."""
 
 
+def lambda_expr(
+    params: str | Expression | tuple[Expression, ...], expr: Expression, /
+) -> Expression:
+    """Wraps [`duckdb.LambdaExpression`].
+
+    [`duckdb.LambdaExpression`]: https://duckdb.org/docs/stable/sql/functions/lambda
+    """
+    try:
+        from duckdb import LambdaExpression
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        msg = f"DuckDB>=1.2.0 is required for this operation. Found: DuckDB {duckdb.__version__}"
+        raise NotImplementedError(msg) from exc
+    args = (params,) if isinstance(params, Expression) else params
+    return LambdaExpression(args, expr)
+
+
 def concat_str(*exprs: Expression, separator: str = "") -> Expression:
     """Concatenate many strings, NULL inputs are skipped.
 

narwhals/_ibis/expr_str.py

@@ -81,3 +81,4 @@ def fn(expr: ir.StringColumn) -> ir.DateValue:
         return self.compliant._with_callable(fn)
 
     replace = not_implemented()
+    to_titlecase = not_implemented()

narwhals/_pandas_like/series_str.py

@@ -88,5 +88,8 @@ def to_uppercase(self) -> PandasLikeSeries:
     def to_lowercase(self) -> PandasLikeSeries:
         return self.with_native(self.native.str.lower())
 
+    def to_titlecase(self) -> PandasLikeSeries:
+        return self.with_native(self.native.str.title())
+
     def zfill(self, width: int) -> PandasLikeSeries:
         return self.with_native(self.native.str.zfill(width))

narwhals/_polars/expr.py

@@ -5,6 +5,7 @@
 import polars as pl
 
 from narwhals._polars.utils import (
+    BACKEND_VERSION,
     PolarsAnyNamespace,
     PolarsCatNamespace,
     PolarsDateTimeNamespace,
@@ -411,6 +412,21 @@ class PolarsExprDateTimeNamespace(
 class PolarsExprStringNamespace(
     PolarsExprNamespace, PolarsStringNamespace[PolarsExpr, pl.Expr]
 ):
+    def to_titlecase(self) -> PolarsExpr:
+        native_expr = self.native
+
+        if BACKEND_VERSION < (1, 5):
+            native_result = (
+                native_expr.str.to_lowercase()
+                .str.extract_all(r"[a-z0-9]*[^a-z0-9]*")
+                .list.eval(pl.element().str.to_titlecase())
+                .list.join("")
+            )
+        else:
+            native_result = native_expr.str.to_titlecase()
+
+        return self.compliant._with_native(native_result)
+
     @requires.backend_version((0, 20, 5))
     def zfill(self, width: int) -> PolarsExpr:
         backend_version = self.compliant._backend_version

narwhals/_polars/series.py

@@ -786,6 +786,11 @@ class PolarsSeriesDateTimeNamespace(
 class PolarsSeriesStringNamespace(
     PolarsSeriesNamespace, PolarsStringNamespace[PolarsSeries, pl.Series]
 ):
+    def to_titlecase(self) -> PolarsSeries:
+        name = self.name
+        ns = self.__narwhals_namespace__()
+        return self.to_frame().select(ns.col(name).str.to_titlecase()).get_column(name)
+
     def zfill(self, width: int) -> PolarsSeries:
         name = self.name
         ns = self.__narwhals_namespace__()

narwhals/_polars/utils.py

@@ -326,6 +326,9 @@ class PolarsStringNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
     _accessor: ClassVar[Accessor] = "str"
 
     # NOTE: Use `abstractmethod` if we have defs to implement, but also `Method` usage
+    @abc.abstractmethod
+    def to_titlecase(self) -> CompliantT: ...
+
     @abc.abstractmethod
     def zfill(self, width: int) -> CompliantT: ...
 

narwhals/_spark_like/expr_str.py

@@ -5,9 +5,11 @@
 
 from narwhals._spark_like.utils import strptime_to_pyspark_format
 from narwhals._sql.expr_str import SQLExprStringNamespace
-from narwhals._utils import _is_naive_format, not_implemented
+from narwhals._utils import _is_naive_format, not_implemented, requires
 
 if TYPE_CHECKING:
+    from sqlframe.base.column import Column
+
     from narwhals._spark_like.expr import SparkLikeExpr
 
 
@@ -33,4 +35,30 @@ def to_date(self, format: str | None) -> SparkLikeExpr:
             lambda expr: F.to_date(expr, format=strptime_to_pyspark_format(format))
         )
 
+    def to_titlecase(self) -> SparkLikeExpr:
+        impl = self.compliant._implementation
+        sqlframe_required_version = (3, 43, 1)
+        if (
+            impl.is_sqlframe()
+            and (version := impl._backend_version()) < sqlframe_required_version
+        ):  # pragma: no cover
+            required_str = requires._unparse_version(sqlframe_required_version)
+            found_str = requires._unparse_version(version)
+            msg = (
+                f"`str.to_titlecase` is only available in 'sqlframe>={required_str}', "
+                f"found version {found_str!r}."
+            )
+            raise NotImplementedError(msg)
+
+        def _to_titlecase(expr: Column) -> Column:
+            F = self.compliant._F
+            lower_expr = F.lower(expr)
+            extract_expr = F.regexp_extract_all(
+                lower_expr, regexp=F.lit(r"[a-z0-9]*[^a-z0-9]*"), idx=0
+            )
+            capitalized_expr = F.transform(extract_expr, f=F.initcap)
+            return F.array_join(capitalized_expr, delimiter="")
+
+        return self.compliant._with_elementwise(_to_titlecase)
+
     replace = not_implemented()

narwhals/expr_str.py

@@ -455,6 +455,62 @@ def to_lowercase(self) -> ExprT:
             lambda plx: self._expr._to_compliant_expr(plx).str.to_lowercase()
         )
 
+    def to_titlecase(self) -> ExprT:
+        """Modify strings to their titlecase equivalent.
+
+        Notes:
+            This is a form of case transform where the first letter of each word is
+            capitalized, with the rest of the word in lowercase.
+
+        Warning:
+            Different backends might follow different rules to determine what a "word" is:
+
+            - duckdb, polars and spark-like use non-**alphanumeric** characters to
+                define the word boundaries.
+            - pandas-like, pyarrow and dask use non-**alphabetic** characters to define
+                the word boundaries, matching the behavior of
+                [`str.title`](https://docs.python.org/3/library/stdtypes.html#str.title).
+
+            We can observe the difference with the string `"with123numbers"`:
+
+            - non-**alphanumeric** -> `"With123numbers"`
+                - notice lowercase **n** after the digits
+            - non-**alphabetic** -> `"With123Numbers"`
+                - notice uppercase **N** after the digits
+
+        Examples:
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> df_native = pl.DataFrame(
+            ...     {
+            ...         "quotes": [
+            ...             "'e.t. phone home'",
+            ...             "you talkin' to me?",
+            ...             "to infinity,and BEYOND!",
+            ...         ]
+            ...     }
+            ... )
+            >>> df = nw.from_native(df_native)
+            >>> df.with_columns(quotes_title=nw.col("quotes").str.to_titlecase())
+            ┌─────────────────────────────────────────────────────┐
+            |                 Narwhals DataFrame                  |
+            |-----------------------------------------------------|
+            |shape: (3, 2)                                        |
+            |┌─────────────────────────┬─────────────────────────┐|
+            |│ quotes                  ┆ quotes_title            │|
+            |│ ---                     ┆ ---                     │|
+            |│ str                     ┆ str                     │|
+            |╞═════════════════════════╪═════════════════════════╡|
+            |│ 'e.t. phone home'       ┆ 'E.T. Phone Home'       │|
+            |│ you talkin' to me?      ┆ You Talkin' To Me?      │|
+            |│ to infinity,and BEYOND! ┆ To Infinity,And Beyond! │|
+            |└─────────────────────────┴─────────────────────────┘|
+            └─────────────────────────────────────────────────────┘
+        """
+        return self._expr._with_elementwise(
+            lambda plx: self._expr._to_compliant_expr(plx).str.to_titlecase()
+        )
+
     def zfill(self, width: int) -> ExprT:
         """Transform string to zero-padded variant.
 

narwhals/series_str.py

@@ -392,6 +392,52 @@ def to_date(self, format: str | None = None) -> SeriesT:
             self._narwhals_series._compliant_series.str.to_date(format=format)
         )
 
+    def to_titlecase(self) -> SeriesT:
+        """Modify strings to their titlecase equivalent.
+
+        Notes:
+            This is a form of case transform where the first letter of each word is
+            capitalized, with the rest of the word in lowercase.
+
+        Warning:
+            Different backends might follow different rules to determine what a "word" is:
+
+            - polars uses **non-alphanumeric** characters to define the word boundaries.
+            - pandas-like and pyarrow use **non-alphabetic** characters to define
+                the word boundaries, matching the behavior of
+                [`str.title`](https://docs.python.org/3/library/stdtypes.html#str.title).
+
+            As an example of such difference, in the former case the string `"with123numbers"`
+            is mapped to `"With123numbers"` (notice lowercase **n** after the digits), while
+            in the latter to `"With123Numbers"` (notice uppercase **N** after the digits).
+
+        Examples:
+            >>> import pyarrow as pa
+            >>> import narwhals as nw
+            >>> s_native = pa.chunked_array(
+            ...     [
+            ...         [
+            ...             "'e.t. phone home'",
+            ...             "you talkin' to me?",
+            ...             "to infinity,and BEYOND!",
+            ...         ]
+            ...     ]
+            ... )
+            >>> s = nw.from_native(s_native, series_only=True)
+            >>> s.str.to_titlecase().to_native()  # doctest: +ELLIPSIS
+            <pyarrow.lib.ChunkedArray object at ...>
+            [
+              [
+                "'E.T. Phone Home'",
+                "You Talkin' To Me?",
+                "To Infinity,And Beyond!"
+              ]
+            ]
+        """
+        return self._narwhals_series._with_compliant(
+            self._narwhals_series._compliant_series.str.to_titlecase()
+        )
+
     def zfill(self, width: int) -> SeriesT:
         r"""Pad strings with zeros on the left.
 

pyproject.toml

@@ -303,6 +303,7 @@ exclude_also = [
   'request.applymarker\(pytest.mark.xfail',
   'backend_version <',
   '.*._backend_version\(\) <',
+  'BACKEND_VERSION <',
   'if ".*" in str\(constructor',
   'pytest.skip\(',
   'assert_never\(',