Skip to content

DOC: fix docstring validation errors for pandas.PeriodIndex #59638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 28, 2024
Merged

DOC: fix docstring validation errors for pandas.PeriodIndex #59638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6f7b8b0
DOC: pandas.PeriodIndex GL08, PR07, RT03, and SA01 docstring validati…
hlakams Aug 28, 2024
0e8c2b8
DOC: pandas.Series.dt.qyear docstring validation error addressed by e…
hlakams Aug 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 0 additions & 22 deletions ci/code_checks.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" \
Expand All @@ -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" \
Expand Down
148 changes: 147 additions & 1 deletion pandas/core/arrays/period.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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")
Expand All @@ -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')
Expand All @@ -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')
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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")
Expand All @@ -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")
Expand All @@ -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")
Expand All @@ -551,19 +623,74 @@ 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")
>>> idx.quarter
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:
Expand Down Expand Up @@ -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")
Expand All @@ -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
--------
Expand Down
18 changes: 18 additions & 0 deletions pandas/core/indexes/period.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,19 +261,31 @@ 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.

Returns
-------
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])
Expand Down Expand Up @@ -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")
Expand Down