diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 35358306468c50..d16249724127f0 100755 --- a/ci/code_checks.sh +++ b/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)' ; echo $MSG - $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR05,EX04,RT04 + MSG='Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, EX04, RT04, SS05)' ; echo $MSG + $BASE_DIR/scripts/validate_docstrings.py --format=azure --errors=GL06,GL07,GL09,SS04,PR03,PR05,EX04,RT04,SS05 RET=$(($RET + $?)) ; echo $MSG "DONE" fi diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index f2de3fda3be153..b64c3479f23fe5 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/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 diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index a9be60214080ac..cad63b43230154 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/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 diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 6259ead5ed93e3..e26f6cb03a7684 100644 --- a/pandas/core/arrays/categorical.py +++ b/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 diff --git a/pandas/core/dtypes/common.py b/pandas/core/dtypes/common.py index 0379a3d3eb3cb2..4be7eb8ddb8906 100644 --- a/pandas/core/dtypes/common.py +++ b/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 ---------- diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index f84471c3b04e8f..ac38b2fbbe9577 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/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 diff --git a/pandas/core/frame.py b/pandas/core/frame.py index b11d1437752500..afc4194e71eb1d 100644 --- a/pandas/core/frame.py +++ b/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 diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 10d866d67edea8..d03d78bd9f18c9 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10125,7 +10125,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""", diff --git a/pandas/core/groupby/generic.py b/pandas/core/groupby/generic.py index c5142a4ee98ccd..78aa6d13a9e021 100644 --- a/pandas/core/groupby/generic.py +++ b/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() diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 8766fdbc297551..bee806df824df8 100644 --- a/pandas/core/groupby/groupby.py +++ b/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. diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index d0b44db840a29f..664bf3a4040d82 100644 --- a/pandas/core/indexes/base.py +++ b/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 diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index e43b64827d02a3..0a5536854ebd42 100644 --- a/pandas/core/indexes/category.py +++ b/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 diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 9c46860eb49d65..f34eb75d352a15 100644 --- a/pandas/core/indexes/datetimes.py +++ b/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 diff --git a/pandas/core/ops.py b/pandas/core/ops.py index b3b3b9dd2c20bc..dbdabecafae3a3 100644 --- a/pandas/core/ops.py +++ b/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 diff --git a/pandas/core/panel.py b/pandas/core/panel.py index 8dd604fb580b40..c8afafde48ac26 100644 --- a/pandas/core/panel.py +++ b/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 ---------- diff --git a/pandas/core/series.py b/pandas/core/series.py index 427da96c5e1c49..fb84a36d215e54 100644 --- a/pandas/core/series.py +++ b/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 diff --git a/pandas/core/strings.py b/pandas/core/strings.py index ca79dcd9408d84..bfa36cb4bfd86b 100644 --- a/pandas/core/strings.py +++ b/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). diff --git a/pandas/core/window.py b/pandas/core/window.py index 5556a01307a7ee..060226d94cca08 100644 --- a/pandas/core/window.py +++ b/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 diff --git a/pandas/io/stata.py b/pandas/io/stata.py index 0bd084f4e5df7c..9ba3290c0b51a9 100644 --- a/pandas/io/stata.py +++ b/pandas/io/stata.py @@ -119,7 +119,7 @@ _iterator_params) _data_method_doc = """\ -Reads observations from Stata file, converting them into a dataframe +Read observations from Stata file, converting them into a dataframe .. deprecated:: This is a legacy method. Use `read` in new code. @@ -1726,18 +1726,22 @@ def _do_convert_categoricals(self, data, value_label_dict, lbllist, return data def data_label(self): - """Returns data label of Stata file""" + """ + Return data label of Stata file. + """ return self.data_label def variable_labels(self): - """Returns variable labels as a dict, associating each variable name - with corresponding label + """ + Return variable labels as a dict, associating each variable name + with corresponding label. """ return dict(zip(self.varlist, self._variable_labels)) def value_labels(self): - """Returns a dict, associating each variable name a dict, associating - each value its corresponding label + """ + Return a dict, associating each variable name a dict, associating + each value its corresponding label. """ if not self._value_labels_read: self._read_value_labels() @@ -1747,7 +1751,7 @@ def value_labels(self): def _open_file_binary_write(fname): """ - Open a binary file or no-op if file-like + Open a binary file or no-op if file-like. Parameters ---------- @@ -1778,14 +1782,14 @@ def _set_endianness(endianness): def _pad_bytes(name, length): """ - Takes a char string and pads it with null bytes until it's length chars + Take a char string and pads it with null bytes until it's length chars. """ return name + "\x00" * (length - len(name)) def _convert_datetime_to_stata_type(fmt): """ - Converts from one of the stata date formats to a type in TYPE_MAP + Convert from one of the stata date formats to a type in TYPE_MAP. """ if fmt in ["tc", "%tc", "td", "%td", "tw", "%tw", "tm", "%tm", "tq", "%tq", "th", "%th", "ty", "%ty"]: @@ -1812,7 +1816,7 @@ def _maybe_convert_to_int_keys(convert_dates, varlist): def _dtype_to_stata_type(dtype, column): """ - Converts dtype types to stata types. Returns the byte of the given ordinal. + Convert dtype types to stata types. Returns the byte of the given ordinal. See TYPE_MAP and comments for an explanation. This is also explained in the dta spec. 1 - 244 are strings of this length @@ -1850,7 +1854,7 @@ def _dtype_to_stata_type(dtype, column): def _dtype_to_default_stata_fmt(dtype, column, dta_version=114, force_strl=False): """ - Maps numpy dtype to stata's default format for this type. Not terribly + Map numpy dtype to stata's default format for this type. Not terribly important since users can change this in Stata. Semantics are object -> "%DDs" where DD is the length of the string. If not a string, diff --git a/pandas/plotting/_misc.py b/pandas/plotting/_misc.py index 1c69c03025e007..01cc8ecc6f957a 100644 --- a/pandas/plotting/_misc.py +++ b/pandas/plotting/_misc.py @@ -273,7 +273,7 @@ def normalize(series): def andrews_curves(frame, class_column, ax=None, samples=200, color=None, colormap=None, **kwds): """ - Generates a matplotlib plot of Andrews curves, for visualising clusters of + Generate a matplotlib plot of Andrews curves, for visualising clusters of multivariate data. Andrews curves have the functional form: @@ -598,7 +598,8 @@ def lag_plot(series, lag=1, ax=None, **kwds): def autocorrelation_plot(series, ax=None, **kwds): - """Autocorrelation plot for time series. + """ + Autocorrelation plot for time series. Parameters: ----------- diff --git a/pandas/util/_decorators.py b/pandas/util/_decorators.py index 86cd8b1e698c69..2f7816e3a6d001 100644 --- a/pandas/util/_decorators.py +++ b/pandas/util/_decorators.py @@ -9,7 +9,8 @@ def deprecate(name, alternative, version, alt_name=None, klass=None, stacklevel=2, msg=None): - """Return a new function that emits a deprecation warning on use. + """ + Return a new function that emits a deprecation warning on use. To use this method for a deprecated function, another function `alternative` with the same signature must exist. The deprecated