DOC: documented that .apply(func) executes func twice on the first time

Related issues are pandas-dev#2656, pandas-dev#2936 and pandas-dev#6753.

Author: anton-d

doc/source/groupby.rst

@@ -663,6 +663,25 @@ The dimension of the returned result can also change:
     s
     s.apply(f)
 
+
+.. warning::
+
+		In the current implementation apply calls func twice on the
+		first group to decide whether it can take a fast or slow code
+		path. This can lead to unexpected behavior if func has
+		side-effects, as they will take effect twice for the first
+		group.
+
+    .. ipython:: python
+    
+        d = DataFrame({"a":["x", "y"], "b":[1,2]})
+        def identity(df):
+          print df
+          return df
+    
+        d.groupby("a").apply(identity)
+      
+
 Other useful features
 ---------------------
 

pandas/core/frame.py

@@ -3296,6 +3296,14 @@ def apply(self, func, axis=0, broadcast=False, raw=False, reduce=None,
             array/series
         Additional keyword arguments will be passed as keywords to the function
 
+        Notes
+        -----
+        In the current implementation apply calls func twice on the
+        first column/row to decide whether it can take a fast or slow
+        code path. This can lead to unexpected behavior if func has
+        side-effects, as they will take effect twice for the first
+        column/row.
+        
         Examples
         --------
         >>> df.apply(numpy.sqrt) # returns DataFrame

pandas/core/groupby.py

@@ -547,7 +547,14 @@ def apply(self, func, *args, **kwargs):
 
         Notes
         -----
-        See online documentation for full exposition on how to use apply
+        See online documentation for full exposition on how to use apply.
+
+        In the current implementation apply calls func twice on the
+        first group to decide whether it can take a fast or slow code
+        path. This can lead to unexpected behavior if func has
+        side-effects, as they will take effect twice for the first
+        group.
+        
 
         See also
         --------