diff --git a/doc/source/whatsnew/v1.5.0.rst b/doc/source/whatsnew/v1.5.0.rst index 931d18dc349f3..3af0f1d553c0d 100644 --- a/doc/source/whatsnew/v1.5.0.rst +++ b/doc/source/whatsnew/v1.5.0.rst @@ -448,6 +448,7 @@ Other Deprecations - Deprecated passing arguments as positional in :meth:`DataFrame.any` and :meth:`Series.any` (:issue:`44802`) - Deprecated the ``closed`` argument in :meth:`interval_range` in favor of ``inclusive`` argument; In a future version passing ``closed`` will raise (:issue:`40245`) - Deprecated the methods :meth:`DataFrame.mad`, :meth:`Series.mad`, and the corresponding groupby methods (:issue:`11787`) +- Deprecated positional arguments to :meth:`Index.join` except for ``other``, use keyword-only arguments instead of positional arguments (:issue:`46518`) .. --------------------------------------------------------------------------- .. _whatsnew_150.performance: diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 80527474f2be6..59e55bdcb405a 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -48,6 +48,7 @@ DtypeObj, F, IgnoreRaise, + Level, Shape, npt, ) @@ -4529,16 +4530,53 @@ def _reindex_non_unique( # -------------------------------------------------------------------- # Join Methods + @overload + def join( + self, + other: Index, + *, + how: str_t = ..., + level: Level = ..., + return_indexers: Literal[True], + sort: bool = ..., + ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]: + ... + + @overload + def join( + self, + other: Index, + *, + how: str_t = ..., + level: Level = ..., + return_indexers: Literal[False] = ..., + sort: bool = ..., + ) -> Index: + ... + + @overload + def join( + self, + other: Index, + *, + how: str_t = ..., + level: Level = ..., + return_indexers: bool = ..., + sort: bool = ..., + ) -> Index | tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]: + ... + @final + @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "other"]) @_maybe_return_indexers def join( self, - other, + other: Index, how: str_t = "left", - level=None, + level: Level = None, return_indexers: bool = False, sort: bool = False, - ): + ) -> Index | tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]: """ Compute join_index and indexers to conform data structures to the new index. @@ -4723,7 +4761,7 @@ def _join_multi(self, other: Index, how: str_t): # Join left and right # Join on same leveled multi-index frames is supported join_idx, lidx, ridx = self_jnlevels.join( - other_jnlevels, how, return_indexers=True + other_jnlevels, how=how, return_indexers=True ) # Restore the dropped levels @@ -4731,8 +4769,16 @@ def _join_multi(self, other: Index, how: str_t): # common levels, ldrop_names, rdrop_names dropped_names = ldrop_names + rdrop_names + # error: Argument 5/6 to "restore_dropped_levels_multijoin" has + # incompatible type "Optional[ndarray[Any, dtype[signedinteger[Any + # ]]]]"; expected "ndarray[Any, dtype[signedinteger[Any]]]" levels, codes, names = restore_dropped_levels_multijoin( - self, other, dropped_names, join_idx, lidx, ridx + self, + other, + dropped_names, + join_idx, + lidx, # type: ignore[arg-type] + ridx, # type: ignore[arg-type] ) # Re-create the multi-index