A Python module which repeats ICalendar events by RRULE, RDATE and EXDATE.
Project description
ICal has some complexity to it: Events can be repeated, removed from the feed and edited later on. This tool takes care of these circumstances.
Let’s put our expertise together and build a tool that can solve this!
day light saving time (DONE)
recurring events (DONE)
recurring events with edits (DONE)
recurring events where events are omitted (DONE)
recurring events events where the edit took place later (DONE)
normal events (DONE)
recurrence of dates but not hours, minutes, and smaller (DONE)
endless recurrence (DONE)
ending recurrence (DONE)
events with start date and no end date (DONE)
events with start as date and start as datetime (DONE)
RRULE (DONE)
RDATE (DONE)
DURATION (DONE)
EXDATE (DONE)
X-WR-TIMEZONE compatibilty (DONE)
Not included:
EXRULE (deprecated), see 8.3.2. Properties Registry
Installation
pip install recurring-ical-eventsExample
import icalendar
import recurring_ical_events
import urllib.request
start_date = (2019, 3, 5)
end_date = (2019, 4, 1)
url = "http://tinyurl.com/y24m3r8f"
ical_string = urllib.request.urlopen(url).read()
calendar = icalendar.Calendar.from_ical(ical_string)
events = recurring_ical_events.of(calendar).between(start_date, end_date)
for event in events:
start = event["DTSTART"].dt
duration = event["DTEND"].dt - event["DTSTART"].dt
print("start {} duration {}".format(start, duration))Output:
start 2019-03-18 04:00:00+01:00 duration 1:00:00
start 2019-03-20 04:00:00+01:00 duration 1:00:00
start 2019-03-19 04:00:00+01:00 duration 1:00:00
start 2019-03-07 02:00:00+01:00 duration 1:00:00
start 2019-03-08 01:00:00+01:00 duration 2:00:00
start 2019-03-09 03:00:00+01:00 duration 0:30:00
start 2019-03-10 duration 1 day, 0:00:00Usage
The icalendar module is responsible for parsing and converting calendars. The recurring_ical_events module uses such a calendar and creates all repetitions of its events within a time span.
To import this module, write
import recurring_ical_eventsThere are several methods you can use to unfold repeating events, such as at(a_time) and between(a_start, an_end).
at(a_date)
You can get all events which take place at a_date. A date can be a year, e.g. 2023, a month of a year e.g. January in 2023 (2023, 1), a day of a certain month e.g. (2023, 1, 1), an hour e.g. (2023, 1, 1, 0), a minute e.g. (2023, 1, 1, 0, 0), or second as well as a datetime.date object and datetime.datetime.
The start and end are inclusive. As an example: if an event is longer than one day it is still included if it takes place at a_date.
a_date = 2023 # a year
a_date = (2023,) # a year
a_date = (2023, 1) # January in 2023
a_date = (2023, 1, 1) # the 1st of January in 2023
a_date = "20230101" # the 1st of January in 2023
a_date = (2023, 1, 1, 0) # the first hour of the year 2023
a_date = (2023, 1, 1, 0, 0) # the first minute in 2023
a_date = datetime.date(2023) # the first day in 2023
a_date = datetime.date(2023, 1, 1) # the first day in 2023
a_date = datetime.datetime.now() # this exact second
events = recurring_ical_events.of(an_icalendar_object).at(a_date)The resulting events are a list of icalendar events, see below.
between(start, end)
between(start, end) returns all events happening between a start and an end time. Both arguments can be datetime.datetime, datetime.date, tuples of numbers passed as arguments to datetime.datetime or strings in the form of %Y%m%d (yyyymmdd) and %Y%m%dT%H%M%SZ (yyyymmddThhmmssZ). For examples, see at(a_date) above.
events = recurring_ical_events.of(an_icalendar_object).between(start, end)The resulting events are in a list, see below.
events as list
The result of both between(start, end) and at(a_date) is a list of icalendar events. By default, all attributes of the event with repetitions are copied, like UID and SUMMARY. However, these attributes may differ from the source event:
DTSTART which is the start of the event instance. (always present)
DTEND which is the end of the event instance. (always present)
RDATE, EXDATE, RRULE are the rules to create event repetitions. They are not included in repeated events, see Issue 23. To change this, use of(calendar, keep_recurrence_attributes=True).
Speed
If you use between() or at() several times, it is faster to re-use the object coming from of().
rcalendar = recurring_ical_events.of(an_icalendar_object)
events_of_day_1 = rcalendar.at(day_1)
events_of_day_2 = rcalendar.at(day_2)
events_of_day_3 = rcalendar.at(day_3)
# ...Version Fixing
If you use this library in your code, you may want to make sure that updates can be received but they do not break your code. The version numbers are handeled this way: a.b.c example: 0.1.12
c is changed for each minor bug fix.
b is changed whenever new features are added.
a is changed when the interface or major assumptions change that may break your code.
So, I recommend to version-fix this library to stay with the same a while b and c can change.
Support
This library is part of the Open Web Calendar Collective. We accept donations to sustain our work, once or regular. Open Collective makes it easy for you to give and for us to receive. Consider donating money to open-source as everyone benefits.
Development
Optional: Install virtualenv and Python3 and create a virtual environment.
virtualenv -p python3 ENV source ENV/bin/activateInstall the packages.
pip install -r requirements.txt -r test-requirements.txtRun the tests
pytest
New Releases
To release new versions,
edit the Changelog Section
edit setup.py, the __version__ variable
create a commit and push it
Wait for GitHub Actions to finish the build.
run
python3 setup.py tag_and_deploynotify the issues about their release
Testing
This project’s development is driven by tests. Tests assure a consistent interface and less knowledge lost over time. If you like to change the code, tests help that nothing breaks in the future. They are required in that sense. Example code and ics files can be transferred into tests and speed up fixing bugs.
You can view the tests in the test folder. If you have a calendar ICS file for which this library does not generate the desired output, you can add it to the test/calendars folder and write tests for what you expect. If you like, open an issue first, e.g. to discuss the changes and how to go about it.
Changelog
v1.1.0b
Add repeated TODOs and Journals. See Pull Request 100 and Issue 97.
v1.0.3b
Remove syntax anomalies in README.
Switch to GitHub actions because GitLab decided to remove support.
v1.0.2b
Add support for X-WR-TIMEZONE calendars which contain events without an explicit time zone, see Issue 86.
v1.0.1b
Add support for zoneinfo.ZoneInfo time zones, see Issue 57.
Migrate from Travis CI to Gitlab CI.
Add code coverage on Gitlab.
v1.0.0b
v0.2.4b
Events with a duration of 0 seconds are correctly returned.
between() and at() take the same kind of arguments. These arguments are documented.
v0.2.3b
v0.2.2b
Check that at() does not return an event starting at the next day, see Issue 44.
v0.2.1b
Check that recurring events are removed if they are modified to leave the requested time span, see Issue 62.
v0.2.0b
Add ability to keep the recurrence attributes (RRULE, RDATE, EXDATE) on the event copies instead of stripping them. See Pull Request 54.
v0.1.21b
Fix issue with repetitions over DST boundary. See Issue 48.
v0.1.20b
Fix handling of modified recurrences with lower sequence number than their base event Pull Request 45
v0.1.19b
v0.1.18b
v0.1.17b
Handle Issue 28 where passed arguments lead to errors where it is expected to work.
v0.1.16b
Events with an empty RRULE are handled like events without an RRULE.
Remove fixed dependency versions, see Issue 14
v0.1.15b
Repeated events also include subcomponents. Issue 6
v0.1.14b
Fix compatibility issue 20: EXDATEs of different time zones are now supported.
v0.1.13b
Remove attributes RDATE, EXDATE, RRULE from repeated events Issue 23
Use vDDDTypes instead of explicit date/datetime type Pull Request 19
Start Changelog
Libraries Used
python-dateutil - to compute the recurrences of events using rrule
icalendar - the library used to parse ICS files
pytz - for timezones
x-wr-timezone for handling the non-standard X-WR-TIMEZONE property.
Media
Nicco Kunzmann talked about this library at the FOSSASIA 2022 Summit:
Research
RFC 7986 – an update to RFC 5545. It does not change any properties useful for scheduling events.
https://stackoverflow.com/questions/20268204/ical-get-date-from-recurring-event-by-rrule-and-dtstart
https://stackoverflow.com/questions/46471852/ical-parsing-reoccuring-events-in-python
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for recurring_ical_events-1.1.0b0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 9091671454a9df62356c9d0e9ef66365e255c6cc04044f665d083dd08a6c5c88 |
|
| MD5 | e7eddc6596fae144e7dbc79d43f3254f |
|
| BLAKE2b-256 | e48dd6c4a721284130e92ac3ea494c33af95a87da9a75721fbde9300fd597099 |
Hashes for recurring_ical_events-1.1.0b0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | afc82fa613a79484820aaacd0eccbe442da92b6bff4b87614ac58b5d22c65386 |
|
| MD5 | 9b19f5e9ca8bcd2cacc88383899da11c |
|
| BLAKE2b-256 | e832ee78793564b6a2d3dd0d125949e1380378a3067c36308df48a6fe43daf48 |
