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)
Not included:
- EXRULE (deprecated), see 8.3.2. Properties Registry
pip install recurring-ical-events
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:00
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_events
There are several methods you can use to unfold repeating events, such as at(a_time)
and between(a_start, an_end)
.
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, 1) # January in 2023
a_date = (2023, 1, 1) # 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
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)
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.
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.
- DTEND which is the end of the event instance.
- RDATE, EXDATE, RRULE are the rules to create event repetitions. They are not included in repeated events, see Issue 23.
- Optional: Install virtualenv and Python3 and create a virtual environment.
virtualenv -p python3 ENV source ENV/bin/activate
- Install the packages.
pip install -r requirements.txt -r test-requirements.txt
- Run the tests
pytest
To release new versions,
- edit the Changelog Section
- edit setup.py, the
__version__
variable - create a commit and push it
- run
python3 setup.py tag_and_deploy
- notify the issues about their release
This project's development is driven by tests. 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.
- 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
- python-dateutil - to compute the recurrences of events using
rrule
- icalendar - the library used to parse ICS files
- pytz - for timezones
- icalevents - another library for roughly the same use-case
- Open Web Calendar - a web calendar to embed into websites which uses this library