docs: update docstrings with pyarrow examples

narwhals/expr.py

@@ -452,19 +452,21 @@ def median(self) -> Self:
         Get median value.
 
         Examples:
-            >>> import polars as pl
             >>> import pandas as pd
+            >>> import polars as pl
+            >>> import pyarrow as pa
             >>> import narwhals as nw
             >>> df_pd = pd.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
             >>> df_pl = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
+            >>> df_pa = pa.table({"a": [1, 8, 3], "b": [4, 5, 2]})
 
             Let's define a dataframe-agnostic function:
 
             >>> @nw.narwhalify
             ... def func(df):
             ...     return df.select(nw.col("a", "b").median())
 
-            We can then pass either pandas or Polars to `func`:
+            We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
 
             >>> func(df_pd)
                  a    b
@@ -478,6 +480,13 @@ def median(self) -> Self:
             ╞═════╪═════╡
             │ 3.0 ┆ 4.0 │
             └─────┴─────┘
+            >>> func(df_pa)
+            pyarrow.Table
+            a: double
+            b: double
+            ----
+            a: [[3]]
+            b: [[4]]
         """
         return self.__class__(lambda plx: self._call(plx).median())
 
@@ -4597,17 +4606,19 @@ def median(*columns: str) -> Expr:
     Examples:
         >>> import pandas as pd
         >>> import polars as pl
+        >>> import pyarrow as pa
         >>> import narwhals as nw
         >>> df_pd = pd.DataFrame({"a": [4, 5, 2]})
         >>> df_pl = pl.DataFrame({"a": [4, 5, 2]})
+        >>> df_pa = pa.table({"a": [4, 5, 2]})
 
-        We define a dataframe agnostic function:
+        Let's define a dataframe agnostic function:
 
         >>> @nw.narwhalify
         ... def func(df):
         ...     return df.select(nw.median("a"))
 
-        We can then pass either pandas or Polars to `func`:
+        We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
 
         >>> func(df_pd)
              a
@@ -4621,6 +4632,11 @@ def median(*columns: str) -> Expr:
         ╞═════╡
         │ 4.0 │
         └─────┘
+        >>> func(df_pa)
+        pyarrow.Table
+        a: double
+        ----
+        a: [[4]]
     """
 
     return Expr(lambda plx: plx.median(*columns))

narwhals/series.py

@@ -528,23 +528,27 @@ def median(self) -> Any:
         Examples:
             >>> import pandas as pd
             >>> import polars as pl
+            >>> import pyarrow as pa
             >>> import narwhals as nw
             >>> s = [5, 3, 8]
             >>> s_pd = pd.Series(s)
             >>> s_pl = pl.Series(s)
+            >>> s_pa = pa.chunked_array([s])
 
-            We define a library agnostic function:
+            Let's define a library agnostic function:
 
             >>> @nw.narwhalify
             ... def func(s):
             ...     return s.median()
 
-            We can then pass either pandas or Polars to `func`:
+            We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
 
             >>> func(s_pd)
             np.float64(5.0)
             >>> func(s_pl)
             5.0
+            >>> func(s_pa)
+            <pyarrow.DoubleScalar: 5.0>
         """
         return self._compliant_series.median()
 

narwhals/stable/v1/__init__.py

@@ -1370,17 +1370,19 @@ def median(*columns: str) -> Expr:
     Examples:
         >>> import pandas as pd
         >>> import polars as pl
+        >>> import pyarrow as pa
         >>> import narwhals.stable.v1 as nw
         >>> df_pd = pd.DataFrame({"a": [4, 5, 2]})
         >>> df_pl = pl.DataFrame({"a": [4, 5, 2]})
+        >>> df_pa = pa.table({"a": [4, 5, 2]})
 
-        We define a dataframe agnostic function:
+        Let's define a dataframe agnostic function:
 
         >>> @nw.narwhalify
         ... def func(df):
         ...     return df.select(nw.median("a"))
 
-        We can then pass either pandas or Polars to `func`:
+        We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
 
         >>> func(df_pd)
              a
@@ -1394,6 +1396,11 @@ def median(*columns: str) -> Expr:
         ╞═════╡
         │ 4.0 │
         └─────┘
+        >>> func(df_pa)
+        pyarrow.Table
+        a: double
+        ----
+        a: [[4]]
     """
     return _stableify(nw.median(*columns))