diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 0d1c362a87f12..0fa886dc27abd 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -81,27 +81,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Period.to_timestamp SA01" \ -i "pandas.PeriodDtype SA01" \ -i "pandas.PeriodDtype.freq SA01" \ - -i "pandas.PeriodIndex.day SA01" \ - -i "pandas.PeriodIndex.day_of_week SA01" \ - -i "pandas.PeriodIndex.day_of_year SA01" \ - -i "pandas.PeriodIndex.dayofweek SA01" \ - -i "pandas.PeriodIndex.dayofyear SA01" \ - -i "pandas.PeriodIndex.days_in_month SA01" \ - -i "pandas.PeriodIndex.daysinmonth SA01" \ - -i "pandas.PeriodIndex.from_fields PR07,SA01" \ - -i "pandas.PeriodIndex.from_ordinals SA01" \ - -i "pandas.PeriodIndex.hour SA01" \ - -i "pandas.PeriodIndex.is_leap_year SA01" \ - -i "pandas.PeriodIndex.minute SA01" \ - -i "pandas.PeriodIndex.month SA01" \ - -i "pandas.PeriodIndex.quarter SA01" \ - -i "pandas.PeriodIndex.qyear GL08" \ - -i "pandas.PeriodIndex.second SA01" \ - -i "pandas.PeriodIndex.to_timestamp RT03,SA01" \ - -i "pandas.PeriodIndex.week SA01" \ - -i "pandas.PeriodIndex.weekday SA01" \ - -i "pandas.PeriodIndex.weekofyear SA01" \ - -i "pandas.PeriodIndex.year SA01" \ -i "pandas.RangeIndex PR07" \ -i "pandas.RangeIndex.from_range PR01,SA01" \ -i "pandas.RangeIndex.start SA01" \ @@ -124,7 +103,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Series.dt.month_name PR01,PR02" \ -i "pandas.Series.dt.nanoseconds SA01" \ -i "pandas.Series.dt.normalize PR01" \ - -i "pandas.Series.dt.qyear GL08" \ -i "pandas.Series.dt.round PR01,PR02" \ -i "pandas.Series.dt.seconds SA01" \ -i "pandas.Series.dt.strftime PR01,PR02" \ diff --git a/pandas/core/arrays/period.py b/pandas/core/arrays/period.py index b3513dd083e41..aa8dacbd6aad5 100644 --- a/pandas/core/arrays/period.py +++ b/pandas/core/arrays/period.py @@ -432,6 +432,15 @@ def __arrow_array__(self, type=None): """ The year of the period. + See Also + -------- + PeriodIndex.day_of_year : The ordinal day of the year. + PeriodIndex.dayofyear : The ordinal day of the year. + PeriodIndex.is_leap_year : Logical indicating if the date belongs to a + leap year. + PeriodIndex.weekofyear : The week ordinal of the year. + PeriodIndex.year : The year of the period. + Examples -------- >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") @@ -444,6 +453,11 @@ def __arrow_array__(self, type=None): """ The month as January=1, December=12. + See Also + -------- + PeriodIndex.days_in_month : The number of days in the month. + PeriodIndex.daysinmonth : The number of days in the month. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M") @@ -456,6 +470,16 @@ def __arrow_array__(self, type=None): """ The days of the period. + See Also + -------- + PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. + PeriodIndex.day_of_year : The ordinal day of the year. + PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. + PeriodIndex.dayofyear : The ordinal day of the year. + PeriodIndex.days_in_month : The number of days in the month. + PeriodIndex.daysinmonth : The number of days in the month. + PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. + Examples -------- >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D') @@ -468,6 +492,12 @@ def __arrow_array__(self, type=None): """ The hour of the period. + See Also + -------- + PeriodIndex.minute : The minute of the period. + PeriodIndex.second : The second of the period. + PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01 10:00", "2023-01-01 11:00"], freq='h') @@ -480,6 +510,12 @@ def __arrow_array__(self, type=None): """ The minute of the period. + See Also + -------- + PeriodIndex.hour : The hour of the period. + PeriodIndex.second : The second of the period. + PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01 10:30:00", @@ -493,6 +529,12 @@ def __arrow_array__(self, type=None): """ The second of the period. + See Also + -------- + PeriodIndex.hour : The hour of the period. + PeriodIndex.minute : The minute of the period. + PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01 10:00:30", @@ -506,6 +548,14 @@ def __arrow_array__(self, type=None): """ The week ordinal of the year. + See Also + -------- + PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. + PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. + PeriodIndex.week : The week ordinal of the year. + PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. + PeriodIndex.year : The year of the period. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M") @@ -519,6 +569,17 @@ def __arrow_array__(self, type=None): """ The day of the week with Monday=0, Sunday=6. + See Also + -------- + PeriodIndex.day : The days of the period. + PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. + PeriodIndex.day_of_year : The ordinal day of the year. + PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. + PeriodIndex.dayofyear : The ordinal day of the year. + PeriodIndex.week : The week ordinal of the year. + PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. + PeriodIndex.weekofyear : The week ordinal of the year. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01-01", "2023-01-02", "2023-01-03"], freq="D") @@ -533,6 +594,17 @@ def __arrow_array__(self, type=None): """ The ordinal day of the year. + See Also + -------- + PeriodIndex.day : The days of the period. + PeriodIndex.day_of_week : The day of the week with Monday=0, Sunday=6. + PeriodIndex.day_of_year : The ordinal day of the year. + PeriodIndex.dayofweek : The day of the week with Monday=0, Sunday=6. + PeriodIndex.dayofyear : The ordinal day of the year. + PeriodIndex.weekday : The day of the week with Monday=0, Sunday=6. + PeriodIndex.weekofyear : The week ordinal of the year. + PeriodIndex.year : The year of the period. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01-10", "2023-02-01", "2023-03-01"], freq="D") @@ -551,6 +623,11 @@ def __arrow_array__(self, type=None): """ The quarter of the date. + See Also + -------- + PeriodIndex.qyear : Fiscal year the Period lies in according to its + starting-quarter. + Examples -------- >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M") @@ -558,12 +635,62 @@ def __arrow_array__(self, type=None): Index([1, 1, 1], dtype='int64') """, ) - qyear = _field_accessor("qyear") + qyear = _field_accessor( + "qyear", + """ + Fiscal year the Period lies in according to its starting-quarter. + + The `year` and the `qyear` of the period will be the same if the fiscal + and calendar years are the same. When they are not, the fiscal year + can be different from the calendar year of the period. + + Returns + ------- + int + The fiscal year of the period. + + See Also + -------- + PeriodIndex.quarter : The quarter of the date. + PeriodIndex.year : The year of the period. + + Examples + -------- + If the natural and fiscal year are the same, `qyear` and `year` will + be the same. + + >>> per = pd.Period('2018Q1', freq='Q') + >>> per.qyear + 2018 + >>> per.year + 2018 + + If the fiscal year starts in April (`Q-MAR`), the first quarter of + 2018 will start in April 2017. `year` will then be 2017, but `qyear` + will be the fiscal year, 2018. + + >>> per = pd.Period('2018Q1', freq='Q-MAR') + >>> per.start_time + Timestamp('2017-04-01 00:00:00') + >>> per.qyear + 2018 + >>> per.year + 2017 + """, + ) + days_in_month = _field_accessor( "days_in_month", """ The number of days in the month. + See Also + -------- + PeriodIndex.day : The days of the period. + PeriodIndex.days_in_month : The number of days in the month. + PeriodIndex.daysinmonth : The number of days in the month. + PeriodIndex.month : The month as January=1, December=12. + Examples -------- For Series: @@ -595,6 +722,12 @@ def is_leap_year(self) -> npt.NDArray[np.bool_]: """ Logical indicating if the date belongs to a leap year. + See Also + -------- + PeriodIndex.qyear : Fiscal year the Period lies in according to its + starting-quarter. + PeriodIndex.year : The year of the period. + Examples -------- >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y") @@ -618,6 +751,19 @@ def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray: Returns ------- DatetimeArray/Index + Timestamp representation of given Period-like object. + + See Also + -------- + PeriodIndex.day : The days of the period. + PeriodIndex.from_fields : Construct a PeriodIndex from fields + (year, month, day, etc.). + PeriodIndex.from_ordinals : Construct a PeriodIndex from ordinals. + PeriodIndex.hour : The hour of the period. + PeriodIndex.minute : The minute of the period. + PeriodIndex.month : The month as January=1, December=12. + PeriodIndex.second : The second of the period. + PeriodIndex.year : The year of the period. Examples -------- diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py index edd1fdd4da943..b5f05ef0ab78f 100644 --- a/pandas/core/indexes/period.py +++ b/pandas/core/indexes/period.py @@ -261,12 +261,19 @@ def from_fields( Parameters ---------- year : int, array, or Series, default None + Year for the PeriodIndex. quarter : int, array, or Series, default None + Quarter for the PeriodIndex. month : int, array, or Series, default None + Month for the PeriodIndex. day : int, array, or Series, default None + Day for the PeriodIndex. hour : int, array, or Series, default None + Hour for the PeriodIndex. minute : int, array, or Series, default None + Minute for the PeriodIndex. second : int, array, or Series, default None + Second for the PeriodIndex. freq : str or period object, optional One of pandas period strings or corresponding objects. @@ -274,6 +281,11 @@ def from_fields( ------- PeriodIndex + See Also + -------- + PeriodIndex.from_ordinals : Construct a PeriodIndex from ordinals. + PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. + Examples -------- >>> idx = pd.PeriodIndex.from_fields(year=[2000, 2002], quarter=[1, 3]) @@ -311,6 +323,12 @@ def from_ordinals(cls, ordinals, *, freq, name=None) -> Self: ------- PeriodIndex + See Also + -------- + PeriodIndex.from_fields : Construct a PeriodIndex from fields + (year, month, day, etc.). + PeriodIndex.to_timestamp : Cast to DatetimeArray/Index. + Examples -------- >>> idx = pd.PeriodIndex.from_ordinals([-1, 0, 1], freq="Q")