Recurring iCal Events

3.8.1 · active · verified Sat Apr 11

This library calculates recurrence times of events, todos, alarms, and journals based on the iCalendar RFC5545 specification. It provides a convenient way to expand recurring events within a given time range from an iCalendar object. The current version is 3.8.1, with a regular release cadence as evidenced by frequent updates.

Warnings

breaking The `end` parameter of the `between()` method (and formerly the `of()` function) is now exclusive, meaning events occurring exactly at the `end` datetime are no longer included.
Fix: If you need to include events exactly on the end date, adjust your `end` datetime to be one unit (e.g., one second or one day) after your desired inclusive end.
breaking The default timezone inference for events without a `TZID` parameter changed from UTC to the local system timezone.
Fix: Explicitly set `DTSTART` and `DTEND` with `TZID` for all events where timezone certainty is critical, or ensure your local system timezone matches expectations, especially when dealing with events lacking explicit timezone information.
breaking Python 3.7 is no longer supported. The library now requires Python 3.8 or newer.
Fix: Upgrade your Python environment to 3.8 or a later version to use `recurring-ical-events` v3.0.0 and above.
gotcha The `of()` function's signature changed in v3.0.0, moving from `of(events, start, end)` to `of(calendar_or_events).between(start, end)`. Directly calling `of` with three arguments will raise an error.
Fix: Update your code to use the new chained method call: `recurring_ical_events.of(calendar).between(start_date, end_date)`.
gotcha While `pytz` is still a dependency, the library encourages the use of Python 3.9+'s built-in `zoneinfo` module or `backports.zoneinfo` for Python 3.8 for timezone handling where possible, to align with modern Python practices.
Fix: Prefer `datetime.timezone.utc` or `zoneinfo.ZoneInfo` for defining timezone-aware datetimes when interacting with the library, especially in new code.

Install

pip install recurring-ical-events Install stable version

Imports

recurring_ical_events
```
import recurring_ical_events
```
of
```
recurring_ical_events.of(calendar).between(start_date, end_date)
```
The signature of `of` changed significantly in v3.0.0. It now returns an object with a `between` method.

Quickstart

This quickstart demonstrates how to parse an iCalendar string, extract a recurring event, and then expand its occurrences within a specified date range using the `recurring_ical_events` library. It uses `icalendar` for parsing the base calendar and `datetime` for defining the period.

import recurring_ical_events
import icalendar
import datetime

# An iCalendar string with a daily recurring event
calendar_string = """BEGIN:VCALENDAR\nPRODID:-//Example Corp.//iCalGen 1.0//EN\nVERSION:2.0\nBEGIN:VEVENT\nDTSTART;TZID=America/New_York:20231201T090000\nDTEND;TZID=America/New_York:20231201T100000\nRRULE:FREQ=DAILY;COUNT=3\nSUMMARY:Daily Meeting\nEND:VEVENT\nEND:VCALENDAR"""

# Parse the iCalendar string
calendar = icalendar.Calendar.from_ical(calendar_string)

# Define the period for which to get events
start_date = datetime.datetime(2023, 11, 20, tzinfo=datetime.timezone.utc)
end_date = datetime.datetime(2023, 12, 31, tzinfo=datetime.timezone.utc)

# Get recurring events within the specified period
events = recurring_ical_events.of(calendar).between(start_date, end_date)

print(f"Found {len(events)} events:")
for event in events:
    print(f"- {event['SUMMARY']} on {event['DTSTART'].dt.isoformat()}")

view raw JSON →