feat[python]: add new (optional) "name" param to Series.to_frame (#…

…4934)

py-polars/polars/internals/dataframe/frame.py

@@ -26,7 +26,6 @@
 from polars.datatypes import (
     Boolean,
     ColumnsType,
-    DataType,
     Int8,
     Int16,
     Int32,
@@ -3922,7 +3921,7 @@ def join(
     def apply(
         self: DF,
         f: Callable[[tuple[Any, ...]], Any],
-        return_dtype: type[DataType] | None = None,
+        return_dtype: PolarsDataType | None = None,
         inference_size: int = 256,
     ) -> DF:
         """

py-polars/polars/internals/expr/datetime.py

@@ -196,7 +196,7 @@ def year(self) -> pli.Expr:
 
     def iso_year(self) -> pli.Expr:
         """
-        Extract iso-year from underlying Date representation.
+        Extract ISO year from underlying Date representation.
 
         Applies to Date and Datetime columns.
 
@@ -205,7 +205,7 @@ def iso_year(self) -> pli.Expr:
 
         Returns
         -------
-        Year as Int32
+        ISO Year as Int32
 
         """
         return pli.wrap_expr(self._pyexpr.iso_year())

py-polars/polars/internals/lazy_functions.py

@@ -1856,12 +1856,12 @@ def coalesce(
     ],
 ) -> pli.Expr:
     """
-    Folds the expressions from left to right keeping the first no null values.
+    Folds the expressions from left to right, keeping the first non-null value.
 
     Parameters
     ----------
     exprs
-        Expression to coalesce.
+        Expressions to coalesce.
 
     """
     exprs = pli.selection_to_pyexpr_list(exprs)

py-polars/polars/internals/series/datetime.py

@@ -75,11 +75,11 @@ def year(self) -> pli.Series:
 
     def iso_year(self) -> pli.Series:
         """
-        Extract iso-year from underlying Date representation.
+        Extract ISO year from underlying Date representation.
 
         Applies to Date and Datetime columns.
 
-        Returns the year number in the iso standard.
+        Returns the year number according to the ISO standard.
         This may not correspond with the calendar year.
 
         Returns
@@ -172,7 +172,7 @@ def ordinal_day(self) -> pli.Series:
 
         Returns
         -------
-        Ordinaly day as UInt32
+        Ordinal day as UInt32
 
         """
 

py-polars/polars/internals/series/series.py

@@ -879,33 +879,49 @@ def drop_nulls(self) -> Series:
     def drop_nans(self) -> Series:
         """Drop NaN values."""
 
-    def to_frame(self) -> pli.DataFrame:
+    def to_frame(self, name: str | None = None) -> pli.DataFrame:
         """
         Cast this Series to a DataFrame.
 
+        Parameters
+        ----------
+        name
+            optionally name/rename the Series column in the new DataFrame.
+
         Examples
         --------
-        >>> s = pl.Series("a", [1, 2, 3])
+        >>> s = pl.Series("a", [123, 456])
         >>> df = s.to_frame()
         >>> df
-        shape: (3, 1)
+        shape: (2, 1)
         ┌─────┐
         │ a   │
         │ --- │
         │ i64 │
         ╞═════╡
-        │ 1   │
-        ├╌╌╌╌╌┤
-        │ 2   │
+        │ 123 │
         ├╌╌╌╌╌┤
-        │ 3   │
+        │ 456 │
         └─────┘
 
-        >>> type(df)
-        <class 'polars.internals.dataframe.frame.DataFrame'>
+        >>> df = s.to_frame("xyz")
+        >>> df
+        shape: (2, 1)
+        ┌─────┐
+        │ xyz │
+        │ --- │
+        │ i64 │
+        ╞═════╡
+        │ 123 │
+        ├╌╌╌╌╌┤
+        │ 456 │
+        └─────┘
 
         """
-        return pli.wrap_df(PyDataFrame([self._s]))
+        df = pli.wrap_df(PyDataFrame([self._s]))
+        if name is not None:
+            return df.rename({self.name: name})
+        return df
 
     def describe(self) -> pli.DataFrame:
         """
@@ -1189,7 +1205,7 @@ def value_counts(self, sort: bool = False) -> pli.DataFrame:
 
         Parameters
         ----------
-        sort:
+        sort
             Ensure the output is sorted from most values to least.
 
         Examples
@@ -2500,12 +2516,13 @@ def set(self, filter: Series, value: int | float | str) -> Series:
         filter
             Boolean mask.
         value
-            Value to replace the the masked values with.
+            Value with which to replace the masked values.
 
         Notes
         -----
-        Using this is an anti-pattern.
-        Always prefer: `pl.when(predicate).then(value).otherwise(self)`
+        Use of this function is frequently an anti-pattern, as it can
+        block optimisation (predicate pushdown, etc). Consider using
+        `pl.when(predicate).then(value).otherwise(self)` instead.
 
         """
         f = get_ffi_func("set_with_mask_<>", self.dtype, self._s)
@@ -2547,8 +2564,9 @@ def set_at_idx(
 
         Notes
         -----
-        Using this is considered an anti-pattern.
-        Always prefer: `pl.when(predicate).then(value).otherwise(self)`
+        Use of this function is frequently an anti-pattern, as it can
+        block optimisation (predicate pushdown, etc). Consider using
+        `pl.when(predicate).then(value).otherwise(self)` instead.
 
         """
         if isinstance(idx, int):

py-polars/tests/unit/test_series.py

@@ -109,8 +109,22 @@ def test_concat() -> None:
 
 
 def test_to_frame() -> None:
-    s = pl.Series([1, 2])
-    assert s.to_frame().shape == (2, 1)
+    s1 = pl.Series([1, 2])
+    s2 = pl.Series("s", [1, 2])
+
+    df1 = s1.to_frame()
+    df2 = s2.to_frame()
+    df3 = s1.to_frame("xyz")
+    df4 = s2.to_frame("xyz")
+
+    for df, name in ((df1, ""), (df2, "s"), (df3, "xyz"), (df4, "xyz")):
+        assert isinstance(df, pl.DataFrame)
+        assert df.rows() == [(1,), (2,)]
+        assert df.columns == [name]
+
+    # note: the empty string IS technically a valid column name
+    assert s2.to_frame("").columns == [""]
+    assert s2.name == "s"
 
 
 def test_bitwise_ops() -> None: