Merge remote-tracking branch 'upstream/master' into Rt05

* upstream/master:
  Fix validation error type `SS05` and check in CI  (pandas-dev#25133)

Author: thoo

ci/code_checks.sh

@@ -240,8 +240,8 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
-    MSG='Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, EX04, RT04, RT05)' ; echo $MSG
-    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR05,EX04,RT04,RT05
+    MSG='Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, EX04, RT04, RT05, SS05)' ; echo $MSG
+    $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR05,EX04,RT04,RT05,SS05
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/_libs/tslibs/nattype.pyx

@@ -183,7 +183,9 @@ cdef class _NaT(datetime):
         return np.datetime64(NPY_NAT, 'ns')
 
     def to_datetime64(self):
-        """ Returns a numpy.datetime64 object with 'ns' precision """
+        """
+        Return a numpy.datetime64 object with 'ns' precision.
+        """
         return np.datetime64('NaT', 'ns')
 
     def __repr__(self):
@@ -448,7 +450,7 @@ class NaTType(_NaT):
         """
         Timestamp.now(tz=None)
 
-        Returns new Timestamp object representing current time local to
+        Return new Timestamp object representing current time local to
         tz.
 
         Parameters

pandas/_libs/tslibs/timestamps.pyx

@@ -340,7 +340,9 @@ cdef class _Timestamp(datetime):
                         self.microsecond, self.tzinfo)
 
     cpdef to_datetime64(self):
-        """ Returns a numpy.datetime64 object with 'ns' precision """
+        """
+        Return a numpy.datetime64 object with 'ns' precision.
+        """
         return np.datetime64(self.value, 'ns')
 
     def __add__(self, other):
@@ -614,7 +616,7 @@ class Timestamp(_Timestamp):
         """
         Timestamp.now(tz=None)
 
-        Returns new Timestamp object representing current time local to
+        Return new Timestamp object representing current time local to
         tz.
 
         Parameters

pandas/core/arrays/categorical.py

@@ -214,7 +214,7 @@ def contains(cat, key, container):
 
 class Categorical(ExtensionArray, PandasObject):
     """
-    Represents a categorical variable in classic R / S-plus fashion
+    Represent a categorical variable in classic R / S-plus fashion
 
     `Categoricals` can only take on only a limited, and usually fixed, number
     of possible values (`categories`). In contrast to statistical categorical
@@ -747,7 +747,7 @@ def _set_dtype(self, dtype):
 
     def set_ordered(self, value, inplace=False):
         """
-        Sets the ordered attribute to the boolean value
+        Set the ordered attribute to the boolean value
 
         Parameters
         ----------
@@ -793,7 +793,7 @@ def as_unordered(self, inplace=False):
     def set_categories(self, new_categories, ordered=None, rename=False,
                        inplace=False):
         """
-        Sets the categories to the specified new_categories.
+        Set the categories to the specified new_categories.
 
         `new_categories` can include new categories (which will result in
         unused categories) or remove old categories (which results in values
@@ -864,7 +864,7 @@ def set_categories(self, new_categories, ordered=None, rename=False,
 
     def rename_categories(self, new_categories, inplace=False):
         """
-        Renames categories.
+        Rename categories.
 
         Parameters
         ----------
@@ -958,7 +958,7 @@ def rename_categories(self, new_categories, inplace=False):
 
     def reorder_categories(self, new_categories, ordered=None, inplace=False):
         """
-        Reorders categories as specified in new_categories.
+        Reorder categories as specified in new_categories.
 
         `new_categories` need to include all old categories and no new category
         items.
@@ -1051,7 +1051,7 @@ def add_categories(self, new_categories, inplace=False):
 
     def remove_categories(self, removals, inplace=False):
         """
-        Removes the specified categories.
+        Remove the specified categories.
 
         `removals` must be included in the old categories. Values which were in
         the removed categories will be set to NaN
@@ -1104,7 +1104,7 @@ def remove_categories(self, removals, inplace=False):
 
     def remove_unused_categories(self, inplace=False):
         """
-        Removes categories which are not used.
+        Remove categories which are not used.
 
         Parameters
         ----------
@@ -1454,7 +1454,7 @@ def dropna(self):
 
     def value_counts(self, dropna=True):
         """
-        Returns a Series containing counts of each category.
+        Return a Series containing counts of each category.
 
         Every category will have an entry, even those with a count of 0.
 
@@ -1570,7 +1570,7 @@ def argsort(self, *args, **kwargs):
 
     def sort_values(self, inplace=False, ascending=True, na_position='last'):
         """
-        Sorts the Categorical by category value returning a new
+        Sort the Categorical by category value returning a new
         Categorical by default.
 
         While an ordering is applied to the category values, sorting in this

pandas/core/dtypes/common.py

@@ -2006,7 +2006,7 @@ def _validate_date_like_dtype(dtype):
 
 def pandas_dtype(dtype):
     """
-    Converts input into a pandas only dtype object or a numpy dtype object.
+    Convert input into a pandas only dtype object or a numpy dtype object.
 
     Parameters
     ----------

pandas/core/dtypes/dtypes.py

@@ -17,7 +17,8 @@
 
 
 def register_extension_dtype(cls):
-    """Class decorator to register an ExtensionType with pandas.
+    """
+    Register an ExtensionType with pandas as class decorator.
 
     .. versionadded:: 0.24.0
 

pandas/core/frame.py

@@ -6009,7 +6009,7 @@ def unstack(self, level=-1, fill_value=None):
         return unstack(self, level, fill_value)
 
     _shared_docs['melt'] = ("""
-    Unpivots a DataFrame from wide format to long format, optionally
+    Unpivot a DataFrame from wide format to long format, optionally
     leaving identifier variables set.
 
     This function is useful to massage a DataFrame into a format where one

pandas/core/generic.py

@@ -10126,7 +10126,7 @@ def nanptp(values, axis=0, skipna=True):
 
         cls.ptp = _make_stat_function(
             cls, 'ptp', name, name2, axis_descr,
-            """Returns the difference between the maximum value and the
+            """Return the difference between the maximum value and the
             minimum value in the object. This is the equivalent of the
             ``numpy.ndarray`` method ``ptp``.\n\n.. deprecated:: 0.24.0
                 Use numpy.ptp instead""",

pandas/core/groupby/generic.py

@@ -1021,7 +1021,9 @@ def true_and_notna(x, *args, **kwargs):
         return filtered
 
     def nunique(self, dropna=True):
-        """ Returns number of unique elements in the group """
+        """
+        Return number of unique elements in the group.
+        """
         ids, _, _ = self.grouper.group_info
 
         val = self.obj.get_values()

pandas/core/groupby/groupby.py

@@ -625,7 +625,7 @@ def curried(x):
 
     def get_group(self, name, obj=None):
         """
-        Constructs NDFrame from group with provided name.
+        Construct NDFrame from group with provided name.
 
         Parameters
         ----------
@@ -1047,7 +1047,7 @@ def result_to_bool(result):
     @Appender(_common_see_also)
     def any(self, skipna=True):
         """
-        Returns True if any value in the group is truthful, else False.
+        Return True if any value in the group is truthful, else False.
 
         Parameters
         ----------
@@ -1060,7 +1060,7 @@ def any(self, skipna=True):
     @Appender(_common_see_also)
     def all(self, skipna=True):
         """
-        Returns True if all values in the group are truthful, else False.
+        Return True if all values in the group are truthful, else False.
 
         Parameters
         ----------
@@ -1813,7 +1813,7 @@ def cumcount(self, ascending=True):
     def rank(self, method='average', ascending=True, na_option='keep',
              pct=False, axis=0):
         """
-        Provides the rank of values within each group.
+        Provide the rank of values within each group.
 
         Parameters
         ----------
@@ -2039,7 +2039,7 @@ def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
     @Substitution(name='groupby', see_also=_common_see_also)
     def head(self, n=5):
         """
-        Returns first n rows of each group.
+        Return first n rows of each group.
 
         Essentially equivalent to ``.apply(lambda x: x.head(n))``,
         except ignores as_index flag.
@@ -2067,7 +2067,7 @@ def head(self, n=5):
     @Substitution(name='groupby', see_also=_common_see_also)
     def tail(self, n=5):
         """
-        Returns last n rows of each group.
+        Return last n rows of each group.
 
         Essentially equivalent to ``.apply(lambda x: x.tail(n))``,
         except ignores as_index flag.

pandas/core/indexes/base.py

@@ -4049,7 +4049,7 @@ def putmask(self, mask, value):
 
     def equals(self, other):
         """
-        Determines if two Index objects contain the same elements.
+        Determine if two Index objects contain the same elements.
         """
         if self.is_(other):
             return True
@@ -4144,7 +4144,7 @@ def asof(self, label):
 
     def asof_locs(self, where, mask):
         """
-        Finds the locations (indices) of the labels from the index for
+        Find the locations (indices) of the labels from the index for
         every entry in the `where` argument.
 
         As in the `asof` function, if the label (a particular entry in

pandas/core/indexes/category.py

@@ -232,7 +232,7 @@ def _is_dtype_compat(self, other):
 
     def equals(self, other):
         """
-        Determines if two CategorialIndex objects contain the same elements.
+        Determine if two CategorialIndex objects contain the same elements.
         """
         if self.is_(other):
             return True

pandas/core/indexes/datetimes.py

@@ -1284,7 +1284,7 @@ def delete(self, loc):
 
     def indexer_at_time(self, time, asof=False):
         """
-        Returns index locations of index values at particular time of day
+        Return index locations of index values at particular time of day
         (e.g. 9:30AM).
 
         Parameters

pandas/core/ops.py

@@ -447,7 +447,7 @@ def _get_op_name(op, special):
         _op_descriptions[reverse_op]['reverse'] = key
 
 _flex_doc_SERIES = """
-{desc} of series and other, element-wise (binary operator `{op_name}`).
+Return {desc} of series and other, element-wise (binary operator `{op_name}`).
 
 Equivalent to ``{equiv}``, but with support to substitute a fill_value for
 missing data in one of the inputs.
@@ -547,7 +547,7 @@ def _get_op_name(op, special):
 """
 
 _flex_doc_FRAME = """
-{desc} of dataframe and other, element-wise (binary operator `{op_name}`).
+Get {desc} of dataframe and other, element-wise (binary operator `{op_name}`).
 
 Equivalent to ``{equiv}``, but with support to substitute a fill_value
 for missing data in one of the inputs. With reverse version, `{reverse}`.
@@ -701,7 +701,7 @@ def _get_op_name(op, special):
 """
 
 _flex_comp_doc_FRAME = """
-{desc} of dataframe and other, element-wise (binary operator `{op_name}`).
+Get {desc} of dataframe and other, element-wise (binary operator `{op_name}`).
 
 Among flexible wrappers (`eq`, `ne`, `le`, `lt`, `ge`, `gt`) to comparison
 operators.
@@ -847,7 +847,7 @@ def _get_op_name(op, special):
 """
 
 _flex_doc_PANEL = """
-{desc} of series and other, element-wise (binary operator `{op_name}`).
+Return {desc} of series and other, element-wise (binary operator `{op_name}`).
 Equivalent to ``{equiv}``.
 
 Parameters

pandas/core/panel.py

@@ -999,7 +999,7 @@ def construct_index_parts(idx, major=True):
 
     def apply(self, func, axis='major', **kwargs):
         """
-        Applies function along axis (or axes) of the Panel.
+        Apply function along axis (or axes) of the Panel.
 
         Parameters
         ----------

pandas/core/series.py

@@ -580,7 +580,7 @@ def nonzero(self):
 
     def put(self, *args, **kwargs):
         """
-        Applies the `put` method to its `values` attribute if it has one.
+        Apply the `put` method to its `values` attribute if it has one.
 
         See Also
         --------
@@ -1456,7 +1456,7 @@ def iteritems(self):
 
     def keys(self):
         """
-        Alias for index.
+        Return alias for index.
         """
         return self.index
 
@@ -2987,7 +2987,7 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
 
     def argsort(self, axis=0, kind='quicksort', order=None):
         """
-        Overrides ndarray.argsort. Argsorts the value, omitting NA/null values,
+        Override ndarray.argsort. Argsorts the value, omitting NA/null values,
         and places the result in the same locations as the non-NA values.
 
         Parameters

pandas/core/strings.py

@@ -2869,7 +2869,7 @@ def rindex(self, sub, start=0, end=None):
         return self._wrap_result(result)
 
     _shared_docs['len'] = ("""
-    Computes the length of each element in the Series/Index. The element may be
+    Compute the length of each element in the Series/Index. The element may be
     a sequence (such as a string, tuple or list) or a collection
     (such as a dictionary).
 

pandas/core/window.py

@@ -438,7 +438,7 @@ def aggregate(self, arg, *args, **kwargs):
 
 class Window(_Window):
     """
-    Provides rolling window calculations.
+    Provide rolling window calculations.
 
     .. versionadded:: 0.18.0
 
@@ -1803,7 +1803,7 @@ def corr(self, other=None, pairwise=None, **kwargs):
 
 class RollingGroupby(_GroupByMixin, Rolling):
     """
-    Provides a rolling groupby implementation.
+    Provide a rolling groupby implementation.
 
     .. versionadded:: 0.18.1
 
@@ -1834,7 +1834,7 @@ def _validate_monotonic(self):
 
 class Expanding(_Rolling_and_Expanding):
     """
-    Provides expanding transformations.
+    Provide expanding transformations.
 
     .. versionadded:: 0.18.0
 
@@ -2076,7 +2076,7 @@ def corr(self, other=None, pairwise=None, **kwargs):
 
 class ExpandingGroupby(_GroupByMixin, Expanding):
     """
-    Provides a expanding groupby implementation.
+    Provide a expanding groupby implementation.
 
     .. versionadded:: 0.18.1