DOC/CLN: Fix various docstring errors (#25295)

Author: Daniel Saxton

pandas/core/arrays/categorical.py

@@ -214,7 +214,7 @@ def contains(cat, key, container):
 
 class Categorical(ExtensionArray, PandasObject):
  """
- Represent 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
@@ -235,7 +235,7 @@ class Categorical(ExtensionArray, PandasObject):
  The unique categories for this categorical. If not given, the
  categories are assumed to be the unique values of `values` (sorted, if
  possible, otherwise in the order in which they appear).
- ordered : boolean, (default False)
+ ordered : bool, default False
  Whether or not this categorical is treated as a ordered categorical.
  If True, the resulting categorical will be ordered.
  An ordered categorical respects, when sorted, the order of its
@@ -253,7 +253,7 @@ class Categorical(ExtensionArray, PandasObject):
  codes : ndarray
  The codes (integer positions, which point to the categories) of this
  categorical, read only.
- ordered : boolean
+ ordered : bool
  Whether or not this Categorical is ordered.
  dtype : CategoricalDtype
  The instance of ``CategoricalDtype`` storing the ``categories``
@@ -297,7 +297,7 @@ class Categorical(ExtensionArray, PandasObject):
  Ordered `Categoricals` can be sorted according to the custom order
  of the categories and can have a min and max value.
 
- >>> c = pd.Categorical(['a','b','c','a','b','c'], ordered=True,
+ >>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'], ordered=True,
  ... categories=['c', 'b', 'a'])
  >>> c
  [a, b, c, a, b, c]
@@ -618,7 +618,7 @@ def from_codes(cls, codes, categories=None, ordered=None, dtype=None):
  ----------
  codes : array-like, integers
  An integer array, where each integer points to a category in
- categories or dtype.categories, or else is -1 for NaN
+ categories or dtype.categories, or else is -1 for NaN.
  categories : index-like, optional
  The categories for the categorical. Items need to be unique.
  If the categories are not given here, then they must be provided
@@ -700,7 +700,7 @@ def _set_categories(self, categories, fastpath=False):
 
  Parameters
  ----------
- fastpath : boolean (default: False)
+ fastpath : bool, default False
  Don't perform validation of the categories for uniqueness or nulls
 
  Examples
@@ -747,15 +747,15 @@ def _set_dtype(self, dtype):
 
  def set_ordered(self, value, inplace=False):
  """
- Set the ordered attribute to the boolean value
+ Set the ordered attribute to the boolean value.
 
  Parameters
  ----------
- value : boolean to set whether this categorical is ordered (True) or
- not (False)
- inplace : boolean (default: False)
- Whether or not to set the ordered attribute inplace or return a copy
- of this categorical with ordered set to the value
+ value : bool
+ Set whether this categorical is ordered (True) or not (False).
+ inplace : bool, default False
+ Whether or not to set the ordered attribute in-place or return
+ a copy of this categorical with ordered set to the value.
  """
  inplace = validate_bool_kwarg(inplace, 'inplace')
  new_dtype = CategoricalDtype(self.categories, ordered=value)
@@ -770,9 +770,9 @@ def as_ordered(self, inplace=False):
 
  Parameters
  ----------
- inplace : boolean (default: False)
- Whether or not to set the ordered attribute inplace or return a copy
- of this categorical with ordered set to True
+ inplace : bool, default False
+ Whether or not to set the ordered attribute in-place or return
+ a copy of this categorical with ordered set to True.
  """
  inplace = validate_bool_kwarg(inplace, 'inplace')
  return self.set_ordered(True, inplace=inplace)
@@ -783,9 +783,9 @@ def as_unordered(self, inplace=False):
 
  Parameters
  ----------
- inplace : boolean (default: False)
- Whether or not to set the ordered attribute inplace or return a copy
- of this categorical with ordered set to False
+ inplace : bool, default False
+ Whether or not to set the ordered attribute in-place or return
+ a copy of this categorical with ordered set to False.
  """
  inplace = validate_bool_kwarg(inplace, 'inplace')
  return self.set_ordered(False, inplace=inplace)
@@ -815,19 +815,19 @@ def set_categories(self, new_categories, ordered=None, rename=False,
  ----------
  new_categories : Index-like
  The categories in new order.
- ordered : boolean, (default: False)
+ ordered : bool, default False
  Whether or not the categorical is treated as a ordered categorical.
  If not given, do not change the ordered information.
- rename : boolean (default: False)
+ rename : bool, default False
  Whether or not the new_categories should be considered as a rename
  of the old categories or as reordered categories.
- inplace : boolean (default: False)
- Whether or not to reorder the categories inplace or return a copy of
- this categorical with reordered categories.
+ inplace : bool, default False
+ Whether or not to reorder the categories in-place or return a copy
+ of this categorical with reordered categories.
 
  Returns
  -------
- cat : Categorical with reordered categories or None if inplace.
+ Categorical with reordered categories or None if inplace.
 
  Raises
  ------
@@ -890,7 +890,7 @@ def rename_categories(self, new_categories, inplace=False):
  Currently, Series are considered list like. In a future version
  of pandas they'll be considered dict-like.
 
- inplace : boolean (default: False)
+ inplace : bool, default False
  Whether or not to rename the categories inplace or return a copy of
  this categorical with renamed categories.
 
@@ -967,10 +967,10 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
  ----------
  new_categories : Index-like
  The categories in new order.
- ordered : boolean, optional
+ ordered : bool, optional
  Whether or not the categorical is treated as a ordered categorical.
  If not given, do not change the ordered information.
- inplace : boolean (default: False)
+ inplace : bool, default False
  Whether or not to reorder the categories inplace or return a copy of
  this categorical with reordered categories.
 
@@ -1010,7 +1010,7 @@ def add_categories(self, new_categories, inplace=False):
  ----------
  new_categories : category or list-like of category
  The new categories to be included.
- inplace : boolean (default: False)
+ inplace : bool, default False
  Whether or not to add the categories inplace or return a copy of
  this categorical with added categories.
 
@@ -1060,7 +1060,7 @@ def remove_categories(self, removals, inplace=False):
  ----------
  removals : category or list of categories
  The categories which should be removed.
- inplace : boolean (default: False)
+ inplace : bool, default False
  Whether or not to remove the categories inplace or return a copy of
  this categorical with removed categories.
 
@@ -1108,7 +1108,7 @@ def remove_unused_categories(self, inplace=False):
 
  Parameters
  ----------
- inplace : boolean (default: False)
+ inplace : bool, default False
  Whether or not to drop unused categories inplace or return a copy of
  this categorical with unused categories dropped.
 
@@ -1460,7 +1460,7 @@ def value_counts(self, dropna=True):
 
  Parameters
  ----------
- dropna : boolean, default True
+ dropna : bool, default True
  Don't include counts of NaN.
 
  Returns
@@ -1581,9 +1581,9 @@ def sort_values(self, inplace=False, ascending=True, na_position='last'):
 
  Parameters
  ----------
- inplace : boolean, default False
+ inplace : bool, default False
  Do operation in place.
- ascending : boolean, default True
+ ascending : bool, default True
  Order ascending. Passing False orders descending. The
  ordering parameter provides the method by which the
  category values are organized.
@@ -2239,7 +2239,7 @@ def mode(self, dropna=True):
 
  Parameters
  ----------
- dropna : boolean, default True
+ dropna : bool, default True
  Don't consider counts of NaN/NaT.
 
  .. versionadded:: 0.24.0
@@ -2332,7 +2332,7 @@ def equals(self, other):
 
  Returns
  -------
- are_equal : boolean
+ bool
  """
  if self.is_dtype_equal(other):
  if self.categories.equals(other.categories):
@@ -2356,7 +2356,7 @@ def is_dtype_equal(self, other):
 
  Returns
  -------
- are_equal : boolean
+ bool
  """
 
  try:

pandas/core/arrays/datetimes.py

@@ -799,14 +799,14 @@ def tz_convert(self, tz):
 
  Parameters
  ----------
- tz : string, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for time. Corresponding timestamps would be converted
  to this time zone of the Datetime Array/Index. A `tz` of None will
  convert to UTC and remove the timezone information.
 
  Returns
  -------
- normalized : same type as self
+ Array or Index
 
  Raises
  ------
@@ -842,7 +842,7 @@ def tz_convert(self, tz):
  With the ``tz=None``, we can remove the timezone (after converting
  to UTC if necessary):
 
- >>> dti = pd.date_range(start='2014-08-01 09:00',freq='H',
+ >>> dti = pd.date_range(start='2014-08-01 09:00', freq='H',
  ... periods=3, tz='Europe/Berlin')
 
  >>> dti
@@ -882,7 +882,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
 
  Parameters
  ----------
- tz : string, pytz.timezone, dateutil.tz.tzfile or None
+ tz : str, pytz.timezone, dateutil.tz.tzfile or None
  Time zone to convert timestamps to. Passing ``None`` will
  remove the time zone information preserving local time.
  ambiguous : 'infer', 'NaT', bool array, default 'raise'
@@ -930,7 +930,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
 
  Returns
  -------
- result : same type as self
+ Same type as self
  Array/Index converted to the specified time zone.
 
  Raises
@@ -970,43 +970,39 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
 
  Be careful with DST changes. When there is sequential data, pandas can
  infer the DST time:
- >>> s = pd.to_datetime(pd.Series([
- ... '2018-10-28 01:30:00',
- ... '2018-10-28 02:00:00',
- ... '2018-10-28 02:30:00',
- ... '2018-10-28 02:00:00',
- ... '2018-10-28 02:30:00',
- ... '2018-10-28 03:00:00',
- ... '2018-10-28 03:30:00']))
+ >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:30:00',
+ ... '2018-10-28 02:00:00',
+ ... '2018-10-28 02:30:00',
+ ... '2018-10-28 02:00:00',
+ ... '2018-10-28 02:30:00',
+ ... '2018-10-28 03:00:00',
+ ... '2018-10-28 03:30:00']))
  >>> s.dt.tz_localize('CET', ambiguous='infer')
- 2018-10-28 01:30:00+02:00 0
- 2018-10-28 02:00:00+02:00 1
- 2018-10-28 02:30:00+02:00 2
- 2018-10-28 02:00:00+01:00 3
- 2018-10-28 02:30:00+01:00 4
- 2018-10-28 03:00:00+01:00 5
- 2018-10-28 03:30:00+01:00 6
- dtype: int64
+ 0 2018-10-28 01:30:00+02:00
+ 1 2018-10-28 02:00:00+02:00
+ 2 2018-10-28 02:30:00+02:00
+ 3 2018-10-28 02:00:00+01:00
+ 4 2018-10-28 02:30:00+01:00
+ 5 2018-10-28 03:00:00+01:00
+ 6 2018-10-28 03:30:00+01:00
+ dtype: datetime64[ns, CET]
 
  In some cases, inferring the DST is impossible. In such cases, you can
  pass an ndarray to the ambiguous parameter to set the DST explicitly
 
- >>> s = pd.to_datetime(pd.Series([
- ... '2018-10-28 01:20:00',
- ... '2018-10-28 02:36:00',
- ... '2018-10-28 03:46:00']))
+ >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:20:00',
+ ... '2018-10-28 02:36:00',
+ ... '2018-10-28 03:46:00']))
  >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False]))
- 0 2018-10-28 01:20:00+02:00
- 1 2018-10-28 02:36:00+02:00
- 2 2018-10-28 03:46:00+01:00
- dtype: datetime64[ns, CET]
+ 0 2015-03-29 03:00:00+02:00
+ 1 2015-03-29 03:30:00+02:00
+ dtype: datetime64[ns, Europe/Warsaw]
 
  If the DST transition causes nonexistent times, you can shift these
  dates forward or backwards with a timedelta object or `'shift_forward'`
  or `'shift_backwards'`.
- >>> s = pd.to_datetime(pd.Series([
- ... '2015-03-29 02:30:00',
- ... '2015-03-29 03:30:00']))
+ >>> s = pd.to_datetime(pd.Series(['2015-03-29 02:30:00',
+ ... '2015-03-29 03:30:00']))
  >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')
  0 2015-03-29 03:00:00+02:00
  1 2015-03-29 03:30:00+02:00
@@ -1129,7 +1125,7 @@ def to_period(self, freq=None):
 
  Parameters
  ----------
- freq : string or Offset, optional
+ freq : str or Offset, optional
  One of pandas' :ref:`offset strings <timeseries.offset_aliases>`
  or an Offset object. Will be inferred by default.
 
@@ -1150,7 +1146,7 @@ def to_period(self, freq=None):
 
  Examples
  --------
- >>> df = pd.DataFrame({"y": [1,2,3]},
+ >>> df = pd.DataFrame({"y": [1, 2, 3]},
  ... index=pd.to_datetime(["2000-03-31 00:00:00",
  ... "2000-05-31 00:00:00",
  ... "2000-08-31 00:00:00"]))