Address requested changes

Author: Albert Villanova del Moral

pandas/core/frame.py

@@ -4465,13 +4465,15 @@ def join(self, other, on=None, how='left', lsuffix='', rsuffix='',
             * outer: form union of calling frame's index (or column if on is
                 specified) with other frame's index, and sort it
             * inner: form intersection of calling frame's index (or column if
-                on is specified) with other frame's index
+                on is specified) with other frame's index, preserving the
+                order of the calling's one
         lsuffix : string
             Suffix to use from left frame's overlapping columns
         rsuffix : string
             Suffix to use from right frame's overlapping columns
         sort : boolean, default False
-            Order result DataFrame lexicographically by the join key
+            Order result DataFrame lexicographically by the join key. If False,
+            the order of the join key depends on the join type (how keyword)
 
         Notes
         -----

pandas/tests/frame/test_join.py

@@ -7,19 +7,39 @@
 from pandas.tests.frame.common import TestData
 
 import pandas.util.testing as tm
-from pandas.util.testing import (assertRaisesRegexp,
-                                 assert_frame_equal)
 
 
-class TestDataFrameJoin(tm.TestCase, TestData):
+class TestDataFrameJoin(TestData):
 
     def test_join(self):
         df1 = pd.DataFrame({'a': [20, 10, 0]}, index=[2, 1, 0])
         df2 = pd.DataFrame({'b': [100, 200, 300]}, index=[1, 2, 3])
 
+        result = df1.join(df2)
+        expected = pd.DataFrame({'a': [20, 10, 0], 'b': [200, 100, None]},
+                                index=[2, 1, 0])
+        tm.assert_frame_equal(result, expected)
+
+        result = df1.join(df2, how='left')
+        expected = pd.DataFrame({'a': [20, 10, 0], 'b': [200, 100, None]},
+                                index=[2, 1, 0])
+        tm.assert_frame_equal(result, expected)
+
+        result = df1.join(df2, how='right')
+        expected = pd.DataFrame({'a': [10, 20, None], 'b': [100, 200, 300]},
+                                index=[1, 2, 3])
+        tm.assert_frame_equal(result, expected)
+
         result = df1.join(df2, how='inner')
-        expected = pd.DataFrame({'a': [20, 10], 'b': [200, 100]}, index=[2, 1])
-        self.assert_frame_equal(result, expected)
+        expected = pd.DataFrame({'a': [20, 10], 'b': [200, 100]},
+                                index=[2, 1])
+        tm.assert_frame_equal(result, expected)
+
+        result = df1.join(df2, how='outer')
+        expected = pd.DataFrame({'a': [0, 10, 20, None],
+                                 'b': [None, 100, 200, 300]},
+                                index=[0, 1, 2, 3])
+        tm.assert_frame_equal(result, expected)
 
     def test_join_index(self):
         # left / right
@@ -28,35 +48,35 @@ def test_join_index(self):
         f2 = self.frame.loc[self.frame.index[5:], ['C', 'D']].iloc[::-1]
 
         joined = f.join(f2)
-        self.assert_index_equal(f.index, joined.index)
+        tm.assert_index_equal(f.index, joined.index)
         expected_columns = pd.Index(['A', 'B', 'C', 'D'])
-        self.assert_index_equal(joined.columns, expected_columns)
+        tm.assert_index_equal(joined.columns, expected_columns)
 
         joined = f.join(f2, how='left')
-        self.assert_index_equal(joined.index, f.index)
-        self.assert_index_equal(joined.columns, expected_columns)
+        tm.assert_index_equal(joined.index, f.index)
+        tm.assert_index_equal(joined.columns, expected_columns)
 
         joined = f.join(f2, how='right')
-        self.assert_index_equal(joined.index, f2.index)
-        self.assert_index_equal(joined.columns, expected_columns)
+        tm.assert_index_equal(joined.index, f2.index)
+        tm.assert_index_equal(joined.columns, expected_columns)
 
         # inner
 
         joined = f.join(f2, how='inner')
-        self.assert_index_equal(joined.index, f.index[5:10])
-        self.assert_index_equal(joined.columns, expected_columns)
+        tm.assert_index_equal(joined.index, f.index[5:10])
+        tm.assert_index_equal(joined.columns, expected_columns)
 
         # outer
 
         joined = f.join(f2, how='outer')
-        self.assert_index_equal(joined.index, self.frame.index.sort_values())
-        self.assert_index_equal(joined.columns, expected_columns)
+        tm.assert_index_equal(joined.index, self.frame.index.sort_values())
+        tm.assert_index_equal(joined.columns, expected_columns)
 
-        assertRaisesRegexp(ValueError, 'join method', f.join, f2, how='foo')
+        tm.assertRaisesRegexp(ValueError, 'join method', f.join, f2, how='foo')
 
         # corner case - overlapping columns
         for how in ('outer', 'left', 'inner'):
-            with assertRaisesRegexp(ValueError, 'columns overlap but '
+            with tm.assertRaisesRegexp(ValueError, 'columns overlap but '
                                     'no suffix'):
                 self.frame.join(self.frame, how=how)
 
@@ -69,24 +89,24 @@ def test_join_index_more(self):
         expected['D'] = self.frame['D'][::2]
 
         result = af.join(bf)
-        assert_frame_equal(result, expected)
+        tm.assert_frame_equal(result, expected)
 
         result = af.join(bf, how='right')
-        assert_frame_equal(result, expected[::2])
+        tm.assert_frame_equal(result, expected[::2])
 
         result = bf.join(af, how='right')
-        assert_frame_equal(result, expected.loc[:, result.columns])
+        tm.assert_frame_equal(result, expected.loc[:, result.columns])
 
     def test_join_index_series(self):
         df = self.frame.copy()
         s = df.pop(self.frame.columns[-1])
         joined = df.join(s)
 
         # TODO should this check_names ?
-        assert_frame_equal(joined, self.frame, check_names=False)
+        tm.assert_frame_equal(joined, self.frame, check_names=False)
 
         s.name = None
-        assertRaisesRegexp(ValueError, 'must have a name', df.join, s)
+        tm.assertRaisesRegexp(ValueError, 'must have a name', df.join, s)
 
     def test_join_overlap(self):
         df1 = self.frame.loc[:, ['A', 'B', 'C']]
@@ -100,4 +120,4 @@ def test_join_overlap(self):
         expected = df1_suf.join(df2_suf).join(no_overlap)
 
         # column order not necessarily sorted
-        assert_frame_equal(joined, expected.loc[:, joined.columns])
+        tm.assert_frame_equal(joined, expected.loc[:, joined.columns])