make series axis parameter docs consistent (#47109)

* make series docs consistent

add series unused param info to DF docs

* fix trailing whitespace

* fix docs build

* add unused

* add or update docs for all series methods

* small fix

* fix line length

* fix param order

* fix param order

* add

* add backticks to None and fix space

Co-authored-by: uncjackg <[email protected]>

Author: jackgoldsmith4

pandas/core/arrays/datetimes.py

@@ -2004,6 +2004,7 @@ def std(
         ----------
         axis : int optional, default None
             Axis for the function to be applied on.
+            For `Series` this parameter is unused and defaults to `None`.
         ddof : int, default 1
             Degrees of Freedom. The divisor used in calculations is N - ddof,
             where N represents the number of elements.

pandas/core/base.py

@@ -595,7 +595,7 @@ def argmax(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
         Parameters
         ----------
         axis : {{None}}
-            Dummy argument for consistency with Series.
+            Unused. Parameter needed for compatibility with DataFrame.
         skipna : bool, default True
             Exclude NA/null values when showing the result.
         *args, **kwargs

pandas/core/generic.py

@@ -727,7 +727,8 @@ def set_axis(self, labels, axis: Axis = 0, inplace: bool_t = False):
             The values for the new index.
 
         axis : %(axes_single_arg)s, default 0
-            The axis to update. The value 0 identifies the rows%(axis_description_sub)s.
+            The axis to update. The value 0 identifies the rows. For `Series`
+            this parameter is unused and defaults to 0.
 
         inplace : bool, default False
             Whether to return a new %(klass)s instance.
@@ -807,6 +808,8 @@ def droplevel(self: NDFrameT, level, axis=0) -> NDFrameT:
             * 0 or 'index': remove level(s) in column.
             * 1 or 'columns': remove level(s) in row.
 
+            For `Series` this parameter is unused and defaults to 0.
+
         Returns
         -------
         {klass}
@@ -875,7 +878,7 @@ def squeeze(self, axis=None):
         ----------
         axis : {0 or 'index', 1 or 'columns', None}, default None
             A specific axis to squeeze. By default, all length-1 axes are
-            squeezed.
+            squeezed. For `Series` this parameter is unused and defaults to `None`.
 
         Returns
         -------
@@ -1063,7 +1066,7 @@ def rename_axis(self, mapper=lib.no_default, **kwargs):
             specify the axis to target with ``mapper``, or ``index``
             and/or ``columns``.
         axis : {0 or 'index', 1 or 'columns'}, default 0
-            The axis to rename.
+            The axis to rename. For `Series` this parameter is unused and defaults to 0.
         copy : bool, default True
             Also copy underlying data.
         inplace : bool, default False
@@ -3542,6 +3545,7 @@ def take(
         axis : {0 or 'index', 1 or 'columns', None}, default 0
             The axis on which to select elements. ``0`` means that we are
             selecting rows, ``1`` means that we are selecting columns.
+            For `Series` this parameter is unused and defaults to 0.
         is_copy : bool
             Before pandas 1.0, ``is_copy=False`` can be specified to ensure
             that the return value is an actual copy. Starting with pandas 1.0,
@@ -5087,8 +5091,8 @@ def filter(
             Keep labels from axis for which re.search(regex, label) == True.
         axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
             The axis to filter on, expressed either as an index (int)
-            or axis name (str). By default this is the info axis,
-            'index' for Series, 'columns' for DataFrame.
+            or axis name (str). By default this is the info axis, 'columns' for
+            DataFrame. For `Series` this parameter is unused and defaults to `None`.
 
         Returns
         -------
@@ -5372,7 +5376,7 @@ def sample(
 
         axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
             Axis to sample. Accepts axis number or name. Default is stat axis
-            for given data type (0 for Series and DataFrames).
+            for given data type. For `Series` this parameter is unused and defaults to `None`.
         ignore_index : bool, default False
             If True, the resulting index will be labeled 0, 1, …, n - 1.
 
@@ -6354,7 +6358,8 @@ def fillna(
             pad / ffill: propagate last valid observation forward to next valid
             backfill / bfill: use next valid observation to fill gap.
         axis : {axes_single_arg}
-            Axis along which to fill missing values.
+            Axis along which to fill missing values. For `Series`
+            this parameter is unused and defaults to 0.
         inplace : bool, default False
             If True, fill in-place. Note: this will modify any
             other views on this object (e.g., a no-copy slice for a column in a
@@ -6830,7 +6835,8 @@ def interpolate(
               scipy 0.18.
 
         axis : {{0 or 'index', 1 or 'columns', None}}, default None
-            Axis to interpolate along.
+            Axis to interpolate along. For `Series` this parameter is unused
+            and defaults to 0.
         limit : int, optional
             Maximum number of consecutive NaNs to fill. Must be greater than
             0.
@@ -7477,8 +7483,9 @@ def clip(
             Maximum threshold value. All values above this
             threshold will be set to it. A missing
             threshold (e.g `NA`) will not clip the value.
-        axis : int or str axis name, optional
+        axis : {{0 or 'index', 1 or 'columns', None}}, default None
             Align object with lower and upper along the given axis.
+            For `Series` this parameter is unused and defaults to `None`.
         inplace : bool, default False
             Whether to perform the operation in place on the data.
         *args, **kwargs
@@ -7744,6 +7751,7 @@ def at_time(self: NDFrameT, time, asof: bool_t = False, axis=None) -> NDFrameT:
         ----------
         time : datetime.time or str
         axis : {0 or 'index', 1 or 'columns'}, default 0
+            For `Series` this parameter is unused and defaults to 0.
 
         Returns
         -------
@@ -7830,6 +7838,7 @@ def between_time(
             Include boundaries; whether to set each bound as closed or open.
         axis : {0 or 'index', 1 or 'columns'}, default 0
             Determine range time on index or columns value.
+            For `Series` this parameter is unused and defaults to 0.
 
         Returns
         -------
@@ -7951,8 +7960,8 @@ def resample(
         rule : DateOffset, Timedelta or str
             The offset string or object representing target conversion.
         axis : {{0 or 'index', 1 or 'columns'}}, default 0
-            Which axis to use for up- or down-sampling. For `Series` this
-            will default to 0, i.e. along the rows. Must be
+            Which axis to use for up- or down-sampling. For `Series` this parameter
+            is unused and defaults to 0. Must be
             `DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`.
         closed : {{'right', 'left'}}, default None
             Which side of bin interval is closed. The default is 'left'
@@ -8521,6 +8530,7 @@ def rank(
         ----------
         axis : {0 or 'index', 1 or 'columns'}, default 0
             Index to direct ranking.
+            For `Series` this parameter is unused and defaults to 0.
         method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
             How to rank the group of records that have the same value (i.e. ties):
 
@@ -9258,7 +9268,8 @@ def where(
         inplace : bool, default False
             Whether to perform the operation in place on the data.
         axis : int, default None
-            Alignment axis if needed.
+            Alignment axis if needed. For `Series` this parameter is
+            unused and defaults to 0.
         level : int, default None
             Alignment level if needed.
         errors : str, {{'raise', 'ignore'}}, default 'raise'
@@ -9443,7 +9454,7 @@ def shift(
             the freq or inferred_freq attributes of the index. If neither of
             those attributes exist, a ValueError is thrown.
         axis : {{0 or 'index', 1 or 'columns', None}}, default None
-            Shift direction.
+            Shift direction. For `Series` this parameter is unused and defaults to 0.
         fill_value : object, optional
             The scalar value to use for newly introduced missing values.
             the default depends on the dtype of `self`.
@@ -9577,6 +9588,8 @@ def slice_shift(self: NDFrameT, periods: int = 1, axis=0) -> NDFrameT:
         ----------
         periods : int
             Number of periods to move, can be positive or negative.
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            For `Series` this parameter is unused and defaults to 0.
 
         Returns
         -------
@@ -9628,6 +9641,7 @@ def tshift(self: NDFrameT, periods: int = 1, freq=None, axis: Axis = 0) -> NDFra
             or time rule expressed as a string (e.g. 'EOM').
         axis : {0 or ‘index’, 1 or ‘columns’, None}, default 0
             Corresponds to the axis that contains the Index.
+            For `Series` this parameter is unused and defaults to 0.
 
         Returns
         -------
@@ -9670,6 +9684,7 @@ def truncate(
             Truncate all rows after this index value.
         axis : {0 or 'index', 1 or 'columns'}, optional
             Axis to truncate. Truncates the index (rows) by default.
+            For `Series` this parameter is unused and defaults to 0.
         copy : bool, default is True,
             Return a copy of the truncated section.
 
@@ -10893,6 +10908,7 @@ def mad(
         ----------
         axis : {axis_descr}
             Axis for the function to be applied on.
+            For `Series` this parameter is unused and defaults to 0.
         skipna : bool, default True
             Exclude NA/null values when computing the result.
         level : int or level name, default None
@@ -11551,6 +11567,7 @@ def _doc_params(cls):
 ----------
 axis : {axis_descr}
     Axis for the function to be applied on.
+    For `Series` this parameter is unused and defaults to 0.
 skipna : bool, default True
     Exclude NA/null values when computing the result.
 level : int or level name, default None
@@ -11581,6 +11598,7 @@ def _doc_params(cls):
 Parameters
 ----------
 axis : {axis_descr}
+    For `Series` this parameter is unused and defaults to 0.
 skipna : bool, default True
     Exclude NA/null values. If an entire row/column is NA, the result
     will be NA.
@@ -11672,7 +11690,8 @@ def _doc_params(cls):
 Parameters
 ----------
 axis : {{0 or 'index', 1 or 'columns', None}}, default 0
-    Indicate which axis or axes should be reduced.
+    Indicate which axis or axes should be reduced. For `Series` this parameter
+    is unused and defaults to 0.
 
     * 0 / 'index' : reduce the index, return a Series whose index is the
       original column labels.
@@ -11774,6 +11793,7 @@ def _doc_params(cls):
 ----------
 axis : {{0 or 'index', 1 or 'columns'}}, default 0
     The index or the name of the axis. 0 is equivalent to None or 'index'.
+    For `Series` this parameter is unused and defaults to 0.
 skipna : bool, default True
     Exclude NA/null values. If an entire row/column is NA, the result
     will be NA.

pandas/core/ops/docstrings.py

@@ -428,14 +428,16 @@ def make_flex_doc(op_name: str, typ: str) -> str:
 Parameters
 ----------
 other : Series or scalar value
+level : int or name
+    Broadcast across a level, matching Index values on the
+    passed MultiIndex level.
 fill_value : None or float value, default None (NaN)
     Fill existing missing (NaN) values, and any new element needed for
     successful Series alignment, with this value before computation.
     If data in both corresponding Series locations is missing
     the result of filling (at that location) will be missing.
-level : int or name
-    Broadcast across a level, matching Index values on the
-    passed MultiIndex level.
+axis : {{0 or 'index'}}
+    Unused. Parameter needed for compatibility with DataFrame.
 
 Returns
 -------
@@ -462,7 +464,7 @@ def make_flex_doc(op_name: str, typ: str) -> str:
 other : scalar, sequence, Series, or DataFrame
     Any single or multiple element data structure, or list-like object.
 axis : {{0 or 'index', 1 or 'columns'}}
-    Whether to compare by the index (0 or 'index') or columns
+    Whether to compare by the index (0 or 'index') or columns.
     (1 or 'columns'). For Series input, axis to match Series index on.
 level : int or label
     Broadcast across a level, matching Index values on the

pandas/core/series.py

@@ -171,7 +171,7 @@
     "klass": "Series",
     "axes_single_arg": "{0 or 'index'}",
     "axis": """axis : {0 or 'index'}
-        Parameter needed for compatibility with DataFrame.""",
+        Unused. Parameter needed for compatibility with DataFrame.""",
     "inplace": """inplace : bool, default False
         If True, performs operation inplace and returns None.""",
     "unique": "np.ndarray",
@@ -1322,8 +1322,7 @@ def repeat(self, repeats, axis=None) -> Series:
             non-negative integer. Repeating 0 times will return an empty
             Series.
         axis : None
-            Must be ``None``. Has no effect but is accepted for compatibility
-            with numpy.
+            Unused. Parameter needed for compatibility with DataFrame.
 
         Returns
         -------
@@ -2309,9 +2308,8 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs):
 
         Parameters
         ----------
-        axis : int, default 0
-            For compatibility with DataFrame.idxmin. Redundant for application
-            on Series.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         skipna : bool, default True
             Exclude NA/null values. If the entire Series is NA, the result
             will be NA.
@@ -2378,9 +2376,8 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs):
 
         Parameters
         ----------
-        axis : int, default 0
-            For compatibility with DataFrame.idxmax. Redundant for application
-            on Series.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         skipna : bool, default True
             Exclude NA/null values. If the entire Series is NA, the result
             will be NA.
@@ -3391,9 +3388,8 @@ def sort_values(
 
         Parameters
         ----------
-        axis : {0 or 'index'}, default 0
-            Axis to direct sorting. The value 'index' is accepted for
-            compatibility with DataFrame.sort_values.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         ascending : bool or list of bools, default True
             If True, sort values in ascending order, otherwise descending.
         inplace : bool, default False
@@ -3652,8 +3648,8 @@ def sort_index(  # type: ignore[override]
 
         Parameters
         ----------
-        axis : int, default 0
-            Axis to direct sorting. This can only be 0 for Series.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         level : int, optional
             If not None, sort on values in specified index level(s).
         ascending : bool or list-like of bools, default True
@@ -3800,8 +3796,8 @@ def argsort(self, axis=0, kind="quicksort", order=None) -> Series:
 
         Parameters
         ----------
-        axis : {0 or "index"}
-            Has no effect but is accepted for compatibility with numpy.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         kind : {'mergesort', 'quicksort', 'heapsort', 'stable'}, default 'quicksort'
             Choice of sorting algorithm. See :func:`numpy.sort` for more
             information. 'mergesort' and 'stable' are the only stable algorithms.
@@ -4718,8 +4714,8 @@ def rename(
 
         Parameters
         ----------
-        axis : {0 or "index"}
-            Unused. Accepted for compatibility with DataFrame method only.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         index : scalar, hashable sequence, dict-like or function, optional
             Functions or dict-like are transformations to apply to
             the index.
@@ -4916,8 +4912,8 @@ def drop(  # type: ignore[override]
         ----------
         labels : single label or list-like
             Index labels to drop.
-        axis : 0, default 0
-            Redundant for application on Series.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         index : single label or list-like
             Redundant for application on Series, but 'index' can be used instead
             of 'labels'.
@@ -5531,8 +5527,8 @@ def dropna(self, axis=0, inplace=False, how=None):
 
         Parameters
         ----------
-        axis : {0 or 'index'}, default 0
-            There is only one axis to drop values from.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
         inplace : bool, default False
             If True, do operation inplace and return None.
         how : str, optional

pandas/core/shared_docs.py

@@ -101,7 +101,8 @@
     of labels may be passed to group by the columns in ``self``.
     Notice that a tuple is interpreted as a (single) key.
 axis : {0 or 'index', 1 or 'columns'}, default 0
-    Split along rows (0) or columns (1).
+    Split along rows (0) or columns (1). For `Series` this parameter
+    is unused and defaults to 0.
 level : int, level name, or sequence of such, default None
     If the axis is a MultiIndex (hierarchical), group by a particular
     level or levels.

pandas/core/window/ewm.py

@@ -211,6 +211,8 @@ class ExponentialMovingWindow(BaseWindow):
 
         If ``1`` or ``'columns'``, calculate across the columns.
 
+        For `Series` this parameter is unused and defaults to 0.
+
     times : str, np.ndarray, Series, default None
 
         .. versionadded:: 1.1.0