DOC: Enforce Numpy Docstring Validation for pandas.DataFrame.swaplevel (

#58566) * DOC: add SA01 for pandas.DataFrame.swaplevel * DOC: remove SA01 for pandas.DataFrame.swaplevel
pandas-dev · May 6, 2024 · 8330de2 · 8330de2
1 parent d765547
commit 8330de2
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 15 deletions.
diff --git a/ci/code_checks.sh b/ci/code_checks.sh
@@ -75,7 +75,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.DataFrame.median RT03,SA01" \
         -i "pandas.DataFrame.min RT03" \
         -i "pandas.DataFrame.plot PR02,SA01" \
-        -i "pandas.DataFrame.swaplevel SA01" \
         -i "pandas.Grouper PR02" \
         -i "pandas.Index PR07" \
         -i "pandas.Index.ravel PR01,RT03" \

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
@@ -7642,16 +7642,30 @@ def nsmallest(
         """
         return selectn.SelectNFrame(self, n=n, keep=keep, columns=columns).nsmallest()
 
-    @doc(
-        Series.swaplevel,
-        klass=_shared_doc_kwargs["klass"],
-        extra_params=dedent(
-            """axis : {0 or 'index', 1 or 'columns'}, default 0
-            The axis to swap levels on. 0 or 'index' for row-wise, 1 or
-            'columns' for column-wise."""
-        ),
-        examples=dedent(
-            """\
+    def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame:
+        """
+        Swap levels i and j in a :class:`MultiIndex`.
+
+        Default is to swap the two innermost levels of the index.
+
+        Parameters
+        ----------
+        i, j : int or str
+            Levels of the indices to be swapped. Can pass level name as string.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+                    The axis to swap levels on. 0 or 'index' for row-wise, 1 or
+                    'columns' for column-wise.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with levels swapped in MultiIndex.
+
+        See Also
+        --------
+        DataFrame.reorder_levels: Reorder levels of MultiIndex.
+        DataFrame.sort_index: Sort MultiIndex.
+
         Examples
         --------
         >>> df = pd.DataFrame(
@@ -7701,10 +7715,8 @@ def nsmallest(
         History     Final exam  January         A
         Geography   Final exam  February        B
         History     Coursework  March           A
-        Geography   Coursework  April           C"""
-        ),
-    )
-    def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame:
+        Geography   Coursework  April           C
+        """
         result = self.copy(deep=False)
 
         axis = self._get_axis_number(axis)