From 9ca1058a24939c5853315d907697666a5fc56b24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Diridollou?= <loic.diridollou@gmail.com>
Date: Wed, 30 Jul 2025 17:45:11 -0400
Subject: [PATCH 1/2] GH61998 Add documentation to pd.MultiIndex.argsort

---
 pandas/core/indexes/multi.py | 50 +++++++++++++++++++++++++++++++++---
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
index 29b34f560ab2e..759c53cb674de 100644
--- a/pandas/core/indexes/multi.py
+++ b/pandas/core/indexes/multi.py
@@ -39,6 +39,7 @@
     IgnoreRaise,
     IndexLabel,
     IndexT,
+    NaPosition,
     Scalar,
     Self,
     Shape,
@@ -2398,8 +2399,52 @@ def append(self, other):
             return Index(new_tuples)
 
     def argsort(
-        self, *args, na_position: str = "last", **kwargs
+        self, *args, na_position: NaPosition = "last", **kwargs
     ) -> npt.NDArray[np.intp]:
+        """
+        Return the integer indices that would sort the index.
+
+        Parameters
+        ----------
+        *args
+            Passed to `numpy.ndarray.argsort`.
+        na_position : {'first' or 'last'}, default 'last'
+            Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
+            the end.
+        **kwargs
+            Passed to `numpy.ndarray.argsort`.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            Integer indices that would sort the index if used as
+            an indexer.
+
+        See Also
+        --------
+        numpy.argsort : Similar method for NumPy arrays.
+        Index.argsort : Similar method for Index.
+
+        Examples
+        --------
+        >>> midx = pd.MultiIndex.from_arrays([[3, 2], ["e", "c"]])
+        >>> midx
+        MultiIndex([(3, 'e'), (2, 'c')])
+
+        >>> order = midx.argsort()
+        >>> order
+        array([1, 0])
+
+        >>> midx[order]
+        Index(['a', 'b', 'c', 'd'], dtype='object')
+
+        >>> midx = pd.MultiIndex.from_arrays([[2, 2], [np.nan, 0]])
+        >>> midx.argsort(na_position='first')
+        array([0, 1])
+
+        >>> midx.argsort()
+        array([1, 0])
+        """
         target = self._sort_levels_monotonic(raise_if_incomparable=True)
         keys = [lev.codes for lev in target._get_codes_for_sorting()]
         return lexsort_indexer(keys, na_position=na_position, codes_given=True)
@@ -2791,8 +2836,7 @@ def sortlevel(
         # error: Item "Hashable" of "Union[Hashable, Sequence[Hashable]]" has
         # no attribute "__iter__" (not iterable)
         level = [
-            self._get_level_number(lev)
-            for lev in level  # type: ignore[union-attr]
+            self._get_level_number(lev) for lev in level  # type: ignore[union-attr]
         ]
         sortorder = None
 

From e23cb4192e5cfd654521b320992b7a64f1196eba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Diridollou?= <loic.diridollou@gmail.com>
Date: Wed, 30 Jul 2025 17:47:48 -0400
Subject: [PATCH 2/2] GH61998 Add documentation to pd.MultiIndex.argsort

---
 pandas/core/indexes/multi.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py
index 759c53cb674de..26b71cc7b653c 100644
--- a/pandas/core/indexes/multi.py
+++ b/pandas/core/indexes/multi.py
@@ -2439,7 +2439,7 @@ def argsort(
         Index(['a', 'b', 'c', 'd'], dtype='object')
 
         >>> midx = pd.MultiIndex.from_arrays([[2, 2], [np.nan, 0]])
-        >>> midx.argsort(na_position='first')
+        >>> midx.argsort(na_position="first")
         array([0, 1])
 
         >>> midx.argsort()
@@ -2836,7 +2836,8 @@ def sortlevel(
         # error: Item "Hashable" of "Union[Hashable, Sequence[Hashable]]" has
         # no attribute "__iter__" (not iterable)
         level = [
-            self._get_level_number(lev) for lev in level  # type: ignore[union-attr]
+            self._get_level_number(lev)
+            for lev in level  # type: ignore[union-attr]
         ]
         sortorder = None