improve persist example (#322)

* improve persist example

* use scalar.persist

* Update spec/API_specification/dataframe_api/dataframe_object.py

Co-authored-by: Keith Kraus <[email protected]>

* remove unnecessary scalar.persist

---------

Co-authored-by: Keith Kraus <[email protected]>

Author: MarcoGorelli

spec/API_specification/dataframe_api/dataframe_object.py

@@ -995,10 +995,11 @@ def persist(self) -> Self:
             .. code-block:: python
 
                 df: DataFrame
-                df = df.persist()
                 features = []
+                result = df.std() > 0
+                result = result.persist()
                 for column_name in df.column_names:
-                    if df.col(column_name).std() > 0:
+                    if result.col(column_name).get_value(0):
                         features.append(column_name)
 
             instead of this:
@@ -1008,7 +1009,8 @@ def persist(self) -> Self:
                 df: DataFrame
                 features = []
                 for column_name in df.column_names:
-                    # Do NOT do this!
+                    # Do NOT call `persist` on a `DataFrame` within a for-loop!
+                    # This may re-trigger the same computation multiple times
                     if df.persist().col(column_name).std() > 0:
                         features.append(column_name)
         """