From 336998eaf386d6c02461b7d63757e3ed5c1bef51 Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Sun, 16 Oct 2022 23:48:46 +0300 Subject: [PATCH 1/6] Update offsets.pyx [DOC] - Added more examples and explanation regarding MonthEnd method. --- pandas/_libs/tslibs/offsets.pyx | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 8bdd3d6ac259e..aec19717b7045 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2476,12 +2476,42 @@ cdef class MonthOffset(SingleConstructorOffset): cdef class MonthEnd(MonthOffset): """ DateOffset of one month end. + + When parameter n=0, always offset to the end of month. + + When parameter n=1, depend on the given date: + a) Given date is on an anchor point (last day of the month) -> offset to the end of the following month + b) Given date is not on an anchor point -> offset to the end of the same month + + + Parameters + ---------- + n : int, default 1 + Examples -------- >>> ts = pd.Timestamp(2022, 1, 1) - >>> ts + pd.offsets.MonthEnd() + >>> ts + pd.offsets.MonthEnd(n=1) Timestamp('2022-01-31 00:00:00') + + >>> ts = pd.Timestamp(2022, 1, 31) + >>> ts + pd.offsets.MonthEnd(n=0) + Timestamp('2022-01-31 00:00:00') + + + >>> ts = pd.Timestamp(2022, 1, 31) + >>> ts + pd.offsets.MonthEnd(n=1) + Timestamp('2022-02-28 00:00:00') + + + >>> ts = pd.Timestamp(2022, 1, 31) + >>> ts + pd.offsets.MonthEnd(n=2) + Timestamp('2022-03-31 00:00:00') + + >>> ts = pd.Timestamp(2022, 1, 31) + >>> ts + pd.offsets.MonthEnd(n=-1) + Timestamp('2021-12-31 00:00:00') """ _period_dtype_code = PeriodDtypeCode.M _prefix = "M" From fae682da0b2fe4e0d27cda9079993dc20130a8c6 Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Mon, 17 Oct 2022 10:46:15 +0300 Subject: [PATCH 2/6] Clear whitespaces --- pandas/_libs/tslibs/offsets.pyx | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index aec19717b7045..b6ac3e316776e 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2480,15 +2480,13 @@ cdef class MonthEnd(MonthOffset): When parameter n=0, always offset to the end of month. When parameter n=1, depend on the given date: - a) Given date is on an anchor point (last day of the month) -> offset to the end of the following month - b) Given date is not on an anchor point -> offset to the end of the same month - - + a) Given date is on an anchor point (last day of the month) -> offset to the end of the following month. + b) Given date is not on an anchor point -> offset to the end of the same month. + Parameters ---------- n : int, default 1 - - + Examples -------- >>> ts = pd.Timestamp(2022, 1, 1) @@ -2497,14 +2495,12 @@ cdef class MonthEnd(MonthOffset): >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=0) - Timestamp('2022-01-31 00:00:00') - + Timestamp('2022-01-31 00:00:00') >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=1) Timestamp('2022-02-28 00:00:00') - >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=2) Timestamp('2022-03-31 00:00:00') From 2bf9a87cd83beda8b34aa8511ad5f20277be8db4 Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Mon, 17 Oct 2022 12:52:24 +0300 Subject: [PATCH 3/6] [DOCS] - Added more comment and examples of n parameter --- pandas/_libs/tslibs/offsets.pyx | 37 ++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index b6ac3e316776e..ae53b77cec960 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2476,35 +2476,56 @@ cdef class MonthOffset(SingleConstructorOffset): cdef class MonthEnd(MonthOffset): """ DateOffset of one month end. - - When parameter n=0, always offset to the end of month. - - When parameter n=1, depend on the given date: - a) Given date is on an anchor point (last day of the month) -> offset to the end of the following month. - b) Given date is not on an anchor point -> offset to the end of the same month. - + + Parameters ---------- n : int, default 1 + n = 0 -> offset to the end of month. + n = 1 -> depend on the given date: + a) Given date is on an anchor point (last day of the month) -> offset to the end of the following month. + b) Given date is not on an anchor point -> offset to the end of the same month. Examples -------- + Offset to the end of the month: + >>> ts = pd.Timestamp(2022, 1, 1) - >>> ts + pd.offsets.MonthEnd(n=1) + >>> ts + pd.offsets.MonthEnd() Timestamp('2022-01-31 00:00:00') + However be careful, if given date is the last day of a month, method offsets to the end of the following month: + + >>> ts = pd.Timestamp(2022, 1, 31) + >>> ts + pd.offsets.MonthEnd() + Timestamp('2022-02-28 00:00:00') + + With the ``n`` parameter, we can control logic of offset. + + See below, when ``n`` is set to 0, offset is always made the end of the current month: + >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=0) Timestamp('2022-01-31 00:00:00') + When ``n`` is set to 1 (default) it will be moved to the following month: + >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=1) + Timestamp('2022-02-28 00:00:00') + + When ``n`` is set to 2, method offsets one additional month. And again depends whether given date is on on anchor point: + + >>> ts = pd.Timestamp(2022, 1, 1) + >>> ts + pd.offsets.MonthEnd(n=2) Timestamp('2022-02-28 00:00:00') >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=2) Timestamp('2022-03-31 00:00:00') + Also we can use negative ``n`` to find end of previous months: + >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=-1) Timestamp('2021-12-31 00:00:00') From e8552c2a159f7d0d2e9f722fe1f51e449afe0a9b Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Mon, 17 Oct 2022 15:43:11 +0300 Subject: [PATCH 4/6] Remove trailing white spaces --- pandas/_libs/tslibs/offsets.pyx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index ae53b77cec960..a1a316c35b72a 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2477,7 +2477,6 @@ cdef class MonthEnd(MonthOffset): """ DateOffset of one month end. - Parameters ---------- n : int, default 1 @@ -2506,7 +2505,7 @@ cdef class MonthEnd(MonthOffset): >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=0) - Timestamp('2022-01-31 00:00:00') + Timestamp('2022-01-31 00:00:00') When ``n`` is set to 1 (default) it will be moved to the following month: @@ -2514,7 +2513,7 @@ cdef class MonthEnd(MonthOffset): >>> ts + pd.offsets.MonthEnd(n=1) Timestamp('2022-02-28 00:00:00') - When ``n`` is set to 2, method offsets one additional month. And again depends whether given date is on on anchor point: + When ``n`` is set to 2, method offsets one additional month. And again depends whether given date is on on anchor point: >>> ts = pd.Timestamp(2022, 1, 1) >>> ts + pd.offsets.MonthEnd(n=2) From edcbdc15b61cac3556dc22301ee868f344dcde00 Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Mon, 17 Oct 2022 16:56:01 +0300 Subject: [PATCH 5/6] Update pandas/_libs/tslibs/offsets.pyx Co-authored-by: Marco Edward Gorelli <33491632+MarcoGorelli@users.noreply.github.com> --- pandas/_libs/tslibs/offsets.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index a1a316c35b72a..4eeefdc18e959 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2501,7 +2501,7 @@ cdef class MonthEnd(MonthOffset): With the ``n`` parameter, we can control logic of offset. - See below, when ``n`` is set to 0, offset is always made the end of the current month: + See below, when ``n`` is set to 0, offset is always made to the end of the current month: >>> ts = pd.Timestamp(2022, 1, 31) >>> ts + pd.offsets.MonthEnd(n=0) From 0e98b9f32548fc545c014ec6f265ee7705377713 Mon Sep 17 00:00:00 2001 From: Jan Timko <61096773+honza26@users.noreply.github.com> Date: Mon, 17 Oct 2022 16:56:08 +0300 Subject: [PATCH 6/6] Update pandas/_libs/tslibs/offsets.pyx Co-authored-by: Marco Edward Gorelli <33491632+MarcoGorelli@users.noreply.github.com> --- pandas/_libs/tslibs/offsets.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx index 4eeefdc18e959..7a16bdb15ab5d 100644 --- a/pandas/_libs/tslibs/offsets.pyx +++ b/pandas/_libs/tslibs/offsets.pyx @@ -2513,7 +2513,7 @@ cdef class MonthEnd(MonthOffset): >>> ts + pd.offsets.MonthEnd(n=1) Timestamp('2022-02-28 00:00:00') - When ``n`` is set to 2, method offsets one additional month. And again depends whether given date is on on anchor point: + When ``n`` is set to 2, method offsets one additional month. And again depends whether given date is on an anchor point: >>> ts = pd.Timestamp(2022, 1, 1) >>> ts + pd.offsets.MonthEnd(n=2)