Skip to content

Commit 92834f4

Browse files
SiniadeSiniade
committed
DOC: Enforce Numpy Docstring Validation for freqstr, nanos, and rule_code methods of pandas.tseries.offsets Week, WeekOfMonth, YearBegin, and YearEnd classes.
1 parent 93198fb commit 92834f4

File tree

2 files changed

+98
-17
lines changed

2 files changed

+98
-17
lines changed

‎ci/code_checks.sh

-12
Original file line numberDiff line numberDiff line change
@@ -685,36 +685,24 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
685685
-i "pandas.tseries.offsets.Tick.normalize GL08" \
686686
-i "pandas.tseries.offsets.Tick.rule_code GL08" \
687687
-i "pandas.tseries.offsets.Week PR02" \
688-
-i "pandas.tseries.offsets.Week.freqstr SA01" \
689688
-i "pandas.tseries.offsets.Week.is_on_offset GL08" \
690689
-i "pandas.tseries.offsets.Week.n GL08" \
691-
-i "pandas.tseries.offsets.Week.nanos GL08" \
692690
-i "pandas.tseries.offsets.Week.normalize GL08" \
693-
-i "pandas.tseries.offsets.Week.rule_code GL08" \
694691
-i "pandas.tseries.offsets.Week.weekday GL08" \
695692
-i "pandas.tseries.offsets.WeekOfMonth PR02,SA01" \
696-
-i "pandas.tseries.offsets.WeekOfMonth.freqstr SA01" \
697693
-i "pandas.tseries.offsets.WeekOfMonth.is_on_offset GL08" \
698694
-i "pandas.tseries.offsets.WeekOfMonth.n GL08" \
699-
-i "pandas.tseries.offsets.WeekOfMonth.nanos GL08" \
700695
-i "pandas.tseries.offsets.WeekOfMonth.normalize GL08" \
701-
-i "pandas.tseries.offsets.WeekOfMonth.rule_code GL08" \
702696
-i "pandas.tseries.offsets.WeekOfMonth.week GL08" \
703697
-i "pandas.tseries.offsets.WeekOfMonth.weekday GL08" \
704-
-i "pandas.tseries.offsets.YearBegin.freqstr SA01" \
705698
-i "pandas.tseries.offsets.YearBegin.is_on_offset GL08" \
706699
-i "pandas.tseries.offsets.YearBegin.month GL08" \
707700
-i "pandas.tseries.offsets.YearBegin.n GL08" \
708-
-i "pandas.tseries.offsets.YearBegin.nanos GL08" \
709701
-i "pandas.tseries.offsets.YearBegin.normalize GL08" \
710-
-i "pandas.tseries.offsets.YearBegin.rule_code GL08" \
711-
-i "pandas.tseries.offsets.YearEnd.freqstr SA01" \
712702
-i "pandas.tseries.offsets.YearEnd.is_on_offset GL08" \
713703
-i "pandas.tseries.offsets.YearEnd.month GL08" \
714704
-i "pandas.tseries.offsets.YearEnd.n GL08" \
715-
-i "pandas.tseries.offsets.YearEnd.nanos GL08" \
716705
-i "pandas.tseries.offsets.YearEnd.normalize GL08" \
717-
-i "pandas.tseries.offsets.YearEnd.rule_code GL08" \
718706
-i "pandas.util.hash_pandas_object PR07,SA01" # There should be no backslash in the final line, please keep this comment in the last ignored function
719707

720708
RET=$(($RET + $?)) ; echo $MSG "DONE"

‎pandas/_libs/tslibs/offsets.pyx

+98-5
Original file line numberDiff line numberDiff line change
@@ -589,13 +589,36 @@ cdef class BaseOffset:
589589

590590
@property
591591
def rule_code(self) -> str:
592+
"""
593+
Return a string representing the base frequency.
594+
595+
See Also
596+
--------
597+
tseries.offsets.Hour.rule_code : Returns a string representing the base frequency of 'h'.
598+
tseries.offsets.Day.rule_code : Returns a string representing the base frequency of 'D'.
599+
600+
Examples
601+
--------
602+
>>> pd.offsets.Hour().rule_code
603+
'h'
604+
605+
>>> pd.offsets.Week(5).rule_code
606+
'W'
607+
"""
592608
return self._prefix
593609

594610
@cache_readonly
595611
def freqstr(self) -> str:
596612
"""
597613
Return a string representing the frequency.
598614

615+
See Also
616+
--------
617+
tseries.offsets.BusinessDay.freqstr : Return a string representing an offset frequency in Business Days.
618+
tseries.offsets.BusinessHour.freqstr : Return a string representing an offset frequency in Business Hours.
619+
tseries.offsets.Week.freqstr : Return a string representing an offset frequency in Weeks.
620+
tseries.offsets.Hour.freqstr : Return a string representing an offset frequency in Hours.
621+
599622
Examples
600623
--------
601624
>>> pd.DateOffset(5).freqstr
@@ -773,6 +796,26 @@ cdef class BaseOffset:
773796

774797
@property
775798
def nanos(self):
799+
"""
800+
Returns a ValueError becuase the frequency is non-fixed.
801+
802+
Raises
803+
------
804+
ValueError
805+
If the frequency is non-fixed.
806+
807+
See Also
808+
--------
809+
tseries.offsets.WeekOfMonth.nanos : Raises a ValueError becuase the frequency is non-fixed.
810+
tseries.offsets.YearBegin.nanos : Raises a ValueError becuase the frequency is non-fixed.
811+
tseries.offsets.Hour.nanos : Returns an integer of the total number of nanoseconds.
812+
tseries.offsets.Day.nanos : Returns an integer of the total number of nanoseconds.
813+
814+
Examples
815+
--------
816+
>>> pd.offsets.Week(n=1).nanos
817+
ValueError: <5 * Weeks: weekday=None> is a non-fixed frequency
818+
"""
776819
raise ValueError(f"{self} is a non-fixed frequency")
777820

778821
# ------------------------------------------------------------------
@@ -980,12 +1023,14 @@ cdef class Tick(SingleConstructorOffset):
9801023
@property
9811024
def nanos(self) -> int64_t:
9821025
"""
983-
Return an integer of the total number of nanoseconds.
1026+
Returns an integer of the total number of nanoseconds.
9841027

985-
Raises
986-
------
987-
ValueError
988-
If the frequency is non-fixed.
1028+
See Also
1029+
--------
1030+
tseries.offsets.Hour.nanos : Returns an integer of the total number of nanoseconds.
1031+
tseries.offsets.Day.nanos : Returns an integer of the total number of nanoseconds.
1032+
tseries.offsets.WeekOfMonth.nanos : Raises a ValueError becuase the frequency is non-fixed.
1033+
tseries.offsets.YearBegin.nanos : Raises a ValueError becuase the frequency is non-fixed.
9891034

9901035
Examples
9911036
--------
@@ -2420,6 +2465,22 @@ cdef class WeekOfMonthMixin(SingleConstructorOffset):
24202465

24212466
@property
24222467
def rule_code(self) -> str:
2468+
"""
2469+
Return a string representing the base frequency.
2470+
2471+
See Also
2472+
--------
2473+
tseries.offsets.Hour.rule_code : Returns a string representing the base frequency of 'h'.
2474+
tseries.offsets.Day.rule_code : Returns a string representing the base frequency of 'D'.
2475+
2476+
Examples
2477+
--------
2478+
>>> pd.offsets.Week(5).rule_code
2479+
'W'
2480+
2481+
>>> pd.offsets.WeekOfMonth(n=1, week=0, weekday=0).rule_code
2482+
'WOM-1MON'
2483+
"""
24232484
weekday = int_to_weekday.get(self.weekday, "")
24242485
if self.week == -1:
24252486
# LastWeekOfMonth
@@ -2466,6 +2527,22 @@ cdef class YearOffset(SingleConstructorOffset):
24662527

24672528
@property
24682529
def rule_code(self) -> str:
2530+
"""
2531+
Return a string representing the base frequency.
2532+
2533+
See Also
2534+
--------
2535+
tseries.offsets.Hour.rule_code : Returns a string representing the base frequency of 'h'.
2536+
tseries.offsets.Day.rule_code : Returns a string representing the base frequency of 'D'.
2537+
2538+
Examples
2539+
--------
2540+
>>> pd.tseries.offsets.YearBegin(n=1, month=2).rule_code
2541+
'YS-FEB'
2542+
2543+
>>> pd.tseries.offsets.YearEnd(n=1, month=6).rule_code
2544+
'YE-JUN'
2545+
"""
24692546
month = MONTH_ALIASES[self.month]
24702547
return f"{self._prefix}-{month}"
24712548

@@ -3452,6 +3529,22 @@ cdef class Week(SingleConstructorOffset):
34523529

34533530
@property
34543531
def rule_code(self) -> str:
3532+
"""
3533+
Return a string representing the base frequency.
3534+
3535+
See Also
3536+
--------
3537+
tseries.offsets.Hour.name : Returns a string representing the base frequency of 'h'.
3538+
tseries.offsets.Day.name : Returns a string representing the base frequency of 'D'.
3539+
3540+
Examples
3541+
--------
3542+
>>> pd.offsets.Hour().rule_code
3543+
'h'
3544+
3545+
>>> pd.offsets.Week(5).rule_code
3546+
'W'
3547+
"""
34553548
suffix = ""
34563549
if self.weekday is not None:
34573550
weekday = int_to_weekday[self.weekday]

0 commit comments

Comments
 (0)