Fast/cheap empty clone ops (#3883)

py-polars/docs/source/reference/dataframe.rst

@@ -81,6 +81,7 @@ Manipulation/ selection
 .. autosummary::
    :toctree: api/
 
+    DataFrame.cleared
     DataFrame.clone
     DataFrame.distinct
     DataFrame.drop

py-polars/docs/source/reference/lazyframe.rst

@@ -46,6 +46,7 @@ Manipulation/ selection
 .. autosummary::
    :toctree: api/
 
+    LazyFrame.cleared
     LazyFrame.clone
     LazyFrame.distinct
     LazyFrame.drop

py-polars/docs/source/reference/series.rst

@@ -155,6 +155,7 @@ Manipulation/ selection
     Series.argsort
     Series.cast
     Series.ceil
+    Series.cleared
     Series.clip
     Series.clone
     Series.drop_nans

py-polars/polars/internals/frame.py

@@ -4081,9 +4081,15 @@ def select_at_idx(self, idx: int) -> pli.Series:
         """
         return pli.wrap_s(self._df.select_at_idx(idx))
 
+    def cleared(self: DF) -> DF:
+        """
+        Create an empty copy of the current DataFrame, with identical schema but no data.
+        """
+        return self.head(0) if len(self) > 0 else self.clone()
+
     def clone(self: DF) -> DF:
         """
-        Cheap deepcopy/clone.
+        Very cheap deepcopy/clone.
         """
         return self._from_pydf(self._df.clone())
 

py-polars/polars/internals/lazy_frame.py

@@ -746,9 +746,15 @@ def cache(self: LDF) -> LDF:
         """
         return self._from_pyldf(self._ldf.cache())
 
+    def cleared(self: LDF) -> LDF:
+        """
+        Create an empty copy of the current LazyFrame, with identical schema but no data.
+        """
+        return self._dataframe_class(columns=self.schema).lazy()
+
     def clone(self: LDF) -> LDF:
         """
-        Cheap deepcopy/clone.
+        Very cheap deepcopy/clone.
         """
         return self._from_pyldf(self._ldf.clone())
 

py-polars/polars/internals/series.py

@@ -2352,9 +2352,15 @@ def set_at_idx(
 
         return wrap_s(f(idx_array, value))
 
-    def clone(self) -> Series:
+    def cleared(self) -> "Series":
         """
-        Cheap deep clones.
+        Create an empty copy of the current Series, with identical name/dtype but no data.
+        """
+        return self.limit(0) if len(self) > 0 else self.clone()
+
+    def clone(self) -> "Series":
+        """
+        Very cheap deepcopy/clone.
         """
         return wrap_s(self._s.clone())
 

py-polars/tests/test_df.py

@@ -85,6 +85,9 @@ def test_init_only_columns() -> None:
         assert df.dtypes == [pl.Date, pl.UInt64, pl.Int8, pl.List]
         assert getattr(df.schema["d"], "inner") == pl.UInt8
 
+        dfe = df.cleared()
+        assert (df.schema == dfe.schema) and (dfe.shape == df.shape)
+
 
 def test_special_char_colname_init() -> None:
     from string import punctuation
@@ -173,6 +176,9 @@ def test_init_dict() -> None:
     )
     assert df.schema == {"c": pl.Int8, "d": pl.Int16}
 
+    dfe = df.cleared()
+    assert (df.schema == dfe.schema) and (len(dfe) == 0)
+
 
 def test_init_ndarray() -> None:
     # Empty array

py-polars/tests/test_lazy.py

@@ -1258,6 +1258,9 @@ def test_lazy_schema() -> None:
     ).lazy()
     assert lf.dtypes == [pl.Int64, pl.Float64, pl.Utf8]
 
+    lfe = lf.cleared()
+    assert lfe.schema == lf.schema
+
 
 def test_deadlocks_3409() -> None:
     assert (

py-polars/tests/test_series.py

@@ -630,6 +630,11 @@ def test_empty() -> None:
         pl.Series(dtype=pl.Int32), pl.Series(dtype=pl.Int64), check_dtype=False
     )
 
+    a = pl.Series(name="a", values=[1, 2, 3], dtype=pl.Int16)
+    empty_a = a.cleared()
+    assert a.dtype == empty_a.dtype
+    assert len(empty_a) == 0
+
 
 def test_describe() -> None:
     num_s = pl.Series([1, 2, 3])