feat: add strip_chars to string namespace (#715)

* feat: add `strip_chars` to string namespace

* fix: remove unnecessary "\n"

* doc: complete docstrings /doctests

* perf: hard-code whitespace instead of importing from `string`

* Update narwhals/_arrow/series.py

Co-authored-by: Francesco Bruzzesi <[email protected]>

* doc: better docstrings

---------

Co-authored-by: Francesco Bruzzesi <[email protected]>

docs/api-reference/expr_str.md

@@ -9,6 +9,7 @@
         - head
         - slice
         - starts_with
+        - strip_chars
         - tail
         - to_datetime
         - to_lowercase

docs/api-reference/series_str.md

@@ -9,6 +9,7 @@
         - head
         - slice
         - starts_with
+        - strip_chars
         - tail
       show_source: false
       show_bases: false

narwhals/_arrow/expr.py

@@ -400,6 +400,14 @@ class ArrowExprStringNamespace:
     def __init__(self, expr: ArrowExpr) -> None:
         self._expr = expr
 
+    def strip_chars(self, characters: str | None = None) -> ArrowExpr:
+        return reuse_series_namespace_implementation(
+            self._expr,
+            "str",
+            "strip_chars",
+            characters,
+        )
+
     def starts_with(self, prefix: str) -> ArrowExpr:
         return reuse_series_namespace_implementation(
             self._expr,

narwhals/_arrow/series.py

@@ -791,6 +791,16 @@ class ArrowSeriesStringNamespace:
     def __init__(self: Self, series: ArrowSeries) -> None:
         self._arrow_series = series
 
+    def strip_chars(self: Self, characters: str | None = None) -> ArrowSeries:
+        pc = get_pyarrow_compute()
+        whitespace = " \t\n\r\v\f"
+        return self._arrow_series._from_native_series(
+            pc.utf8_trim(
+                self._arrow_series._native_series,
+                characters or whitespace,
+            )
+        )
+
     def starts_with(self: Self, prefix: str) -> ArrowSeries:
         pc = get_pyarrow_compute()
         return self._arrow_series._from_native_series(

narwhals/_dask/expr.py

@@ -283,6 +283,11 @@ class DaskExprStringNamespace:
     def __init__(self, expr: DaskExpr) -> None:
         self._expr = expr
 
+    def strip_chars(self, characters: str | None = None) -> DaskExpr:
+        return self._expr._from_call(
+            lambda _input, characters: _input.str.strip(characters), "strip", characters
+        )
+
     def starts_with(self, prefix: str) -> DaskExpr:
         return self._expr._from_call(
             lambda _input, prefix: _input.str.startswith(prefix), "starts_with", prefix

narwhals/_pandas_like/expr.py

@@ -365,6 +365,14 @@ class PandasLikeExprStringNamespace:
     def __init__(self, expr: PandasLikeExpr) -> None:
         self._expr = expr
 
+    def strip_chars(self, characters: str | None = None) -> PandasLikeExpr:
+        return reuse_series_namespace_implementation(
+            self._expr,
+            "str",
+            "strip_chars",
+            characters,
+        )
+
     def starts_with(self, prefix: str) -> PandasLikeExpr:
         return reuse_series_namespace_implementation(
             self._expr,

narwhals/_pandas_like/series.py

@@ -659,6 +659,11 @@ class PandasLikeSeriesStringNamespace:
     def __init__(self, series: PandasLikeSeries) -> None:
         self._pandas_series = series
 
+    def strip_chars(self, characters: str | None) -> PandasLikeSeries:
+        return self._pandas_series._from_native_series(
+            self._pandas_series._native_series.str.strip(characters),
+        )
+
     def starts_with(self, prefix: str) -> PandasLikeSeries:
         return self._pandas_series._from_native_series(
             self._pandas_series._native_series.str.startswith(prefix),

narwhals/expr.py

@@ -1833,6 +1833,40 @@ class ExprStringNamespace:
     def __init__(self, expr: Expr) -> None:
         self._expr = expr
 
+    def strip_chars(self, characters: str | None = None) -> Expr:
+        r"""
+        Remove leading and trailing characters.
+
+        Arguments:
+            characters: The set of characters to be removed. All combinations of this set of characters will be stripped from the start and end of the string. If set to None (default), all leading and trailing whitespace is removed instead.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> data = {"fruits": ["apple", "\nmango"]}
+            >>> df_pd = pd.DataFrame(data)
+            >>> df_pl = pl.DataFrame(data)
+
+            We define a dataframe-agnostic function:
+
+            >>> @nw.narwhalify
+            ... def func(df):
+            ...     df = df.with_columns(stripped=nw.col("fruits").str.strip_chars())
+            ...     return df.to_dict(as_series=False)
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(df_pd)
+            {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']}
+
+            >>> func(df_pl)
+            {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']}
+        """
+        return self._expr.__class__(
+            lambda plx: self._expr._call(plx).str.strip_chars(characters)
+        )
+
     def starts_with(self, prefix: str) -> Expr:
         r"""
         Check if string values start with a substring.

narwhals/series.py

@@ -2148,6 +2148,40 @@ class SeriesStringNamespace:
     def __init__(self, series: Series) -> None:
         self._narwhals_series = series
 
+    def strip_chars(self, characters: str | None = None) -> Series:
+        r"""
+        Remove leading and trailing characters.
+
+        Arguments:
+            characters: The set of characters to be removed. All combinations of this set of characters will be stripped from the start and end of the string. If set to None (default), all leading and trailing whitespace is removed instead.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> data = ["apple", "\nmango"]
+            >>> s_pd = pd.Series(data)
+            >>> s_pl = pl.Series(data)
+
+            We define a dataframe-agnostic function:
+
+            >>> @nw.narwhalify
+            ... def func(s):
+            ...     s = s.str.strip_chars()
+            ...     return s.to_list()
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(s_pd)
+            ['apple', 'mango']
+
+            >>> func(s_pl)
+            ['apple', 'mango']
+        """
+        return self._narwhals_series._from_compliant_series(
+            self._narwhals_series._compliant_series.str.strip_chars(characters)
+        )
+
     def starts_with(self, prefix: str) -> Series:
         r"""
         Check if string values start with a substring.

tests/expr_and_series/str/strip_chars_test.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+import narwhals.stable.v1 as nw
+from tests.utils import compare_dicts
+
+data = {"a": ["foobar", "bar\n", " baz"]}
+
+
+@pytest.mark.parametrize(
+    ("characters", "expected"),
+    [
+        (None, {"a": ["foobar", "bar", "baz"]}),
+        ("foo", {"a": ["bar", "bar\n", " baz"]}),
+    ],
+)
+def test_str_strip_chars(constructor: Any, characters: str | None, expected: Any) -> None:
+    df = nw.from_native(constructor(data))
+    result_frame = df.select(nw.col("a").str.strip_chars(characters))
+    compare_dicts(result_frame, expected)
+
+
+@pytest.mark.parametrize(
+    ("characters", "expected"),
+    [
+        (None, {"a": ["foobar", "bar", "baz"]}),
+        ("foo", {"a": ["bar", "bar\n", " baz"]}),
+    ],
+)
+def test_str_strip_chars_series(
+    constructor_eager: Any, characters: str | None, expected: Any
+) -> None:
+    df = nw.from_native(constructor_eager(data), eager_only=True)
+
+    result_series = df["a"].str.strip_chars(characters)
+    assert result_series.to_list() == expected["a"]