DEPR: join_axes-kwarg in pd.concat

Author: h-vetinari

doc/source/whatsnew/v0.24.0.txt

@@ -479,6 +479,7 @@ Deprecations
 - :meth:`Series.ptp` is deprecated. Use ``numpy.ptp`` instead (:issue:`21614`)
 - :meth:`Series.compress` is deprecated. Use ``Series[condition]`` instead (:issue:`18262`)
 - :meth:`Categorical.from_codes` has deprecated providing float values for the ``codes`` argument. (:issue:`21767`)
+- :meth:`pandas.concat` has deprecated the ``join_axes``-keyword. Instead, use :meth:`DataFrame.reindex` or :meth:`DataFrame.reindex_like` on the result (:issue:`21951`)
 - :func:`pandas.read_table` is deprecated. Instead, use :func:`pandas.read_csv` passing ``sep='\t'`` if necessary (:issue:`21948`)
 
 .. _whatsnew_0240.prior_deprecations:

pandas/core/reshape/concat.py

@@ -14,6 +14,7 @@
 import pandas.core.indexes.base as ibase
 from pandas.core.generic import NDFrame
 import pandas.core.dtypes.concat as _concat
+import warnings
 
 # ---------------------------------------------------------------------
 # Concatenate DataFrame objects
@@ -219,6 +220,11 @@ def concat(objs, axis=0, join='outer', join_axes=None, ignore_index=False,
         ...
     ValueError: Indexes have overlapping values: ['a']
     """
+    if join_axes is not None:
+        warnings.warn('The join_axes-keyword is deprecated. Use .reindex or '
+                      '.reindex_like on the result to achieve the same '
+                      'functionality, or apply those methods to the inputs if '
+                      'performance-sensitive.', FutureWarning, stacklevel=2)
     op = _Concatenator(objs, axis=axis, join_axes=join_axes,
                        ignore_index=ignore_index, join=join,
                        keys=keys, levels=levels, names=names,

pandas/tests/reshape/test_concat.py

@@ -729,6 +729,20 @@ def test_concat_categorical_empty(self):
         tm.assert_series_equal(pd.concat([s2, s1], ignore_index=True), exp)
         tm.assert_series_equal(s2.append(s1, ignore_index=True), exp)
 
+    def test_concat_join_axes(self, axis):
+        one = pd.DataFrame([[0., 1.], [2., 3.]], columns=list('ab'))
+        two = pd.DataFrame([[10., 11.], [12., 13.]], index=[1, 2], columns=list('bc'))
+
+        expected = pd.concat([one, two], axis=1, sort=False).reindex(index=two.index)
+        with tm.assert_produces_warning(expected_warning=FutureWarning):
+            result = pd.concat([one, two], axis=1, sort=False, join_axes=[two.index])
+        tm.assert_frame_equal(result, expected)
+
+        expected = pd.concat([one, two], axis=0, sort=False).reindex(columns=two.columns)
+        with tm.assert_produces_warning(expected_warning=FutureWarning):
+            result = pd.concat([one, two], axis=0, sort=False, join_axes=[two.columns])
+        tm.assert_frame_equal(result, expected)
+
 
 class TestAppend(ConcatenateBase):