ENH: Use 'left' constructor on pd.merge

Use the _constructor property when creating the merge/ordered_merge result to
preserve the output type. Update test and docs appropriately.

Author: jwass

doc/source/merging.rst

@@ -376,6 +376,10 @@ Here's a description of what each argument is for:
     can be avoided are somewhat pathological but this option is provided
     nonetheless.
 
+The return type will be the same as ``left``. If ``left`` is a ``DataFrame``
+and ``right`` is a subclass of DataFrame, the return type will still be
+``DataFrame``.
+
 ``merge`` is a function in the pandas namespace, and it is also available as a
 DataFrame instance method, with the calling DataFrame being implicitly
 considered the left object in the join.

doc/source/v0.15.0.txt

@@ -166,6 +166,9 @@ previously results in ``Exception`` or ``TypeError`` (:issue:`7812`)
 - ``DataFrame.tz_localize`` and ``DataFrame.tz_convert`` now accepts an optional ``level`` argument
   for localizing a specific level of a MultiIndex (:issue:`7846`)
 
+- ``merge``, ``DataFrame.merge``, and ``ordered_merge`` now return the same type
+  as the ``left`` argument.  (:issue:`7737`)
+
 .. _whatsnew_0150.dt:
 
 .dt accessor

pandas/core/frame.py

@@ -135,6 +135,8 @@
 Returns
 -------
 merged : DataFrame
+    The output type will the be same as 'left', if it is a subclass
+    of DataFrame.
 """
 
 #----------------------------------------------------------------------

pandas/tools/merge.py

@@ -106,6 +106,8 @@ def ordered_merge(left, right, on=None, left_by=None, right_by=None,
     Returns
     -------
     merged : DataFrame
+        The output type will the be same as 'left', if it is a subclass
+        of DataFrame.
     """
     def _merger(x, y):
         op = _OrderedMerge(x, y, on=on, left_on=left_on, right_on=right_on,
@@ -198,7 +200,8 @@ def get_result(self):
             axes=[llabels.append(rlabels), join_index],
             concat_axis=0, copy=self.copy)
 
-        result = DataFrame(result_data).__finalize__(self, method='merge')
+        typ = self.left._constructor
+        result = typ(result_data).__finalize__(self, method='merge')
 
         self._maybe_add_join_keys(result, left_indexer, right_indexer)
 
@@ -520,7 +523,8 @@ def get_result(self):
             axes=[llabels.append(rlabels), join_index],
             concat_axis=0, copy=self.copy)
 
-        result = DataFrame(result_data)
+        typ = self.left._constructor
+        result = typ(result_data).__finalize__(self, method='ordered_merge')
 
         self._maybe_add_join_keys(result, left_indexer, right_indexer)
 

pandas/tools/tests/test_merge.py

@@ -781,6 +781,16 @@ def test_merge_nan_right(self):
                               1: nan}})[['i1', 'i2', 'i1_', 'i3']]
         assert_frame_equal(result, expected)
 
+    def test_merge_type(self):
+        class NotADataFrame(DataFrame):
+            @property
+            def _constructor(self):
+                return NotADataFrame
+
+        nad = NotADataFrame(self.df)
+        result = nad.merge(self.df2, on='key1')
+
+        tm.assert_isinstance(result, NotADataFrame)
 
     def test_append_dtype_coerce(self):
 
@@ -2154,6 +2164,18 @@ def test_multigroup(self):
         result = ordered_merge(left, self.right, on='key', left_by='group')
         self.assertTrue(result['group'].notnull().all())
 
+    def test_merge_type(self):
+        class NotADataFrame(DataFrame):
+            @property
+            def _constructor(self):
+                return NotADataFrame
+
+        nad = NotADataFrame(self.left)
+        result = nad.merge(self.right, on='key')
+
+        tm.assert_isinstance(result, NotADataFrame)
+
+
 if __name__ == '__main__':
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],
                    exit=False)