DEPR: deprecate passing Series to Index.join

- Add Pandas4Warning when Series is passed to Index.join
- Add test for deprecation warning
- Update whatsnew for v3.0.0
Closes #62897

Author: Lakshya-Upadhyaya

doc/source/whatsnew/v3.0.0.rst

@@ -737,6 +737,7 @@ Other Deprecations
 - Deprecated allowing ``fill_value`` that cannot be held in the original dtype (excepting NA values for integer and bool dtypes) in :meth:`Series.shift` and :meth:`DataFrame.shift` (:issue:`53802`)
 - Deprecated backward-compatibility behavior for :meth:`DataFrame.select_dtypes` matching "str" dtype when ``np.object_`` is specified (:issue:`61916`)
 - Deprecated option "future.no_silent_downcasting", as it is no longer used. In a future version accessing this option will raise (:issue:`59502`)
+- Deprecated passing a :class:`Series` to :meth:`Index.join`, pass ``Index.join(other.index)`` instead (:issue:`62897`)
 - Deprecated silent casting of non-datetime 'other' to datetime in :meth:`Series.combine_first` (:issue:`62931`)
 - Deprecated slicing on a :class:`Series` or :class:`DataFrame` with a :class:`DatetimeIndex` using a ``datetime.date`` object, explicitly cast to :class:`Timestamp` instead (:issue:`35830`)
 - Deprecated the 'inplace' keyword from :meth:`Resampler.interpolate`, as passing ``True`` raises ``AttributeError`` (:issue:`58690`)

pandas/core/indexes/base.py

@@ -69,6 +69,7 @@
 from pandas.errors import (
     DuplicateLabelError,
     InvalidIndexError,
+    Pandas4Warning
 )
 from pandas.util._decorators import (
     Appender,
@@ -4426,6 +4427,15 @@ def join(
         (Index([1, 2, 3, 4, 5, 6], dtype='int64'),
         array([ 0,  1,  2, -1, -1, -1]), array([-1, -1, -1,  0,  1,  2]))
         """
+        if not isinstance(other, Index):
+            warnings.warn(
+                f"Passing a Series to {type(self).__name__}.join is deprecated "
+                "and will raise in a future version. "
+                "Pass Index.join(other.index) instead.",
+                Pandas4Warning,
+                stacklevel=find_stack_level()
+            )
+            
         other = ensure_index(other)
         sort = sort or how == "outer"
 

pandas/tests/indexes/test_common.py

@@ -28,7 +28,7 @@
     RangeIndex,
 )
 import pandas._testing as tm
-
+from pandas.errors import Pandas4Warning
 
 class TestCommon:
     @pytest.mark.parametrize("name", [None, "new_name"])
@@ -523,3 +523,10 @@ def test_to_frame_name_tuple_multiindex():
     result = idx.to_frame(name=(1, 2))
     expected = pd.DataFrame([1], columns=MultiIndex.from_arrays([[1], [2]]), index=idx)
     tm.assert_frame_equal(result, expected)
+
+def test_join_series_deprecated():
+    # GH#62897
+    idx = pd.Index([1, 2])
+    ser = pd.Series([1, 2, 2])
+    with tm.assert_produces_warning(Pandas4Warning, match="Passing a Series"):
+        idx.join(ser)