DOC: Add numpydoc SS06 validation (#47885)

Author: mroeschke

ci/code_checks.sh

@@ -78,8 +78,8 @@ fi
 ### DOCSTRINGS ###
 if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
 
- MSG='Validate docstrings (EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05)' ; echo $MSG
- $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05
+ MSG='Validate docstrings (EX04, GL01, GL02, GL03, GL04, GL05, GL06, GL07, GL09, GL10, PR03, PR04, PR05, PR06, PR08, PR09, PR10, RT01, RT04, RT05, SA02, SA03, SA04, SS01, SS02, SS03, SS04, SS05, SS06)' ; echo $MSG
+ $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06
  RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/_config/config.py

@@ -102,8 +102,9 @@ class RegisteredOption(NamedTuple):
 
 class OptionError(AttributeError, KeyError):
  """
- Exception for pandas.options, backwards compatible with KeyError
- checks.
+ Exception raised for pandas.options.
+
+ Backwards compatible with KeyError checks.
  """
 
 

pandas/_libs/interval.pyx

@@ -352,8 +352,9 @@ cdef class Interval(IntervalMixin):
 
  cdef readonly str inclusive
  """
- Whether the interval is inclusive on the left-side, right-side, both or
- neither.
+ String describing the inclusive side the intervals.
+
+ Either ``left``, ``right``, ``both`` or ``neither``.
  """
 
  def __init__(self, left, right, inclusive: str | None = None, closed: None | lib.NoDefault = lib.no_default):
@@ -384,10 +385,11 @@ cdef class Interval(IntervalMixin):
  @property
  def closed(self):
  """
- Whether the interval is closed on the left-side, right-side, both or
- neither.
+ String describing the inclusive side the intervals.
 
  .. deprecated:: 1.5.0
+
+ Either ``left``, ``right``, ``both`` or ``neither``.
  """
  warnings.warn(
  "Attribute `closed` is deprecated in favor of `inclusive`.",

pandas/_libs/lib.pyx

@@ -1347,8 +1347,7 @@ cdef object _try_infer_map(object dtype):
 
 def infer_dtype(value: object, skipna: bool = True) -> str:
  """
- Efficiently infer the type of a passed val, or list-like
- array of values. Return a string describing the type.
+ Return a string label of the type of a scalar or list-like of values.
 
  Parameters
  ----------

pandas/_libs/tslibs/nattype.pyx

@@ -446,13 +446,15 @@ class NaTType(_NaT):
  "weekday",
  """
  Return the day of the week represented by the date.
+
  Monday == 0 ... Sunday == 6.
  """,
  )
  isoweekday = _make_nan_func(
  "isoweekday",
  """
  Return the day of the week represented by the date.
+
  Monday == 1 ... Sunday == 7.
  """,
  )
@@ -533,10 +535,7 @@ class NaTType(_NaT):
  strftime = _make_error_func(
  "strftime",
  """
- Timestamp.strftime(format)
-
- Return a string representing the given POSIX timestamp
- controlled by an explicit format string.
+ Return a formatted string of the Timestamp.
 
  Parameters
  ----------
@@ -680,10 +679,7 @@ class NaTType(_NaT):
  fromordinal = _make_error_func(
  "fromordinal",
  """
- Timestamp.fromordinal(ordinal, freq=None, tz=None)
-
- Passed an ordinal, translate and convert to a ts.
- Note: by definition there cannot be any tz info on the ordinal itself.
+ Construct a timestamp from a a proleptic Gregorian ordinal.
 
  Parameters
  ----------
@@ -694,6 +690,10 @@ class NaTType(_NaT):
  tz : str, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for the Timestamp.
 
+ Notes
+ -----
+ By definition there cannot be any tz info on the ordinal itself.
+
  Examples
  --------
  >>> pd.Timestamp.fromordinal(737425)
@@ -725,10 +725,7 @@ class NaTType(_NaT):
  now = _make_nat_func(
  "now",
  """
- Timestamp.now(tz=None)
-
- Return new Timestamp object representing current time local to
- tz.
+ Return new Timestamp object representing current time local to tz.
 
  Parameters
  ----------
@@ -749,10 +746,9 @@ class NaTType(_NaT):
  today = _make_nat_func(
  "today",
  """
- Timestamp.today(cls, tz=None)
+ Return the current time in the local timezone.
 
- Return the current time in the local timezone. This differs
- from datetime.today() in that it can be localized to a
+ This differs from datetime.today() in that it can be localized to a
  passed timezone.
 
  Parameters
@@ -1090,7 +1086,9 @@ timedelta}, default 'raise'
  tz_localize = _make_nat_func(
  "tz_localize",
  """
- Convert naive Timestamp to local time zone, or remove
+ Localize the Timestamp to a timezone.
+
+ Convert naive Timestamp to local time zone or remove
  timezone from timezone-aware Timestamp.
 
  Parameters

pandas/_libs/tslibs/np_datetime.pyx

@@ -156,16 +156,16 @@ cdef inline bint cmp_scalar(int64_t lhs, int64_t rhs, int op) except -1:
 
 class OutOfBoundsDatetime(ValueError):
  """
- Raised when the datetime is outside the range that
- can be represented.
+ Raised when the datetime is outside the range that can be represented.
  """
  pass
 
 
 class OutOfBoundsTimedelta(ValueError):
  """
- Raised when encountering a timedelta value that cannot be represented
- as a timedelta64[ns].
+ Raised when encountering a timedelta value that cannot be represented.
+
+ Representation should be within a timedelta64[ns].
  """
  # Timedelta analogue to OutOfBoundsDatetime
  pass

pandas/_libs/tslibs/offsets.pyx

@@ -585,9 +585,7 @@ cdef class BaseOffset:
 
  def apply_index(self, dtindex):
  """
- Vectorized apply of DateOffset to DatetimeIndex,
- raises NotImplementedError for offsets without a
- vectorized implementation.
+ Vectorized apply of DateOffset to DatetimeIndex.
 
  .. deprecated:: 1.1.0
 
@@ -2448,8 +2446,7 @@ cdef class SemiMonthOffset(SingleConstructorOffset):
 
 cdef class SemiMonthEnd(SemiMonthOffset):
  """
- Two DateOffset's per month repeating on the last
- day of the month and day_of_month.
+ Two DateOffset's per month repeating on the last day of the month & day_of_month.
 
  Parameters
  ----------
@@ -2470,8 +2467,7 @@ cdef class SemiMonthEnd(SemiMonthOffset):
 
 cdef class SemiMonthBegin(SemiMonthOffset):
  """
- Two DateOffset's per month repeating on the first
- day of the month and day_of_month.
+ Two DateOffset's per month repeating on the first day of the month & day_of_month.
 
  Parameters
  ----------
@@ -2704,8 +2700,9 @@ cdef class WeekOfMonth(WeekOfMonthMixin):
 
 cdef class LastWeekOfMonth(WeekOfMonthMixin):
  """
- Describes monthly dates in last week of month like "the last Tuesday of
- each month".
+ Describes monthly dates in last week of month.
+
+ For example "the last Tuesday of each month".
 
  Parameters
  ----------
@@ -2991,8 +2988,9 @@ cdef class FY5253(FY5253Mixin):
 
 cdef class FY5253Quarter(FY5253Mixin):
  """
- DateOffset increments between business quarter dates
- for 52-53 week fiscal year (also known as a 4-4-5 calendar).
+ DateOffset increments between business quarter dates for 52-53 week fiscal year.
+
+ Also known as a 4-4-5 calendar.
 
  It is used by companies that desire that their
  fiscal year always end on the same day of the week.
@@ -3602,8 +3600,7 @@ def _get_offset(name: str) -> BaseOffset:
 
 cpdef to_offset(freq):
  """
- Return DateOffset object from string or tuple representation
- or datetime.timedelta object.
+ Return DateOffset object from string or datetime.timedelta object.
 
  Parameters
  ----------

pandas/_libs/tslibs/period.pyx

@@ -2322,12 +2322,12 @@ cdef class _Period(PeriodMixin):
 
  def strftime(self, fmt: str) -> str:
  r"""
- Returns the string representation of the :class:`Period`, depending
- on the selected ``fmt``. ``fmt`` must be a string
- containing one or several directives. The method recognizes the same
- directives as the :func:`time.strftime` function of the standard Python
- distribution, as well as the specific additional directives ``%f``,
- ``%F``, ``%q``, ``%l``, ``%u``, ``%n``.
+ Returns a formatted string representation of the :class:`Period`.
+
+ ``fmt`` must be a string containing one or several directives.
+ The method recognizes the same directives as the :func:`time.strftime`
+ function of the standard Python distribution, as well as the specific
+ additional directives ``%f``, ``%F``, ``%q``, ``%l``, ``%u``, ``%n``.
  (formatting & docs originally from scikits.timeries).
 
  +-----------+--------------------------------+-------+

pandas/_libs/tslibs/timedeltas.pyx

@@ -1464,7 +1464,8 @@ cdef class _Timedelta(timedelta):
 
  def isoformat(self) -> str:
  """
- Format Timedelta as ISO 8601 Duration like
+ Format the Timedelta as ISO 8601 Duration.
+
  ``P[n]Y[n]M[n]DT[n]H[n]M[n]S``, where the ``[n]`` s are replaced by the
  values. See https://en.wikipedia.org/wiki/ISO_8601#Durations.
 

pandas/_libs/tslibs/timestamps.pyx

@@ -1345,10 +1345,7 @@ class Timestamp(_Timestamp):
  @classmethod
  def fromordinal(cls, ordinal, freq=None, tz=None):
  """
- Timestamp.fromordinal(ordinal, freq=None, tz=None)
-
- Passed an ordinal, translate and convert to a ts.
- Note: by definition there cannot be any tz info on the ordinal itself.
+ Construct a timestamp from a a proleptic Gregorian ordinal.
 
  Parameters
  ----------
@@ -1359,6 +1356,10 @@ class Timestamp(_Timestamp):
  tz : str, pytz.timezone, dateutil.tz.tzfile or None
  Time zone for the Timestamp.
 
+ Notes
+ -----
+ By definition there cannot be any tz info on the ordinal itself.
+
  Examples
  --------
  >>> pd.Timestamp.fromordinal(737425)
@@ -1370,10 +1371,7 @@ class Timestamp(_Timestamp):
  @classmethod
  def now(cls, tz=None):
  """
- Timestamp.now(tz=None)
-
- Return new Timestamp object representing current time local to
- tz.
+ Return new Timestamp object representing current time local to tz.
 
  Parameters
  ----------
@@ -1397,10 +1395,9 @@ class Timestamp(_Timestamp):
  @classmethod
  def today(cls, tz=None):
  """
- Timestamp.today(cls, tz=None)
+ Return the current time in the local timezone.
 
- Return the current time in the local timezone. This differs
- from datetime.today() in that it can be localized to a
+ This differs from datetime.today() in that it can be localized to a
  passed timezone.
 
  Parameters
@@ -1477,10 +1474,7 @@ class Timestamp(_Timestamp):
 
  def strftime(self, format):
  """
- Timestamp.strftime(format)
-
- Return a string representing the given POSIX timestamp
- controlled by an explicit format string.
+ Return a formatted string of the Timestamp.
 
  Parameters
  ----------
@@ -2052,7 +2046,9 @@ timedelta}, default 'raise'
 
  def tz_localize(self, tz, ambiguous='raise', nonexistent='raise'):
  """
- Convert naive Timestamp to local time zone, or remove
+ Localize the Timestamp to a timezone.
+
+ Convert naive Timestamp to local time zone or remove
  timezone from timezone-aware Timestamp.
 
  Parameters
@@ -2343,6 +2339,7 @@ default 'raise'
  def to_julian_date(self) -> np.float64:
  """
  Convert TimeStamp to a Julian Date.
+
  0 Julian date is noon January 1, 4713 BC.
 
  Examples
@@ -2374,6 +2371,7 @@ default 'raise'
  def isoweekday(self):
  """
  Return the day of the week represented by the date.
+
  Monday == 1 ... Sunday == 7.
  """
  # same as super().isoweekday(), but that breaks because of how
@@ -2383,6 +2381,7 @@ default 'raise'
  def weekday(self):
  """
  Return the day of the week represented by the date.
+
  Monday == 0 ... Sunday == 6.
  """
  # same as super().weekday(), but that breaks because of how