Registry / serialization / recurring-ical-events

recurring-ical-events

library3.8.2pypypi✓ verified 27d ago

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.

serialization

pip install recurring-ical-events

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · RECURRING-ICAL-EVE

recurring-ical-events

serializationpythonv3.8.2

Install

2.4s avg

Import

381ms

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.8.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.396s · 29.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.366s · 30MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

recurring_ical_events

✓ import recurring_ical_events

✓ recurring_ical_events.of(calendar).between(start_date, end_date)

✗ recurring_ical_events.of(events, period_start, period_end)

The signature of `of` changed significantly in v3.0.0. It now returns an object with a `between` method.

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()}")

Debug

Known issues

breakingThe `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.

affects: >=3.0.0

breakingThe 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.

affects: >=3.0.0

breakingPython 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.

affects: >=3.0.0

gotchaThe `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)`.

affects: >=3.0.0

gotchaWhile `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.

affects: >=3.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'recurring_ical_events'

The 'recurring_ical_events' module is not installed in the Python environment.

fix

Install the module using pip: 'pip install recurring-ical-events'.

AttributeError: module 'recurring_ical_events' has no attribute 'of'

The 'of' function is not a valid attribute of the 'recurring_ical_events' module.

fix

Use the correct function to parse the calendar, such as 'recurring_ical_events.icalendar.Calendar'.

TypeError: 'NoneType' object is not iterable

The 'between' method is called on a 'None' object, likely due to a failed parsing of the iCalendar file.

fix

Ensure the iCalendar file is correctly parsed and the resulting object is not 'None' before calling 'between'.

ValueError: Invalid recurrence rule: 'FREQ=DAILY;COUNT=3;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR'

The recurrence rule string is improperly formatted or contains invalid parameters.

fix

Verify the recurrence rule string adheres to the iCalendar RFC 5545 specification and correct any formatting errors.

ImportError: cannot import name 'of' from 'recurring_ical_events'

Attempting to import a non-existent 'of' function from the 'recurring_ical_events' module.

fix

Check the module's documentation for the correct import statements and available functions.

Upgrade

Version history

3.8.2latest on PyPI · released Apr 30, 2026

Audit

Dependencies

icalendarrequiredCore dependency for parsing and handling iCalendar data.

python-dateutilrequiredUsed for robust date/time parsing and manipulation.

pytzrequiredProvides timezone definitions, though the library increasingly uses built-in `zoneinfo` for Python 3.9+.

rfc5545-parserrequiredProvides robust parsing of RFC5545 recurrence rules.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/niccokunzmann/python-recurring-ical-events?tab=readme-ov-file#changelog ↗

packagehttps://pypi.org/project/recurring-ical-events/ ↗

homepagehttps://recurring-ical-events.readthedocs.io/ ↗

docshttps://github.com/niccokunzmann/python-recurring-ical-events ↗

changeloghttps://github.com/niccokunzmann/python-recurring-ical-events?tab=readme-ov-file#changelog ↗