docs(python): add big warnings about using apply (#9906)

py-polars/polars/dataframe/frame.py

@@ -5682,6 +5682,10 @@ def apply(
         """
         Apply a custom/user-defined function (UDF) over the rows of the DataFrame.
 
+        .. warning::
+            This method is much slower than the native expressions API.
+            Only use it if you cannot implement your logic otherwise.
+
         The UDF will receive each row as a tuple of values: ``udf(row)``.
 
         Implementing logic using a Python function is almost always _significantly_

py-polars/polars/dataframe/groupby.py

@@ -252,6 +252,10 @@ def apply(self, function: Callable[[DataFrame], DataFrame]) -> DataFrame:
         """
         Apply a custom/user-defined function (UDF) over the groups as a sub-DataFrame.
 
+        .. warning::
+            This method is much slower than the native expressions API.
+            Only use it if you cannot implement your logic otherwise.
+
         Implementing logic using a Python function is almost always _significantly_
         slower and more memory intensive than implementing the same logic using
         the native expression API because:

py-polars/polars/expr/expr.py

@@ -3613,6 +3613,10 @@ def apply(
         """
         Apply a custom/user-defined function (UDF) in a GroupBy or Projection context.
 
+        .. warning::
+            This method is much slower than the native expressions API.
+            Only use it if you cannot implement your logic otherwise.
+
         Depending on the context it has the following behavior:
 
         * Selection

py-polars/polars/functions/lazy.py

@@ -1164,6 +1164,10 @@ def apply(
     """
     Apply a custom/user-defined function (UDF) in a GroupBy context.
 
+    .. warning::
+        This method is much slower than the native expressions API.
+        Only use it if you cannot implement your logic otherwise.
+
     Depending on the context it has the following behavior:
 
     * Select

py-polars/polars/lazyframe/groupby.py

@@ -163,6 +163,10 @@ def apply(
         """
         Apply a custom/user-defined function (UDF) over the groups as a new DataFrame.
 
+        .. warning::
+            This method is much slower than the native expressions API.
+            Only use it if you cannot implement your logic otherwise.
+
         Using this is considered an anti-pattern. This will be very slow because:
 
         - it forces the engine to materialize the whole `DataFrames` for the groups.

py-polars/polars/series/series.py

@@ -4364,6 +4364,10 @@ def apply(
         """
         Apply a custom/user-defined function (UDF) over elements in this Series.
 
+        .. warning::
+            This method is much slower than the native expressions API.
+            Only use it if you cannot implement your logic otherwise.
+
         If the function returns a different datatype, the return_dtype arg should
         be set, otherwise the method will fail.