TYP: Index.join (#46518)

Author: twoertwein

doc/source/whatsnew/v1.5.0.rst

@@ -527,6 +527,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:

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,16 +4761,24 @@ 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
  # Returned index level order is
  # 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