Merge branch 'main' into test_date_range_for_bug_57456

Author: mroeschke

ci/code_checks.sh

@@ -595,13 +595,42 @@ cdef class BaseOffset:
 
     @property
     def rule_code(self) -> str:
+        """
+        Return a string representing the base frequency.
+
+        See Also
+        --------
+        tseries.offsets.Hour.rule_code :
+            Returns a string representing the base frequency of 'h'.
+        tseries.offsets.Day.rule_code :
+            Returns a string representing the base frequency of 'D'.
+
+        Examples
+        --------
+        >>> pd.offsets.Hour().rule_code
+        'h'
+
+        >>> pd.offsets.Week(5).rule_code
+        'W'
+        """
         return self._prefix
 
     @cache_readonly
     def freqstr(self) -> str:
         """
         Return a string representing the frequency.
 
+        See Also
+        --------
+        tseries.offsets.BusinessDay.freqstr :
+            Return a string representing an offset frequency in Business Days.
+        tseries.offsets.BusinessHour.freqstr :
+            Return a string representing an offset frequency in Business Hours.
+        tseries.offsets.Week.freqstr :
+            Return a string representing an offset frequency in Weeks.
+        tseries.offsets.Hour.freqstr :
+            Return a string representing an offset frequency in Hours.
+
         Examples
         --------
         >>> pd.DateOffset(5).freqstr
@@ -779,6 +808,26 @@ cdef class BaseOffset:
 
     @property
     def nanos(self):
+        """
+        Returns a integer of the total number of nanoseconds for fixed frequencies.
+
+        Raises
+        ------
+        ValueError
+            If the frequency is non-fixed.
+
+        See Also
+        --------
+        tseries.offsets.Hour.nanos :
+            Returns an integer of the total number of nanoseconds.
+        tseries.offsets.Day.nanos :
+            Returns an integer of the total number of nanoseconds.
+
+        Examples
+        --------
+        >>> pd.offsets.Week(n=1).nanos
+        ValueError: Week: weekday=None is a non-fixed frequency
+        """
         raise ValueError(f"{self} is a non-fixed frequency")
 
     # ------------------------------------------------------------------
@@ -986,12 +1035,14 @@ cdef class Tick(SingleConstructorOffset):
     @property
     def nanos(self) -> int64_t:
         """
-        Return an integer of the total number of nanoseconds.
+        Returns an integer of the total number of nanoseconds.
 
-        Raises
-        ------
-        ValueError
-            If the frequency is non-fixed.
+        See Also
+        --------
+        tseries.offsets.Hour.nanos :
+            Returns an integer of the total number of nanoseconds.
+        tseries.offsets.Day.nanos :
+            Returns an integer of the total number of nanoseconds.
 
         Examples
         --------
@@ -2426,6 +2477,24 @@ cdef class WeekOfMonthMixin(SingleConstructorOffset):
 
     @property
     def rule_code(self) -> str:
+        """
+        Return a string representing the base frequency.
+
+        See Also
+        --------
+        tseries.offsets.Hour.rule_code :
+            Returns a string representing the base frequency of 'h'.
+        tseries.offsets.Day.rule_code :
+            Returns a string representing the base frequency of 'D'.
+
+        Examples
+        --------
+        >>> pd.offsets.Week(5).rule_code
+        'W'
+
+        >>> pd.offsets.WeekOfMonth(n=1, week=0, weekday=0).rule_code
+        'WOM-1MON'
+        """
         weekday = int_to_weekday.get(self.weekday, "")
         if self.week == -1:
             # LastWeekOfMonth
@@ -2472,6 +2541,24 @@ cdef class YearOffset(SingleConstructorOffset):
 
     @property
     def rule_code(self) -> str:
+        """
+        Return a string representing the base frequency.
+
+        See Also
+        --------
+        tseries.offsets.Hour.rule_code :
+            Returns a string representing the base frequency of 'h'.
+        tseries.offsets.Day.rule_code :
+            Returns a string representing the base frequency of 'D'.
+
+        Examples
+        --------
+        >>> pd.tseries.offsets.YearBegin(n=1, month=2).rule_code
+        'YS-FEB'
+
+        >>> pd.tseries.offsets.YearEnd(n=1, month=6).rule_code
+        'YE-JUN'
+        """
         month = MONTH_ALIASES[self.month]
         return f"{self._prefix}-{month}"
 
@@ -3458,6 +3545,24 @@ cdef class Week(SingleConstructorOffset):
 
     @property
     def rule_code(self) -> str:
+        """
+        Return a string representing the base frequency.
+
+        See Also
+        --------
+        tseries.offsets.Hour.name :
+            Returns a string representing the base frequency of 'h'.
+        tseries.offsets.Day.name :
+            Returns a string representing the base frequency of 'D'.
+
+        Examples
+        --------
+        >>> pd.offsets.Hour().rule_code
+        'h'
+
+        >>> pd.offsets.Week(5).rule_code
+        'W'
+        """
         suffix = ""
         if self.weekday is not None:
             weekday = int_to_weekday[self.weekday]

pandas/_libs/tslibs/offsets.pyx

@@ -1913,20 +1913,58 @@ cdef class _Period(PeriodMixin):
         Parameters
         ----------
         freq : str, BaseOffset
-            The desired frequency. If passing a `str`, it needs to be a
-            valid :ref:`period alias <timeseries.period_aliases>`.
+            The target frequency to convert the Period object to.
+            If a string is provided,
+            it must be a valid :ref:`period alias <timeseries.period_aliases>`.
+
         how : {'E', 'S', 'end', 'start'}, default 'end'
-            Start or end of the timespan.
+            Specifies whether to align the period to the start or end of the interval:
+            - 'E' or 'end': Align to the end of the interval.
+            - 'S' or 'start': Align to the start of the interval.
 
         Returns
         -------
-        resampled : Period
+        Period : Period object with the specified frequency, aligned to the parameter.
+
+        See Also
+        --------
+        Period.end_time : Return the end Timestamp.
+        Period.start_time : Return the start Timestamp.
+        Period.dayofyear : Return the day of the year.
+        Period.dayofweek : Return the day of the week.
 
         Examples
         --------
-        >>> period = pd.Period('2023-1-1', freq='D')
+        Convert a daily period to an hourly period, aligning to the end of the day:
+
+        >>> period = pd.Period('2023-01-01', freq='D')
         >>> period.asfreq('h')
         Period('2023-01-01 23:00', 'h')
+
+        Convert a monthly period to a daily period, aligning to the start of the month:
+
+        >>> period = pd.Period('2023-01', freq='M')
+        >>> period.asfreq('D', how='start')
+        Period('2023-01-01', 'D')
+
+        Convert a yearly period to a monthly period, aligning to the last month:
+
+        >>> period = pd.Period('2023', freq='Y')
+        >>> period.asfreq('M', how='end')
+        Period('2023-12', 'M')
+
+        Convert a monthly period to an hourly period,
+        aligning to the first day of the month:
+
+        >>> period = pd.Period('2023-01', freq='M')
+        >>> period.asfreq('h', how='start')
+        Period('2023-01-01 00:00', 'H')
+
+        Convert a weekly period to a daily period, aligning to the last day of the week:
+
+        >>> period = pd.Period('2023-08-01', freq='W')
+        >>> period.asfreq('D', how='end')
+        Period('2023-08-04', 'D')
         """
         freq = self._maybe_convert_freq(freq)
         how = validate_end_alias(how)
@@ -2014,11 +2052,45 @@ cdef class _Period(PeriodMixin):
         """
         Return the month this Period falls on.
 
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        period.week : Get the week of the year on the given Period.
+        Period.year : Return the year this Period falls on.
+        Period.day : Return the day of the month this Period falls on.
+
+        Notes
+        -----
+        The month is based on the `ordinal` and `base` attributes of the Period.
+
         Examples
         --------
+        Create a Period object for January 2022 and get the month:
+
         >>> period = pd.Period('2022-01', 'M')
         >>> period.month
         1
+
+        Period object with no specified frequency, resulting in a default frequency:
+
+        >>> period = pd.Period('2022', 'Y')
+        >>> period.month
+        12
+
+        Create a Period object with a specified frequency but an incomplete date string:
+
+        >>> period = pd.Period('2022', 'M')
+        >>> period.month
+        1
+
+        Handle a case where the Period object is empty, which results in `NaN`:
+
+        >>> period = pd.Period('nan', 'M')
+        >>> period.month
+        nan
         """
         base = self._dtype._dtype_code
         return pmonth(self.ordinal, base)

pandas/_libs/tslibs/period.pyx

@@ -557,7 +557,3 @@ def _wrap_ndarray_result(self, result: np.ndarray):
 
             return TimedeltaArray._simple_new(result, dtype=result.dtype)
         return type(self)(result)
-
-    # ------------------------------------------------------------------------
-    # String methods interface
-    _str_na_value = np.nan

pandas/core/arrays/numpy_.py

@@ -848,12 +848,6 @@ def _cmp_method(self, other, op):
 
     _arith_method = _cmp_method
 
-    # ------------------------------------------------------------------------
-    # String methods interface
-    # error: Incompatible types in assignment (expression has type "NAType",
-    # base class "NumpyExtensionArray" defined the type as "float")
-    _str_na_value = libmissing.NA  # type: ignore[assignment]
-
 
 class StringArrayNumpySemantics(StringArray):
     _storage = "python"
@@ -884,7 +878,3 @@ def _from_backing_data(self, arr: np.ndarray) -> StringArrayNumpySemantics:
         # need to override NumpyExtensionArray._from_backing_data to ensure
         # we always preserve the dtype
         return NDArrayBacked._from_backing_data(self, arr)
-
-    # ------------------------------------------------------------------------
-    # String methods interface
-    _str_na_value = np.nan

pandas/core/arrays/string_.py

@@ -275,10 +275,6 @@ def astype(self, dtype, copy: bool = True):
     # ------------------------------------------------------------------------
     # String methods interface
 
-    # error: Incompatible types in assignment (expression has type "NAType",
-    # base class "ObjectStringArrayMixin" defined the type as "float")
-    _str_na_value = libmissing.NA  # type: ignore[assignment]
-
     _str_map = BaseStringArray._str_map
 
     def _str_contains(

pandas/core/arrays/string_arrow.py

@@ -1636,6 +1636,17 @@ def _set_names(self, names, *, level=None, validate: bool = True) -> None:
         doc="""
         Names of levels in MultiIndex.
 
+        This attribute provides access to the names of the levels in a `MultiIndex`.
+        The names are stored as a `FrozenList`, which is an immutable list-like
+        container. Each name corresponds to a level in the `MultiIndex`, and can be
+        used to identify or manipulate the levels individually.
+
+        See Also
+        --------
+        MultiIndex.set_names : Set Index or MultiIndex name.
+        MultiIndex.rename : Rename specific levels in a MultiIndex.
+        Index.names : Get names on index.
+
         Examples
         --------
         >>> mi = pd.MultiIndex.from_arrays(
@@ -2681,8 +2692,15 @@ def sortlevel(
         """
         Sort MultiIndex at the requested level.
 
-        The result will respect the original ordering of the associated
-        factor at that level.
+        This method is useful when dealing with MultiIndex objects, allowing for
+        sorting at a specific level of the index. The function preserves the
+        relative ordering of data within the same level while sorting
+        the overall MultiIndex. The method provides flexibility with the `ascending`
+        parameter to define the sort order and with the `sort_remaining` parameter to
+        control whether the remaining levels should also be sorted. Sorting a
+        MultiIndex can be crucial when performing operations that require ordered
+        indices, such as grouping or merging datasets. The `na_position` argument is
+        important in handling missing values consistently across different levels.
 
         Parameters
         ----------
@@ -2692,7 +2710,9 @@ def sortlevel(
         ascending : bool, default True
             False to sort in descending order.
             Can also be a list to specify a directed ordering.
-        sort_remaining : sort by the remaining levels after level
+        sort_remaining : bool, default True
+            If True, sorts by the remaining levels after sorting by the specified
+            `level`.
         na_position : {'first' or 'last'}, default 'first'
             Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
             the end.
@@ -2706,6 +2726,13 @@ def sortlevel(
         indexer : np.ndarray[np.intp]
             Indices of output values in original index.
 
+        See Also
+        --------
+        MultiIndex : A multi-level, or hierarchical, index object for pandas objects.
+        Index.sort_values : Sort Index values.
+        DataFrame.sort_index : Sort DataFrame by the index.
+        Series.sort_index : Sort Series by the index.
+
         Examples
         --------
         >>> mi = pd.MultiIndex.from_arrays([[0, 0], [2, 1]])