Document or support anchored calendar recurrences / anniversaries

[pszpetkowski]

Hi! I’ve been looking at calendar arithmetic involving leap-day dates and recurring anniversary-style periods.

Date.add(years=1) correctly truncates invalid target dates, e.g. Date(2024, 2, 29).add(years=1) becomes Date(2025, 2, 28). However, for contract-like schedules, bond interest periods, birthdays, anniversaries, etc., there is a subtly different operation: computing the nth occurrence from the original anchor date.

For example, if a contract starts on 2024-02-29, the expected yearly boundaries might be:

n = 0 -> 2024-02-29
n = 1 -> 2025-02-28
n = 2 -> 2026-02-28
n = 3 -> 2027-02-28
n = 4 -> 2028-02-29

This works if each occurrence is calculated from the original date:

>>> whenever.Date(2024, 2, 29).add(years=4)
Date("2028-02-29")

But it does not work if one year is repeatedly added to the previous occurrence (e.g. in a loop), because the original leap-day anchor is lost after the first truncation:

>>> whenever.Date(2024, 2, 29).add(years=1).add(years=1).add(years=1).add(years=1)
Date("2028-02-28")

Would you be open to either documenting this pattern or considering an API for anchored calendar recurrences? I’m not sure whether this belongs in core API, but it feels like an easy pitfall for financial/legal/subscription-style schedules.

[ariebovenberg]

Hi @pszpetkowski, thanks for posting. This is indeed a footgun that deserves a nice API. It requires some thought.

We could do a series() method much like the one Jiff has:

>>> series = Date(2024, 2, 29).series(years=1)
>>> list(series)
[Date("2024-02-29"), Date("2025-02-28"), Date("2026-02-28"), ...]

However, an "infinite" (bounded by Date.MAX) iterator isn't the most ergonomic in Python. You'd have to import takewhile or islice from itertools.

Perhaps a nicer alternative is some kind of Sequence interface like the builtin range:

>>> series[:10]  # first 10 occurrences
>>> series[::3]  # every 3rd occurrence

Looking at standards like iCal, there are fundamentally two kinds of ranges:

• COUNT: a fixed number of occurences
• UNTIL: occurrences until a certain date

Based on my experience, both occur often. Both should be supported by any new API.

Perhaps...

>>> d = Date("2024-02-29")
>>> d.series(years=1)  # open-ended
"R/2024-02-29/P1y"
>>> d.series(years=1)[:20]  # LIMIT=20
"R20/2024-02-29/P1y"
>>> d.series(years=1, until=Date("2030-01-01"))  # UNTIL=2030-01-01
"R/2024-02-29/2030-01-01/P1y"

edit: clarify wording

[pszpetkowski]

Thanks for the quick reply, that sounds very promising.

I agree that a plain infinite iterator is probably not the most ergonomic/pythonic solution for this issue. I like the .series() API idea itself though, Jiff is indeed great piece of inspiration.

Obviously, but just for clarity: the key semantic property I’d hope such an API preserves is that each occurrence is calculated from the original anchor date, not from the previous occurrence. In other words, for something like:

series = Date(2024, 2, 29).series(years=1)

I would expect roughly:

series[n] == Date(2024, 2, 29).add(years=n)

There are however, even more questions here to answer:

• End-of-month monthly recurrence. Personally, I think the .series(months=1) should probably follow the series[n] == Date(YYYY, MM, DD).add(months=n) semantics.

>>> Date(2024, 1, 31).series(months=1)[:6]
# Will monthly series also support anchoring?
[
    Date(2024, 1, 31),
    Date(2024, 2, 29),
    Date(2024, 3, 31),
    Date(2024, 4, 30),
    Date(2024, 5, 31),
    Date(2024, 6, 30),
]
# Or will the behavior look like in the current .add() API?
Date(2024, 1, 31)
    .add(months=1)  # 2024-02-29
    .add(months=1)  # 2024-03-29, anchor lost

• Would .series() allow to provide combined units just like .add() does? So, for example would .series(years=1, months=1) be allowed? If so, this would probably mean that series[n] == anchor.add(years=n, months=n)?

• Degenerate case of Zero step should probably be invalid? So this should probably raise:

>>> Date(2024, 1, 1).series()
>>> Date(2024, 1, 1).series(years=0)
>>> Date(2024, 1, 1).series(months=0, days=0)
# Otherwise you could get degenerate infinite sequence of the same date which seems like a bug magnet:
2024-01-01
2024-01-01
2024-01-01
...

• Negative recurrence direction?

>>> Date(2024, 2, 29).series(years=-1)[:5]
[
    Date(2024, 2, 29),
    Date(2023, 2, 28),
    Date(2022, 2, 28),
    Date(2021, 2, 28),
    Date(2020, 2, 29),
]

I'm also wondering about overflow behavior customization for series, but I think this is already a little too long, so I'll let you digest that and hopefully let me know what you think.