Add tests to ensure sort preserved by groupby, add docs

doc/source/groupby.rst

@@ -160,6 +160,31 @@ only verifies that you've passed a valid mapping.
    GroupBy operations (though can't be guaranteed to be the most
    efficient). You can get quite creative with the label mapping functions.
 
+.. _groupby.sorting:
+
+GroupBy sorting
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default the group keys are sorted during the ``groupby`` operation. You may however pass ``sort=False`` for potential speedups:
+
+.. ipython:: python
+
+   df2 = pd.DataFrame({'X' : ['B', 'B', 'A', 'A'], 'Y' : [1, 2, 3, 4]})
+   df2.groupby(['X']).sum()
+   df2.groupby(['X'], sort=False).sum()
+
+
+Note that ``groupby`` will preserve the order in which *observations* are sorted *within* each group. For example, the groups created by ``groupby()`` below are in the order the appeared in the original ``DataFrame``:
+
+.. ipython:: python
+
+   df3 = pd.DataFrame({'X' : ['A', 'B', 'A', 'B'], 'Y' : [1, 4, 3, 2]})
+   df3.groupby(['X']).get_group('A')
+
+   df3.groupby(['X']).get_group('B')
+
+
+
 .. _groupby.attributes:
 
 GroupBy object attributes
@@ -183,14 +208,6 @@ the length of the ``groups`` dict, so it is largely just a convenience:
    grouped.groups
    len(grouped)
 
-By default the group keys are sorted during the groupby operation. You may
-however pass ``sort=False`` for potential speedups:
-
-.. ipython:: python
-
-   df2 = pd.DataFrame({'X' : ['B', 'B', 'A', 'A'], 'Y' : [1, 2, 3, 4]})
-   df2.groupby(['X'], sort=True).sum()
-   df2.groupby(['X'], sort=False).sum()
 
 .. _groupby.tabcompletion:
 

pandas/core/generic.py

@@ -3247,11 +3247,13 @@ def groupby(self, by=None, axis=0, level=None, as_index=True, sort=True,
             index. Only relevant for DataFrame input. as_index=False is
             effectively "SQL-style" grouped output
         sort : boolean, default True
-            Sort group keys. Get better performance by turning this off
+            Sort group keys. Get better performance by turning this off.
+            Note this does not influence the order of observations within each group. 
+            groupby preserves the order of rows within each group. 
         group_keys : boolean, default True
             When calling apply, add group keys to index to identify pieces
         squeeze : boolean, default False
-            reduce the dimensionaility of the return type if possible,
+            reduce the dimensionality of the return type if possible,
             otherwise return a consistent type
 
         Examples

pandas/tests/test_groupby.py

@@ -5436,6 +5436,32 @@ def test_first_last_max_min_on_time_data(self):
         assert_frame_equal(grouped_ref.first(),grouped_test.first())
         assert_frame_equal(grouped_ref.last(),grouped_test.last())
 
+    def test_groupby_preserves_sort(self):
+        # Test to ensure that groupby always preserves sort order of original
+        # object. Issue #8588 and #9651
+
+        df = DataFrame({'int_groups':[3,1,0,1,0,3,3,3], 
+                        'string_groups':['z','a','z','a','a','g','g','g'], 
+                        'ints':[8,7,4,5,2,9,1,1],
+                        'floats':[2.3,5.3,6.2,-2.4,2.2,1.1,1.1,5],
+                        'strings':['z','d','a','e','word','word2','42','47']})
+
+        # Try sorting on different types and with different group types
+        for sort_column in ['ints', 'floats', 'strings', ['ints','floats'], 
+                  ['ints','strings']]:
+            for group_column in ['int_groups', 'string_groups', 
+                                 ['int_groups','string_groups']]:
+
+                df = df.sort_values(by=sort_column)
+
+                g = df.groupby(group_column)
+
+                def test_sort(x):
+                    assert_frame_equal(x, x.sort_values(by=sort_column))
+
+                g.apply(test_sort)
+
+
 def assert_fp_equal(a, b):
     assert (np.abs(a - b) < 1e-12).all()